Utilize Folder Trees for Workspaces

API Endpoint: workspace_folder_tree

Creates a folder tree from a workspace folder

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”.

Description

The folder tree API endpoint, workspace_folder_tree, provides users with a workspace folder ‘view’. This visual representation of a workspace folder can be at the root level of the folder, or start a specific folder in a different sub-level.

Recursion Limits of Folder Trees

The folder tree API endpoint recursively builds a visual representation of a workspace’s folder and resource structure. However, there is a limit to the depth of recursion the folder tree API endpoint can go.

Important

The maximum supported recursion depth is 900 levels. Requests exceeding this limit will result in an error.

Parameter Definitions

Parameter Definition

Description

Required Fields

workspace_id

Unique ID or name of the workspace

Required

parent_folder

Unique ID of the folder that will be set to the parent level of the folder tree

Required

show_resources

Boolean value to display the resources within the parent folder and sub-folders in the folder tree

Optional

Note

To acquire the value for workspace_id, copy the name from the URL

url path image

Warning

Due to the ability of having mutliple folders in a workspace having the same folder name, the id of the folder must be used as the value for the parent_folder value

Important

To acquire the id of a folder in a workspace use the following steps:

  • Navigate to the workspace where the folder resides

  • In EDX Drive, navigate to the folder level that the parent folder is located

  • Right-click on the folder and select the Get Folder ID Optional

  • Copy the folder ID by clicking the Copy ID to Clipboard button

Note

The show_resources parameter is not required to utilize the workspace_folder_tree endpoint.

  • If show_resources parameter is not present in the script, the default value will be FALSE

  • if show_resources parameter value is left blank, the default value will be FALSE

  • Any other value than TRUE , FALSE, or an empty value will result in an error


Parameter Definitions for Folders and Sub-Folder in API Script Output

Parameter Definition

Description

folder_id

Unique ID of the folder

folder_name

Name of the folder

parent_folder-id

Unique ID of the parent folder

created_at

Date the folder was created

last_modified

Date a folder was modified in a folder

Parameter Definitions for Resources in API Script Output

Parameter Definition

Description

resource_id

Unique ID of the resource in a folder

resource_name

Name of the resource in a folder

resource_type

File type of the resource

license_type

License type assigned to the resource

resource_created_at

Date the resource was created and added to the folder

resource_modified

Date a resource was modified in a folder

Example 1: Create a Folder Tree from the Root Folder of a Workspace with Resources

Attention

  • Add the "User-Agent": parameter within the headers of the API request

  • Set "User-Agent": to the value "EDX-USER"

Important

If the value for the parent_folder parameter is invalid, the output will result in an error

  • Input
  • Successful Output
  • Failed Output with Invalid Workspace ID
  • Failed Output with Invalid Parent Folder ID
  • Failed Output with Invalid value for ``show_resources`` Parameter
import requests

headers = {
"EDX-API-Key": ''YOUR-API-KEY-HERE'',
"User-Agent": 'EDX-USER',
'Content-Type': 'application/json',
'Accept':'application/json'
}

data = {
'workspace_id': 'WORKSPACE-NAME-ID-HERE',
'parent_folder': 'ID-OF-PARENT-FOLDER',
'show_resources': True #value of of boolean must be TRUE, FALSE, or and empty string
}

