Invoke an agent with a streamed request/response

POST

/v1/proxy/{id}/stream

curl --request POST \
  --url https://example.com/v1/proxy/example/stream \
  --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).

Opens a long-lived connection to the agent’s upstream and streams the request and response bodies verbatim, without buffering (spec 0002). X-Farcaster-Invocation-ID is set on the response before any upstream byte is written, regardless of outcome. On a settlement-enabled priced route (spec 0006), settlement completes before the upstream stream opens, and a successful settle’s receipt rides the X-PAYMENT-RESPONSE response header.

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

Streamed verbatim to the agent’s upstream URL, unbounded (no 32 MiB cap on this path).

Media type*/*

Responses

200

The upstream’s response, streamed back verbatim (status, headers, and body are the upstream’s own — this describes the success shape, not a fixed status code).

Media type*/*

Headers

X-Farcaster-Invocation-ID

string

The invocation ID.

X-PAYMENT-RESPONSE

string

Present only after a successful settle-then-forward; the facilitator’s settlement receipt.

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

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

502

The upstream was unreachable or refused the connection.

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

X-Farcaster-Invocation-ID

string

504

The upstream call timed out.

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

X-Farcaster-Invocation-ID

string