Skip to main content
Back to the Tools Execution API overview Executes a tool in a project and returns its result. The request supplies the tool’s caller-defined input parameters in a JSON body. Execution is synchronous: the request waits for the tool to complete or reach its timeout. Use this endpoint to run an executable tool after identifying it and retrieving its input schema. The tool’s output is returned without being reshaped by the platform, except that an Agent Table tool’s output is returned as a JSON object. Permission: tool:execute, granted by the platform API key scope tools.execute.

Path parameters

Request body

Send a JSON object with the following properties: The request body is strict. Unknown top-level properties and platform-derived fields are rejected rather than ignored. Platform-derived fields include values such as tenantId, environment, and agentSession. For Agent Table tools without a query template, params contains a structured call with op and the operands for that operation. The accepted operations depend on the tool’s binding.

Authentication

Use one of the supported credentials:
  • x-api-key: abl_... for a platform API key.
  • Authorization: Bearer <abl_... | JWT> for a platform API key or Studio user JWT.
  • auth: <assertion> for a JWT App assertion.
Public SDK keys (pk_...) are not accepted. The JWT App assertion must be sent in the auth header, not the Authorization header. The credential must have the tool:execute permission. A sensitive-column lookup also requires table:sensitive:reveal. A JWT App created with payload encryption enforced doesn’t send a plain JSON body. It sends a JWE in compact serialization with Content-Type: application/jose and receives application/jose back. Errors from the encryption layer, such as PAYLOAD_MALFORMED or PAYLOAD_DECRYPT_FAILED, are returned unencrypted.

Response

A successful response contains success and data. The data object includes the execution status, the tool’s output when provided, and trace information when the caller is entitled to it. A 200 response means the tool ran. The status field reports the tool executor’s own outcome. The response headers identify the tool type, resolved environment, and configuration source: For Agent Table tools, output is a JSON object rather than a serialized JSON string. For other tool types, the output is returned without platform-level reshaping.

Execution considerations

  • Only tool types enabled for public API execution can be invoked. Agent Table tools are enabled by default; other supported types require explicit enablement.
  • A tool’s declared effect can indicate whether it is read-only, writes state, or has side effects. Review this metadata before invoking the tool.
  • Tool failures are returned using status codes appropriate to the failure. Do not assume every execution failure is a transient server error or safe to retry.

Errors

The 429 response uses a rate-limiter-specific response format rather than the standard API error envelope. Check the response headers for rate-limit information and retry guidance. For transient dependency failures (503), retry with backoff. Resolve conflicts such as 409 before retrying. Do not automatically retry operations with side effects unless their retry behavior is known to be safe.