Product UpdatesStatus PageAutomation Institute
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.

# Quick reference

Type Resource Description
GET /api/managed_users/:managed_user_id/projects List projects in a customer workspace.
POST /api/managed_users/:managed_user_id/folders Create 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/properties List project-level properties by prefix and project ID.
POST /api/managed_users/:managed_user_id/properties Upsert project-level properties.
GET /api/managed_users/:managed_user_id/deployments Retrieve a list of deployments in a customer workspace.
GET /api/managed_users/:managed_user_id/deployments/:id Retrieve a single deployment in a customer workspace.
GET /api/managed_users/:managed_user_id/api/project_builds/:id Retrieve a downloaded package in a customer workspace.
POST /api/managed_users/:managed_user_id/projects/:id/build Build 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.

GET /api/managed_users/:managed_user_id/projects

# 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).

# Query parameters

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

# Sample request

curl  -X GET 'https://www.workato.com/api/managed_users/19029/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 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.

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

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).
project_id string
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

Name Type Description
name string
optional		 The new name for the project.
description string
optional		 The new description for the project.

PROJECT NAME

The project name cannot include the / or \ characters.

# Sample request

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

{
    "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
DELETE /api/managed_users/:managed_user_id/projects/:project_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).
project_id string
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

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

# Responses

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"
}

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

GET /api/managed_users/:managed_user_id/properties

# URL parameters

Name Type Description
managed_user_id string
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

Name Type Description
prefix string
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_id string
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

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

{
  "public_url": "https://www.example.com",
  "admin_email": "[email protected]"
}

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

POST /api/managed_users/:managed_user_id/properties

# URL parameters

Name Type Description
managed_user_id string
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

Name Type Description
project_id string
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

Name Type Description
properties Hash
required		 Contains the names and values of the properties you plan to upsert.

# Sample request

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": "[email protected]", "public_url": "https://www.example.com" }}'

# Response

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

GET /api/managed_users/:managed_user_id/deployments

# 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).

# Query parameters

Name Type Description
project_id string
optional		 Retrieves deployments associated with the specified project ID.
folder_id string
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_type string
optional		 An environment type. If provided, only deployments associated with the environment are included in the response. Accepted values include test or prod.
state string
optional		 Retrieves deployments by the specified state. Accepted values include pending, success, or failed.
from timestamp
optional		 Includes deployments created after the specified timestamp. Use the ISO 8601 format (for example, 2024-10-14T10:09:43Z).
to timestamp
optional		 Includes deployments created before the specified timestamp. Use the ISO 8601 format (for example, 2024-10-15T10:09:43Z).

# Sample request

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

# Response

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

GET /api/managed_users/:managed_user_id/deployments/: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).
id integer
required		 The unique identifier of the deployment you plan to retrieve.

# Sample request

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

# Response

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

GET /api/managed_users/:managed_user_id/api/project_builds/: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).
id integer
required		 The unique identifier of the downloaded package you plan to retrieve.

# Sample request

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

# Response

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

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

# 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).
id string
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

Name Type Description
description string
optional		 A brief description of the build.
include_test_cases boolean
optional		 Specifies whether to include test cases in the build.
include_tags boolean
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

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

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

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

# 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).
id integer
required		 The unique identifier of the downloaded package you plan to deploy.

# Payload

Name Type Description
environment_type string
required		 Specifies the environment where you plan to deploy the downloaded package. Accepted values include test and prod.
title string
optional		 A title for the deployment.
description string
optional		 A brief description of the deployment.
include_tags boolean
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

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

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

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

# 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).
project_id string
required		 The unique identifier of the project you plan to deploy. Use the List projects endpoint to retrieve project IDs in the workspace.

# Payload

Name Type Description
environment_type string
required		 Specifies the environment where you plan to deploy the project.
title string
required		 The title of the deployment.
description string
optional		 A brief description of the deployment.
include_tags boolean
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

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

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

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

# 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).
id integer
required		 The unique identifier of the deployment.

# Sample request

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

# Response

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

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

# 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).
id integer
required		 The unique identifier of the deployment.

# Payload

Name Type Description
reviewer_ids array of strings
required		 An array of user IDs to assign as reviewers for the deployment.

# Sample request

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

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

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

# 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).
id integer
required		 The unique identifier of the deployment to submit for review.

# Sample request

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

# Response

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

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

# 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).
id integer
required		 The unique identifier of the approved deployment to deploy.

# Payload

Name Type Description
include_tags boolean
optional		 Specify whether the deployment should include tags.

# Sample request

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

{
    "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"
        }
    ]
}
← Get picklist values
Recipes →


Last updated: 11/27/2024, 7:03:53 PM

On this page