# 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 will accept any of 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.

# Request Examples

# Using A Project ID

curl  -X POST https://www.workato.com/api/projects/10416/build \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'
      -d '{
            "description": "Fixes bugs"
          }'

# Using A Folder ID

curl  -X POST https://www.workato.com/api/projects/f660222/build \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <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 will be 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 'x-user-email: <email>' \
          -H 'x-user-token: <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 'x-user-email: <email>' \
          -H 'x-user-token: <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 will accept any of 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 'x-user-email: <email>' \
          -H 'x-user-token: <token>'
    
    # Using A Folder ID
    curl  -X POST https://www.workato.com/api/projects/f660222/deploy?environment_type=test \
          -H 'x-user-email: <email>' \
          -H 'x-user-token: <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 POST https://www.workato.com/api/deployments/43 \
          -H 'x-user-email: <email>' \
          -H 'x-user-token: <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 POST https://www.workato.com/api/deployments \
          -H 'x-user-email: <email>' \
          -H 'x-user-token: <token>'
    
    # With A Folder ID
    curl  -X POST https://www.workato.com/api/deployments?folder_id=f660222 \
          -H 'x-user-email: <email>' \
          -H 'x-user-token: <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": "dev",
              "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": "dev",
              "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": "dev",
              "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