# Folders

Use the following endpoint 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:

1

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.

2

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

3

Select the checkbox(es) next to the endpoint(s) 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
  • Delete project DELETE /api/managed_users/:managed_user_id/projects
    /:project_id

Select the endpoints you plan to enableSelect the endpoints you plan to enable

# Quick reference

Type Resource Description
GET /api/managed_users/:managed_user_id/folders List folders.
GET /api/managed_users/:managed_user_id/projects List projects.
POST /api/managed_users/:managed_user_id/folders Create a folder.
DELETE /api/managed_users/:managed_user_id/folders/:folder_id Delete a folder.
DELETE /api/managed_users/:managed_user_id/projects/:project_id Delete a project.

# List folders

Lists all folders in a customer account.

GET /api/managed_users/:managed_user_id/folders

# URL Parameters

Name Type Description
managed_user_id string
required
Embedded customer Account ID/External ID.
External ID must be prefixed with an E(eg: EA2300) and the resulting ID should be URL encoded.

# Query Parameters

Name Type Description
parent_id string Parent folder ID. Defaults to Home folder.
page integer Page number. Defaults to 1.
per_page integer Page size. Defaults to 100 (maximum is 100).

# Sample request

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

{
    "result": [
        {
            "id": 1789,
            "name": "Netsuite production",
            "parent_id": 4515,
            "created_at": "2020-07-16T10:49:53.337-07:00",
            "updated_at": "2020-07-16T10:49:53.347-07:00"
        }
    ]
}

# List projects

Lists all projects. Projects are top level folders that normally encompass a single use case.

GET /api/managed_users/:managed_user_id/projects

# URL Parameters

Name Type Description
page integer Page number. Defaults to 1.
per_page integer Page size. Defaults to 100 (maximum is 100).

# Sample request

curl  -X GET 'https://www.workato.com/api/managed_users/:managed_user_id/projects' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \

# Response

{
    "result": [
        {
            "id": 649122,
            "description": "Coupa to Netsuite automations",
            "folder_id": 1563029,
            "name": "Procure to Pay"
        },
        {
            "id": 604202,
            "description": "Salesforce to Netsuite automations",
            "folder_id": 1486330,
            "name": "Order to Cash"
        },
    ]
}

# Create folder

Creates a new folder in the specified parent folder. If no parent folder ID is specified, the folder created will be a top level folder (in the Home folder).

POST /api/managed_users/:managed_user_id/folders

# URL Parameters

Name Type Description
managed_user_id string
required
Embedded customer Account ID/External ID.
External ID must be prefixed with an E(eg: EA2300) and the resulting ID should be URL encoded.

# Payload

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

# Sample request

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

{
  "id": 3498583,
}

# Delete a folder

Delete a folder in a customer workspace.

WARNING

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

To use this endpoint, your API client role must have the following privilege:

  • Delete folder DELETE /api/managed_users/:managed_user_id/folders/:folder_id
DELETE /api/managed_users/:managed_user_id/folders/:folder_id

# URL parameters

Name Type Description
managed_user_id string
required
Embedded customer Account 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

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

# Response

# Successful response

{
    "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:

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

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

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

# Delete a project

Delete a project within your workspace. Projects are top level folders that normally encompass a single use case.

WARNING

This action deletes a project and all of its contents. This includes all child folders, recipes, connections, and Workflow apps assets (if applicable) inside the project.

To use this endpoint, your API client role must have the following privilege:

  • Delete project DELETE /api/managed_users/:managed_user_id/projects/:project_id
DELETE /api/managed_users/:managed_user_id/projects/:project_id

# URL parameters

Name Type Description
managed_user_id string
required
Embedded customer Account ID/External ID.
The External ID must be URL encoded and prefixed with an E (for example, EA2300).
project_id string
required
The ID of the project you plan to delete. Retrieve a list of all projects in your workspace by calling the list projects endpoint.

# Sample request

curl  -X DELETE 'https://www.workato.com/api/managed_users/:managed_user_id/projects/54321' \
      -H 'Authorization: Bearer <api_token>'

# Response

# Successful response

{
    "success": "true"
}

# Unsuccessful response

If you attempt to delete a project and do not have the appropriate privileges, Workato returns the following response.

{
    "message": "Cannot destroy folder"
}


Last updated: 2/13/2024, 1:10:22 AM