Prerequisites
- A credential: a platform API key (
abl_…) in thex-api-keyheader, a platform API key or Studio user JWT asAuthorization: Bearer, or a JWT App assertion in theauthheader. Public SDK keys (pk_…) are refused. - The
tool:readpermission to list and describe tools. Thetool:executepermission to execute them. A platform API key gets these from thetools.readandtools.executescopes. - The project slug. A project ID or UUID returns
404. - A tool of a type that is enabled for public API execution.
Workflow and use cases
- List the project’s tools. Check
executableandunsupportedReasonfor each tool. - Describe the tool you want to run to get its input schema.
- Execute the tool with a
paramsobject that matches the schema.
List of endpoints
All paths start with/api/v1/project/{projectSlug}/tools.
Behavior to know
- The API serves the live working copy of each tool definition. The environment is always
draft. Nothing is pinned to a version or a deployment. Paths that include an{env}segment still respond for existing integrations but are deprecated. Don’t build new integrations on them. - Only tool types on the allowlist run. The
tabletype is enabled by default. Thehttp,mcp,searchai,workflow, andintegrationtypes are opt-in for each environment. Thesandboxtype never runs. A tool of a disabled type returns404, the same response as an unknown tool name. - The
connectortype is the older stored name ofintegration. The list can return either one, so treat them as the same type. - The
timeoutproperty sets a per-call timeout from 1000 to 300000 milliseconds. Amodeother thansyncreturns400 ASYNC_NOT_SUPPORTED. - A
200response means the tool ran. Checkdata.statusfor the outcome of the tool itself. - The request body is strict. Unknown properties and platform-derived fields return
400. - A JWT App created with payload encryption enforced sends a JWE in compact serialization with
Content-Type: application/joseinstead of JSON. - The
429response has its own format, not the standard error envelope. Use theRetry-AfterandX-RateLimit-*headers. - Retry
503errors with backoff. Don’t automatically retry a tool that has side effects unless you know a retry is safe.