Product UpdatesStatus PageWorkato Academy
English
日本語
Get a trial
Embedded API
Resources

Projects ​

Use the following endpoints to manage projects, project properties, and project deployments in a customer workspace programmatically.

PRIVATE BETA

The following endpoints are in private beta:

Private beta features are available in production but only to selected customers. Customers must opt in and be accepted into the beta.

During the private beta, Workato may update its functionality or change its availability without prior notice.

Rate limits ​

Project resources have the following rate limits:

Quick reference ​

TypeResourceDescription
GET/api/managed_users/:managed_user_id/projectsList projects in a customer workspace.
POST/api/managed_users/:managed_user_id/foldersCreate a project in a customer workspace.
PUT/api/managed_users/:managed_user_id/projects/
:project_id		Update a project in a customer workspace.
DELETE/api/managed_users/:managed_user_id/projects/
:project_id		Delete a project in a customer workspace.
GET/api/managed_users/:managed_user_id/propertiesList project-level properties by prefix and project ID.
POST/api/managed_users/:managed_user_id/propertiesUpsert project-level properties.
GET/api/managed_users/:managed_user_id/deploymentsRetrieve a list of deployments in a customer workspace.
GET/api/managed_users/:managed_user_id/deployments/:idRetrieve a single deployment in a customer workspace.
GET/api/managed_users/:managed_user_id/api/project_builds/:idRetrieve a downloaded package in a customer workspace.
POST/api/managed_users/:managed_user_id/projects/:id/buildBuild a project in a customer workspace.
POST/api/managed_users/:managed_user_id/project_builds/:id/
deploy		Deploy a downloaded package in a customer workspace.
POST/api/managed_users/:managed_user_id/projects/:project_id/
deploy		Deploy a project in a customer workspace.
GET/api/managed_users/:managed_user_id/deployments/:id/
eligible_reviewers		Retrieve a list of eligible reviewers that can be assigned to review a deployment in a customer workspace.
POST/api/managed_users/:managed_user_id/deployments/:id/
assign_reviewers		Assign reviewers to a deployment in a customer workspace.
POST/api/managed_users/:managed_user_id/deployments/:id/
submit_for_review		Submit a deployment for review in a customer workspace.
POST/api/managed_users/:managed_user_id/deployments/:id/
deploy		Deploy an approved deployment in a customer workspace.

List projects ​

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

shell
GET /api/managed_users/:managed_user_id/projects

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID.
The External ID must be URL encoded and prefixed with an E (for example, EA2300).

Query parameters ​

NameTypeDescription
pageinteger
optional		Page number. Defaults to 1.
per_pageinteger
optional		Page size. Defaults to 100. The maximum is 100.
updated_afterstring
optional		Filter the list of projects 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/19029/projects' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \

Response ​

json
{
    "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"
        }
    ],
    "count": 2,
    "page": 1,
    "per_page": 100
}

Create a project ​

To create a project within a customer workspace, use the Create a folder endpoint and omit the parent_id from the request payload.

Update a project ​

Update a project within a customer workspace. Projects are top-level folders that typically encompass a single use case. Use this endpoint to modify a project's name and/or description.

shell
PUT /api/managed_users/:managed_user_id/projects/:project_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 ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID.
The External ID must be URL encoded and prefixed with an E (for example, EA2300).
project_idstring
required		The ID of the project you plan to update. This is distinct from the project's folder_id. Retrieve a list of projects in the customer workspace by calling the List projects endpoint.

Payload ​

NameTypeDescription
namestring
optional		The new name for the project.
descriptionstring
optional		The new description for the project.

PROJECT NAME

The project name cannot include the / or \ characters.

Sample request ​

shell
curl  -X PUT https://www.workato.com/api/managed_users/19029/projects/54321 \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "My updated project name",
            "description": "My updated project description"
          }'

Responses ​

Successful response
json
{
    "id": 54321,
    "description": "My updated project description",
    "folder_id": 09876,
    "name": "My updated project name"
}
Unsuccessful response

Attempting to update your project name to include the / or \ character returns the following error:

json
{
    "message": "Name is invalid"
}

Delete a project ​

Delete a project within the customer workspace. Projects are top-level folders that typically encompass a single use case.

