Skip to content
Farcaster

Update an agent

PATCH
/v1/agents/{id}
curl --request PATCH \
  --url https://example.com/v1/agents/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "description": "example", "tags": [ "example" ], "metadata": {}, "upstream_url": "https://example.com", "credential_ref": "example", "suspended": true, "invocation_rate_limit": 1, "invocation_burst": 1, "emit_receipts": true, "capture_body": true, "protocol": "http", "mcp_transport": "streamable_http", "mcp_protocol_version": "example", "pricing": { "amount": "example", "asset": "USDC", "network": "base", "pay_to": "example", "tools": { "additionalProperty": "example" } } }'

Partial update. Only client-settable fields are accepted; id, status, created_by, and timestamps are immutable. Several fields are tri-state (absent key = leave unchanged, null = clear, a value = set) — see each field’s description.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The agt_<uuidv7> agent ID.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Partial update (PATCH). Fields documented “tri-state” accept: an absent key (leave unchanged), an explicit null (clear the field), or a value (set it). Other fields are simple “absent leaves unchanged, a value sets it” toggles — they have no clear semantics.

object
name

Absent leaves unchanged. Must not be empty when present.

string
description

Absent leaves unchanged.

string
tags

Absent leaves unchanged.

Array<string>
metadata

Absent leaves unchanged.

object
key
additional properties
any
upstream_url

Tri-state. Same SSRF hygiene as create. Setting/clearing this also re-derives status.

string format: uri
nullable
credential_ref

Tri-state.

string
nullable
suspended

Absent leaves unchanged.

boolean
invocation_rate_limit

Tri-state. Must be greater than zero when set to a value.

number
nullable
invocation_burst

Tri-state. Must be at least 1 when set to a value.

integer
nullable
emit_receipts

Absent leaves unchanged.

boolean
capture_body

Absent leaves unchanged.

boolean
protocol

Absent leaves unchanged. Validated against the resulting mcp_transport/pricing combination.

string
Allowed values: http mcp
mcp_transport

Tri-state.

string
nullable
Allowed values: streamable_http
mcp_protocol_version

Tri-state.

string
nullable
pricing

Tri-state — null unprices the agent.

object
amount
required

Flat per-call price, smallest-unit decimal string.

string
/^[0-9]+$/
asset
required

V1 accepts only “USDC”.

string
Allowed values: USDC
network
required

V1 accepts only “base”.

string
Allowed values: base
pay_to
required

Operator payout address (the gateway holds no key).

string
/^0x[0-9a-fA-F]{40}$/
tools

Optional per-MCP-tool price overrides, keyed by tool name. Requires the agent’s protocol to be mcp.

object
key
additional properties
string
/^[0-9]+$/

Responses

Section titled “Responses”

200

Section titled “200”

The updated agent.

Media typeapplication/json
object
id
required

The agt_<uuidv7> resource ID.

string
name
required
string
description
required
string
tags
required
Array<string>
nullable
metadata
required
object
key
additional properties
any
status
required

Derived from upstream_url — pending when absent, active once set; inactive after a delete.

string
Allowed values: pending active inactive
suspended
required

A suspended agent stays in the catalog but rejects invocations.

boolean
created_by
required

The subject claim of the user who created the agent.

string
created_at
required
string format: date-time
updated_at
required
string format: date-time
upstream_url
required
string format: uri
nullable
credential_ref
required

The credential ID injected into upstream calls.

string
nullable
invocation_rate_limit
required

Per-agent requests/second override (spec 0002).

number
nullable
invocation_burst
required

Token-bucket burst depth; defaults to 20 when only the rate is set.

integer
nullable
emit_receipts
required

Whether a Treeship trust receipt is emitted after each completed invocation.

boolean
capture_body
required

Whether request/response bodies are captured on invocations (spec 0003).

boolean
protocol
required
string
Allowed values: http mcp
mcp_transport
required

Required and validated only when protocol=mcp (spec 0004).

string
nullable
Allowed values: streamable_http
mcp_protocol_version
required
string
nullable
pricing
required
object
amount
required

Flat per-call price, smallest-unit decimal string.

string
/^[0-9]+$/
asset
required

V1 accepts only “USDC”.

string
Allowed values: USDC
network
required

V1 accepts only “base”.

string
Allowed values: base
pay_to
required

Operator payout address (the gateway holds no key).

string
/^0x[0-9a-fA-F]{40}$/
tools

Optional per-MCP-tool price overrides, keyed by tool name. Requires the agent’s protocol to be mcp.

object
key
additional properties
string
/^[0-9]+$/
Example
{
  "status": "pending",
  "protocol": "http",
  "mcp_transport": "streamable_http",
  "pricing": {
    "asset": "USDC",
    "network": "base"
  }
}

400

Section titled “400”

Invalid body or an invalid resulting protocol/mcp/pricing combination.

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.

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

409

Section titled “409”

The new name conflicts with another active or pending agent in the 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"
}

500

Section titled “500”

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