{ "openapi": "3.0.3", "info": { "title": "Agentomy Governance API", "description": "The governance layer for AI agents, as an API. Agentomy sits between an agent and the systems it acts on: it decides whether each action may run, holds or halts what may not, and produces a hash-linked record of every decision.\n\nThis document describes the governance surface an agent or an integrator calls: authorization and halt (claw), the audit export and its integrity check, the authority read for one agent, usage and cost metering, and the agent routes on the control plane (signup, escalation, key lifecycle). Every operation here resolves to a served route; a commit gate enforces it.\n\nScores and coverage are reproducible: the benchmarks that produce them are open and run against this API (https://agentomy.com/governancebench). Compliance readiness mappings are readiness, not certification.\n\n## Authentication\nAuthenticated operations accept an API key in the `X-API-Key` header or as a Bearer token. Keys are minted at signup or under Settings and carry a tier ceiling; policy decides each action. `/claw/authorize` and `/claw/log` are rate limited.", "version": "1.2.0", "contact": { "name": "Agentomy Engineering" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.agentomy.com/api", "description": "Governance API (production)" } ], "tags": [ { "name": "Health & Status", "description": "System health checks and readiness probes" }, { "name": "Chat & AI", "description": "Core AI chat completion, web search, and model listing" }, { "name": "Personas & Routing", "description": "Identity tier listing and intent-based persona routing" }, { "name": "Memory", "description": "Conversation memory storage, retrieval, and management" }, { "name": "Message Gateway", "description": "Slack message gateway for agent-to-channel communication" }, { "name": "Governance Bridge", "description": "Core governance endpoints for agent authorization, logging, halt/resume, status, and health. These are the primary integration points for Claw ecosystem variants (OpenClaw, NemoClaw, KiloClaw, Hermes Agent, etc.)." }, { "name": "Audit Trail", "description": "Trust chain audit export, integrity checks, and compliance reports" }, { "name": "Usage Metering", "description": "Token usage tracking, cost estimates, and breakdowns" }, { "name": "Optimization", "description": "Model routing optimization loop controller" }, { "name": "Extensions", "description": "Extension registry for modular capability plugins" }, { "name": "Agent Management", "description": "Deploy, list, inspect, and terminate agents" }, { "name": "Advanced Agent Management", "description": "Secure agent deployment, relay orchestration, persona modulation, and decision execution (requires advanced mode)" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key as a Bearer token." }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key header; accepted by the same middleware as Bearer." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } }, "AuditEvent": { "type": "object", "properties": { "id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "agent": { "type": "object", "properties": { "tier": { "type": "string", "example": "Operator" }, "id": { "type": "string" } } }, "action": { "type": "string" }, "inputHash": { "type": "string" }, "outputHash": { "type": "string" }, "trustScore": { "type": "integer" }, "chainPosition": { "type": "integer" } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } } }, "ClawAuthorizeRequest": { "type": "object", "required": [ "agentId", "action" ], "properties": { "tier": { "type": "integer", "minimum": 0, "maximum": 4, "description": "Requested registration tier on an agent's FIRST authorize call. Capped to the authenticated caller's own tier -- it can never raise an agent above the credential presented. It does NOT decide whether the first-contact write control applies: that determination is host-derived, so a caller cannot exempt itself by declaring the value the server would have defaulted to anyway." }, "agentId": { "type": "string", "description": "Unique identifier for the agent requesting authorization", "example": "agent-lexara-001" }, "action": { "type": "string", "description": "The action the agent wants to perform", "enum": [ "read", "query", "list", "search", "status", "write", "create", "update", "execute", "delete", "deploy", "configure", "halt", "override", "admin" ], "example": "write" }, "scope": { "type": "string", "description": "Optional scope context for the action. Stored as SHA-256 hash in audit trail -- raw value is never persisted.", "example": "documents/contracts" }, "clawVariant": { "type": "string", "description": "The Claw ecosystem variant making the request", "example": "OpenClaw" }, "metadata": { "type": "object", "description": "Optional additional context" }, "eventId": { "type": "string", "description": "Optional idempotency key. If provided, reused as the audit ID." }, "orchestrator_id": { "type": "string", "description": "ID of the orchestrator agent, if this is an inter-agent authorization request. Both orchestrator and sub-agent permissions are checked." }, "onBehalfOf": { "type": "string", "description": "The principal this agent acts for; judged against the delegation edge that principal granted (scope, expiry, revocation, depth); the grantor's tier bounds the action" } } }, "ClawAuthorizeResponse": { "type": "object", "properties": { "denyReason": { "type": "object", "description": "Structured explanation of a refusal, including operator-facing guidance." }, "firstContact": { "type": "boolean", "description": "True when this is the first time the governance registry has seen this agent and the first-contact control applied. Absent on ordinary decisions." }, "firstContactWriteDeniedAt": { "type": "string", "format": "date-time", "description": "When a first-contact write-class refusal was recorded. Durable across restart, so the refusal is reproducible rather than resident in process memory." }, "override_available": { "type": "boolean", "description": "Whether an operator override path exists for this refusal." }, "override_endpoint": { "type": "string", "description": "Endpoint an authorised operator uses to override this refusal." }, "override_modes": { "type": "array", "items": { "type": "string" }, "description": "Override modes the caller's tier may invoke." }, "override_tier": { "type": "string", "description": "Minimum tier required to override this refusal." }, "governanceVersion": { "type": "string", "description": "Policy version in force when this decision was made. Present on every authorize response; required to re-derive a decision under the rules that produced it." }, "timestamp": { "type": "string", "format": "date-time", "description": "When the decision was made." }, "pipeline": { "type": "object", "description": "Per-stage result of the governance pipeline phase that ran for this call." }, "policy": { "type": "object", "description": "Server-registered policy checks evaluated for this call, and whether any blocked." }, "authorized": { "type": "boolean", "description": "Whether the action is permitted for this agent's tier" }, "tier": { "type": "string", "description": "The agent's current identity tier", "example": "Builder" }, "reason": { "type": "string", "description": "Human-readable authorization decision" }, "auditId": { "type": "string", "description": "Audit trail identifier for this authorization event" }, "inter_agent_instruction": { "type": "object", "nullable": true, "description": "Present only when orchestrator_id was supplied", "properties": { "orchestrator_id": { "type": "string" }, "sub_agent_id": { "type": "string" }, "action": { "type": "string" }, "orchestrator_decision": { "type": "string", "enum": [ "ALLOW", "DENY" ] }, "sub_agent_decision": { "type": "string", "enum": [ "ALLOW", "DENY" ] } } } } }, "ClawLogRequest": { "type": "object", "required": [ "agentId", "action" ], "properties": { "agentId": { "type": "string", "description": "Unique identifier for the agent", "example": "agent-lexara-001" }, "action": { "type": "string", "description": "The action that was taken", "example": "write" }, "input": { "description": "Input data for the action (any type). Stored as SHA-256 hash only." }, "output": { "description": "Output data from the action (any type). Stored as SHA-256 hash only." }, "timestamp": { "type": "string", "format": "date-time", "description": "Optional action timestamp. Defaults to server time." }, "clawVariant": { "type": "string", "description": "The Claw ecosystem variant", "example": "OpenClaw" }, "eventId": { "type": "string", "description": "Optional idempotency key" } } }, "ClawLogResponse": { "type": "object", "properties": { "logged": { "type": "boolean", "example": true }, "auditId": { "type": "string", "description": "Audit trail block ID" }, "chainPosition": { "type": "integer", "description": "Position of this event in the agent's action chain" } } }, "ClawHaltRequest": { "type": "object", "required": [ "reason", "operatorId" ], "properties": { "agentId": { "type": "string", "description": "Target agent ID. Omit to apply a fleet-wide halt to all registered agents.", "example": "agent-lexara-001" }, "reason": { "type": "string", "description": "Human-readable reason for the halt. Stored as SHA-256 hash in audit trail.", "example": "Anomalous behavior detected" }, "operatorId": { "type": "string", "description": "Identity of the operator issuing the halt. Must match the authenticated caller's identity.\n", "example": "admin-ops-001" } } }, "ClawHaltResponse": { "type": "object", "properties": { "halted": { "type": "boolean", "example": true }, "agentsAffected": { "type": "integer", "description": "Number of agents quarantined by this halt" }, "confirmed": { "type": "boolean", "description": "Whether all targeted agents were confirmed quarantined" }, "confirmedCount": { "type": "integer", "description": "Number of agents confirmed quarantined" }, "timestamp": { "type": "string", "format": "date-time" }, "auditId": { "type": "string" }, "halt_sequence": { "type": "object", "nullable": true, "description": "Present on fleet halt -- shows coordinators halted before sub-agents", "properties": { "coordinators": { "type": "array", "items": { "type": "string" } }, "subAgents": { "type": "array", "items": { "type": "string" } } } } } }, "ClawResumeRequest": { "type": "object", "required": [ "operatorId" ], "properties": { "operatorId": { "type": "string", "description": "Identity of the operator lifting the halt. Must satisfy the same authorization check as halt. Only lifts fleet-wide halt -- individual agent quarantine must be handled separately.\n", "example": "admin-ops-001" }, "reason": { "type": "string", "description": "Optional reason for resuming. Stored as SHA-256 hash in audit trail." } } }, "ClawResumeResponse": { "type": "object", "properties": { "resumed": { "type": "boolean" }, "operatorId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "auditId": { "type": "string" }, "reason": { "type": "string", "nullable": true, "description": "Present when no fleet halt was active" } } }, "ClawStatusResponse": { "type": "object", "properties": { "agentId": { "type": "string" }, "tier": { "type": "string", "description": "Current identity tier", "example": "Builder" }, "quarantined": { "type": "boolean", "description": "Whether this agent is currently quarantined" }, "lastAction": { "type": "object", "nullable": true, "description": "Most recent action metadata. scopeHash is a SHA-256 of the original scope value.", "properties": { "action": { "type": "string" }, "scopeHash": { "type": "string", "nullable": true }, "timestamp": { "type": "string", "format": "date-time" }, "authorized": { "type": "boolean" } } }, "actionCount": { "type": "integer", "description": "Total number of actions recorded for this agent" }, "auditTrailActive": { "type": "boolean", "description": "Whether the persistent audit trail is available" } } }, "ClawHealthResponse": { "type": "object", "properties": { "bridge": { "type": "string", "enum": [ "active", "halted" ], "description": "Current bridge state" }, "fleetHaltActive": { "type": "boolean" }, "auditPersistent": { "type": "boolean", "description": "Whether the audit trail is writing to PostgreSQL" }, "registeredAgents": { "type": "integer" }, "quarantinedAgents": { "type": "integer" }, "fleetHaltReason": { "type": "string", "nullable": true, "description": "Reason for the active fleet halt (omitted when no halt is active; omitted in PUBLIC_MODE)" }, "authentication": { "type": "string", "nullable": true, "description": "Authentication mode description (omitted in PUBLIC_MODE)" }, "authRequired": { "type": "boolean", "nullable": true, "description": "Whether authentication is enforced (omitted in PUBLIC_MODE)" }, "contextSteering": { "type": "object", "nullable": true, "description": "Context steering subsystem state (omitted in PUBLIC_MODE)", "properties": { "active": { "type": "boolean" }, "registeredPayloads": { "type": "integer" }, "activeIgnoreCounters": { "type": "integer" } } } } }, "AgentEscalationRequest": { "type": "object", "required": [ "agent_name", "principal_email", "reason" ], "properties": { "agent_name": { "type": "string", "maxLength": 120 }, "principal_email": { "type": "string", "format": "email" }, "reason": { "type": "string", "maxLength": 2000 }, "context": { "type": "string", "maxLength": 4000 }, "wants": { "type": "string", "maxLength": 300 } } }, "AgentEscalationReceipt": { "type": "object", "properties": { "ticket_id": { "type": "string", "example": "esc_l8X3D-hU" }, "status": { "type": "string", "enum": [ "received" ] }, "received_at": { "type": "string", "format": "date-time" }, "human_follow_up": { "type": "boolean" }, "follow_up_channel": { "type": "string" }, "note": { "type": "string" } } }, "MachineError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Machine code: invalid_request, rate_limited, agent_signup_closed, agent_signup_capacity, challenge_failed, principal_exists, provisioning_failed, escalation_failed, invalid_key, internal_error" }, "detail": { "type": "string" }, "message": { "type": "string" }, "escalation": { "type": "object", "additionalProperties": true } } }, "AgentKeyRotation": { "type": "object", "properties": { "key": { "type": "string", "description": "The replacement key, returned exactly once" }, "hint": { "type": "string" }, "tier": { "type": "string" }, "rotated_from": { "type": "string" }, "endpoint": { "type": "string", "format": "uri" } } }, "AuthorityState": { "type": "object", "description": "agentomy.authority-state/v1: what one agent may cause right now, composed from the primitives that decide it", "properties": { "schema": { "type": "string", "example": "agentomy.authority-state/v1" }, "identity": { "type": "object", "additionalProperties": true }, "authority_ceiling": { "type": "object", "additionalProperties": true }, "standing": { "type": "object", "additionalProperties": true }, "economic": { "type": "object", "additionalProperties": true }, "evidence": { "type": "object", "additionalProperties": true }, "validity": { "type": "object", "additionalProperties": true }, "risk": { "type": "object", "additionalProperties": true }, "may_act": { "type": "boolean" }, "blocking_reasons": { "type": "array", "items": { "type": "string" } }, "unavailable": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "object", "additionalProperties": true } } }, "DelegationEdge": { "type": "object", "properties": { "id": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "scope": { "type": "array", "items": { "type": "string" } }, "purpose": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "maxDepth": { "type": "integer" }, "grantorTier": { "type": "string", "nullable": true }, "grantedBy": { "type": "string" }, "grantedAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "DelegationGrantRequest": { "type": "object", "required": [ "from", "to", "scope", "purpose" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "scope": { "type": "array", "items": { "type": "string" }, "description": "Actions the delegate may take on the grantor's behalf; never wider than the grantor's tier permits" }, "purpose": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "maxDepth": { "type": "integer", "minimum": 0, "maximum": 8, "description": "Further hops that may be delegated beneath the delegate; 0 means none" } } }, "AgentCertificate": { "type": "object", "description": "AgentCertificate v1 or v2. The JSON Schemas are served at https://agentomy.com/schemas/agent-cert-v1.json and https://agentomy.com/schemas/agent-cert-v2.json. v2 adds principal, delegation_ref, governance_status and conformance_profile inside the signed payload.", "properties": { "agentomy_cert_version": { "type": "string", "enum": [ "1.0", "2.0" ] }, "agent_id": { "type": "string" }, "tier": { "type": "string" }, "public_key": { "type": "object", "additionalProperties": true }, "issued_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "key_rotation_marker": { "type": "object", "additionalProperties": true }, "chain_anchor": { "type": "object", "additionalProperties": true }, "issuer": { "type": "object", "additionalProperties": true }, "signature": { "type": "object", "additionalProperties": true }, "principal": { "type": "object", "additionalProperties": true }, "delegation_ref": { "type": "object", "additionalProperties": true }, "governance_status": { "type": "object", "additionalProperties": true }, "conformance_profile": { "type": "object", "additionalProperties": true } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "paths": { "/health": { "get": { "tags": [ "Health & Status" ], "summary": "System health check", "description": "Returns system health, uptime, conversation memory stats, orchestrator stats,\nand audit trail status. No authentication required. In PUBLIC_MODE, internal\nstats (failedWrites, queuedEvents) are stripped from the audit trail object.\n\nStatus is `degraded` when the audit trail persistence layer is down and\nfailed writes have been detected.\n", "security": [], "responses": { "200": { "description": "Health status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded" ] }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string", "example": "1.0.0" }, "uptime": { "type": "number", "description": "Server uptime in seconds" }, "memory": { "type": "object", "description": "Conversation memory statistics" }, "orchestrator": { "type": "object", "description": "Orchestrator statistics" }, "auditTrail": { "type": "object", "properties": { "persistent": { "type": "boolean", "description": "Whether PostgreSQL audit persistence is connected" }, "failedWrites": { "type": "integer" }, "queuedEvents": { "type": "integer" }, "degraded": { "type": "boolean" } } }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Present only when status is degraded" } } }, "example": { "status": "healthy", "timestamp": "2026-04-17T10:00:00.000Z", "version": "1.0.0", "uptime": 3600, "memory": { "conversations": 12, "totalTurns": 84 }, "orchestrator": { "totalExecutions": 45, "activeAgents": 3 }, "auditTrail": { "persistent": true, "failedWrites": 0, "queuedEvents": 0, "degraded": false } } } } } } } }, "/audit/export": { "get": { "tags": [ "Audit Trail" ], "summary": "Export audit events (paginated)", "description": "Returns paginated audit events from the trust chain ledger.\nSupports filtering by date range, agent tier, and event type.\nRate limited to 20 requests per 10-minute window.\n", "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 }, "description": "Page number (1-based)" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Events per page (max 200)" }, { "in": "query", "name": "startDate", "schema": { "type": "string", "format": "date-time" }, "description": "Filter events after this date" }, { "in": "query", "name": "endDate", "schema": { "type": "string", "format": "date-time" }, "description": "Filter events before this date" }, { "in": "query", "name": "agentTier", "schema": { "type": "string", "enum": [ "Analyst", "Builder", "Operator", "Strategist" ] }, "description": "Filter by identity tier" }, { "in": "query", "name": "eventType", "schema": { "type": "string" }, "description": "Filter by event type" } ], "responses": { "200": { "description": "Paginated audit events", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "source": { "type": "string", "enum": [ "persistent", "in-memory" ], "description": "Whether events came from PostgreSQL or the in-memory trust chain" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "example": { "success": true, "source": "persistent", "data": [ { "id": "block_001", "timestamp": "2026-04-17T10:00:00.000Z", "capsule": "claw-bridge:authorize", "agent": { "tier": "Builder", "id": "[redacted]" }, "action": "claw-bridge:authorize", "inputHash": null, "outputHash": null, "trustScore": 100, "chainPosition": 1, "persistent": true } ], "pagination": { "page": 1, "limit": 50, "total": 142, "totalPages": 3, "hasNext": true, "hasPrev": false } } } } }, "401": { "description": "Authentication required" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Server error" } } } }, "/audit/export/summary": { "get": { "tags": [ "Audit Trail" ], "summary": "Audit summary statistics", "description": "Aggregated trust chain statistics including event counts by tier and type.", "security": [], "responses": { "200": { "description": "Summary stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "summary": { "type": "object", "properties": { "totalEvents": { "type": "integer" }, "eventsByTier": { "type": "object" }, "eventsByType": { "type": "object" }, "timeRange": { "type": "object", "nullable": true, "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } }, "chainIntegrity": { "type": "boolean" } } } } }, "example": { "success": true, "summary": { "totalEvents": 142, "eventsByTier": { "Analyst": 35, "Builder": 42, "Operator": 50, "Strategist": 15 }, "eventsByType": { "chat_completion": 120, "search": 22 }, "timeRange": { "start": "2026-03-01T00:00:00.000Z", "end": "2026-03-28T12:00:00.000Z" }, "chainIntegrity": true } } } } } } } }, "/audit/export/report": { "get": { "tags": [ "Audit Trail" ], "summary": "Compliance audit report", "description": "Generates a formatted compliance audit report. In PUBLIC_MODE, all fields are scrubbed.", "security": [], "responses": { "200": { "description": "Audit report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "report": { "type": "object" } } } } } }, "500": { "description": "Server error" } } } }, "/audit/export/integrity": { "get": { "tags": [ "Audit Trail" ], "summary": "Trust chain integrity check", "description": "Validates the integrity of the trust chain ledger and reports any tamper-detection issues.", "security": [], "responses": { "200": { "description": "Integrity result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "valid": { "type": "boolean" }, "blocksChecked": { "type": "integer" }, "issues": { "type": "array", "items": { "type": "string" } } } }, "example": { "success": true, "valid": true, "blocksChecked": 142, "issues": [] } } } } } } }, "/claw/authorize": { "post": { "tags": [ "Governance Bridge" ], "summary": "Authorize an agent action", "description": "Primary governance endpoint. An agent calls this before executing any action.\nAgentomy checks the agent's identity tier, quarantine status, and behavioral\nhistory before returning an authorization decision.\n\nThe request is also passed through the behavioral monitor. If behavioral anomalies\nare detected but below the quarantine threshold, a `steer` object is included in\nthe response -- the action is still permitted but the agent receives corrective guidance.\n\nWhen `orchestrator_id` is provided, both the sub-agent and the orchestrator must\nhave permission for the action, and the action class must be in the orchestrator's\nauthorized instruction classes.\n\nRate limited to 100 requests per 10-minute window.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClawAuthorizeRequest" }, "example": { "agentId": "agent-lexara-001", "action": "write", "scope": "documents/contracts", "clawVariant": "OpenClaw" } } } }, "responses": { "200": { "description": "Authorization decision (always 200 -- check `authorized` field)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClawAuthorizeResponse" }, "examples": { "permitted": { "summary": "Action permitted", "value": { "authorized": true, "tier": "Builder", "reason": "Action permitted for tier", "auditId": "claw_1714000000000_a1b2c3d4" } }, "denied_quarantine": { "summary": "Agent quarantined", "value": { "authorized": false, "tier": "Builder", "reason": "Agent is quarantined", "auditId": "claw_1714000000000_a1b2c3d4" } }, "denied_fleet_halt": { "summary": "Fleet halt active", "value": { "authorized": false, "tier": "Builder", "reason": "Fleet halt active since 2026-04-17T10:00:00.000Z", "auditId": "claw_1714000000000_a1b2c3d4" } } } } } }, "400": { "description": "Missing required fields (agentId or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "agentId and action are required" } } } }, "401": { "description": "Authentication required" }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Rate limit exceeded for governance bridge" } } } } } } }, "/claw/log": { "post": { "tags": [ "Governance Bridge" ], "summary": "Log an agent action", "description": "Records a completed agent action to the governance audit trail. The input and\noutput are stored as SHA-256 hashes -- raw content is never persisted.\n\nEach log entry is appended to the agent's hash-linked audit chain and optionally\nsigned with a post-quantum signature (ML-DSA when PQC module is available).\n\nRate limited to 100 requests per 10-minute window.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClawLogRequest" }, "example": { "agentId": "agent-lexara-001", "action": "write", "input": { "document": "contract_draft_v2.docx" }, "output": { "status": "saved", "bytes": 42816 }, "clawVariant": "OpenClaw" } } } }, "responses": { "200": { "description": "Action logged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClawLogResponse" }, "example": { "logged": true, "auditId": "claw_1714000000001_b2c3d4e5", "chainPosition": 7 } } } }, "400": { "description": "Missing required fields (agentId or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "429": { "description": "Rate limit exceeded" } } } }, "/claw/halt": { "post": { "tags": [ "Governance Bridge" ], "summary": "Halt an agent or the entire fleet", "description": "Emergency halt control. When `agentId` is provided, only that agent is quarantined.\nWhen `agentId` is omitted, a fleet-wide halt is triggered: all registered agents\nare quarantined and the global halt flag is set. The halt flag is persisted to\nPostgreSQL and survives container restarts.\n\nCoordinators are always quarantined before sub-agents in a fleet halt.\n\nThis endpoint is never rate-limited. Authentication is required.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClawHaltRequest" }, "example": { "reason": "Anomalous behavior -- emergency stop", "operatorId": "admin-security-001" } } } }, "responses": { "200": { "description": "Halt executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClawHaltResponse" }, "example": { "halted": true, "agentsAffected": 12, "confirmed": true, "confirmedCount": 12, "timestamp": "2026-04-17T10:30:00.000Z", "auditId": "claw_1714000000002_c3d4e5f6" } } } }, "400": { "description": "Missing required fields (reason or operatorId)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "reason and operatorId are required" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Unauthorized operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "identity_mismatch": { "summary": "Production -- operatorId does not match authenticated caller", "value": { "error": "Operator identity mismatch", "authorized": false } }, "unauthorized": { "summary": "operatorId not authorized", "value": { "error": "Unauthorized operator", "authorized": false } } } } } } } } }, "/claw/resume": { "post": { "tags": [ "Governance Bridge" ], "summary": "Resume after a fleet halt", "description": "Lifts an active fleet-wide halt. Clears the in-memory halt flag and removes\nthe persisted halt state from PostgreSQL.\n\nThis endpoint only affects the fleet halt flag -- individually quarantined agents\nremain quarantined. This endpoint is never rate-limited. Authentication is required.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClawResumeRequest" }, "example": { "operatorId": "admin-security-001", "reason": "Incident resolved -- resuming operations" } } } }, "responses": { "200": { "description": "Fleet resumed (or no halt was active)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClawResumeResponse" }, "examples": { "resumed": { "summary": "Halt lifted", "value": { "resumed": true, "operatorId": "admin-security-001", "timestamp": "2026-04-17T11:00:00.000Z", "auditId": "claw_1714000000003_d4e5f6a7" } }, "no_halt": { "summary": "No halt was active", "value": { "resumed": false, "reason": "No fleet halt is active" } } } } } }, "400": { "description": "Missing operatorId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Unauthorized operator" } } } }, "/claw/status/{agentId}": { "get": { "tags": [ "Governance Bridge" ], "summary": "Get governance status for an agent", "description": "Returns the current governance state for a registered agent: identity tier,\nquarantine status, last action (with hashed scope), and total action count.\n\nReturns 404 if the agent has never called /authorize or /log (not yet registered).\n", "parameters": [ { "in": "path", "name": "agentId", "required": true, "schema": { "type": "string" }, "description": "The agent identifier", "example": "agent-lexara-001" } ], "responses": { "200": { "description": "Agent governance status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClawStatusResponse" }, "example": { "agentId": "agent-lexara-001", "tier": "Builder", "quarantined": false, "lastAction": { "action": "write", "scopeHash": "sha256:a3f1b2c4...", "timestamp": "2026-04-17T10:45:00.000Z", "authorized": true }, "actionCount": 7, "auditTrailActive": true } } } }, "401": { "description": "Authentication required" }, "404": { "description": "Agent not registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Agent not registered" } } } } } } }, "/claw/health": { "get": { "tags": [ "Governance Bridge" ], "summary": "Governance bridge health check", "description": "Returns the operational state of the governance bridge: fleet halt status,\naudit trail persistence, registered agent count, and quarantine count.\n\nIn PUBLIC_MODE, internal fields (fleetHaltReason, authentication, authRequired,\ncontextSteering) are omitted from the response.\n\nThis endpoint is never rate-limited and does not require authentication.\n", "security": [], "responses": { "200": { "description": "Bridge health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClawHealthResponse" }, "examples": { "public_mode": { "summary": "PUBLIC_MODE response", "value": { "bridge": "active", "auditPersistent": true, "registeredAgents": 5, "quarantinedAgents": 0, "fleetHaltActive": false } }, "internal": { "summary": "Full response (non-PUBLIC_MODE)", "value": { "bridge": "active", "fleetHaltActive": false, "auditPersistent": true, "registeredAgents": 5, "quarantinedAgents": 0, "authentication": "required", "authRequired": true, "contextSteering": { "active": true, "registeredPayloads": 0, "activeIgnoreCounters": 0 } } } } } } } } } }, "/metering/usage": { "get": { "tags": [ "Usage Metering" ], "summary": "Aggregated usage data", "description": "Returns aggregated token usage data with optional date range and grouping.", "parameters": [ { "in": "query", "name": "startDate", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "endDate", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "groupBy", "schema": { "type": "string", "enum": [ "tier", "model", "hour", "day" ] }, "description": "Group results by dimension" } ], "responses": { "200": { "description": "Aggregated usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } }, "401": { "description": "Authentication required" } } } }, "/metering/summary": { "get": { "tags": [ "Usage Metering" ], "summary": "Quick usage summary", "description": "Returns high-level summary statistics for usage metering.", "responses": { "200": { "description": "Summary stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } }, "401": { "description": "Authentication required" } } } }, "/metering/top-models": { "get": { "tags": [ "Usage Metering" ], "summary": "Top models by usage", "description": "Returns the most-used models ranked by token consumption.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 5 }, "description": "Number of top models to return" } ], "responses": { "200": { "description": "Top models", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "Authentication required" } } } }, "/metering/by-tier": { "get": { "tags": [ "Usage Metering" ], "summary": "Usage breakdown by identity tier", "description": "Returns token usage broken down by identity tier (Analyst, Builder, Operator, Strategist).", "responses": { "200": { "description": "Per-tier usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } }, "401": { "description": "Authentication required" } } } }, "/metering/cost": { "get": { "tags": [ "Usage Metering" ], "summary": "Cost estimate", "description": "Returns estimated cost based on token usage and model pricing.", "responses": { "200": { "description": "Cost estimate", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } }, "401": { "description": "Authentication required" } } } }, "/metering/status": { "get": { "tags": [ "Usage Metering" ], "summary": "Metering system status", "description": "Returns the operational status of the usage metering subsystem.", "responses": { "200": { "description": "Metering status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } }, "401": { "description": "Authentication required" } } } }, "/agent/signup/challenge": { "servers": [ { "url": "https://agentomy.com/api", "description": "Control plane (agent acquisition, escalation, key lifecycle)" } ], "get": { "summary": "Fetch a signed, expiring proof-of-work challenge", "tags": [ "Agent acquisition" ], "security": [], "responses": { "200": { "description": "Challenge token, difficulty bits and TTL", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Agent-native signup is closed; body carries an escalation object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "429": { "description": "Rate limited; Retry-After header set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } } } } }, "/agent/signup": { "servers": [ { "url": "https://agentomy.com/api", "description": "Control plane (agent acquisition, escalation, key lifecycle)" } ], "post": { "summary": "Create a governed free workspace as an agent acting for a principal", "tags": [ "Agent acquisition" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Challenge token, proof-of-work solution, agent name, principal email and organization (see llms-full.txt for the exact body)" } } } }, "responses": { "201": { "description": "Workspace created; the API key is returned exactly once with its tier ceiling", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "invalid_request or challenge_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "409": { "description": "principal_exists, with an escalation object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "503": { "description": "agent_signup_closed or agent_signup_capacity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } } } } }, "/agent/escalate": { "servers": [ { "url": "https://agentomy.com/api", "description": "Control plane (agent acquisition, escalation, key lifecycle)" } ], "post": { "summary": "Record a structured escalation a human follows up on", "tags": [ "Agent acquisition" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEscalationRequest" } } } }, "responses": { "202": { "description": "Ticket recorded; the principal is acknowledged by email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEscalationReceipt" } } } }, "400": { "description": "invalid_request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "502": { "description": "escalation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } } } } }, "/agent/key": { "servers": [ { "url": "https://agentomy.com/api", "description": "Control plane (agent acquisition, escalation, key lifecycle)" } ], "post": { "summary": "Rotate the presented agent key (the old key stops working)", "tags": [ "Agent acquisition" ], "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Replacement key, returned exactly once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentKeyRotation" } } } }, "401": { "description": "invalid_key: the presented key is unknown, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } } } }, "delete": { "summary": "Revoke the presented agent key", "tags": [ "Agent acquisition" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" }, "hint": { "type": "string" } } } } } }, "401": { "description": "invalid_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } } } } }, "/authority/{agentId}": { "get": { "summary": "Authority state of one agent: what it may cause right now", "tags": [ "Authority" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Composed from tier, feature ceiling, halt, quarantine, budget, policy freshness, decision validity, last authorization and the behavioral read; missing sources are listed under unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "authority": { "$ref": "#/components/schemas/AuthorityState" } } } } } }, "401": { "description": "Authentication required" } } } }, "/claw/delegate": { "post": { "summary": "Grant a bounded delegation (scope, purpose, expiry, depth) from one agent to another", "tags": [ "Governance" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationGrantRequest" } } } }, "responses": { "201": { "description": "Edge created; recorded on the chain as an authority event", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "edge": { "$ref": "#/components/schemas/DelegationEdge" }, "auditId": { "type": "string" } } } } } }, "400": { "description": "Refused: scope wider than the grantor's tier, depth exhausted, cycle, or a malformed field (reason names it)" }, "403": { "description": "Only the grantor itself or an Operator may create a delegation" }, "401": { "description": "Authentication required" } } } }, "/claw/delegate/{edgeId}": { "delete": { "summary": "Revoke a delegation edge; every chain beneath it stops working", "tags": [ "Governance" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "edgeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked; recorded on the chain as a revocation event", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "edge": { "$ref": "#/components/schemas/DelegationEdge" } } } } } }, "404": { "description": "Unknown edge" }, "409": { "description": "Already revoked" }, "403": { "description": "Only the grantor itself or an Operator may revoke" }, "401": { "description": "Authentication required" } } } }, "/claw/delegations/{agentId}": { "get": { "summary": "Active delegation edges from and to an agent, and its depth in the delegation graph", "tags": [ "Governance" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Edges and depth", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string" }, "depth": { "type": "integer" }, "from": { "type": "array", "items": { "$ref": "#/components/schemas/DelegationEdge" } }, "to": { "type": "array", "items": { "$ref": "#/components/schemas/DelegationEdge" } } } } } } }, "401": { "description": "Authentication required" } } } }, "/auth/cert/issue": { "post": { "summary": "Issue an AgentCertificate (v1 by default; v2 when a principal or delegationRef is given)", "tags": [ "Trust" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentId" ], "properties": { "agentId": { "type": "string" }, "tier": { "type": "string", "description": "Requested tier, capped to the caller's own" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "principal": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "human", "organization", "agent", "service" ] }, "ref": { "type": "string", "nullable": true } }, "description": "v2: who the agent acts for" }, "delegationRef": { "type": "object", "properties": { "edge_id": { "type": "string" } }, "description": "v2: an active delegation edge that ends at this agent; refused otherwise" } } } } } }, "responses": { "201": { "description": "Certificate, private key (once), public key, hash, version; governance_status is read server-side, conformance_profile is the issuer's", "content": { "application/json": { "schema": { "type": "object", "properties": { "cert": { "$ref": "#/components/schemas/AgentCertificate" }, "privateKeyDer": { "type": "string" }, "publicKeyDer": { "type": "string" }, "certHash": { "type": "string" }, "version": { "type": "string" }, "tierCapped": { "type": "boolean" } } } } } }, "400": { "description": "Malformed principal, unknown or inactive delegation edge, or an edge that does not end at this agent" }, "403": { "description": "Issuing for another agent requires Builder" }, "401": { "description": "Authentication required" } } } }, "/auth/cert/verify": { "post": { "summary": "Verify a presented AgentCertificate: structure, signature, expiry, and for v2 whether the referenced delegation edge still stands", "tags": [ "Trust" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cert" ], "properties": { "cert": { "$ref": "#/components/schemas/AgentCertificate" } } } } } }, "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "signatureValid": { "type": "boolean" }, "expired": { "type": "boolean" }, "version": { "type": "string" }, "agentId": { "type": "string" }, "tier": { "type": "string" }, "certHash": { "type": "string" }, "delegation": { "type": "object", "properties": { "edgeId": { "type": "string" }, "known": { "type": "boolean" }, "active": { "type": "boolean" } } } } } } } }, "401": { "description": "Authentication required" } } } } } }