The published governance API, operation by operation.

Base URL and authentication

Hosted workspaces call https://api.agentomy.com/api. A self-hosted deployment serves the same paths under its own origin. Authenticated operations accept either scheme; workspace API keys are shown once at creation and the control plane stores only a hint.

One global limiter of 100 requests per 15 minutes per client; audit export operations use a stricter 20 per 10 minutes. Rate-limited responses carry Retry-After. A plan sets the ceiling tier a workspace key can carry; policy decides each action (see tiers).

Health & Status

GET /health Returns system health, uptime, conversation memory stats, orchestrator stats, and audit trail status. No authentication required. In PUBLIC_MODE, internal stats (failedWrites, queuedEvents) are stripped from the audit trail object. Status is `degraded` when the audit trail persistence layer is down and failed writes have been detected.

Governance Bridge

POST /claw/authorize Primary governance endpoint. An agent calls this before executing any action. Agentomy checks the agent's identity tier, quarantine status, and behavioral history before returning an authorization decision. The request is also passed through the behavioral monitor. If behavioral anomalies are detected but below the quarantine threshold, a `steer` object is included in the response -- the action is still permitted but the agent receives corrective guidance. When `orchestrator_id` is provided, both the sub-agent and the orchestrator must have permission for the action, and the action class must be in the orchestrator's authorized instruction classes. Rate limited to 100 requests per 10-minute window.

POST /claw/halt Emergency halt control. When `agentId` is provided, only that agent is quarantined. When `agentId` is omitted, a fleet-wide halt is triggered: all registered agents are quarantined and the global halt flag is set. The halt flag is persisted to PostgreSQL and survives container restarts. Coordinators are always quarantined before sub-agents in a fleet halt. This endpoint is never rate-limited. Authentication is required.

GET /claw/health Returns the operational state of the governance bridge: fleet halt status, audit trail persistence, registered agent count, and quarantine count. In PUBLIC_MODE, internal fields (fleetHaltReason, authentication, authRequired, contextSteering) are omitted from the response. This endpoint is never rate-limited and does not require authentication.

POST /claw/log Records a completed agent action to the governance audit trail. The input and output are stored as SHA-256 hashes -- raw content is never persisted. Each log entry is appended to the agent's hash-linked audit chain and optionally signed with a post-quantum signature (ML-DSA when PQC module is available). Rate limited to 100 requests per 10-minute window.

POST /claw/resume Lifts an active fleet-wide halt. Clears the in-memory halt flag and removes the persisted halt state from PostgreSQL. This endpoint only affects the fleet halt flag -- individually quarantined agents remain quarantined. This endpoint is never rate-limited. Authentication is required.

GET /claw/status/{agentId} Returns the current governance state for a registered agent: identity tier, quarantine status, last action (with hashed scope), and total action count. Returns 404 if the agent has never called /authorize or /log (not yet registered).

Governance

Authority

Trust

Audit Trail

GET /audit/export Returns paginated audit events from the trust chain ledger. Supports filtering by date range, agent tier, and event type. Rate limited to 20 requests per 10-minute window.

GET /audit/export/integrity Validates the integrity of the trust chain ledger and reports any tamper-detection issues.

GET /audit/export/report Generates a formatted compliance audit report. In PUBLIC_MODE, all fields are scrubbed.

GET /audit/export/summary Aggregated trust chain statistics including event counts by tier and type.

Usage Metering

GET /metering/by-tier Returns token usage broken down by identity tier (Analyst, Builder, Operator, Strategist).

GET /metering/cost Returns estimated cost based on token usage and model pricing.

GET /metering/status Returns the operational status of the usage metering subsystem.

GET /metering/summary Returns high-level summary statistics for usage metering.

GET /metering/top-models Returns the most-used models ranked by token consumption.

GET /metering/usage Returns aggregated token usage data with optional date range and grouping.

Agent acquisition

Machine files beside this reference

• openapi.json: the document this page is rendered from.
• service.json: the service descriptor: endpoints, acquisition, trust, what is governed.
• benchmark-manifest.json: the published result manifest, rendered from the verification receipt.
• changes.json: a feed of every change to a published figure.
• api-catalog: the linkset that lists all of the above.

Endpoints outside this surface exist for operators of a deployment and are described in the operator manual, not here. Governance tools are also hosted over the Model Context Protocol at POST /mcp on the API host.