url = 'https://edx.netl.doe.gov/api/3/action/workspace_folder_tree'
r = requests.post(
url, # URL to API endpoint
headers=headers, # Headers dictionary
json=data, # Dictionary of data params

)
r_json = r.json()
print (r.json())

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'success': True, 'result': {'workspace_id': '26e0b176-4b47-47ec-9c13-b480e7b7b431',
'resources': [{'resource_id': '49c74d03-6b0b-4b8c-b8be-94f4330fa490', 'resource_name': '10.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:55:22.758000', 'resource_modified': '2025-07-10 09:55:22.758000'},
{'resource_id': 'ac58b3e9-a788-4ae9-ab71-b9835ccfb780', 'resource_name': '22.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:55:22.755000', 'resource_modified': '2025-07-10 09:55:22.755000'}],
'folders': [{'folder_id': '032a265e-0a57-4839-a01a-f730fd1c40e3', 'folder_name': 'level-2-folder', 'parent_folder_id': 'b54d4e9a-ff4a-4c80-b7a4-2715b5c10bda', 'created_at': '2025-07-10 09:53:47.877843', 'last_modified': '2025-07-10 09:53:47.877851',
'resources': [{'resource_id': '3f4300f3-b227-4c55-a3d4-8914486cdfd0', 'resource_name': '223.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:55:30.286000', 'resource_modified': '2025-07-10 09:55:30.286000'},
{'resource_id': '7482a4a3-de4b-4295-987d-b053a7f2bc66', 'resource_name': '33.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:55:30.309000', 'resource_modified': '2025-07-10 09:55:30.309000'}],

'sub_folders': [{'folder_id': '613a88a6-600b-49d9-8d13-1974867c8e03', 'folder_name': 'level-3-folder', 'parent_folder_id': '032a265e-0a57-4839-a01a-f730fd1c40e3', 'created_at': '2025-07-10 09:53:58.297283', 'last_modified': '2025-07-10 09:53:58.297290',
'resources': [{'resource_id': 'e2fefbfa-9d8a-433b-9692-41371699d672', 'resource_name': 'IMAG0002.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:55:47.311000', 'resource_modified': '2025-07-10 09:55:47.311000'},
{'resource_id': 'a320bb26-ee72-41ea-947c-b2d615897163', 'resource_name': 'IMAG0006.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:55:47.310000', 'resource_modified': '2025-07-10 09:55:47.310000'},
{'resource_id': '7cf61d9f-f0d2-47f4-ab6c-3f61da76b5bc', 'resource_name': 'IMAG0011.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:55:47.313000', 'resource_modified': '2025-07-10 09:55:47.313000'},
{'resource_id': '4277a1e1-83bc-4096-b7de-cedc38fe0fb6', 'resource_name': 'IMAG3.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:55:47.259000', 'resource_modified': '2025-07-10 09:55:47.259000'}],

'sub_folders': [{'folder_id': '81882fd7-28f0-4abd-b77b-5df29bfef40d', 'folder_name': 'level-4-folder', 'parent_folder_id': '613a88a6-600b-49d9-8d13-1974867c8e03', 'created_at': '2025-07-10 09:54:11.292940', 'last_modified': '2025-07-10 09:54:11.292947',
'resources': [{'resource_id': '27c48546-0bbb-4422-9a4d-be93dc1913af', 'resource_name': 'IMAG0012.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:55:58.451000', 'resource_modified': '2025-07-10 09:55:58.451000'},
{'resource_id': '42d2bc24-0c33-47fa-93e1-f82420e0c276', 'resource_name': 'IMAG0013.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:55:58.444000', 'resource_modified': '2025-07-10 09:55:58.444000'},
{'resource_id': 'b8f6386e-17a0-4db5-b6cd-ee3ebd18f140', 'resource_name': 'IMAG0014.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:55:58.493000', 'resource_modified': '2025-07-10 09:55:58.493000'}],

'sub_folders': [{'folder_id': '59663b89-41fa-4df7-9c25-8ffd6414e291', 'folder_name': 'level-5-folder', 'parent_folder_id': '81882fd7-28f0-4abd-b77b-5df29bfef40d', 'created_at': '2025-07-10 09:54:21.351815', 'last_modified': '2025-07-10 09:54:21.351821',
'resources': [{'resource_id': '33a58404-c57b-4b69-b9b3-e1553313b36e', 'resource_name': 'nod.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:56:08.801000', 'resource_modified': '2025-07-10 09:56:08.801000'}],
'sub_folders': []}]}]}]}]}}

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'error': {'__type': 'Not Found Error', 'message': 'Not found'}, 'success': False}

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'error': {'message': 'Parent folder "81882fd7-28f0-4abd-b77b-5df29bfef40d11" does not exist in the workspace you provided.
Please check that the folder ID is valid and refers to an existing folder.', '__type': 'Validation Error'}, 'success': False}

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'error': {'message': "'show_resources' must be True or False.", '__type': 'Validation Error'}, 'success': False}

Example 2: Create a Folder Tree from the Root Folder of a Workspace without Resources

Attention

  • Add the "User-Agent": parameter within the headers of the API request

  • Set "User-Agent": to the value "EDX-USER"

