Invoke an agent transactionally

POST

/v1/proxy/{id}

curl --request POST \
  --url https://example.com/v1/proxy/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: */*' \
  --data example

• The gateway serves this contract at its own root; no fixed host is baked in (self-hostable).

Creates a durable invocation record and returns 202 Accepted immediately with invocation_id; the upstream call runs server-side and the caller polls GET /v1/proxy/{id}/invocations/{inv_id} for the result (spec 0002). The request body is forwarded verbatim to the agent’s upstream_url, capped at 32 MiB. When ZERKER_REASON_BINARY is configured, MCP tools/call requests must use zerker.gateway.reason-mcp-call.v1: Gateway sends the exact bundled authorization bytes to Reason, requires verified+authorized output, compares the inner call’s tool and normalized arguments, and requires the verified request to bind mission.principal to the authenticated OAuth subject plus gateway.tenant_id and gateway.agent_id mission constraints to the authenticated tenant and route agent. Gateway forwards only the inner JSON-RPC call. Verification, comparison, and a replay preflight happen before policy webhooks, x402, invocation creation, settlement, or forwarding. Invocation creation persists the verified request digest under a tenant-unique index before settlement or forwarding, closing concurrent replay races. This reservation is one-shot and is not refunded after an observed upstream timeout or error, because Gateway cannot prove that the upstream performed no side effect. Failures before invocation creation do not consume it.

For a priced agent (pricing set on the agent, spec 0005): a request with no X-PAYMENT header receives 402 with an x402 payment-required challenge instead of being forwarded, and no invocation is created; a request with an X-PAYMENT header has the payment authorization verified before forwarding, and — when the tenant has settlement configured (spec 0006) — settled via the facilitator before the upstream is ever called.

Authorizations

• oidcBearer

Parameters

Path Parameters

id

required

string

The agt_<uuidv7> agent ID.

Header Parameters

X-PAYMENT

string

Base64-encoded x402 payment payload (spec 0005), required only for priced agents.

X-Zerker-Model

string

<= 256 characters

Caller-supplied model identifier recorded on the invocation (spec 0003). Max 256 bytes.

Request Body

Forwarded verbatim to the agent’s upstream URL. For protocol=mcp agents this is a single JSON-RPC 2.0 request; a Reason-enabled MCP tools/call uses the envelope below and only its call value is forwarded.

One of:

unknown

object

object

schema

required

string

Allowed values: zerker.gateway.reason-mcp-call.v1

call

required

A single JSON-RPC 2.0 MCP tools/call request. This exact object is forwarded after verification.

object

authorization

required

A complete zerker.reason.authorization-bundle.v1, passed to Reason over bounded stdin without reopening another source. Its request must set mission.principal to the authenticated OAuth subject and string mission constraints gateway.tenant_id and gateway.agent_id to the authenticated tenant and route agent.

object

Responses

202

Invocation accepted; the upstream call is running asynchronously.

Media typeapplication/json

object

invocation_id

required

string

Example^generated

{
  "invocation_id": "example"
}

Headers

X-Zerker-Invocation-ID

string

The invocation ID, also present in the body.

400

X-Zerker-Model exceeds 256 bytes, or a Reason-enabled MCP request/envelope is malformed.

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object

error

required

A coarse, caller-safe message. Never contains internal state (invariant

string

Example^generated

{
  "error": "example"
}

401

Missing or invalid bearer token, or the token’s tenant/user claims are absent. No body.

402

No X-PAYMENT header on a priced agent (body is an x402 payment challenge), or the supplied payment failed verification/settlement (body is a coarse Error).

Media typeapplication/json

One of:

object

The 402 Payment Required challenge body for a priced route with no X-PAYMENT header (spec 0005).

object

x402Version

required

integer

accepts

required

Array<object>

One entry of a 402 challenge’s accepts array.

object

scheme

required

string

network

required

string

maxAmountRequired

required

Decimal string (256-bit)

string

asset

required

Token contract address (hex)

string

payTo

required

string

resource

required

string

maxTimeoutSeconds

required

integer

object

The uniform error body for all 4xx responses that carry one.

object

error

required

A coarse, caller-safe message. Never contains internal state (invariant

string

Example^generated

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "example",
      "network": "example",
      "maxAmountRequired": "example",
      "asset": "example",
      "payTo": "example",
      "resource": "example",
      "maxTimeoutSeconds": 1
    }
  ]
}

403

A Reason-enabled MCP tools/call is missing authorization, fails independent verification, or does not exactly match the verified action.

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object

error

required

A coarse, caller-safe message. Never contains internal state (invariant

string

Example^generated

{
  "error": "example"
}

404

No resource with this ID exists in the caller’s tenant.

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object

error

required

A coarse, caller-safe message. Never contains internal state (invariant

string

Example^generated

{
  "error": "example"
}

409

The independently verified Reason request digest has already been used by this tenant.

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object

error

required

A coarse, caller-safe message. Never contains internal state (invariant

string

Example^generated

{
  "error": "example"
}

413

Request body exceeds the 32 MiB cap, or the embedded Reason authorization bundle exceeds 1 MiB.

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object

error

required

A coarse, caller-safe message. Never contains internal state (invariant

string

Example^generated

{
  "error": "example"
}

422

The agent is inactive, suspended, or has no upstream_url configured.

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object

error

required

A coarse, caller-safe message. Never contains internal state (invariant

string

Example^generated

{
  "error": "example"
}

429

The agent’s per-agent invocation rate limit was exceeded (spec 0002).

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object

error

required

A coarse, caller-safe message. Never contains internal state (invariant

string

Example^generated

{
  "error": "example"
}

Headers

Retry-After

integer

Seconds until the next token is available (capped at 60).

500

An unexpected server-side error. No body (internal detail is never returned to callers, invariant