# Projects API

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

Endpoint	Description
POST /projects/:id/build	Builds a project. Use the Deploy a project build endpoint to deploy the project to an environment.
GET /project_builds/:id	Retrieves a project build by its unique ID.
POST /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 /projects/:id/deploy?environment_type=:environment_type	Builds and deploys a project to an environment.
GET /deployments/:id	Retrieves a single deployment by its unique ID.
GET /deployments	Retrieves a list of deployments. Query parameters may be used to filter results to a specific project, folder, date range, etc.

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

{
    "id": 43,
    "created_at": "2021-12-09T22:30:09.005-08:00",
    "updated_at": "2021-12-09T22:30:09.933-08:00",
    "description": null,
    "project_build_id": 46,
    "environment_type": "test",
    "project_id": "10416",
    "state": "success",
    "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 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.

{
  "items": [
      {
          "id": 49,
          "created_at": "2021-12-09T22:58:45.306-08:00",
          "updated_at": "2021-12-09T22:58:46.483-08:00",
          "description": "Resolve bugs",
          "project_build_id": 54,
          "environment_type": "test",
          "project_id": "10416",
          "state": "success",
          "performed_by_name": "Finn the Human"
      },
      {
          "id": 48,
          "created_at": "2021-12-09T22:57:10.820-08:00",
          "updated_at": "2021-12-09T22:57:11.865-08:00",
          "description": "Add functionality",
          "project_build_id": 53,
          "environment_type": "prod",
          "project_id": "10416",
          "state": "success",
          "performed_by_name": "Finn the Human"
      },
      {
          "id": 47,
          "created_at": "2021-12-09T22:37:30.025-08:00",
          "updated_at": "2021-12-09T22:37:31.186-08:00",
          "description": null,
          "project_build_id": 52,
          "environment_type": "test",
          "project_id": "10416",
          "state": "success",
          "performed_by_name": "Finn the Human"
      }
  ]
}

Name Type Description

items

array

A list of deployment objects.

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 URI

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

Unsupported method

Incorrect URI

Last updated: 12/19/2023, 1:08:37 AM