PROJECT DELETION INCLUDES ASSETS

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
shell
DELETE /api/managed_users/:managed_user_id/projects/:project_id

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID.
The External ID must be URL encoded and prefixed with an E (for example, EA2300).
project_idstring
required		The ID of the project you plan to delete. Retrieve a list of all projects in the customer workspace by calling the List projects endpoint.

Sample request ​

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

Responses ​

Successful response
json
{
    "success": "true"
}
Unsuccessful response

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

json
{
    "message": "Cannot destroy folder"
}

List project properties ​

Returns a list of project-level properties belonging to a specific project in a customer workspace that matches a project_id you specify. You must also include a prefix. For example, if you provide the prefix salesforce_sync., any project property with a name beginning with salesforce_sync., such as salesforce_sync.admin_email, with the project_id you provided is returned.

shell
GET /api/managed_users/:managed_user_id/properties

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID.
The external ID must be prefixed with an E (example: EA2300) and the resulting ID should be URL encoded.

Query parameters ​

NameTypeDescription
prefixstring
required		Returns properties that contain the prefix you provided. For example, if the prefix is salesforce_sync. the property salesforce_sync.admin_email is returned.
project_idstring
required		Returns project-level properties that match the project_id you specify. If this parameter is not present, this call returns environment properties.

Sample request ​

shell
curl  -X GET 'https://www.workato.com/api/managed_users/19029/properties?prefix=salesforce_sync.&project_id=523144' \
      -H 'Authorization: Bearer <token>' \
      -H 'Content-Type: application/json'

Response ​

json
{
  "public_url": "https://www.example.com",
  "admin_email": "jude.feeney@example.com"
}

Upsert project properties ​

Upserts project properties belonging to a specific project in a customer workspace that matches a project_id you specify. This endpoint maps to properties based on the names you provide in the request.

shell
POST /api/managed_users/:managed_user_id/properties

PROPERTY LIMITS

Project properties have the following limits:

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID.
The external ID must be prefixed with an E (example: EA2300) and the resulting ID should be URL encoded.

Query parameters ​

NameTypeDescription
project_idstring
required		Provide the project ID that contains the project properties you plan to upsert. If this parameter is not present, this call upserts environment properties.

Payload ​

NameTypeDescription
propertiesHash
required		Contains the names and values of the properties you plan to upsert.

Sample request ​

shell
curl  -X POST 'https://www.workato.com/api/managed_users/19029/properties?project_id=523144' \
      -H 'Authorization: Bearer <token>' \
      -H 'Content-Type: application/json' \
      -d '{ "properties": { "admin_email": "lucy.carrigan@example.com", "public_url": "https://www.example.com" }}'

Response ​

json
{
  "success": true
}

List deployments ​

Retrieves a list of deployments in a customer workspace. Use query parameters to filter results by project, folder, or date range.

shell
GET /api/managed_users/:managed_user_id/deployments

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300).

Query parameters ​

NameTypeDescription
project_idstring
optional		Retrieves deployments associated with the specified project ID.
folder_idstring
optional		A folder ID, formatted as f{:folder_id}. For example, f660222. If provided, only deployments associated with the folder are included in the response. Use the List folders endpoint to retrieve these IDs.
environment_typestring
optional		An environment type. If provided, only deployments associated with the environment are included in the response. Accepted values include test or prod.
statestring
optional		Retrieves deployments by the specified state. Accepted values include pending, success, or failed.
fromtimestamp
optional		Includes deployments created after the specified timestamp. Use the ISO 8601 format (for example, 2024-10-14T10:09:43Z).
totimestamp
optional		Includes deployments created before the specified timestamp. Use the ISO 8601 format (for example, 2024-10-15T10:09:43Z).

Sample request ​

shell
curl  -X GET 'https://www.workato.com/api/managed_users/12345/deployments' \
      -H 'Authorization: Bearer <token>' \

Response ​

