Skip to content
Farcaster

Get an agent

GET
/v1/agents/{id}
curl --request GET \
  --url https://example.com/v1/agents/example \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The agt_<uuidv7> agent ID.

Responses

Section titled “Responses”

200

Section titled “200”

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

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

500

Section titled “500”

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