Product UpdatesStatus PageAutomation Institute
English
Get a trial
Developer API
Resources

# Projects

WHO CAN USE THESE APIS?

Accounts with the Environments feature enabled can use the APIs in this guide. Requests sent from accounts without this feature will receive a 400 - Environments not provisioned response.

In Workato, projects are used to organize automation assets and control access. A project holds a set of related assets for your automations, including connections, recipes, and subfolders.

The Project APIs enable you to programmatically manage and deploy projects to the environments provisioned in your workspace.

# Understanding project deployment

In Workato, there are two ways to deploy projects:

  • Build and then deploy. This approach can be used if you want to commit the package to an external version control system. Steps for accomplishing this would be similar to the following:

    1

    Build the project: POST /api/projects/:id/build

    2

    Verify the project built successfully: GET /api/project_builds/:id

    3

    If committing to a version control system like GitHub, use the download_url from Step 2's response to download the package.

    4

    Commit the package to your version control system.

    5

    Deploy the project build to an environment: POST /api/project_builds/:id/deploy?environment_type=:environment_type

    6

    Verify the project deployed successfully: GET /api/deployments/:id

  • Build and deploy in one step. If you don't need to commit the project to a version control system, you can use this approach:

    1

    Build and deploy the project to an environment: POST /api/projects/:id/deploy?environment_type=:environment_type

    2

    Verify the project deployed successfully: GET /api/deployments/:id

# Quick reference

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.

Type Resource Description
POST /api/projects/:id/build Builds a project. Use the Deploy a project build endpoint to deploy the project to an environment.
GET /api/project_builds/:id Retrieves a project build by its unique ID.
POST /api/project_builds/:id/deploy?environment_type=:environment_type Deploys a project build to an environment. Use the Build a project endpoint to build the project first.
POST /api/projects/:id/deploy?environment_type=:environment_type Builds and deploys a project to an environment.
GET /api/deployments/:id Retrieves a single deployment by its unique ID.
GET /api/deployments Retrieves a list of deployments. Use query parameters to filter results by project, folder, or date range.
GET /api/deployments/:id/eligible_reviewers Retrieves a list of eligible reviewers that can be assigned to review a deployment.
POST /api/deployments/:id/assign_reviewers Assigns reviewers to a deployment.
POST /api/deployments/:id/submit_for_review Submits a deployment for review.
POST /api/deployments/:id/approve Approves a deployment.
POST /api/deployments/:id/reject Rejects a deployment.
POST /api/deployments/:id/reopen Re-opens a deployment for review.
POST /api/deployments/:id/update_review_comment Updates a deployment review comment.
POST /api/deployments/:id/deploy Deploys an approved deployment.

# Build a project

Builds a project. Use the Deploy a project build endpoint to deploy the project to an environment. 

POST /api/projects/:id/build

# Request

# URL parameters

Name Type Description
id integer
required		 A project ID. This parameter accepts the following:
  • A valid project_id
  • A valid folder_id, formatted as f{:folder_id}. For example: f660222. Use the List folders endpoint to retrieve these IDs.

# Request body arguments

Name Type Description
description string
optional		 A brief description of the build.
include_test_cases boolean
optional		 Instructs the build to include test cases or not.

# Request examples

# Using a project ID

curl  -X POST https://www.workato.com/api/projects/10416/build \
      -H 'Authorization: Bearer <api_token>' \
      -d '{
            "description": "Fixes bugs"
          }'

# Using a folder ID

curl  -X POST https://www.workato.com/api/projects/f660222/build \
      -H 'Authorization: Bearer <api_token>' \
      -d '{
            "description": "Fixes bugs"
          }'

# Responses

200 OK

If successful, the API will return a 200 OK status and a single project build object.

{
    "id": 46,
    "created_at": "2021-12-09T22:09:29.997-08:00",
    "updated_at": "2021-12-09T22:09:30.004-08:00",
    "description": "Fixes bugs",
    "project_id": "10416",
    "state": "pending",
    "performed_by_name": "Finn the Human",
    "download_url": null
}
Name Type Description
id integer The build ID.
created_at timestamp The time the build was created.
updated_at timestamp The time the build was last updated.
description string The build description. This is null if not provided in the request.
include_test_cases boolean Whether the build includes test cases or not. This is null if not provided in the request.
project_build_id integer The ID of the project build associated with the build.
project_id string The ID of the project that was built.
state string The current state of the build.
performed_by_name string The name of the user who built the project.
download_url string A URL from which the project build can be downloaded.

