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.

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

Media type*/*

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-Farcaster-Invocation-ID

string

The invocation ID, also present in the body.

400

X-Farcaster-Model exceeds 256 bytes.

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
    }
  ]
}

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"
}

413

Request body exceeds the 32 MiB cap.

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