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