Register a new agent

POST

/v1/agents

curl --request POST \
  --url https://example.com/v1/agents \
  --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", "emit_receipts": false, "capture_body": false, "protocol": "http", "mcp_transport": "streamable_http", "mcp_protocol_version": "example", "pricing": { "amount": "example", "asset": "USDC", "network": "base", "pay_to": "example", "tools": { "additionalProperty": "example" } } }'

• The gateway serves this contract at its own root; no fixed host is baked in (self-hostable).

Creates an agent scoped to the caller’s tenant. Status is derived: pending when upstream_url is absent, active once one is set (spec 0002). protocol defaults to http; protocol=mcp requires mcp_transport to be streamable_http (spec 0004 Decision 2/3). pricing, when present, enables the x402 payment gate on this agent (spec 0005) and requires pricing.network=base, pricing.asset=USDC; per-tool overrides in pricing.tools require protocol=mcp.

Authorizations

• oidcBearer

Request Body^required

Media typeapplication/json

object

name

required

string

description

string

tags

Array<string>

metadata

object

key

additional properties

any

upstream_url

Must be http(s) with a host; loopback/private/link-local hosts and localhost are rejected (SSRF hygiene).

string format: uri

nullable

credential_ref

string

nullable

emit_receipts

boolean

capture_body

boolean

protocol

string

default: http

Allowed values: http mcp

mcp_transport

Required when protocol=mcp; rejected when protocol=http.

string

nullable

Allowed values: streamable_http

mcp_protocol_version

string

nullable

pricing

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

201

Agent created.

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

Invalid body, missing name, invalid upstream_url/protocol/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

Example^generated

{
  "error": "example"
}

401

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

409

An active or pending agent with this name already exists 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

Example^generated

{
  "error": "example"
}

500

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