Folders

Use the following endpoints to manage folders and projects (top-level folders) in customer workspaces.

ENDPOINT ACCESS

To access these endpoints, your API client must have the appropriate privileges. This is determined by the role assigned to your API client.

To enable endpoint access:

You can enable access to these endpoints by editing an existing API client role, or by creating a new API client role:

Navigate to Workspace admin > API clients > Client roles.

Select the role you plan to edit.

Alternatively, click + Add client role to create a new API client role.

Navigate to Customer workspaces > Projects > Project assets > Projects & folders.

Select the checkboxes next to the endpoints you plan to enable for this role. The following options are available:

Projects & folders
- Select this option to enable all endpoints for this role.
List folders GET /api/managed_users/:managed_user_id/folders
List projects GET /api/managed_users/:managed_user_id/projects
Create folder POST /api/managed_users/:managed_user_id/folders
Delete folder DELETE /api/managed_users/:managed_user_id/folders /:folder_id
Update folder PUT /api/managed_users/:managed_user_id/folders /:folder_id
Delete project DELETE /api/managed_users/:managed_user_id/projects /:project_id
Update project PUT /api/managed_users/:managed_user_id/projects /:project_id

Select the endpoints you plan to enable

Rate limits

Folder resources have the following rate limit:

Quick reference

Type	Resource	Description
GET	/api/managed_users/:managed_user_id/folders	List folders in a customer workspace.
POST	/api/managed_users/:managed_user_id/folders	Create a folder in a customer workspace.
PUT	/api/managed_users/:managed_user_id/folders/:folder_id	Update a folder in a customer workspace.
DELETE	/api/managed_users/:managed_user_id/folders/:folder_id	Delete a folder in a customer workspace.

List folders

Lists all folders in a customer workspace.

shell

GET /api/managed_users/:managed_user_id/folders

URL parameters

Name	Type	Description
managed_user_id	string required	Embedded customer ID/external ID. External ID must be prefixed with an `E` (for example, `EA2300`) and the resulting ID should be URL encoded.

Query parameters

Name	Type	Description
parent_id	string optional	Parent folder ID. Defaults to Home folder.
page	integer optional	Page number. Defaults to 1.
per_page	integer optional	Page size. Defaults to 100. The maximum is 100.
with_nested_folders	boolean optional	If false, returns all immediate child folders under root, excluding root. The default is false.
updated_after	string optional	Filter the list of folders to include only those updated after the date and time you specify. The date and time must be provided in ISO 8601 format according to the following pattern: `YYYY-MM-DDTHH:MM:SSZ`.

Sample request

shell

curl  -X GET 'https://www.workato.com/api/managed_users/1199/folders?parent_id=12323' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \

Response

json

{
    "result": [
        {
            "id": 1789,
            "name": "Netsuite production",
            "parent_id": 12323,
            "created_at": "2020-07-16T10:49:53.337-07:00",
            "updated_at": "2020-07-16T10:49:53.347-07:00"
        }
    ],
    "count": 1,
    "page": 1,
    "per_page": 100
}

Create a folder

Creates a new folder in the specified parent folder. If you don't specify a parent folder ID, the system creates the folder as a top-level folder in the home folder.

shell

POST /api/managed_users/:managed_user_id/folders

URL parameters

Name	Type	Description
managed_user_id	string required	Embedded customer ID/external ID. External ID must be prefixed with an `E` (for example, `EA2300`) and the resulting ID should be URL encoded.

Payload

Name	Type	Description
name	string required	Name of the folder.
parent_id	string optional	Parent folder ID. Defaults to Home folder.

Sample request

shell

curl  -X POST https://www.workato.com/api/managed_users/1892/folders \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "Salesforce folder"
           }'

Response

json

{
  "id": 3498583,
}

Update a folder

Use this endpoint to update a folder name or move it to a different folder within a customer workspace. You can change the folder's name and update its parent_id if the folder is not a project. If the folder is a project, you can only change the project name using this endpoint.