json
{
    "items": [
        {
            "id": 6409,
            "created_at": "2024-10-14T10:09:43.890-07:00",
            "updated_at": "2024-10-14T10:10:15.370-07:00",
            "title": "Deployment",
            "description": "",
            "project_build_id": 9120,
            "environment_type": "test",
            "project_id": "39334",
            "state": "success",
            "detailed_state": "deploy_finished",
            "performed_by_name": "Alex",
            "assets": [
                {
                    "id": null,
                    "name": "My Salesforce account",
                    "type": "connection",
                    "state": "new",
                    "folder": "Sample deployment"
                },
                {
                    "id": null,
                    "name": "My Zendesk account",
                    "type": "connection",
                    "state": "new",
                    "folder": "Sample deployment"
                },        
                {
                    "id": null,
                    "name": "New Salesforce account will create Zendesk organization",
                    "type": "recipe",
                    "folder": "Sample deployment"
                },
            ],
            "review_state": "review_approved",  
            "reviews": [  
                {
                    "status": "approved",
                    "comment": "LGTM!",
                    "reviewer_name": "Alex"
                }
            ]
        }
        ...
    ]
}

Get a deployment ​

Retrieves a single deployment in a customer workspace by its unique ID.

shell
GET /api/managed_users/:managed_user_id/deployments/:id

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300).
idinteger
required		The unique identifier of the deployment you plan to retrieve.

Sample request ​

shell
curl  -X GET https://www.workato.com/api/managed_users/12345/deployments/6409 \
      -H 'Authorization: Bearer <api_token>'

Response ​

json
{
    "id": 6409,
    "created_at": "2024-10-14T10:09:43.890-07:00",
    "updated_at": "2024-10-14T10:10:15.370-07:00",
    "title": "Deployment",
    "description": "",
    "project_build_id": 9120,
    "environment_type": "test",
    "project_id": "39334",
    "state": "success",
    "detailed_state": "deploy_finished",
    "performed_by_name": "Alex",
    "assets": [
        {
            "id": null,
            "name": "My Salesforce account",
            "type": "connection",
            "state": "new",
            "folder": "Sample deployment"
        },
        {
            "id": null,
            "name": "My Zendesk account",
            "type": "connection",
            "state": "new",
            "folder": "Sample deployment"
        },        
        {
            "id": null,
            "name": "New Salesforce account will create Zendesk organization",
            "type": "recipe",
            "folder": "Sample deployment"
        },
    ],
    "review_state": "review_approved",  
    "reviews": [  
        {
            "status": "approved",
            "comment": "LGTM!",
            "reviewer_name": "Alex"
        }
    ]
}

Get a downloaded package ​

Retrieves a downloaded package in a customer workspace by its unique ID.

shell
GET /api/managed_users/:managed_user_id/api/project_builds/:id

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300).
idinteger
required		The unique identifier of the downloaded package you plan to retrieve.

Sample request ​

shell
curl  -X GET https://www.workato.com/api/managed_users/12345/project_builds/72 \
      -H 'Authorization: Bearer <api_token>'

Response ​

json
{
    "id": 72,
    "created_at": "2021-12-10T11:39:15.738-08:00",
    "updated_at": "2021-12-10T11:39:16.218-08:00",
    "description": null,
    "project_id": "10416",
    "state": "success",
    "performed_by_name": "Alex",
    "download_url": "https://workato-assets.s3.us-west-2.amazonaws.com/packages/zip_files/000/714/699/original/<PROJECT_NAME_DATE>.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<CREDENTIAL>"
}

Build a project ​

Builds a project in a customer workspace. After building, use the Deploy a downloaded package endpoint to deploy the project to an environment.

shell
POST /api/managed_users/:managed_user_id/projects/:id/build

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300).
idstring
required		The ID of the project you plan to build. Accepts a valid project_id or a valid folder_id, formatted as f{:folder_id} (for example, f660222).

Payload ​

NameTypeDescription
descriptionstring
optional		A brief description of the build.
include_test_casesboolean
optional		Specifies whether to include test cases in the build.
include_tagsboolean
optional		Specifies whether to include tags assigned to assets in the build. Tags are excluded from the build when set to false. Set to false by default.

Sample request ​

shell
curl  -X POST https://www.workato.com/api/managed_users/12345/projects/10416/build \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "description": "Fixes bugs",
            "include_tags": true
          }'

Response ​

json
{
    "id": 9121,
    "created_at": "2024-10-14T14:37:29.877-07:00",
    "updated_at": "2024-10-14T14:37:29.885-07:00",
    "description": "Fixes bugs",
    "project_id": "10416",
    "state": "pending",
    "performed_by_name": "Alex",
    "download_url": null
}

