{"openapi":"3.1.0","info":{"title":"AgentLattice API","version":"1.0.0","description":"Governance, identity, and audit infrastructure for AI agents. Submit actions, manage delegations, query policies, and verify audit chains — all scoped to the calling agent via Bearer token auth.","contact":{"name":"AgentLattice","url":"https://www.agentlattice.io"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://www.agentlattice.io","description":"Production"},{"url":"http://localhost:3000","description":"Development"}],"security":[{"BearerAuth":[]}],"paths":{"/api/v1/actions":{"post":{"operationId":"submitAction","summary":"Submit an action","description":"Submit an agent action for policy evaluation. The action is evaluated against org policies, written to the audit trail, and either auto-executed, routed for approval, or denied based on policy conditions.","tags":["Actions"],"parameters":[{"name":"X-AL-Event-ID","in":"header","description":"Idempotency key. If an audit event with this ID already exists, the original result is returned.","schema":{"type":"string"}},{"name":"X-AL-Delegation-ID","in":"header","description":"Delegation ID when acting under delegated scope. Triggers delegation verification before policy evaluation.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionRequest"}}}},"responses":{"200":{"description":"Action evaluated — executed, denied, or idempotent duplicate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResponse"}}}},"202":{"description":"Action requires approval. Approvers have been notified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalPendingResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/delegate":{"post":{"operationId":"createDelegation","summary":"Create ephemeral sub-agent","description":"Atomically creates an ephemeral child agent and grants it a scoped delegation from the calling parent agent. Returns the child's API key and delegation ID. Max 10 active ephemeral children per parent.","tags":["Delegations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegateRequest"}}}},"responses":{"200":{"description":"Ephemeral agent created with delegation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/delegate/{id}":{"delete":{"operationId":"cleanupDelegation","summary":"Clean up ephemeral delegation","description":"Revokes an ephemeral delegation and deactivates the child agent. Idempotent — already-revoked delegations return 200. Called by SDK cleanup (try/finally).","tags":["Delegations"],"parameters":[{"name":"id","in":"path","required":true,"description":"Delegation ID to revoke.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Delegation revoked and child agent deactivated.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/agent/status":{"get":{"operationId":"getAgentStatus","summary":"Agent status check","description":"Returns the agent's current circuit breaker state, calibration progress, and anomaly summary for the past 24 hours.","tags":["Agent"],"responses":{"200":{"description":"Agent status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentStatusResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/whoami":{"get":{"operationId":"whoami","summary":"Agent self-identity","description":"Returns the agent's config, applicable policies, circuit breaker state, calibration progress, and active delegations. The single-call identity endpoint for agent bootstrap.","tags":["Agent"],"responses":{"200":{"description":"Agent identity and state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhoamiResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/policies":{"get":{"operationId":"listPolicies","summary":"List policies","description":"List active policies for the agent's org. Scope 'own' returns only policies matching action types this agent has used; 'org' returns all active org policies.","tags":["Policies"],"parameters":[{"name":"scope","in":"query","description":"Policy scope. 'own' (default) filters to this agent's action types; 'org' returns all org policies.","schema":{"type":"string","enum":["own","org"],"default":"own"}}],"responses":{"200":{"description":"List of policies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PoliciesResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/policies/check":{"get":{"operationId":"checkPolicy","summary":"Dry-run policy check","description":"Evaluate policy conditions against an action type without creating an audit event or approval request. The canI() dry-run endpoint.","tags":["Policies"],"parameters":[{"name":"action_type","in":"query","required":true,"description":"The action type to check against policies.","schema":{"type":"string"}}],"responses":{"200":{"description":"Policy check result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyCheckResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/audit":{"get":{"operationId":"listAuditEvents","summary":"Audit trail","description":"Agent's own audit trail with cursor-based pagination. Agents can only see their own audit events.","tags":["Audit"],"parameters":[{"name":"cursor","in":"query","description":"Audit event ID to start after (exclusive). For pagination.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Max rows to return (1-200).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"action_type","in":"query","description":"Filter by action type.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated audit events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/audit/verify":{"get":{"operationId":"verifyAuditChain","summary":"Chain integrity verification","description":"Verify the integrity of the agent's org audit hash chain. Returns chain validity, total rows verified, and the chain hash.","tags":["Audit"],"responses":{"200":{"description":"Chain verification result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChainVerifyResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/delegations":{"get":{"operationId":"listDelegations","summary":"List own delegations","description":"List delegations where this agent is either parent or child. Filter by role and active status.","tags":["Delegations"],"parameters":[{"name":"role","in":"query","description":"Filter by delegation role.","schema":{"type":"string","enum":["parent","child"]}},{"name":"active_only","in":"query","description":"Exclude expired/revoked delegations.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"List of delegations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegationsListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/delegations/revoke":{"post":{"operationId":"revokeDelegation","summary":"Revoke own child delegation","description":"Revoke a delegation where this agent is the parent. Only the parent agent can revoke. This is agent self-management, not org-admin.","tags":["Delegations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["delegation_id"],"properties":{"delegation_id":{"type":"string","format":"uuid","description":"ID of the delegation to revoke."}}}}}},"responses":{"200":{"description":"Delegation revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"delegation_id":{"type":"string","format":"uuid"}},"required":["ok","delegation_id"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Delegation not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Delegation already revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/report":{"post":{"operationId":"reportOutcome","summary":"Report action outcome","description":"Submit outcome feedback for an audit event. Agents can only report on their own events. Idempotent — last write wins via upsert.","tags":["Reporting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRequest"}}}},"responses":{"201":{"description":"Outcome recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Audit event not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/posture":{"get":{"operationId":"getPosture","summary":"Governance health score","description":"Governance health score (0-100) for the calling agent. Composed of four equally-weighted components: policy coverage, approval rate, anomaly frequency, and chain integrity.","tags":["Governance"],"responses":{"200":{"description":"Governance posture score and component breakdown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostureResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Agent API key passed as a Bearer token. Issued per operator_config in the AgentLattice dashboard."}},"responses":{"BadRequest":{"description":"Invalid request parameters or body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid Bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Authenticated but not authorized for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnavailable":{"description":"Backend service or database unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable detail."},"detail":{"type":"string","description":"Additional context."}}},"ActionRequest":{"type":"object","required":["action_type","timestamp"],"properties":{"action_type":{"type":"string","description":"The type of action being performed (e.g., 'code.commit', 'data.read')."},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp. Must be within 5 minutes of server time."},"data_accessed":{"type":"array","items":{"$ref":"#/components/schemas/DataAccessedEntry"},"description":"What data was accessed during this action."},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata. Namespaced under 'user_metadata' in audit trail."},"repo":{"type":"string","description":"Repository identifier (used in delegation scope enforcement)."},"pr_size":{"type":"integer","description":"Pull request size in lines (used in delegation scope enforcement)."}}},"DataAccessedEntry":{"type":"object","required":["type","count","sensitivity"],"properties":{"type":{"type":"string"},"count":{"type":"integer"},"sensitivity":{"type":"string","enum":["low","medium","high","critical"]}}},"ActionResponse":{"type":"object","properties":{"status":{"type":"string","enum":["executed","denied","policy_not_found"],"description":"Outcome of policy evaluation."},"audit_event_id":{"type":"string","format":"uuid"},"policy_name":{"type":"string"},"denial_reason":{"type":"string","enum":["CONDITIONS_DENIED","POLICY_TAMPERED"]},"conditions_evaluated":{"type":"array","items":{"$ref":"#/components/schemas/ConditionResult"}},"message":{"type":"string"},"idempotent":{"type":"boolean","description":"True if this is a duplicate submission matched by X-AL-Event-ID."}}},"ConditionResult":{"type":"object","properties":{"field":{"type":"string"},"operator":{"type":"string"},"expected":{},"result":{"type":"boolean"}}},"ApprovalPendingResponse":{"type":"object","required":["status","audit_event_id","approval_id"],"properties":{"status":{"type":"string","const":"requested"},"audit_event_id":{"type":"string","format":"uuid"},"approval_id":{"type":"string","format":"uuid"},"message":{"type":"string"},"timeout_at":{"type":"string","format":"date-time"}}},"DelegateRequest":{"type":"object","required":["name","capabilities","ttl_seconds"],"properties":{"name":{"type":"string","description":"Display name for the ephemeral child agent."},"capabilities":{"type":"array","items":{"type":"string","maxLength":100},"minItems":1,"maxItems":100,"description":"Action types the child agent is allowed to perform."},"ttl_seconds":{"type":"integer","minimum":1,"description":"Time-to-live for the delegation in seconds."}}},"DelegateResponse":{"type":"object","required":["delegation_id","child_api_key","child_config_id","expires_at"],"properties":{"delegation_id":{"type":"string","format":"uuid"},"child_api_key":{"type":"string","description":"Bearer token for the ephemeral child agent."},"child_config_id":{"type":"string","format":"uuid"},"expires_at":{"type":"string","format":"date-time"}}},"AgentStatusResponse":{"type":"object","properties":{"config_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"cb_state":{"$ref":"#/components/schemas/CircuitBreakerState"},"calibration":{"type":"object","properties":{"action_count":{"type":"integer"},"complete":{"type":"boolean"}}},"anomalies_24h":{"type":"object","properties":{"count":{"type":"integer"},"max_score":{"type":"number"}}}}},"CircuitBreakerState":{"type":"string","enum":["CALIBRATING","MONITORING","WARN","THROTTLE","HALT","KILLED"]},"WhoamiResponse":{"type":"object","required":["config_id","name","org_id","is_active","cb_state"],"properties":{"config_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"org_id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"cb_state":{"$ref":"#/components/schemas/CircuitBreakerState"},"calibration":{"type":"object","properties":{"actions":{"type":"integer"},"complete":{"type":"boolean"}}},"policies":{"type":"array","items":{"$ref":"#/components/schemas/PolicySummary"}},"delegations":{"type":"object","properties":{"as_parent":{"type":"array","items":{"$ref":"#/components/schemas/DelegationEntry"}},"as_child":{"type":"array","items":{"$ref":"#/components/schemas/DelegationEntry"}}}}}},"PolicySummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"action_type":{"type":"string"},"approval_required":{"type":"boolean"},"conditions":{"type":["object","null"]},"is_active":{"type":"boolean"},"version":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"PoliciesResponse":{"type":"object","required":["scope","policies"],"properties":{"scope":{"type":"string","enum":["own","org"]},"policies":{"type":"array","items":{"$ref":"#/components/schemas/PolicySummary"}}}},"PolicyCheckResponse":{"type":"object","required":["allowed"],"properties":{"allowed":{"type":"boolean"},"needs_approval":{"type":"boolean"},"reason":{"type":"string","enum":["NO_POLICY","CONDITIONS_DENIED"]},"policy_name":{"type":"string"},"action_type":{"type":"string"},"conditions_evaluated":{"type":"array","items":{"$ref":"#/components/schemas/ConditionResult"}}}},"AuditEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"action_type":{"type":"string"},"repo":{"type":["string","null"]},"branch":{"type":["string","null"]},"pr_number":{"type":["integer","null"]},"status":{"type":"string","enum":["executed","approved","denied","requested","policy_not_found"]},"data_accessed":{"type":"array","items":{"$ref":"#/components/schemas/DataAccessedEntry"}},"timestamp":{"type":"string","format":"date-time"},"policy_id":{"type":["string","null"],"format":"uuid"},"policy_version":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"}}},"AuditListResponse":{"type":"object","required":["events"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"}},"next_cursor":{"type":["string","null"],"description":"Pass as ?cursor= for the next page. Null when no more results."}}},"ChainVerifyResponse":{"type":"object","required":["org_id","chain_valid","verified_through_row","chain_hash","timestamp"],"properties":{"org_id":{"type":"string","format":"uuid"},"chain_valid":{"type":"boolean"},"verified_through_row":{"type":"integer"},"chain_hash":{"type":["string","null"]},"first_broken_at_row_id":{"type":"string","format":"uuid"},"verified_from_checkpoint":{"type":"boolean"},"timestamp":{"type":"string","format":"date-time"}}},"DelegationEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parent_config_id":{"type":"string","format":"uuid"},"child_config_id":{"type":"string","format":"uuid"},"scope":{"type":"object","description":"Delegation scope constraints (action types, repo, pr_size, etc.)."},"expires_at":{"type":"string","format":"date-time"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"DelegationsListResponse":{"type":"object","required":["delegations"],"properties":{"delegations":{"type":"array","items":{"$ref":"#/components/schemas/DelegationEntry"}}}},"ReportRequest":{"type":"object","required":["audit_event_id","outcome"],"properties":{"audit_event_id":{"type":"string","format":"uuid","description":"The audit event to report on."},"outcome":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["success","failure","partial"]},"message":{"type":"string"},"metadata":{"type":"object","additionalProperties":true}}}}},"ReportResponse":{"type":"object","properties":{"audit_event_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["success","failure","partial"]},"reported_at":{"type":"string","format":"date-time"}}},"PostureResponse":{"type":"object","required":["score","components"],"properties":{"score":{"type":"integer","minimum":0,"maximum":100},"components":{"type":"object","properties":{"policy_coverage":{"type":"object","properties":{"score":{"type":"integer"},"max":{"type":"integer","const":25},"action_types_total":{"type":"integer"},"action_types_covered":{"type":"integer"}}},"approval_rate":{"type":"object","properties":{"score":{"type":"integer"},"max":{"type":"integer","const":25},"total_actions":{"type":"integer"},"approved_or_executed":{"type":"integer"}}},"anomaly_frequency":{"type":"object","properties":{"score":{"type":"integer"},"max":{"type":"integer","const":25},"anomaly_count":{"type":"integer"},"total_actions":{"type":"integer"}}},"chain_integrity":{"type":"object","properties":{"score":{"type":"integer"},"max":{"type":"integer","const":25},"chain_valid":{"type":"boolean"},"signed":{"type":"boolean"}}}}}}}}},"tags":[{"name":"Actions","description":"Submit and evaluate agent actions against org policies."},{"name":"Agent","description":"Agent identity and status endpoints."},{"name":"Policies","description":"Query and dry-run check policies."},{"name":"Audit","description":"Audit trail and chain integrity verification."},{"name":"Delegations","description":"Create, list, and revoke agent delegations."},{"name":"Reporting","description":"Report action outcomes back to the audit trail."},{"name":"Governance","description":"Governance health scoring."}]}