Skip to main content
POST
Run a single capability synchronously
Executes one capability from GET /v1/tools and returns its result on the same request. There is no job to poll and no streaming, so a slow capability holds the connection for its whole duration.
This is billed. Credits are reserved before the work starts and settled against what it actually used.

Authorizations

Authorization
string
header
required

API key in format: Bearer inf_***

Path Parameters

id
string
required

Capability to run — one of the data[].id values from GET /v1/tools, e.g. image.resize. Also the identity the quota, allowed-model and budget checks are applied against.

Body

application/json
input
object

Capability input payload (shape defined by the capability's zod input schema).

params
object

Capability params payload (shape defined by the capability's zod params schema).

Response

The capability result. File-producing capabilities answer file_id (plus url/mime/size_bytes when the engine reported them); text-producing ones answer result.

id
string
required

Identifier for this run — the literal prefix cap_ followed by a UUID.

Example:

"cap_1f0c2b7e-6b2a-4a1f-9a54-3d1f8b0c2a11"

capability
string
required

The capability that ran — echoes the id path parameter.

Example:

"image.resize"

credits_used
number
required

Credits settled for this run (1 credit = $0.01). 0 when the capability has no priced catalogue entry, in which case the run was not billed — 0 means unbilled, not free by policy. May be fractional.

Example:

0.5

file_id
string

Identifier of the ApiFile the engine registered for the produced bytes, usable with GET /v1/files/{fileId} and GET /v1/files/{fileId}/content. Present only for capabilities that produce a single stored artifact; absent for text-producing capabilities and for archive.unpack, which produces many artifacts and reports them inside result instead.

Example:

"file_1hR9xTPZqK4mVLc2nJ7fY5wB"

url
string

Where the engine reported those bytes can be read. Only ever present alongside file_id, and only when the engine supplied it.

mime
string

MIME type the engine reported for the produced file. Only ever present alongside file_id, and only when the engine supplied it.

Example:

"image/png"

size_bytes
integer

Size of the produced file in bytes. Only ever present alongside file_id, and published only when the engine reported a usable non-negative integer.

Example:

245192

result
object

The capability's own output body, for capabilities that produce no single stored file — web.search, code.run_python, code.run_node, and archive.unpack (whose per-entry object URIs are stripped before it leaves the gateway). Also present alongside file_id for a capability that returns text beside its artifact, such as document.extract_text. The shape is defined by the capability and is not modelled here.