A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Workato API is how an app or AI agent works with a Workato workspace: listing and starting recipes, reading a recipe's job runs, creating and updating connections, organizing folders and projects, and reading and writing lookup table rows. Access is granted through an API token whose client role decides which endpoints it may call, scoped to chosen projects so the token reaches only the recipes, connections, and tables inside them. It is not versioned by a dated string, and it does not push events back to a caller, instead a recipe can listen on its own inbound trigger.
How an app or AI agent connects to Workato determines what it can reach. There is one main route, the Developer API, governed by the token behind it, the client role it carries, and the projects that token is scoped to.
The Developer API is the REST interface for managing a Workato workspace. Its host depends on the data center, www.workato.com for the US and regional workato.com subdomains for the EU, JP, SG, AU, IL, and KR regions, with China on a separate host. It is addressed by path, mostly under /api with a few resources under /api/v1 or /api/v2.
Workato runs a first-party Developer API MCP server, so an agent can call the Developer API through the Model Context Protocol. It answers at app.workato.com/mcp, is available in the US, EU, AU, JP, and SG data centers, and uses a Developer API token as a bearer credential. It respects the same client role and project scopes as direct calls.
An API client is created under Workspace admin and given a client role and project scopes. Its token is sent as an Authorization Bearer header. The client role lists exactly which endpoints the token may call, and the project scopes limit which assets it can reach, so a token can be made least-privilege at creation.
The original method sent an API key and email in x-user-token and x-user-email headers. It was fully deprecated on 14 July 2025 and is no longer accepted. Each legacy key was migrated into Workspace admin as a migrated API client, and integrations must move to an Authorization Bearer token.
The Workato Developer API is split into areas an agent can act on, such as recipes, jobs, connections, folders and projects, and lookup tables. Each area has its own methods, and a client role decides which of those endpoints a token may call at all.
List, read, create, copy, and update recipes, and start, stop, or delete them.
List the job runs for a recipe, read a single job, and resume a paused job.
List connections, create and update them, disconnect, and delete a connection.
List folders and projects, create and update them, build and deploy a project, and read deployments.
List lookup tables, look up and list rows, and add, update, or delete a row.
List project, environment, and legacy roles, and list, create, update, and delete API clients.
List on-prem agent groups and their status, and read the workspace activity audit log.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
RecipesList, read, create, copy, and update recipes, and start, stop, or delete them.8 | ||||||
| GET | /api/recipes | List recipes belonging to a user. | read | Recipes: list | Current | |
The client role must include this endpoint, and the token's project scopes limit which recipes are returned. Acts onrecipe Permission (capability) Recipes: listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/recipes/:id | Get a single recipe's details. | read | Recipes: details | Current | |
The recipe must fall inside the token's project scopes. Acts onrecipe Permission (capability) Recipes: detailsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/recipes | Create a recipe. | write | Recipes: create | Current | |
From 7 May 2026 a folder_id is required so the new recipe lands in a folder rather than the deprecated Home Asset root. Acts onrecipe Permission (capability) Recipes: createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/recipes/:id/copy | Copy a recipe. | write | Recipes: copy | Current | |
From 7 May 2026 a folder_id is required to place the copy. Acts onrecipe Permission (capability) Recipes: copyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/recipes/:id | Update a recipe. | write | Recipes: update | Current | |
The recipe must fall inside the token's project scopes. Acts onrecipe Permission (capability) Recipes: updateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/recipes/:id/start | Start a recipe, so it begins running live. | write | Recipes: start | Current | |
Starting a recipe activates live automation that can read and write the connected apps. Acts onrecipe Permission (capability) Recipes: startVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/recipes/:id/stop | Stop a running recipe. | write | Recipes: stop | Current | |
Stopping a recipe halts a live automation. Acts onrecipe Permission (capability) Recipes: stopVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/recipes/:id | Delete a recipe. | write | Recipes: delete | Current | |
Deletion is permanent and removes the automation logic. Acts onrecipe Permission (capability) Recipes: deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
JobsList the job runs for a recipe, read a single job, and resume a paused job.3 | ||||||
| GET | /api/recipes/:recipe_id/jobs | List the job runs for a recipe. | read | Jobs: list | Current | |
Returns the runs of one recipe, which the token's projects must include. Acts onjob Permission (capability) Jobs: listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/recipes/:recipe_id/jobs/:job_handle | Get a single job for a recipe. | read | Jobs: details | Current | |
Job data can include the records a recipe processed. Acts onjob Permission (capability) Jobs: detailsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/job/resume | Resume a paused job. | write | Jobs: resume | Current | |
Resuming a job continues a real run that was waiting. Acts onjob Permission (capability) Jobs: resumeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ConnectionsList connections, create and update them, disconnect, and delete a connection.5 | ||||||
| GET | /api/connections | List connections in the workspace. | read | Connections: list | Current | |
Returns connection metadata, not the stored secrets, limited to the token's project scopes. Acts onconnection Permission (capability) Connections: listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/connections | Create a connection. | write | Connections: create | Current | |
Limited to 1 request per second. From 7 May 2026 a folder_id is required. Acts onconnection Permission (capability) Connections: createVersionAvailable since the API’s base version Webhook eventNone Rate limit1 request per second SourceOfficial documentation ↗ | ||||||
| PUT | /api/connections/:connection_id | Update a connection. | write | Connections: update | Current | |
Changing a connection can alter the credentials live recipes depend on. Acts onconnection Permission (capability) Connections: updateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/connections/:connection_id/disconnect | Disconnect a connection without deleting it. | write | Connections: disconnect | Current | |
Disconnecting stops recipes that rely on the connection from authenticating. Acts onconnection Permission (capability) Connections: disconnectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/connections/:connection_id | Delete a connection. | write | Connections: delete | Current | |
Deletion is permanent and can break any recipe that used the connection. Acts onconnection Permission (capability) Connections: deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Folders & projectsList folders and projects, create and update them, build and deploy a project, and read deployments.5 | ||||||
| GET | /api/folders | List folders. | read | Folders: list | Current | |
Folders organize recipes, connections, and tables inside a project. Acts onfolder Permission (capability) Folders: listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/projects | List projects. | read | Projects: list | Current | |
A project is the top-level folder a token can be scoped to. Acts onproject Permission (capability) Projects: listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/folders | Create a folder or project. | write | Folders: create | Current | |
Creating a top-level folder creates a project. Acts onfolder Permission (capability) Folders: createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/projects/:id/deploy | Build a project and deploy it to a target environment. | write | Projects: deploy | Current | |
Deployment moves recipes and assets between environments, such as from development to production. Acts ondeployment Permission (capability) Projects: deployVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/deployments | List deployments. | read | Deployments: list | Current | |
Reads the history of project deployments. Acts ondeployment Permission (capability) Deployments: listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Lookup tablesList lookup tables, look up and list rows, and add, update, or delete a row.5 | ||||||
| GET | /api/lookup_tables | List lookup tables. | read | Lookup: list | Current | |
Limited to the lookup tables inside the token's project scopes. Acts onlookup table Permission (capability) Lookup: listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/lookup_tables/:lookup_table_id/rows | List the rows in a lookup table. | read | Lookup: rows read | Current | |
Lookup rows are reference data recipes read at runtime. Acts onlookup row Permission (capability) Lookup: rows readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/lookup_tables/:lookup_table_id/rows | Add a row to a lookup table. | write | Lookup: rows write | Current | |
Changes the reference data recipes use. Acts onlookup row Permission (capability) Lookup: rows writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/lookup_tables/:lookup_table_id/rows/:row_id | Update a row in a lookup table. | write | Lookup: rows write | Current | |
Changes the reference data recipes use. Acts onlookup row Permission (capability) Lookup: rows writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/lookup_tables/:lookup_table_id/rows/:row_id | Delete a row from a lookup table. | write | Lookup: rows write | Current | |
Removes reference data a recipe may depend on. Acts onlookup row Permission (capability) Lookup: rows writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Roles & API clientsList project, environment, and legacy roles, and list, create, update, and delete API clients.6 | ||||||
| GET | /api/project_roles | List project roles. | read | Roles: list | Current | |
Project roles define what a collaborator can do inside a project. Acts onrole Permission (capability) Roles: listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/roles | List the workspace's collaborator roles. | read | Roles: list | Current | |
These are the legacy collaborator roles in the workspace. Acts onrole Permission (capability) Roles: listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/developer_api_clients | List developer API clients. | read | API clients: list | Current | |
Reads the API clients that hold tokens for the Developer API. Acts onAPI client Permission (capability) API clients: listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/developer_api_clients | Create a developer API client, which issues a new token. | write | API clients: create | Current | |
Creating an API client mints a new token with its own client role and project scopes. Acts onAPI client Permission (capability) API clients: createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/developer_api_clients/:id/regenerate | Regenerate an API client's token. | write | API clients: rotate | Current | |
Regenerating invalidates the old token, so any integration using it must be updated. Acts onAPI client Permission (capability) API clients: rotateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/developer_api_clients/:id | Delete a developer API client. | write | API clients: delete | Current | |
Deleting a client revokes its token immediately. Acts onAPI client Permission (capability) API clients: deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
On-prem agents & activityList on-prem agent groups and their status, and read the workspace activity audit log.3 | ||||||
| GET | /api/on_prem_groups | List the on-prem agent groups in the workspace. | read | On-prem: list | Current | |
On-prem groups run agents inside a private network so recipes can reach systems behind the firewall. Acts onon-prem group Permission (capability) On-prem: listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/on_prem_groups/:id/status | Get the status of an on-prem group, including its agent count and active agents. | read | On-prem: status | Current | |
Reports how many agents are connected and active in the group. Acts onon-prem group Permission (capability) On-prem: statusVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/activity_logs | Read the workspace activity audit log, with pagination and filters. | read | Activity: read | Current | |
Returns the same audit trail as the in-product Activity view, useful for compliance reporting. Acts onactivity log Permission (capability) Activity: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Workato does not push platform events back to an app or AI agent through the Developer API. Instead, a Workato recipe can itself listen on an inbound webhook trigger, so events flow into a recipe rather than out to a caller of this API.
| Event | What it signals | Triggered by |
|---|
Workato limits how fast and how much an app or AI agent can call, through a per-minute request quota set for each endpoint and a fixed request timeout, with tighter ceilings on the heaviest calls.
Workato sets a request quota per minute on each Developer API endpoint, rather than one quota across the whole API. Most endpoints allow 60 requests per minute. A few are tighter, such as creating a connection at 1 request per second and running a recipe health analysis at 20 requests per minute, while some list endpoints allow up to 1,000 requests per minute. Every request is also held to a 40 second timeout. Customers on Enterprise plans or above can ask their Customer Success representative to raise these limits. Exceeding a limit returns an error response, and a recurring x-correlation-id header on each request helps trace a specific call.
List endpoints page through results with page and per_page query parameters, returning a page of records at a time rather than the whole set. The exact default and maximum per_page vary by endpoint and are stated on each endpoint's reference page, so the per_page value should be set explicitly and the next page fetched until a short or empty page is returned.
Requests and responses are JSON. The event streams publish and consume endpoints cap a payload at 1 MB. Other endpoints do not document a single fixed body size limit, and large operations such as package import or export are handled through dedicated endpoints rather than one oversized request.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The server could not process the request because of a client-side issue, such as a missing or malformed parameter. The body carries an errors array, where each entry has a code and a title. | Read the errors array, correct the named field, and resend the request. |
| 401 | Unauthorized | The request lacks valid authentication credentials, which usually means a missing, invalid, or expired API token, or a request still using the removed legacy key headers. | Send a current API client token as an Authorization Bearer header. |
| 403 | Forbidden | The request is authenticated but not permitted. The token's client role does not include this endpoint, or its project scopes do not cover the asset being acted on. | Add the endpoint to the client role, or widen the project scopes, then retry. |
| 404 | Not Found | The requested resource does not exist, or it cannot be seen by this token, for example a recipe or connection outside the token's project scopes. | Confirm the id and that the token's projects include the resource. |
| 429 | Too Many Requests | A per-endpoint rate limit was exceeded, such as more than 60 requests in a minute on a standard endpoint or more than 1 per second on connection creation. | Slow the call rate to within the endpoint's limit and retry, or ask Customer Success to raise the limit. |
| 500 | Server Error | The server hit an unexpected condition. The x-correlation-id from the request identifies the call for support. | Retry after a short pause, and quote the x-correlation-id if the error persists. |
The Workato Developer API is not versioned by a dated string. It is a single, continuously updated API addressed by path, with most resources under one prefix and a few newer ones under a v1 or v2 segment.
The Workato Developer API is not pinned by a dated version header. It is a single, continuously updated API addressed by path, with most resources under the /api prefix and some newer ones under a /api/v1 or /api/v2 segment. Notable changes ship through the Workato product changelog, so an integration tracks the changelog rather than a version string.
Workato announced that the folder_id parameter is becoming required on three Developer API endpoints that create assets, supporting the deprecation of the Home Asset folder and a cleaner root folder structure. After 7 May 2026, creating a connection, creating a recipe, or copying a recipe without a folder_id returns an error. It was published on 17 April 2026.
Workato fully deprecated the legacy API key method, where requests carried x-user-token and x-user-email headers, on 14 July 2025. After this date those requests are rejected, and every call must use an API client token sent as an Authorization Bearer header. Each migrated legacy key was moved into Workspace admin as a migrated API client.
Notable changes ship through the Workato product changelog rather than a version header, so an integration tracks the changelog rather than pinning a version.
Workato product changelog ↗Bollard AI sits between a team's AI agents and Workato. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.