Skip to main content
Agent management endpoints are called by humans (dashboard session) and by orchestrators (an organization API key) — never by the agents themselves. Agents interact through the MCP server. The org key needs the scope for what it’s doing: agents:read to list or read agents, agents:write for the mutations (create, budget policy, pause/resume, archive). A write-only key cannot list — the scopes are independent, not a hierarchy.
Orchestrators can drive most of these as MCP tools instead of REST — create, list, budget policy, pause/resume, archive — see the management band. Listing needs agents:read; the mutations need agents:write. Not everything on this page is machine-callable: PATCH /v1/agents/:id (name/description) and the key mint/revoke routes remain session-only and have no management tool — they fail even with agents:write.

​
Create agent

Creates an agent with a non-custodial crypto wallet, a spending policy, and (bundled) its first API key.
The response includes the agent and its API key. Store it immediately — you get one delivery. Precisely how “one delivery” works depends on the caller:
  • Dashboard session: the key is shown once and never again. If it’s lost, revoke and mint a new one.
  • Organization API key: the key is returned once, but a replay of the same idempotencyKey and payload re-delivers it for roughly 30 minutes — a deliberate recovery window for a lost response. After that window it is gone the same way, and the replay returns apiKey: null.
Machine callers must send idempotencyKey. Omitting it returns 400 IDEMPOTENCY_KEY_REQUIRED. Persist a stable, high-entropy value before you call: on any ambiguous failure (timeout, network error, code-less 5xx, 409 REQUEST_IN_PROGRESS, 409 ORG_NOT_READY, 503 CREATE_RETRYABLE) you replay the same key and payload to recover the committed agent. Without it, a lost response means an orphaned agent and an unrecoverable credential.
Key re-delivery is time-boxed to roughly 30 minutes — act on an ambiguous failure immediately. A replay only re-delivers the raw apiKey while that window is open. After it closes, the replay still returns the agent but with apiKey: null, mcpConfigBlock: null, and keyDelivery: "expired". Retry promptly and store the key the moment you receive it. Creation draws on the key’s daily quota; replaying an already-completed create is free.
keyDelivery: "expired" does NOT mean the key was never delivered — check your own records before acting on it. It means only that the response arrived after the ~30-minute delivery window — which can happen on a late replay or on the very first response of a slow create that spent long enough provisioning. If your original create response actually arrived, that key is still live and the agent is perfectly usable; the server cannot tell the two cases apart. So do not treat an expired result as proof the agent is stranded. Confirm from your own delivery records that no credential was ever stored, and only then treat it as unrecoverable — the undelivered credential is still the agent’s one active key, so a human must DELETE /v1/agents/:id/key before POST /v1/agents/:id/key (minting straight away returns 409 KEY_ALREADY_EXISTS). The machine alternative is the zombie-archive sequence — but note an expired result from a first response has not stamped the durable non-delivery proof the archive gate needs, so a direct archive_agent there returns 409 KEY_DELIVERY_UNPROVEN and you must replay the create (to stamp it) before archiving — and because that stamp is best-effort, retry the replay + archive a few times with backoff if the code recurs, escalating (not looping) if it persists. Archiving on the expired flag alone can destroy an agent whose key you are holding.

​
List agents

Returns the organization’s agents. Optional filters: projectId, teamId.

​
Update agent

The budget-policy endpoint updates budgetCents, autoApprovalThresholdCents, perTransactionLimitCents, dailySpendLimitCents, and hourly/daily velocity limits. It takes a version token from the last read for optimistic concurrency — a stale token returns 409 VERSION_CONFLICT, so re-read and retry rather than blind-writing.
Step-up applies to human callers. A session must re-verify (passkey or TOTP). An organization API key does not — minting the key was itself performed by a human under step-up, and that ceremony is what authorizes it, so a headless caller is never re-challenged. Reading the current policy via GET /v1/agents/:id/budget-policy requires agents:write for a key, because it is a write precondition.

​
Pause and resume

Pausing is instant and reversible — every payment is denied while paused, and the API key stays intact. See Agent Lifecycle.

​
API keys

One active key per agent. Minting for an archived agent returns 409 AGENT_ARCHIVED.

​
Archive agent

Terminal: revokes the key and detaches the wallet policy. Requires step-up auth for human callers. Archived agents cannot be reactivated.
Organization API keys are heavily restricted here. A key may archive only a zombie of its own making — an agent that key lineage created, whose bundled-key re-delivery window has closed, that never authenticated and has no activity, holds a zero balance, and whose keys no human has ever minted or revoked (any human key management permanently disqualifies the machine path — the agent is no longer a machine orphan). Note the server cannot prove the key was never delivered (only that it can no longer be re-delivered and was never used), so confirm from your own records before archiving.403 MACHINE_ARCHIVE_DENIED is terminal — a human must archive from the dashboard. But not every non-success is terminal. Two 409s are recoverable — KEY_STILL_DELIVERABLE (replay the create to recover the key and keep the agent) and KEY_DELIVERY_UNPROVEN — and so are 409 BALANCE_UNVERIFIABLE (balance couldn’t be confirmed zero; retry later) and a 200 carrying a non-empty walletsFailed array (the local archive committed but a wallet detach failed; re-issue the DELETE until it comes back empty). Full sequences on the management band.
For an emergency hard stop, pause the agent and revoke its API key. Everything halts immediately, and it’s fully reversible.