AgentSchema. API detail: Agents.
create
POST /v1/agents. AgentCreate requires name and model; everything else on the agent config (system, window, effort, budgets, harness, …) is optional. harness selects the agent loop — pi is the only one in Phase 1, and the default.
list
GET /v1/agents, cursor-paginated. See Pagination.
get
GET /v1/agents/{id}.
update
PATCH /v1/agents/{id}. Every config field is optional; a successful patch mints a new version rather than editing the current one. Pass expected_version for optimistic concurrency — a mismatch is a 409 conflict.
listVersions
GET /v1/agents/{id}/versions. History is immutable and never rewritten.
getVersion
GET /v1/agents/{id}/versions/{version}.
rollback
POST /v1/agents/{id}/rollback. Mints a new version cloning to_version — a rollback is itself a versioned change, so history stays linear and auditable.
spend
GET /v1/agents/{id}/spend — metered spend for the agent’s current budget period, integer micro-USD:
by: "component" adds a by_component breakdown — model (the five token tiers summed), computer, search, media, and other for anything a debit did not itemise. A component with no spend is absent, and the breakdown always sums to spent_micro_usd. Absent unless asked for.
delete
DELETE /v1/agents/{id}. Answers the standard { id, object, deleted: true } acknowledgement.