Deploy a downloaded package ​

Deploys a downloaded package in a customer workspace to an environment. Use the Build a project endpoint to build the project before deploying it.

shell
POST /api/managed_users/:managed_user_id/project_builds/:id/deploy

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300).
idinteger
required		The unique identifier of the downloaded package you plan to deploy.

Payload ​

NameTypeDescription
environment_typestring
required		Specifies the environment where you plan to deploy the downloaded package. Accepted values include test and prod.
titlestring
optional		A title for the deployment.
descriptionstring
optional		A brief description of the deployment.
include_tagsboolean
optional		Specifies whether to include tags assigned to assets in the deployed package. Tags exist at the workspace level but are not applied to assets in the target environment when set to false. This is set to false by default.

Sample request ​

shell
curl  -X POST https://www.workato.com/api/managed_users/12345/project_builds/9121 \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "environment_type": "test",
            "include_tags": true
          }'

Response ​

json
{
    "id": 67,
    "created_at": "2021-12-10T11:59:03.426-08:00",
    "updated_at": "2021-12-10T11:59:03.426-08:00",
    "title": null,
    "description": null,
    "project_build_id": 9121,
    "environment_type": "test",
    "project_id": "10416",
    "state": "pending",
    "performed_by_name": "Alex",
    "assets": null
}

Deploy a project ​

Deploys a project in a customer workspace. Specify the target environment in the payload. Projects can only be deployed from the DEV environment.

shell
POST /api/managed_users/:managed_user_id/projects/:project_id/deploy

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300).
project_idstring
required		The unique identifier of the project you plan to deploy. Use the List projects endpoint to retrieve project IDs in the workspace.

Payload ​

NameTypeDescription
environment_typestring
required		Specifies the environment where you plan to deploy the project.
titlestring
required		The title of the deployment.
descriptionstring
optional		A brief description of the deployment.
include_tagsboolean
optional		Specifies whether to include tags assigned to assets in the deployment. Tags exist at the workspace level but are not applied to assets in the target environment when set to false. This is set to false by default.

Sample request ​

shell
curl  -X POST 'https://www.workato.com/api/managed_users/19029/projects/35263/deploy' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "environment_type": "test",
            "title": "My deployment",
            "description": "Description of my deployment",
            "include_tags": true
          }'

Sample response ​

json
{
    "id": 3905,
    "created_at": "2024-03-10T13:08:53.344-08:00",
    "updated_at": "2024-03-10T13:08:53.344-08:00",
    "title": "My deployment",
    "description": "Description of my deployment",
    "project_build_id": 6544,
    "environment_type": "test",
    "project_id": "35263",
    "state": "pending",
    "performed_by_name": "Barnaby",
    "assets": null
}

List eligible reviewers for a deployment ​

Retrieve a list of eligible reviewers that can be assigned to review a deployment in a customer workspace. Reviewers must be collaborators with review permissions in both the DEV environment and the target deployment environment. The Require review and approval toggle must be enabled in Workspace admin > Settings > Deployments to access this endpoint.

shell
GET /api/managed_users/:managed_user_id/deployments/:id/eligible_reviewers

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300).
idinteger
required		The unique identifier of the deployment.

Sample request ​

shell
curl  -X GET https://www.workato.com/api/managed_users/12345/deployments/6390/eligible_reviewers \
      -H 'Authorization: Bearer <api_token>'

Response ​

json
{
    "reviewers": [
        {
            "id": 29036,
            "name": "Jie",
            "avatar_url": ""
        },
        {
            "id": 30143,
            "name": "Alex",
            "avatar_url": ""
        },
        {
            "id": 31836,
            "name": "Charlie",
            "avatar_url": ""
        }
    ]
}

Assign reviewers to a deployment ​

Assigns reviewers to a deployment in a customer workspace. You can assign reviewers either before or after submitting the deployment for review. The Require review and approval toggle must be enabled in Workspace admin > Settings > Deployments to access this endpoint.

This endpoint can also be used to unassign reviewers. To unassign a reviewer, call the endpoint again and provide only the IDs of the users who should remain assigned to the deployment. Unassigning a reviewer removes their review from the deployment.

