Skip to main content

Agents API

All routes require an admin bearer token.

POST /v1/agents​

Register a new agent with its first manifest version.

Request body (AgentCreate):

{
  "name": "kb-search-agent",
  "manifest": { "...": "AgentManifest, see Reference → Agent Manifest schema" },
  "override": { "reason": "optional, only to accept a needs_review outcome" }
}

Responses:

StatusBodyWhen
201{agent_id, manifest_version, status: "reconciled"}Manifest matched discovered capabilities
422{error.code: "reconciliation_rejected", details.diff[]}A hard reconciliation conflict
409{error.code: "needs_review", details.diff[]}Discovery unavailable, no override supplied
401{error.code: "unauthorized"}Missing/invalid bearer

GET /v1/agents​

Paginated agent list.

Query params: limit, cursor (opaque keyset cursor)

Response (Page[AgentListItem]):

{
  "data": [
    {"id": "...", "name": "kb-search-agent", "latest_manifest_version": 1, "latest_status": "reconciled"}
  ],
  "page": {"next_cursor": "...", "limit": 20}
}

GET /v1/agents/{agent_id}/reconciliation​

The most recent reconciliation report for an agent.

Response (ReconciliationReport):

{"manifest_version": 1, "status": "reconciled", "discovery_ok": true, "diff": []}

404 if the agent doesn't exist.