Refer to the Update a project endpoint documentation for additional options in the request payload for projects.

shell

PUT /api/managed_users/:managed_user_id/folders/:folder_id

FOLDER AND PROJECT CONVERSION

You can't use this endpoint to convert a folder into a project or a project into a folder.

URL parameters

Name	Type	Description
managed_user_id	string required	Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an `E` (for example, `EA2300`).
folder_id	string required	The ID of the folder you plan to update. You can retrieve a list of folder IDs by calling the List folders endpoint.

Payload

Name	Type	Description
name	string optional	The new name for the folder.
parent_id	string optional	The ID of the parent folder to which you plan to move the folder.

FOLDER NAME

The folder name cannot include the / or \ characters.

Sample request

shell

curl  -X PUT https://www.workato.com/api/managed_users/19029/folders/12345 \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "My updated folder name",
            "parent_id": 67890
          }'

Responses

Successful response

json

{
    "id": 12345,
    "name": "My updated folder name",
    "parent_id": 67890,
    "created_at": "2024-08-02T13:35:11.691-07:00",
    "updated_at": "2024-08-02T14:26:30.365-07:00"
}

Unsuccessful responses

Changing the parent folder of a project

Projects are top-level folders. Attempting to change the parent folder of a project returns the following error:

json

{
    "message": "Parent can't be changed for project folder"
}

Refer to the Update a project endpoint documentation for the available options for the request payload.

Invalid characters in folder name

Attempting to update a folder name to include the / or \ characters returns the following error:

json

{
    "message": "Folder name can't contain the folder path"
}

Delete a folder

Delete a folder in a customer workspace.

FOLDER DELETION INCLUDES RECIPES AND CONNECTIONS

This action deletes a folder and all of its contents (recipes and connections).

To use this endpoint, your API client role must have the Delete folder privilege.

shell

DELETE /api/managed_users/:managed_user_id/folders/:folder_id

URL parameters

Name	Type	Description
managed_user_id	string required	Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an `E` (for example, `EA2300`).
folder_id	string required	The ID of the folder you plan to delete. You can retrieve a list of folder IDs by calling the list folders endpoint.

Query parameters

Name	Type	Description
force	boolean optional	Set this parameter to `true` to delete a folder that is not empty. When `true`, the folder you specify using the `folder_id` parameter, and its contents (all recipes and connections) within the folder are deleted. If set to `false`, this action can only delete an empty folder.

Sample request

shell

curl  -X DELETE 'https://www.workato.com/api/managed_users/:managed_user_id/folders/12345?force=true' \
      -H 'Authorization: Bearer <api_token>'

Responses

Successful response

json

{
    "success": "true"
}

Unsuccessful response

If you attempt to delete a folder that isn't empty, but do not set the force parameter to true Workato cannot delete the folder you've specified.

If the folder contains a connection, Workato provides the following response:

json

{
    "message": "can't remove a folder with connections"
}

If the folder contains a recipe, Workato provides the following response:

json

{
    "message": "can't remove a folder with recipe"
}

Last updated:

Folders ​

Rate limits ​

Quick reference ​

List folders ​

URL parameters ​

Query parameters ​

Sample request ​

Response ​

Create a folder ​

URL parameters ​

Payload ​

Sample request ​

Response ​

Update a folder ​

URL parameters ​

Payload ​

Sample request ​

Responses ​

Changing the parent folder of a project ​

Invalid characters in folder name ​

Delete a folder ​

URL parameters ​

Query parameters ​

Sample request ​

Responses ​

Folders

Rate limits

Quick reference

List folders

URL parameters

Query parameters

Sample request

Response

Create a folder

URL parameters

Payload

Sample request

Response

Update a folder

URL parameters

Payload

Sample request

Responses

Changing the parent folder of a project

Invalid characters in folder name

Delete a folder

URL parameters

Query parameters

Sample request

Responses