shell
POST /api/managed_users/:managed_user_id/deployments/:id/assign_reviewers

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300).
idinteger
required		The unique identifier of the deployment.

Payload ​

NameTypeDescription
reviewer_idsarray of strings
required		An array of user IDs to assign as reviewers for the deployment.

Sample request ​

shell
curl  -X POST https://www.workato.com/api/managed_users/12345/deployments/6390/assign_reviewers \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "reviewer_ids": ["29036", "30143", "31836"]
          }'

Response ​

json
{
    "reviews": [
        {
            "deployment_id": 6390,
            "reviewer_id": 29036,
            "status": "pending",
            "comment": "",
            "updated_at": "2024-10-11T10:54:26.075-07:00"
        },
        {
            "deployment_id": 6390,
            "reviewer_id": 30143,
            "status": "pending",
            "comment": "",
            "updated_at": "2024-10-11T10:31:07.047-07:00"
        },
        {
            "deployment_id": 6390,
            "reviewer_id": 31836,
            "status": "pending",
            "comment": "",
            "updated_at": "2024-10-11T10:54:26.099-07:00"
        }
    ],
    "authors": [
        {
            "id": 29036,
            "name": "Jie",
            "avatar_url": ""
        },
        {
            "id": 30143,
            "name": "Alex",
            "avatar_url": ""
        },
        {
            "id": 31836,
            "name": "Charlie",
            "avatar_url": ""
        }
    ]
}

Submit a deployment for review ​

Submits a deployment in a customer workspace for review. Before calling this endpoint, use the Build a project and Deploy a downloaded package endpoints to generate and retrieve the deployment ID. The Require review and approval toggle must be enabled in Workspace admin > Settings > Deployments to access this endpoint.

shell
POST /api/managed_users/:managed_user_id/deployments/:id/submit_for_review

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300).
idinteger
required		The unique identifier of the deployment to submit for review.

Sample request ​

shell
curl  -X POST https://www.workato.com/api/managed_users/12345/deployments/6390/submit_for_review \
      -H 'Authorization: Bearer <api_token>'

Response ​

json
{
    "success": true
}

REVIEW ACTIONS IN A CUSTOMER WORKSPACE

To accept, reject, or reset a review in a customer workspace, the Embedded customer must take action either through the UI or by using the Developer API endpoints. The Embedded partner can't perform these actions through the Embedded API.

Deploy an approved deployment ​

Deploys an approved deployment in a customer workspace. The Require review and approval toggle must be enabled in Workspace admin > Settings > Deployments to access this endpoint.

shell
POST /api/managed_users/:managed_user_id/deployments/:id/deploy

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300).
idinteger
required		The unique identifier of the approved deployment to deploy.

Payload ​

NameTypeDescription
include_tagsboolean
optional		Specify whether the deployment should include tags.

Sample request ​

shell
curl  -X POST https://www.workato.com/api/managed_users/12345/deployments/6390/deploy \
      -H 'Authorization: Bearer <api_token>'
      -H 'Content-Type: application/json' \
      -d '{
            "include_tags": true
          }'

Response ​

json
{
    "id": 6390,
    "created_at": "2024-10-11T13:16:58.170-07:00",
    "updated_at": "2024-10-11T13:47:31.254-07:00",
    "title": "",
    "description": "",
    "project_build_id": 9104,
    "environment_type": "test",
    "project_id": "44946",
    "state": "pending",
    "detailed_state": "deploy_started",
    "performed_by_name": "Alex",
    "assets": [
        {
            "id": null,
            "name": "My Salesforce account",
            "type": "connection",
            "state": "new",
            "folder": "Sample deployment"
        },
        {
            "id": null,
            "name": "My Zendesk account",
            "type": "connection",
            "state": "new",
            "folder": "Sample deployment"
        },        
        {
            "id": null,
            "name": "New Salesforce account will create Zendesk organization",
            "type": "recipe",
            "folder": "Sample deployment"
        },
    ],
    "review_state": "review_approved",
    "reviews": [
        {
            "status": "approved",
            "comment": "Looks good!",
            "reviewer_name": "Jie"
        }
    ]
}

Last updated: