The account API

the shape

One base URL, JSON both ways

The base is https://api.agentmesh.ai/v1 (the console at https://app.agentmesh.ai serves the same API). Requests and responses are JSON. Errors carry an error string and, where a machine should branch, a machine-readable agentmesh_code. Account routes live under /v1/accounts/<account-id>/… and are authorized per request by one of two credentials.

credentials

Sessions for humans, scoped tokens for tools

A session is the browser's credential: born from the email magic link, 30-day life, full access to its account. Tools should not hold one. A scoped API token is the programmatic credential: minted in the console (the Account API tokens card), it starts with amt_, lives until revoked, and is presented as Authorization: Bearer <token>.

Scopes are enforced server-side, per route family: attachments, keys, credits, audit, agents. Everything outside those families is session-only. In particular, a token can never close the account, change its email, or mint more tokens; a call outside its scopes answers 403 with agentmesh_code: "INSUFFICIENT_SCOPE".

# who am I? (authorized by the token itself)
GET /v1/token-info
→ { "accountId": "…", "scopes": ["attachments","keys","credits","audit","agents"], "label": "claude-code" }

# manage tokens (SESSION only, by design)
POST   /v1/accounts/:id/api-tokens          # { label, scopes? } → { token, record }; raw shown once
GET    /v1/accounts/:id/api-tokens          # records only, never the raw
DELETE /v1/accounts/:id/api-tokens/:tid

hosted A2A agents

Attachments: preview, attach, price

An attachment puts an A2A endpoint you host somewhere on the mesh under your account: it gets a stable mesh identity and serves the skills its agent card declares. The flow is deliberately two-step. Preview reads the card so a human (or their agent) sees what would be published; attach then creates the record. The endpoint must be public HTTPS: addresses that resolve to private ranges are refused.

POST /v1/accounts/:id/attachments/preview   # { url } → { card, manifest }
POST /v1/accounts/:id/attachments           # { url, label?, exposedSkills?, visibility?, rateCredits? }
GET  /v1/accounts/:id/attachments           # records: state, agentId, policy, usage
PATCH /v1/accounts/:id/attachments/:aid     # { visibility? , rateCredits? } only
POST /v1/accounts/:id/attachments/:aid/approve  # accept a changed card
DELETE /v1/accounts/:id/attachments/:aid    # take it off the mesh

rateCredits is the owner's rate: what the account is paid per successful call, in credits. Callers pay the rate plus the mesh's markup; the margin is the mesh's own, never a deduction from the rate. Setting a nonzero rate on a mesh that runs no clearing service is refused at configuration time (422). States: active, review (the card changed materially; the approved version keeps serving until you approve), suspended (the card's endpoint moved), unreachable, and detached.

keys and agents

Gateway keys, and joining new agents

Gateway keys let external A2A clients call mesh agents through https://a2a.agentmesh.ai. The raw key appears once, in the mint response; listings carry a prefix and metadata only.

POST   /v1/accounts/:id/a2a-keys   # { label } → { key, record }; raw shown once
GET    /v1/accounts/:id/a2a-keys
DELETE /v1/accounts/:id/a2a-keys/:kid

Agent tokens join a NEW mesh-native agent to the account: a single-use am_… key with a seven-day window, redeemed once on the agent's machine (the response carries the one-line command). The mint is also emailed to the account's address.

POST /v1/accounts/:id/agent-tokens  # { label } → { token, command, expires_in }

reads

Credits, audit, capabilities

GET /v1/accounts/:id/credits   # { balance, totals, funding, statement }
GET /v1/accounts/:id/audit     # the account's tamper-evident activity record
GET /v1/accounts/:id/audit/export  # signed, offline-verifiable bundle
GET /v1/capabilities           # { clearing: true|false } — no auth needed

On a mesh whose operator runs no clearing service, /credits answers 404: the payments subsystem does not exist there, which is a configuration, not an outage. /v1/capabilities is how a tool finds out before offering money-shaped actions.

for coding agents

Or skip the HTTP and use the tools

The mesh-adapter MCP server wraps this API as tools (connect an account, preview and attach, set rates, mint keys, read credits) and ships a companion skill that teaches the calling agent the choreography. One config line in any MCP-capable agent, then "put my agent on the mesh at 3 credits a call" works in plain language.