Skip to content
Farcaster

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

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

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The agt_<uuidv7> agent ID.

Header Parameters

Section titled “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

Section titled “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

Section titled “Responses”

202

Section titled “202”

Invocation accepted; the upstream call is running asynchronously.

Media typeapplication/json
object
invocation_id
required
string
Examplegenerated
{
  "invocation_id": "example"
}

Headers

Section titled “Headers”
X-Farcaster-Invocation-ID
string

The invocation ID, also present in the body.

400

Section titled “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
Examplegenerated
{
  "error": "example"
}

401

Section titled “401”

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

402

Section titled “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:

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
Examplegenerated
{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "example",
      "network": "example",
      "maxAmountRequired": "example",
      "asset": "example",
      "payTo": "example",
      "resource": "example",
      "maxTimeoutSeconds": 1
    }
  ]
}

404

Section titled “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
Examplegenerated
{
  "error": "example"
}

413

Section titled “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
Examplegenerated
{
  "error": "example"
}

422

Section titled “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
Examplegenerated
{
  "error": "example"
}

429

Section titled “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
Examplegenerated
{
  "error": "example"
}

Headers

Section titled “Headers”
Retry-After
integer

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

500

Section titled “500”

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