400 BAD REQUEST - MISSING REQUIRED PARAMETERS

The API may return a 400 BAD REQUEST status and the following errors if the request is malformed:

Missing environment_type parameter:

{
   "message": "Missing parameter environment_type"
}

404 NOT FOUND - INVALID PARAMETERS

The API may return a 404 NOT FOUND status and a Not found error for the following reasons:

  • Invalid id
  • Invalid environment_type

    • 404 NOT FOUND - INVALID URI

    The API may return a 404 NOT FOUND status and an API not found error for the following reasons:

    • Unsupported method
  • Incorrect URI

    • # Get a project build

    Retrieves a project build by its unique ID.

    GET /api/project_builds/:id

    # Request

    # URL parameters

    Name Type Description
    id integer
    required    		 The ID of the project build to retrieve.

    # Request examples

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

    # Responses

    200 OK

    If successful, the API will return a 200 OK status and a single project build object.

    {
    "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": "Erin Cochran",
    "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>"
}
    Name Type Description
    id integer The build ID.
    created_at timestamp The time the build was created.
    updated_at timestamp The time the build was last updated.
    description string The build description. This will be null if not provided in the request that created the build.
    project_id string The ID of the project that was built.
    state string The current state of the build.
    performed_by_name string The name of the user who built the project.
    download_url string A URL from which the project build can be downloaded.
    404 NOT FOUND - INVALID PARAMETERS

    The API may return a 404 NOT FOUND status and a Not found error for the following reasons:

    • Invalid project build id

    404 NOT FOUND - INVALID URI

    The API may return a 404 NOT FOUND status and an API not found error for the following reasons:

    • Unsupported method
  • Incorrect URI

    • # Deploy a project build

    Deploys a project build to an environment. Use the Build a project endpoint to build the project first. 

    POST /api/project_builds/:id/deploy?environment_type=:environment_type

    # Request

    # URL parameters

    Name Type Description
    id integer
    required    		 The ID of the build to be deployed.

    # Query parameters

    Name Type Description
    environment_type string
    required    		 The environment the build will be deployed to. Accepted values:
    • test
    • prod

    # Request body arguments

    Name Type Description
    description string
    optional    		 A brief description of the build.

    # Request example

    curl  -X POST https://www.workato.com/api/project_builds/46/deploy?environment_type=test \
      -H 'Authorization: Bearer <api_token>'

    # Responses

    200 OK

    If successful, the API will return a 200 OK status and a single deployment object.

    {
    "id": 67,
    "created_at": "2021-12-10T11:59:03.426-08:00",
    "updated_at": "2021-12-10T11:59:03.426-08:00",
    "description": null,
    "project_build_id": 46,
    "environment_type": "test",
    "project_id": "10416",
    "state": "pending",
    "performed_by_name": "Finn the Human"
}
    Name Type Description
    id integer The deployment ID.
    created_at timestamp The time the deployment was created.
    updated_at timestamp The time the deployment was last updated.
    description string The deployment description. This will be null if not provided in the request.
    project_build_id integer The ID of the project build associated with the deployment.
    environment_type string The environment the build was deployed to.
    project_id string The ID of the project associated with the deployed build.
    state string The current state of the deployment.
    performed_by_name string The name of the user who deployed the build.

    400 BAD REQUEST - MISSING REQUIRED PARAMETERS

    The API may return a 400 BAD REQUEST status and the following errors if the request is malformed:

    Missing environment_type parameter:

    {
   "message": "Missing parameter environment_type"
}

    404 NOT FOUND - INVALID PARAMETERS

    The API may return a 404 NOT FOUND status and a Not found error for the following reasons:

    • Invalid id
  • Invalid environment_type

    • 404 NOT FOUND - INVALID URI

    The API may return a 404 NOT FOUND status and an API not found error for the following reasons:

    • Unsupported method
  • Incorrect URI

    • # Deploy a project

    Builds and deploys a project to an environment. 

    POST /api/projects/:id/deploy?environment_type=:environment_type

    # Request

    # URL parameters

    Name Type Description
    id integer
    required    		 A project ID. This parameter accepts the following:
    • A valid project_id
    • A valid folder_id, formatted as f{:folder_id}. For example: f660222. Use the List folders endpoint to retrieve these IDs.

    # Query parameters

    Name Type Description
    environment_type string
    required    		 The environment the project will be deployed to. Accepted values:
    • test
    • prod

    # Request body arguments

    Name Type Description
    description string
    optional    		 A brief description of the deployment.

    # Request examples

    # Using a project ID
    curl  -X POST https://www.workato.com/api/projects/10416/deploy?environment_type=test \
      -H 'Authorization: Bearer <api_token>'
    # Using a folder ID
    curl  -X POST https://www.workato.com/api/projects/f660222/deploy?environment_type=test \
      -H 'Authorization: Bearer <api_token>'

    # Responses

    200 OK

    If successful, the API will return a 200 OK status and a single deployment object.

    {
    "id": 47,
    "created_at": "2021-12-09T22:37:30.025-08:00",
    "updated_at": "2021-12-09T22:37:30.025-08:00",
    "description": null,
    "project_build_id": 52,
    "environment_type": "test",
    "project_id": "10416",
    "state": "pending",
    "performed_by_name": "Finn the Human"
}
    Name Type Description
    id integer The deployment ID.
    created_at timestamp The time the deployment was created.
    updated_at timestamp The time the deployment was last updated.
    description string The deployment description. This will be null if not provided in the request.
    project_build_id integer The ID of the project build associated with the deployment.
    environment_type string The environment the project was deployed to.
    project_id string The ID of the project that was deployed.
    state string The current state of the deployment.
    performed_by_name string The name of the user who deployed the project.

    400 BAD REQUEST - MISSING REQUIRED PARAMETERS

    The API may return a 400 BAD REQUEST status and the following errors if the request is malformed:

    Missing environment_type parameter:

    {
   "message": "Missing parameter environment_type"
}

    404 NOT FOUND - INVALID PARAMETERS

    The API may return a 404 NOT FOUND status and a Not found error for the following reasons:

    • Invalid id
  • Invalid environment_type

    • 404 NOT FOUND - INVALID URI

    The API may return a 404 NOT FOUND status and an API not found error for the following reasons:

    • Unsupported method
  • Incorrect URI

    • # Get a deployment

    Retrieves a single deployment by its unique ID.

    GET /api/deployments/:id

    # Request

    # URL parameters

    Name Type Description
    id integer
    required    		 The ID of the deployment to be retrieved.

    # Request example

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

    # Responses

    200 OK

    If successful, the API will return a 200 OK status and a single deployment object.

    {
    // Fields related to reviews and approvals (for example, review_state, reviews, status, comment, reviewer_name) 
    // are returned only when reviews and approvals are enabled.
    "id": 43,
    "created_at": "2024-10-15T12:28:40.779-07:00",
    "updated_at": "2024-10-15T12:29:21.292-07:00",
    "title": "Sample deployment",
    "description": "",
    "project_build_id": 46,
    "environment_type": "test",
    "project_id": "10416",
    "state": "success",
    "detailed_state": "deploy_finished",
    "performed_by_name": "Charlie",
    "review_state": "review_approved",  
    "reviews": [  
        {
            "status": "approved",
            "comment": "LGTM!",
            "reviewer_name": "Alex"
        }
    ]
}
    Name Type Description
    id integer The deployment ID.
    created_at timestamp The time the deployment was created.
    updated_at timestamp The time the deployment was last updated.
    description string The deployment description. This will be null if not provided in the request that created the deployment.
    project_build_id integer The ID of the project build associated with the deployment.
    environment_type string The environment associated with the deployment.
    project_id string The ID of the project associated with the deployment.
    state string The current state of the deployment.
    performed_by_name string The name of the user who performed the deployment.
    404 NOT FOUND - INVALID PARAMETERS

    The API may return a 404 NOT FOUND status and a Not found error for the following reasons:

    • Invalid deployment_id

    404 NOT FOUND - INVALID PARAMETERS

    The API may return a 404 NOT FOUND status and a Not found error for the following reasons:

    • Invalid id
  • Invalid environment_type

    • 404 NOT FOUND - INVALID URI

    The API may return a 404 NOT FOUND status and an API not found error for the following reasons:

    • Unsupported method
  • Incorrect URI

    • # List deployments

    Retrieves a list of deployments. Query parameters may be used to filter results to a specific project, folder, date range, etc. 

    GET /api/deployments

    # Request

    # Query parameters

    Name Type Description
    project_id string
    optional    		 A project ID. If provided, only deployments associated with the project will be included in the response.
    folder_id string
    optional    		 A folder ID, formatted as f{:folder_id}. For example: f660222. If provided, only deployments associated with the folder will be 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 will be included in the response. Must be one of:
    • test
    • prod
    state string
    optional    		 The state of the deployments to retrieve. If provided, only deployments with the provided state will be included in the response. Must be one of:
    • pending
    • success
    • failed
    from timestamp
    optional    		 Deployments created after this time will be included in the response. The value must be an ISO 8601 timestamp.
    to timestamp
    optional    		 Deployments created after this time will be included in the response. The value must be an ISO 8601 timestamp.

    # Request examples

    # Without query parameters
    curl  -X GET https://www.workato.com/api/deployments \
      -H 'Authorization: Bearer <api_token>'
    # With a folder ID
    curl  -X GET https://www.workato.com/api/deployments?folder_id=f660222 \
      -H 'Authorization: Bearer <api_token>'

    # Responses

    200 OK

    If successful, the API will return a 200 OK status and a list of deployment objects.

    {
  // Fields related to reviews and approvals (for example, review_state, reviews, status, comment, reviewer_name) 
  // are returned only when reviews and approvals are enabled.
  "items": [
      {
          "id": 43,
          "created_at": "2024-10-15T12:28:40.779-07:00",
          "updated_at": "2024-10-15T12:29:21.292-07:00",
          "title": "Sample deployment",
          "description": "",
          "project_build_id": 46,
          "environment_type": "test",
          "project_id": "10416",
          "state": "success",
          "detailed_state": "deploy_finished",
          "performed_by_name": "Charlie",
          "review_state": "review_approved",    
          "reviews": [                          
              {
                  "status": "approved",         
                  "comment": "LGTM!",           
                  "reviewer_name": "Alex"       
              }
          ]
      },
      {
          "id": 42,
          "created_at": "2024-10-14T12:28:40.779-07:00",
          "updated_at": "2024-10-14T12:29:21.292-07:00",
          "title": "",
          "description": "",
          "project_build_id": 45,
          "environment_type": "test",
          "project_id": "10416",
          "state": "pending",
          "detailed_state": "pending_review",
          "performed_by_name": "Charlie",
          "review_state": "pending_review",     
          "reviews": [                          
              {
                  "status": "pending",          
                  "comment": null,              
                  "reviewer_name": "Alex"       
              }
          ]
      },
  ]
}
    Name Type Description
    items array A list of deployment objects.
    id integer The deployment ID.
    created_at timestamp The time the deployment was created.
    updated_at timestamp The time the deployment was last updated.
    title string The title of the deployment.
    description string The deployment description. This will be null if not provided in the request that created the deployment.
    project_build_id integer The ID of the project build associated with the deployment.
    environment_type string The environment associated with the deployment.
    project_id string The ID of the project associated with the deployment.
    state string The current state of the deployment.
    detailed_state string Additional details about the current state of the deployment.
    review_state string The state of the review. Possible values include pending_review, review_approved, and review_rejected.
    reviews array of objects An array of objects that represent reviews for the deployment.
    status string The status of a specific review. Possible values include pending, approved, or rejected.
    comment string The comment left by the reviewer, if available.
    reviewer_name string The name of the reviewer.
    performed_by_name string The name of the user who performed the deployment.

    404 NOT FOUND - INVALID URI

    The API may return a 404 NOT FOUND status and an API not found error for the following reasons:

    • Unsupported method
  • Incorrect URI

    • # List eligible reviewers for a deployment

    Retrieves a list of eligible reviewers that can be assigned to review a deployment. 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/deployments/:id/eligible_reviewers

    # URL parameters

    Name Type Description
    id integer
    required    		 The unique identifier of the deployment for which you plan to retrieve eligible reviewers.

    # Sample request

    curl  -X GET https://www.workato.com/api/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. 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/deployments/:id/assign_reviewers

    # URL parameters

    Name Type Description
    id integer
    required    		 The unique identifier of the deployment where you plan to assign reviewers.

    # 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/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 for review. Before calling this endpoint, use the Build a project and Deploy a project build 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/deployments/:id/submit_for_review

    # URL parameters

    Name Type Description
    id integer
    required    		 The unique identifier of the deployment to submit for review.

    # Sample request

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

    # Response

    {
    "success": true
}

    # Approve a deployment

    Approves a deployment. The Require review and approval toggle must be enabled in Workspace admin > Settings > Deployments to access this endpoint.

    POST /api/deployments/:id/approve

    # URL parameters

    Name Type Description
    id integer
    required    		 The unique identifier of the deployment to approve.

    # Payload

    Name Type Description
    comment string
    required    		 A comment explaining the approval decision.

    # Sample request

    curl  -X POST https://www.workato.com/api/deployments/6390/approve \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "comment": "Looks good!"
          }'

    # Response

    {
    "review": {
        "deployment_id": 6390,
        "reviewer_id": 29036,
        "status": "approved",
        "comment": "Looks good!",
        "updated_at": "2024-10-11T13:39:22.857-07:00"
    }
}

    # Reject a deployment

    Rejects a deployment. The Require review and approval toggle must be enabled in Workspace admin > Settings > Deployments to access this endpoint.

    POST /api/deployments/:id/reject

    # URL parameters

    Name Type Description
    id integer
    required    		 The unique identifier of the deployment to reject.

    # Payload

    Name Type Description
    comment string
    required    		 A comment explaining the reason for rejection.

    # Sample request

    curl  -X POST https://www.workato.com/api/deployments/6390/reject \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "comment": "Deployment submission rejected due to failing review criteria. Please address the issues and resubmit."
          }'

    # Response

    {
    "review": {
        "deployment_id": 6390,
        "reviewer_id": 29036,
        "status": "rejected",
        "comment": "",
        "updated_at": "2024-10-11T13:42:32.614-07:00"
    }
}

    # Re-open a deployment for review

    Re-opens a deployment for review. The Require review and approval toggle must be enabled in Workspace admin > Settings > Deployments to access this endpoint.

    POST /api/deployments/:id/reopen

    # URL parameters

    Name Type Description
    id integer
    required    		 The unique identifier of the deployment to re-open.

    # Sample request

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

    # Response

    {
    "success": true
}

    # Update a deployment review comment

    Updates a deployment review comment. The Require review and approval toggle must be enabled in Workspace admin > Settings > Deployments to access this endpoint.

    POST /api/deployments/:id/update_review_comment

    # URL parameters

    Name Type Description
    id integer
    required    		 The unique identifier of the deployment.

    # Payload

    Name Type Description
    comment string
    required    		 The updated comment for the deployment review.

    # Sample request

    curl  -X POST https://www.workato.com/api/deployments/6390/update_review_comment \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "comment": "Looks good!"
          }'

    # Response

    {
    "review": {
        "deployment_id": 6390,
        "reviewer_id": 29036,
        "status": "approved",
        "comment": "Looks good!",
        "updated_at": "2024-10-11T13:43:19.547-07:00"
    }
}

    # Deploy an approved deployment

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

    POST /api/deployments/:id/deploy

    # URL parameters

    Name Type Description
    id integer
    required    		 The unique identifier of the deployment.

    # Sample request

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

    # 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",
    "review_state": "review_approved",
    "reviews": [
        {
            "status": "approved",
            "comment": "Looks good!",
            "reviewer_name": "Jie"
        }
    ]
}
    ← Search for an On-prem agent
    Project properties →


    Last updated: 10/17/2024, 2:16:45 PM

    On this page