Important

If the value for the parent_folder parameter is invalid, the output will result in an error

  • Input with FALSE Value
  • Input with Blank Value
  • Input with 'show_resources' Parameter Not Present
  • Successful Output for ALL Input Examples
  • Failed Output with Invalid Workspace ID
  • Failed Output with Invalid Parent Folder ID
  • Failed Output with Invalid value for ``show_resources`` Parameter
import requests

headers = {
"EDX-API-Key": ''YOUR-API-KEY-HERE'',
"User-Agent": 'EDX-USER',
'Content-Type': 'application/json',
'Accept':'application/json'
}

data = {
'workspace_id': 'WORKSPACE-NAME-ID-HERE',
'parent_folder': 'ID-OF-PARENT-FOLDER',
'show_resources': FALSE
}

url = 'https://edx.netl.doe.gov/api/3/action/workspace_folder_tree'
r = requests.post(
url, # URL to API endpoint
headers=headers, # Headers dictionary
json=data, # Dictionary of data params

)
r_json = r.json()
print (r.json())

import requests

headers = {
"EDX-API-Key": ''YOUR-API-KEY-HERE'',
"User-Agent": 'EDX-USER',
'Content-Type': 'application/json',
'Accept':'application/json'
}

data = {
'workspace_id': 'WORKSPACE-NAME-ID-HERE',
'parent_folder': 'ID-OF-PARENT-FOLDER',
'show_resources': ''
}

url = 'https://edx.netl.doe.gov/api/3/action/workspace_folder_tree'
r = requests.post(
url, # URL to API endpoint
headers=headers, # Headers dictionary
json=data, # Dictionary of data params

)
r_json = r.json()
print (r.json())

import requests

headers = {
"EDX-API-Key": ''YOUR-API-KEY-HERE'',
"User-Agent": 'EDX-USER',
'Content-Type': 'application/json',
'Accept':'application/json'
}

data = {
'workspace_id': 'WORKSPACE-NAME-ID-HERE',
'parent_folder': 'ID-OF-PARENT-FOLDER',

}

url = 'https://edx.netl.doe.gov/api/3/action/workspace_folder_tree'
r = requests.post(
url, # URL to API endpoint
headers=headers, # Headers dictionary
json=data, # Dictionary of data params

)
r_json = r.json()
print (r.json())

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'success': True, 'result': {'workspace_id': '26e0b176-4b47-47ec-9c13-b480e7b7b431',
'folders': [{'folder_id': '032a265e-0a57-4839-a01a-f730fd1c40e3', 'folder_name': 'level-2-folder', 'parent_folder_id': 'b54d4e9a-ff4a-4c80-b7a4-2715b5c10bda', 'created_at': '2025-07-10 09:53:47.877843', 'last_modified': '2025-07-10 09:53:47.877851',
'sub_folders': [{'folder_id': '613a88a6-600b-49d9-8d13-1974867c8e03', 'folder_name': 'level-3-folder', 'parent_folder_id': '032a265e-0a57-4839-a01a-f730fd1c40e3', 'created_at': '2025-07-10 09:53:58.297283', 'last_modified': '2025-07-10 09:53:58.297290',
'sub_folders': [{'folder_id': '81882fd7-28f0-4abd-b77b-5df29bfef40d', 'folder_name': 'level-4-folder', 'parent_folder_id': '613a88a6-600b-49d9-8d13-1974867c8e03', 'created_at': '2025-07-10 09:54:11.292940', 'last_modified': '2025-07-10 09:54:11.292947',
'sub_folders': [{'folder_id': '59663b89-41fa-4df7-9c25-8ffd6414e291', 'folder_name': 'level-5-folder', 'parent_folder_id': '81882fd7-28f0-4abd-b77b-5df29bfef40d', 'created_at': '2025-07-10 09:54:21.351815', 'last_modified': '2025-07-10 09:54:21.351821',
'sub_folders': []}]}]}]}]}}

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'error': {'__type': 'Not Found Error', 'message': 'Not found'}, 'success': False}

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'error': {'message': 'Parent folder "81882fd7-28f0-4abd-b77b-5df29bfef40d11" does not exist in the workspace you provided.
Please check that the folder ID is valid and refers to an existing folder.', '__type': 'Validation Error'}, 'success': False}

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'error': {'message': "'show_resources' must be True or False.", '__type': 'Validation Error'}, 'success': False}

Example 3: Create a Folder Tree from a Sub-Folder of a Workspace with Resources

Attention

  • Add the "User-Agent": parameter within the headers of the API request

  • Set "User-Agent": to the value "EDX-USER"

Important

If the value for the parent_folder parameter is invalid, the output will result in an error

Note

The parent folder of this output will be the sub-folder used in example 1. If comparing Example 1 and Example 3, you will notice the output has fewer folder levels to show this.

  • Input
  • Successful Output
  • Failed Output with Invalid Workspace ID
  • Failed Output with Invalid Parent Folder ID
  • Failed Output with Invalid value for ``show_resources`` Parameter
import requests

headers = {
"EDX-API-Key": ''YOUR-API-KEY-HERE'',
"User-Agent": 'EDX-USER',
'Content-Type': 'application/json',
'Accept':'application/json'
}

data = {
'workspace_id': 'WORKSPACE-NAME-ID-HERE',
'parent_folder': 'ID-OF-PARENT-FOLDER',
'show_resources': True #value of of boolean must be TRUE, FALSE, or and empty string
}

url = 'https://edx.netl.doe.gov/api/3/action/workspace_folder_tree'
r = requests.post(
url, # URL to API endpoint
headers=headers, # Headers dictionary
json=data, # Dictionary of data params

)
r_json = r.json()
print (r.json())

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'success': True, 'result': {'workspace_id': '26e0b176-4b47-47ec-9c13-b480e7b7b431',
'resources': [{'resource_id': '27c48546-0bbb-4422-9a4d-be93dc1913af', 'resource_name': 'IMAG0012.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:55:58.451000', 'resource_modified': '2025-07-10 09:55:58.451000'},
{'resource_id': '42d2bc24-0c33-47fa-93e1-f82420e0c276', 'resource_name': 'IMAG0013.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:55:58.444000', 'resource_modified': '2025-07-10 09:55:58.444000'},
{'resource_id': 'b8f6386e-17a0-4db5-b6cd-ee3ebd18f140', 'resource_name': 'IMAG0014.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:55:58.493000', 'resource_modified': '2025-07-10 09:55:58.493000'}],

'folders': [{'folder_id': '59663b89-41fa-4df7-9c25-8ffd6414e291', 'folder_name': 'level-5-folder', 'parent_folder_id': '81882fd7-28f0-4abd-b77b-5df29bfef40d', 'created_at': '2025-07-10 09:54:21.351815', 'last_modified': '2025-07-10 09:54:21.351821',
'resources': [{'resource_id': '33a58404-c57b-4b69-b9b3-e1553313b36e', 'resource_name': 'nod.jpg', 'resource_type': 'file.upload', 'license_type': 'notspecified', 'resource_created_at': '2025-07-10 09:56:08.801000', 'resource_modified': '2025-07-10 09:56:08.801000'}],
'sub_folders': []}]}}

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'error': {'__type': 'Not Found Error', 'message': 'Not found'}, 'success': False}

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'error': {'message': 'Parent folder "81882fd7-28f0-4abd-b77b-5df29bfef40d11" does not exist in the workspace you provided.
Please check that the folder ID is valid and refers to an existing folder.', '__type': 'Validation Error'}, 'success': False}

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'error': {'message': "'show_resources' must be True or False.", '__type': 'Validation Error'}, 'success': False}

Example 4: Create a Folder Tree from a Sub-Folder of a Workspace without Resources

Attention

  • Add the "User-Agent": parameter within the headers of the API request

  • Set "User-Agent": to the value "EDX-USER"

Important

If the value for the parent_folder parameter is invalid, the output will result in an error

Note

The parent folder of this out will be the sub-folder used in the example. If comparing Example 1 and Example 3, you will notice the output has fewer folder levels to show this.

  • Input with FALSE Value
  • Input with Blank Value
  • Input with 'show_resources' Parameter Not Present
  • Successful Output for ALL Input Examples
  • Failed Output with Invalid Workspace ID
  • Failed Output with Invalid Parent Folder ID
  • Failed Output with Invalid value for ``show_resources`` Parameter
import requests

headers = {
"EDX-API-Key": ''YOUR-API-KEY-HERE'',
"User-Agent": 'EDX-USER',
'Content-Type': 'application/json',
'Accept':'application/json'
}

data = {
'workspace_id': 'WORKSPACE-NAME-ID-HERE',
'parent_folder': 'ID-OF-PARENT-FOLDER',
'show_resources': FALSE
}

url = 'https://edx.netl.doe.gov/api/3/action/workspace_folder_tree'
r = requests.post(
url, # URL to API endpoint
headers=headers, # Headers dictionary
json=data, # Dictionary of data params

)
r_json = r.json()
print (r.json())

import requests

headers = {
"EDX-API-Key": ''YOUR-API-KEY-HERE'',
"User-Agent": 'EDX-USER',
'Content-Type': 'application/json',
'Accept':'application/json'
}

data = {
'workspace_id': 'WORKSPACE-NAME-ID-HERE',
'parent_folder': 'ID-OF-PARENT-FOLDER',
'show_resources': ''
}

url = 'https://edx.netl.doe.gov/api/3/action/workspace_folder_tree'
r = requests.post(
url, # URL to API endpoint
headers=headers, # Headers dictionary
json=data, # Dictionary of data params

)
r_json = r.json()
print (r.json())

import requests

headers = {
"EDX-API-Key": ''YOUR-API-KEY-HERE'',
"User-Agent": 'EDX-USER',
'Content-Type': 'application/json',
'Accept':'application/json'
}

data = {
'workspace_id': 'WORKSPACE-NAME-ID-HERE',
'parent_folder': 'ID-OF-PARENT-FOLDER',

}

url = 'https://edx.netl.doe.gov/api/3/action/workspace_folder_tree'
r = requests.post(
url, # URL to API endpoint
headers=headers, # Headers dictionary
json=data, # Dictionary of data params

)
r_json = r.json()
print (r.json())

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'success': True, 'result': {'workspace_id': '26e0b176-4b47-47ec-9c13-b480e7b7b431',
'folders': [{'folder_id': '59663b89-41fa-4df7-9c25-8ffd6414e291', 'folder_name': 'level-5-folder', 'parent_folder_id': '81882fd7-28f0-4abd-b77b-5df29bfef40d', 'created_at': '2025-07-10 09:54:21.351815', 'last_modified': '2025-07-10 09:54:21.351821',
'sub_folders': []}]}}

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'error': {'__type': 'Not Found Error', 'message': 'Not found'}, 'success': False}

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'error': {'message': 'Parent folder "81882fd7-28f0-4abd-b77b-5df29bfef40d11" does not exist in the workspace you provided.
Please check that the folder ID is valid and refers to an existing folder.', '__type': 'Validation Error'}, 'success': False}

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'error': {'message': "'show_resources' must be True or False.", '__type': 'Validation Error'}, 'success': False}

Example 5: Recursion Limit Reached in a Folder Tree of a Workspace

Attention

  • Add the "User-Agent": parameter within the headers of the API request

  • Set "User-Agent": to the value "EDX-USER"

Important

If the value for the parent_folder parameter is invalid, the output will result in an error

Note

The parent folder of this out will be the sub-folder used in the example. If comparing Example 1 and Example 3, you will notice the output has fewer folder levels to show this.

  • Input while Reaching Recursion Limit
  • Recursion Limit Output
import requests

headers = {
"EDX-API-Key": ''YOUR-API-KEY-HERE'',
"User-Agent": 'EDX-USER',
'Content-Type': 'application/json',
'Accept':'application/json'
}

data = {
'workspace_id': 'WORKSPACE-NAME-ID-HERE',
'parent_folder': 'ID-OF-PARENT-FOLDER',
'show_resources': True
}

url = 'https://edx.netl.doe.gov/api/3/action/workspace_folder_tree'
r = requests.post(
url, # URL to API endpoint
headers=headers, # Headers dictionary
json=data, # Dictionary of data params

)
r_json = r.json()
print (r.json())

{'help': '/api/3/action/help_show?name=workspace_folder_tree', 'success': True, 'result': {'error': 'Maximum recursion depth exceeded. Please choose a different parent folder that does not exceed the depth.'}}