Create Folder on EDX Drive
==========================

.. admonition:: API Endpoint: create_folder
   
   Creates a new folder within a private collaborative workspace's EDX Drive.

.. important:: 
    An API Key is required for ALL private workspace activities
    
    The API Key name component can be added to your header using any of the following ways, "X-CKAN-API-Key", "EDX-API-Key", or "Authorization".

    If you wish to create a folder at the root level of the EDX Drive, then use the value ``root`` for ``parent_id``

Parameter Definitions
---------------------

.. list-table::
    :header-rows: 1

    * - Parameter Name
      - Description
      - Required Field 
    * - ``workspace_id``
      - The name or ID of workspace that you wish to add a folder to.
      - **Required**
    * - ``folder_name``
      - The name that you want to give to your folder.
      - **Required**
    * - ``parent_id``
      - The ID of the parent folder where new folder will live.
      - Optional (if omitted, created folder will exist on root level)


Example 1: Create Folder
------------------------

.. attention:: 
   * Add the ``"User-Agent":`` parameter within the ``headers`` of the API request
   * Set  ``"User-Agent":`` to the value ``"EDX-USER"``

.. tabs:: lang3

    .. code-tab:: python

        import requests
        headers = {
            "EDX-API-Key": 'YOUR-API-KEY-HERE',
            "User-Agent": "EDX-USER"   
        }

        data = {
            "workspace_id": 'YOUR-WORKSPACE-NAME-OR-ID-HERE',
            "folder_name": 'Test Folder 123',
            "parent_id": 'ID-OF-DESTINATION-FOLDER-HERE'
        }

        url = 'https://edx.netl.doe.gov/api/3/action/create_folder'

        r = requests.post(
            url, # URL to API endpoint
            headers=headers, # Headers dictionary
            data=data, # Dictionary of data params
        )
        print (r.json())
        print("End results")

    .. code-tab:: output

        {
            'help': 'https://edx.netl.doe.gov/api/3/action/help_show?name=create_folder', 
            'success': True, 
            'result': {
                'folder_id': 'FOLDER-ID-HERE', 
                'name': 'API Test 07-20-2020', 
                'parent_id': 'PARENT-ID-HERE', 
                'workspace_id': 'WORKSPACE-ID-HERE', 
                'workspace_name': 'demo-workspace-test'
            }
        }