openapi: 3.1.0 info: title: (S)AGE API version: 11.25.8 description: |- (Sovereign) Agent Governed Experience — network REST API for memory submission, validation, and query. This machine-readable contract intentionally excludes the same-machine human CEREBRUM control plane under `/v1/dashboard/**`. Those routes are loopback-only management APIs, not remotely callable network APIs. Their authoritative contract is the “App-v23 CEREBRUM access-control routes” section of `docs/reference/rest-api.md`. contact: name: Dhillon Andrew Kannabhiran email: dhillon@levelupctf.com license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: http://localhost:8080 description: Local development # --------------------------------------------------------------------------- # Security — Ed25519 signature authentication via headers # --------------------------------------------------------------------------- security: - ed25519Auth: [] components: # ----------------------------------------------------------------------- # Security Schemes # ----------------------------------------------------------------------- securitySchemes: ed25519Auth: type: apiKey in: header name: X-Agent-ID description: >- Ed25519 authentication is conveyed through three headers sent together: **X-Agent-ID** (hex-encoded public key), **X-Signature** (Ed25519 signature of the canonical request payload), and **X-Timestamp** (unix epoch seconds). All three must be present on authenticated endpoints. Current clients should also send **X-Nonce**. After app-v17 activation, consensus binds delegated REST proofs to the exact canonical request, enforces the timestamp against block time, and consumes each proof once. # ----------------------------------------------------------------------- # Parameters # ----------------------------------------------------------------------- parameters: memoryId: name: memory_id in: path required: true description: Unique memory object identifier (UUID v7). schema: type: string format: uuid # ----------------------------------------------------------------------- # Schemas # ----------------------------------------------------------------------- schemas: # -- Enums ------------------------------------------------------------- MemoryType: type: string enum: - fact - observation - inference - task description: Classification of the memory object. MemoryStatus: type: string enum: - proposed - validated - committed - challenged - deprecated description: Lifecycle state of a memory object. VoteDecisionEnum: type: string enum: - accept - reject - abstain # -- Core domain objects ----------------------------------------------- KnowledgeTriple: type: object required: - subject - predicate - object properties: subject: type: string description: Subject entity of the triple. predicate: type: string description: Relationship between subject and object. object: type: string description: Object entity of the triple. DerivedFromParent: type: object required: - source_chain_id - memory_id - content_hash additionalProperties: false properties: source_chain_id: type: string minLength: 1 maxLength: 64 description: Consensus chain ID. App-v30 currently requires the local chain ID. memory_id: type: string minLength: 1 maxLength: 512 description: Parent memory ID. content_hash: type: string pattern: "^[0-9a-f]{64}$" description: Lowercase SHA-256 content hash of the exact parent memory. MemoryRecord: type: object required: - memory_id - submitting_agent - content - content_hash - memory_type - domain_tag - confidence_score - status - created_at properties: memory_id: type: string format: uuid description: Unique identifier (UUID v7). submitting_agent: type: string description: Hex-encoded Ed25519 public key of the proposing agent. content: type: string description: Natural-language memory content. content_hash: type: string description: SHA-256 hash of content (hex-encoded). embedding: type: array items: type: number format: float description: 1536-dimensional embedding vector. embedding_hash: type: string description: SHA-256 hash of the embedding vector (hex-encoded). memory_type: $ref: "#/components/schemas/MemoryType" domain_tag: type: string description: Domain or topic tag for the memory. confidence_score: type: number format: double minimum: 0 maximum: 1 description: >- Current confidence at query time: the agent-assigned score after time decay and the corroboration boost are applied. initial_confidence: type: number format: double minimum: 0 maximum: 1 description: >- Stored (undecayed) confidence — the on-chain value set at submission (corroboration never rewrites it), before time decay. Sibling to the decayed confidence_score. Present for local memories; omitted (absent) for federated results, where only the serving peer's already-decayed value is available. Not guaranteed on every result. corroboration_count: type: integer minimum: 0 description: >- Number of distinct corroborating agent IDs backing this memory — the multiplier behind the corroboration boost in confidence_score. Returned on recall paths (/v1/memory/query, /search, /hybrid) and the detail endpoint so readers can tell a low score caused by no corroboration (a fresh, untested belief) from one caused by time decay (a once-solid fact). challenge_count: type: integer minimum: 0 description: >- Number of distinct challenger IDs in the off-chain lifetime audit projection. This is evidence history, not an open-vote count. evidence_counts_available: type: boolean description: >- True only when both count queries succeeded and no durable recovery/repair-incomplete marker was detected. It is not an attestation against out-of-band partial SQL audit-table corruption. When false, corroboration_count and challenge_count may still be reconstructed canonical lower bounds after pristine state sync or repair; zero is not proof that no historical evidence existed. challenge_round: type: integer format: int64 minimum: 1 description: Current app-v21 challenge round; absent when no weighted round is open. current_challenger_count: type: integer format: int32 minimum: 1 description: Distinct challengers accrued in the current open app-v21 round. required_challengers: type: integer format: int32 minimum: 1 description: Distinct challengers required to deprecate in the current app-v21 round. disputed: type: boolean description: >- True when the memory remains recallable while challenged. When true, confidence_score already includes the disputed confidence haircut. classification: type: integer minimum: 0 maximum: 4 description: >- Per-record clearance level: 0=PUBLIC, 1=INTERNAL, 2=CONFIDENTIAL, 3=SECRET, 4=TOPSECRET. status: $ref: "#/components/schemas/MemoryStatus" parent_hash: type: string description: Hash of the parent memory (for lineage), if any. task_status: type: string description: >- For task-type memories: planned, in_progress, done, or dropped. knowledge_triples: type: array items: $ref: "#/components/schemas/KnowledgeTriple" description: Extracted knowledge graph triples. votes: type: array items: type: object properties: voter_id: type: string decision: $ref: "#/components/schemas/VoteDecisionEnum" rationale: type: string voted_at: type: string format: date-time description: Votes cast on this memory. corroborations: type: array items: type: object properties: agent_id: type: string evidence: type: string created_at: type: string format: date-time description: Corroborations supporting this memory. linked_memories: type: array items: type: object description: Memories linked to this one. created_at: type: string format: date-time description: Timestamp when the memory was proposed. committed_at: type: string format: date-time description: Timestamp when the memory reached committed status. # -- Request bodies ---------------------------------------------------- MemorySubmitRequest: type: object required: - content - memory_type - confidence_score allOf: - if: properties: memory_type: const: task required: - memory_type then: {} else: required: - domain_tag properties: content: type: string description: Natural-language memory content. memory_type: $ref: "#/components/schemas/MemoryType" domain_tag: type: string description: >- Exact domain or topic tag. Required except for an app-v23 task submitted by an active ordinary agent; that narrow omission uses the caller's currently committed owned home domain. Explicit values are never remapped. confidence_score: type: number format: double minimum: 0 maximum: 1 description: Agent-assigned confidence (0–1). classification: type: integer minimum: 0 maximum: 4 description: >- Per-record clearance: 0=PUBLIC, 1=INTERNAL, 2=CONFIDENTIAL, 3=SECRET, 4=TOPSECRET. Omitting or sending 0 stores as PUBLIC. embedding: type: array items: type: number format: float description: Optional precomputed embedding vector; stored off-chain via supplementary cache. knowledge_triples: type: array items: $ref: "#/components/schemas/KnowledgeTriple" description: >- Optional knowledge graph triples. App-v23 task creation rejects this field because it is not part of the canonical task receipt. parent_hash: type: string description: Hash of a parent memory for lineage tracking. derived_from: type: array minItems: 1 maxItems: 16 items: $ref: "#/components/schemas/DerivedFromParent" description: >- App-v30 authenticated lineage refs. JSON order is canonicalized before signing. Each parent must be local, committed or challenged, readable by the caller, and carry the exact content hash. task_status: type: string enum: - planned description: >- New task memories enter consensus as planned. After app-v27 this field may be omitted: REST transaction construction and consensus proof verification both canonicalize omission to planned. Before app-v27, omission returns 400 Missing task status. Use the task-status endpoint to change it after creation. linked_memories: type: array items: type: string description: >- Related memory IDs for legacy submission paths. App-v23 task creation rejects this field; create links after the task receipt is confirmed. tags: type: array maxItems: 32 items: type: string description: >- Optional user-defined labels, each at most 128 UTF-8 bytes. Above app-v20 the node trims no values: it rejects empty/padded/oversized tags, then sorts and deduplicates them into the signed transaction. For scoped domains they are also AppHash-covered canonical content and survive projection rebuild. Ordinary-domain tags remain node-local serving metadata. Queryable via `tags` on /v1/memory/query and /v1/memory/search. provider: type: string description: Stored off-chain only; not on-chain. idempotency_key: type: string minLength: 1 maxLength: 128 pattern: "^[!-~]+$" description: >- App-v23 tasks only. Permanent creation identity containing visible ASCII without spaces. When omitted, the node derives the same semantic key as MCP from the exact signed agent ID, resolved domain, and content. Reusing a key with a different canonical payload returns 409. Use a fresh explicit key only to intentionally create another occurrence with identical content and domain. evidence_id: type: string description: >- Claims evidence this agent uploaded with POST /v1/memory/evidence, once and before it expires, for the optional memory gate. Only this random id is in the signed body; the evidence text is kept on the receiving node and never enters a transaction. Not accepted for tasks. UploadEvidenceRequest: type: object required: - evidence properties: evidence: type: string maxLength: 32768 description: Source text the memory is based on (at most 32 KiB). UploadEvidenceResponse: type: object properties: evidence_id: type: string expires_in_seconds: type: integer MemoryQueryRequest: type: object required: - embedding properties: embedding: type: array items: type: number format: float description: Query embedding for similarity search. domain_tag: type: string description: Optional domain filter. provider: type: string description: Optional provider filter. min_confidence: type: number format: double minimum: 0 maximum: 1 description: Minimum confidence threshold. status_filter: $ref: "#/components/schemas/MemoryStatus" top_k: type: integer minimum: 1 maximum: 100 default: 10 description: Number of results to return (max 100). cursor: type: string description: Opaque pagination cursor from a previous response. tags: type: array items: type: string description: >- Optional filter — when non-empty, restricts results to memories tagged with ANY of the listed values (OR semantics). Supported by both SQLiteStore and PostgresStore. MemorySearchRequest: type: object required: - query properties: query: type: string description: Full-text search query. domain_tag: type: string description: Optional domain filter. provider: type: string description: Optional provider filter. min_confidence: type: number format: double minimum: 0 maximum: 1 status_filter: $ref: "#/components/schemas/MemoryStatus" top_k: type: integer minimum: 1 maximum: 100 default: 10 tags: type: array items: type: string description: OR-filter by tag; SQLite only. HybridExpansion: type: object properties: query: type: string description: Paraphrase variant text. embedding: type: array items: type: number format: float description: Precomputed embedding for this variant. MemoryHybridRequest: type: object description: >- At least one of `query` or `embedding` is required. At most eight expansion entries are accepted. Under app-v23 one 8,192-candidate live authorization budget is shared by the primary query, every expansion, and every text/vector store leaf. Governed leaf or budget failures fail the whole request instead of returning partial fused results. properties: query: type: string description: Text query for the FTS5 arm. embedding: type: array items: type: number format: float description: Vector for the similarity arm. expansions: type: array maxItems: 8 items: $ref: "#/components/schemas/HybridExpansion" description: >- Up to eight paraphrase variants for multi-variant RRF recall. The array-length limit is applied before blank variants are skipped. domain_tag: type: string provider: type: string min_confidence: type: number format: double minimum: 0 maximum: 1 status_filter: $ref: "#/components/schemas/MemoryStatus" top_k: type: integer minimum: 1 maximum: 100 default: 10 tags: type: array items: type: string FilterInfo: type: object description: >- Identifies authorization filters that were applied. Before app-v23 a server may also emit legacy inventory counts. App-v23 omits denied/raw counts, and presence of this object is not proof that a row was hidden. properties: by: type: array items: type: string description: >- Filter identifiers applied. Values: rbac_submitting_agents, classification. total_before_filter: type: integer deprecated: true description: Legacy/pre-app-v23 only; omitted by app-v23. visible: type: integer deprecated: true description: Legacy/pre-app-v23 only; omitted by app-v23. hidden_count: type: integer deprecated: true description: Legacy/pre-app-v23 only; omitted by app-v23. MemoryQueryResponse: type: object required: - results - total_count properties: results: type: array items: $ref: "#/components/schemas/MemoryRecord" next_cursor: type: string description: Cursor for the next page, absent if no more results. total_count: type: integer description: Number of visible memories returned in this response. filtered: $ref: "#/components/schemas/FilterInfo" index_status: type: string enum: [complete, incomplete, unavailable] description: > Present on an EMPTY, domain-scoped semantic recall. "complete" and "incomplete" are available only for the exact unnarrowed local status_filter=committed contract; other empty query universes emit "unavailable" rather than certifying the wrong scope. "complete": the empty result is genuine local absence. "incomplete": the domain holds committed/challenged rows that no vector, or a foreign vector space, keeps recall from returning — empty is not proof of absence. "unavailable": the verdict could not be proven leak-free and scope-exact (including when the caller lacks full visibility, canonical projection health is not exact, the vector space is unknown, the query uses status/provider/tag/ confidence/cursor/text narrowing, federation is requested, or the live domain is too large to settle cheaply). Never a count or list. MemoryLinkRequest: type: object required: - source_id - target_id properties: source_id: type: string target_id: type: string link_type: type: string default: related description: Relationship type; defaults to "related". MemoryLinkResponse: type: object properties: source_id: type: string target_id: type: string link_type: type: string PreValidateRequest: type: object required: - content properties: content: type: string domain: type: string type: type: string confidence: type: number format: double PreValidateVote: type: object properties: validator: type: string decision: type: string reason: type: string PreValidateResponse: type: object properties: accepted: type: boolean quorum: type: string example: "3/3" votes: type: array items: $ref: "#/components/schemas/PreValidateVote" TaskStatusUpdateRequest: type: object required: - task_status properties: task_status: type: string enum: - in_progress - done - dropped description: >- Agent-authorized transitions. Re-planning/reopening is a local CEREBRUM operator action and is not accepted by this route. TaskStatusUpdateResponse: type: object properties: memory_id: type: string task_status: type: string ForgetRequest: type: object properties: reason: type: string description: Optional reason; defaults to "deprecated by user" if omitted. ForgetResponse: type: object required: - message - tx_hash properties: message: type: string tx_hash: type: string status: type: string enum: [challenged, deprecated] description: Durable post-commit consensus result when available. ReinstateRequest: type: object properties: reason: type: string description: Optional audit note explaining why the challenge is being withdrawn or resolved. ReinstateResponse: type: object required: - message - tx_hash - status properties: message: type: string tx_hash: type: string status: type: string enum: - committed VoteRequest: type: object required: - decision properties: decision: $ref: "#/components/schemas/VoteDecisionEnum" rationale: type: string description: Optional rationale for the vote. ChallengeRequest: type: object required: - reason properties: reason: type: string description: Reason for challenging the memory. evidence: type: string description: Optional supporting evidence. CorroborateRequest: type: object properties: evidence: type: string description: Optional supporting evidence. # -- Response bodies --------------------------------------------------- MemorySubmitResponse: type: object required: - memory_id - tx_hash - status - committed - committed_height properties: memory_id: type: string format: uuid tx_hash: type: string description: CometBFT transaction hash (hex-encoded). status: type: string enum: - proposed - committed_unconfirmed description: >- Governed lifecycle status proposed after a confirmed projection, or committed_unconfirmed when the task transaction is on-chain but its exact local projection could not be confirmed. task_status: type: string enum: - planned - in_progress - done - dropped description: Current task workflow status. Replays may be terminal. committed: type: boolean description: >- True after broadcast_tx_commit proves the transaction committed. This does not by itself prove the serving projection is confirmed. committed_height: type: integer format: int64 description: Block height at which the submission committed. projection_confirmed: type: boolean description: >- For app-v23 tasks, whether the exact task/assignee serving projection was confirmed. False is returned with HTTP 202. retryable: type: boolean description: >- False on committed_unconfirmed: reconcile the exact memory_id and do not resubmit the task. message: type: string idempotency_key: type: string description: >- Permanent explicit or server-derived task identity. Present on app-v23 task responses. idempotent_replay: type: boolean description: True when no new transaction was created for this key. embedding_provider: type: string embedding_queued: type: boolean VoteResponse: type: object required: - message - tx_hash properties: message: type: string tx_hash: type: string description: CometBFT transaction hash (hex-encoded). ChallengeResponse: type: object required: - message - tx_hash properties: message: type: string tx_hash: type: string status: type: string enum: [challenged, deprecated] description: Durable post-commit consensus result when available. CorroborateResponse: type: object required: - message - tx_hash properties: message: type: string tx_hash: type: string AgentProfile: type: object required: - agent_id - display_name - domains - poe_weight - vote_count - accuracy - on_chain_height properties: agent_id: type: string description: Hex-encoded Ed25519 public key. display_name: type: string description: Mutable display name (GUI-editable). domains: type: array items: type: string description: Distinct domain tags the agent has submitted memories under, ordered by participation frequency. role: type: string enum: [member, manager, admin] description: Current app-v23 local role. Present only after app-v23 activation. profile: type: string enum: [standard, companion, read_only, legacy_restricted] description: Current app-v23 named profile. Root never has an ordinary self profile. home_domain: type: string description: The active app-v23 agent's owned non-shared home domain, when its profile is writable. enrollment_status: type: string enum: [active, pending_review, inactive] description: Caller-only app-v23 enrollment standing. Pending and inactive identities may inspect only themselves. registration_status: type: string enum: [active, pending_review, inactive] description: Caller-only app-v23 registration standing. approval_required: type: boolean description: Whether local CEREBRUM review is required before memory access is available. clearance: type: integer minimum: 0 maximum: 4 description: The signed caller's own consensus clearance. capabilities: type: integer format: uint32 description: The signed caller's own consensus capability mask. can_read: type: boolean description: Whether the caller can currently read its exact home_domain. can_write: type: boolean description: Whether the caller can currently write its exact home_domain. access_scope: type: string enum: [home_domain] description: Explicit scope for can_read and can_write. poe_weight: type: number format: double description: Current Proof-of-Experience weight. vote_count: type: integer description: Total votes cast. accuracy: type: number format: double minimum: 0 maximum: 1 description: Global verdict-correctness EWMA — the alpha factor of the PoE quorum weight. Cold-start-blended (0.5 prior, transitions toward the real score after K_min=10 observations). Since v8.6.0 read from the authoritative on-chain vstats record. corr_count: type: integer format: int64 description: "Lifetime count of votes that matched a terminal verdict (the delta corroboration factor). Read from the on-chain vstats record. (v8.6.0+)" domain_expertise: type: object additionalProperties: type: number format: double description: "Per-domain verdict-correctness EWMA (the beta factor, from vstats_domain), keyed by domain tag. Only present for domains the agent has voted in. (v8.6.0+)" on_chain_height: type: integer format: int64 description: Block height at which the agent was registered on-chain (0 for legacy / unregistered). AgentRegisterRequest: type: object required: - name properties: name: type: string description: Human-readable agent name. role: type: string description: "One of: admin, member, observer. Defaults to member." boot_bio: type: string description: Agent bio / system prompt description. provider: type: string description: MCP provider identifier (e.g., "claude-code", "cursor"). p2p_address: type: string description: Peer-to-peer address. AgentUpdateRequest: type: object properties: name: type: string description: Updated agent name. Omit to preserve the current name. boot_bio: type: string description: Updated agent bio. Omit to preserve the current bio. RegisteredAgent: type: object properties: agent_id: type: string description: Hex-encoded Ed25519 public key. name: type: string role: type: string boot_bio: type: string provider: type: string status: type: string clearance: type: integer on_chain_height: type: integer format: int64 description: Block height where registered on-chain. visible_agents: type: string created_at: type: string format: date-time updated_at: type: string format: date-time AgentDirectoryEntry: type: object required: [agent_id, name, registered_name, status] description: Minimal signed local recipient identity; contains no RBAC or memory totals. properties: agent_id: type: string pattern: "^[0-9a-f]{64}$" name: type: string description: Mutable display name. registered_name: type: string description: Immutable name sealed at first registration. provider: type: string status: type: string enum: [active] AgentLookupEntry: allOf: - $ref: "#/components/schemas/AgentDirectoryEntry" - type: object required: [match_kind] properties: match_kind: type: string enum: [exact, substring] ValidatorScore: type: object required: - validator_id - accuracy - domain_score - recency_score - corr_score - raw_weight - capped_weight - normalized_weight properties: validator_id: type: string accuracy: type: number format: double domain_score: type: number format: double recency_score: type: number format: double corr_score: type: number format: double raw_weight: type: number format: double capped_weight: type: number format: double normalized_weight: type: number format: double EpochInfo: type: object required: - epoch_num - block_height - scores properties: epoch_num: type: integer description: Current epoch number. block_height: type: integer format: int64 description: Block height at epoch start. scores: type: array items: $ref: "#/components/schemas/ValidatorScore" PendingMemoriesResponse: type: object required: - memories properties: memories: type: array items: $ref: "#/components/schemas/MemoryRecord" next_cursor: type: string # -- Access Control ------------------------------------------------------- AccessRequestBody: type: object required: - target_domain properties: target_domain: type: string justification: type: string requested_level: type: integer description: 1=read, 2=read+write. Defaults to 1. AccessGrantRequest: type: object required: - grantee_id - domain properties: grantee_id: type: string description: Hex agent ID of the grantee. domain: type: string level: type: integer description: 1=read, 2=read+write. Defaults to 1. expires_at: type: integer format: int64 description: Unix timestamp; 0=permanent. request_id: type: string description: Links to originating access request. AccessRevokeRequest: type: object required: - grantee_id - domain properties: grantee_id: type: string domain: type: string reason: type: string DirectGrantTargetIdentity: type: object required: - active - profile - role - clearance - capabilities - root_generation - enrollment_revision - role_revision properties: active: type: boolean const: true profile: type: string role: type: string clearance: type: integer minimum: 0 maximum: 4 capabilities: type: integer format: int64 root_generation: type: integer format: int64 minimum: 1 enrollment_revision: type: integer format: int64 role_revision: type: integer format: int64 DirectGrantObservation: type: object required: - domain - grantee_id - granter_id - access_level - expires_at properties: domain: type: string grantee_id: type: string pattern: "^[0-9a-f]{64}$" granter_id: type: string pattern: "^[0-9a-f]{64}$" access_level: type: integer minimum: 1 maximum: 3 expires_at: type: integer format: int64 description: Unix timestamp; 0 means no expiry. DirectGrantsSnapshot: type: object required: - schema - caller_id - target_agent_id - height - app_hash - root_principal_id - root_generation - evaluated_at - coverage - complete - target - grants properties: schema: type: string const: sage.direct-grants-snapshot.v1 caller_id: type: string pattern: "^[0-9a-f]{64}$" target_agent_id: type: string pattern: "^[0-9a-f]{64}$" height: type: integer format: int64 minimum: 1 app_hash: type: string pattern: "^[0-9a-f]{64}$" root_principal_id: type: string pattern: "^[0-9a-f]{64}$" root_generation: type: integer format: int64 minimum: 1 evaluated_at: type: integer format: int64 minimum: 1 coverage: type: string const: active-direct-grants-for-target complete: type: boolean const: true target: $ref: "#/components/schemas/DirectGrantTargetIdentity" grants: type: array items: $ref: "#/components/schemas/DirectGrantObservation" # -- Domains --------------------------------------------------------------- DomainRegisterRequest: type: object required: - name properties: name: type: string description: type: string parent: type: string ScopeDomain: type: object required: [name, subtree] properties: name: type: string subtree: type: boolean ScopeMember: type: object required: [validator_id, assigned_weight, joined_revision, active, pending_ballot_count, validator_removal_blocked] properties: validator_id: type: string assigned_weight: type: integer format: uint64 joined_revision: type: integer format: uint64 active: type: boolean pending_ballot_count: type: integer minimum: 0 description: Pending ballots whose pinned roster includes this validator. validator_removal_blocked: type: boolean description: True while active scope membership or a pinned pending ballot prevents safe CometBFT validator removal. ScopeDrain: type: object required: [pending_ballot_count, pending_memory_ids, blocking_validator_ids] properties: pending_ballot_count: type: integer minimum: 0 pending_memory_ids: type: array items: type: string description: Pending scoped memories in canonical memory-ID order. blocking_validator_ids: type: array items: type: string description: Validators blocked from CometBFT removal by this scope head or its pinned ballots. ScopeRecord: type: object required: [scope_id, revision, revision_hash, state, controller_validator_id, created_height, updated_height, domains, members, drain] properties: scope_id: type: string pattern: '^[^/]+$' revision: type: integer format: uint64 revision_hash: type: string description: Domain-separated SHA-256 audit anchor for this revision. state: type: string enum: [active, paused, retired] controller_validator_id: type: string created_height: type: integer format: int64 updated_height: type: integer format: int64 domains: type: array items: $ref: "#/components/schemas/ScopeDomain" members: type: array items: $ref: "#/components/schemas/ScopeMember" drain: $ref: "#/components/schemas/ScopeDrain" ScopeListResponse: type: object required: [scopes, count] properties: scopes: type: array items: $ref: "#/components/schemas/ScopeRecord" count: type: integer ScopeActionMember: type: object required: [validator_id, assigned_weight] properties: validator_id: type: string assigned_weight: type: integer format: uint64 minimum: 1 joined_revision: type: integer format: uint64 minimum: 1 description: Required after revision 1; may be omitted for a new scope. active: type: boolean default: true ScopeActionTemplate: type: object required: [scope_id, revision, state, controller_validator_id, domains, members] properties: scope_id: type: string pattern: '^[^/]+$' revision: type: integer format: uint64 minimum: 1 state: type: string enum: [active, paused, retired] controller_validator_id: type: string domains: type: array minItems: 1 items: type: string members: type: array minItems: 1 items: $ref: "#/components/schemas/ScopeActionMember" description: >- Guided app-v20 scope proposal. The server bytewise-sorts domains and members, defaults omitted member active flags to true, sets both consensus-owned heights to zero, validates ScopeRecordV1 invariants, and emits the canonical binary governance payload. # -- Governance (v8.0 payload-aware) ---------------------------------------- GovernanceContextResponse: type: object required: - validator_id - governance_domain - app_v20_active - validator_active - active_validators properties: validator_id: type: string pattern: '^[0-9a-f]{64}$' description: This node's live CometBFT validator identity. governance_domain: type: string pattern: '^$|^[0-9a-f]{64}$' description: >- SHA-256 chain-binding committed at app-v20 activation. Empty while app-v20 is inactive. app_v20_active: type: boolean description: Whether the following governance mutation must include this context. validator_active: type: boolean description: >- Whether this gateway's live private-validator identity is present in the ABCI application's persisted validator roster. active_validators: type: array description: >- Exact AppHash-covered validator roster loaded from persisted ABCI state. Entries are sorted by validator_id. items: type: object required: - validator_id - voting_power properties: validator_id: type: string pattern: '^[0-9a-f]{64}$' voting_power: type: integer format: int64 minimum: 1 GovProposeRequest: type: object required: - operation - reason properties: validator_id: type: string pattern: '^[0-9a-f]{64}$' description: >- Copy from the immediately preceding authenticated GET /v1/governance/context response when app_v20_active is true. governance_domain: type: string pattern: '^[0-9a-f]{64}$' description: >- Copy from the immediately preceding authenticated GET /v1/governance/context response when app_v20_active is true. operation: type: string enum: - add_validator - remove_validator - update_power - domain_reassign - memory_domain_repair - sync_group_action - scope_action description: >- Governance operation. `memory_domain_repair` (app-v16, 2/3 quorum) is the domainless-forget remediation — it carries a base64 JSON `[{"memory_id","domain"}]` array in `payload` and backfills legacy memories' on-chain domain directly on proposal execution. `domain_reassign` (v8.0) is the access-control recovery primitive — it carries the target DomainReassign body via the `payload` field rather than the scalar target_* fields. `scope_action` (app-v20) accepts either the guided `scope` object or the legacy canonical binary ScopeRecordV1 `payload`; the two fields are mutually exclusive. target_id: type: string description: >- Hex-encoded validator pubkey for validator-set ops; reused as the proposal-keying identifier for `domain_reassign` (typically the dotted-path domain name). Required except when a `scope_action` supplies `scope.scope_id`, from which it is derived. target_pubkey: type: string description: Hex-encoded Ed25519 public key (required for add_validator). target_power: type: integer format: int64 description: Validator power for add/update ops; ignored for domain_reassign. expiry_blocks: type: integer format: int64 description: Proposal expiry in blocks (0 = chain default). reason: type: string description: Human-readable justification. payload: type: string description: >- Base64-encoded operation-specific payload (v8.0). For `domain_reassign`, the JSON-encoded body `{domain, new_owner_id, parent_domain, open_to_shared}` that the subsequent TxTypeDomainReassign execution tx must reproduce byte-for-byte. For legacy `scope_action` callers, the canonical binary ScopeRecordV1 template with zero system-owned heights. Mutually exclusive with `scope`; empty for validator-set ops. scope: $ref: "#/components/schemas/ScopeActionTemplate" GovProposeResponse: type: object required: - proposal_id - tx_hash - status properties: proposal_id: type: string description: >- Deterministic governance-engine identifier used by vote/cancel; intentionally distinct from tx_hash. tx_hash: type: string description: CometBFT transaction hash. status: type: string enum: - voting - executed - rejected - expired - cancelled - unknown description: >- Authoritative committed proposal status. `unknown` is used only when an embedded server has no local governance state store. example: voting GovVoteRequest: type: object required: - proposal_id - decision properties: validator_id: type: string pattern: '^[0-9a-f]{64}$' description: Current app-v20 validator binding from GET /v1/governance/context. governance_domain: type: string pattern: '^[0-9a-f]{64}$' description: Current app-v20 chain binding from GET /v1/governance/context. proposal_id: type: string description: From the propose response. decision: type: string enum: - accept - reject - abstain GovVoteResponse: type: object required: - tx_hash - status properties: tx_hash: type: string status: type: string example: recorded GovCancelRequest: type: object required: - proposal_id properties: validator_id: type: string pattern: '^[0-9a-f]{64}$' description: Current app-v20 validator binding from GET /v1/governance/context. governance_domain: type: string pattern: '^[0-9a-f]{64}$' description: Current app-v20 chain binding from GET /v1/governance/context. proposal_id: type: string GovCancelResponse: type: object required: - tx_hash - status properties: tx_hash: type: string status: type: string example: cancelled # -- Domain reassign (v8.0) --------------------------------------------- DomainReassignRequest: type: object required: - domain - new_owner_id - proposal_id properties: domain: type: string description: Dotted-path domain name to reassign. new_owner_id: type: string description: Hex(64) Ed25519 agent ID of the new owner. parent_domain: type: string description: >- Optional. Must match the existing parent or be left empty to preserve. Mismatched parents are rejected during FinalizeBlock. proposal_id: type: string description: >- Hex-encoded ID of the previously accepted gov_propose (`domain_reassign`) record. The execution tx is a no-op unless this proposal exists, has executed, and hasn't been consumed. open_to_shared: type: boolean default: false description: >- When true, also writes the on-chain `shared_domain:` sentinel so post-fork access checks treat the domain as catch-all-writable. expected_owner_id: type: string pattern: "^[0-9a-fA-F]{64}$" description: >- App-v26 ownership compare-and-swap binding. Must be the exact Hex(64) current owner observed before the governance proposal was created; the proposal and execution transaction bind the same value, and consensus rejects a stale transfer if ownership changed before execution. Omit this field on pre-app-v26 chains. DomainReassignResponse: type: object required: - tx_hash - purged_grants properties: tx_hash: type: string description: CometBFT transaction hash of the executed reassignment. purged_grants: type: integer description: >- Number of grant entries cleared when the domain ownership flipped. The previous owner's chain-of-trust does not survive the reassign — operators audit this count to confirm the blast radius of recovery. # -- Orgs / Federation --------------------------------------------------- OrgRegisterRequest: type: object required: - name properties: name: type: string description: type: string OrgAddMemberRequest: type: object required: - agent_id properties: agent_id: type: string clearance: type: integer minimum: 0 maximum: 4 description: Defaults to 1 (INTERNAL). role: type: string description: "admin, member, or observer. Defaults to member." OrgSetClearanceRequest: type: object required: - agent_id - clearance properties: agent_id: type: string clearance: type: integer minimum: 0 maximum: 4 OrgEnrollTokenIssueRequest: type: object required: - node_label - enrollee_pub - scope - org_signer_pub properties: node_label: type: string minLength: 1 role: type: string enum: [member, observer] default: member enrollee_pub: type: string pattern: '^[0-9a-f]{64}$' description: Exact Ed25519 node key allowed to redeem the bearer. scope: type: string minLength: 1 maxLength: 256 description: Immutable org-policy scope established by enrollment. org_signer_pub: type: string pattern: '^[0-9a-f]{64}$' key_epoch: type: string description: Optional initial policy epoch pin. OrgEnrollTokenSummary: type: object required: - id - org_id - owner_id - node_label - role - enrollee_pub - scope - org_signer_pub - issued_at - expires_at properties: id: type: string org_id: type: string owner_id: type: string node_label: type: string role: type: string enum: [member, observer] enrollee_pub: type: string scope: type: string org_signer_pub: type: string key_epoch: type: string issued_at: type: string format: date-time expires_at: type: string format: date-time revoked_at: type: string format: date-time OrgEnrollTokenIssueResponse: allOf: - $ref: "#/components/schemas/OrgEnrollTokenSummary" - type: object required: - token - use_hint properties: token: type: string description: Plaintext bearer shown exactly once. use_hint: type: string OrgPolicyPayload: type: object required: - judge - checks_version - peer_allow_list - retention properties: judge: type: object required: [model_tag, gguf_sha256, blob_sha256] properties: model_tag: type: string gguf_sha256: type: string blob_sha256: type: string checks_version: type: string peer_allow_list: type: array items: type: string retention: type: object required: [max_age_days, max_items] properties: max_age_days: type: integer format: int64 minimum: 0 max_items: type: integer format: int64 minimum: 0 OrgPolicy: type: object required: - schema - org_id - scope - revision - issuer_key_id - key_epoch - issued_at - not_before - expiry - payload - sig properties: schema: type: string const: sage.org-policy.v1 org_id: type: string scope: type: string revision: type: integer format: int64 minimum: 1 issuer_key_id: type: string key_epoch: type: string issued_at: type: integer format: int64 not_before: type: integer format: int64 expiry: type: integer format: int64 description: Unix seconds; 0 means no expiry. payload: $ref: "#/components/schemas/OrgPolicyPayload" sig: type: string OrgRotationAttestation: type: object required: - schema - org_id - from_key_id - to_key_id - new_key_epoch - not_before - overlap_until - sig properties: schema: type: string const: sage.org-policy-rotation.v1 org_id: type: string from_key_id: type: string to_key_id: type: string new_key_epoch: type: string not_before: type: integer format: int64 overlap_until: type: integer format: int64 sig: type: string OrgEnrollRequest: type: object required: - token - first_policy properties: token: type: string first_policy: $ref: "#/components/schemas/OrgPolicy" attestations: type: array items: $ref: "#/components/schemas/OrgRotationAttestation" OrgPolicyAcceptedState: type: object required: - org_id - scope - revision - digest - key_epoch - issuer_key_id - root_key_id - root_key_epoch - not_before - expiry properties: org_id: type: string scope: type: string revision: type: integer format: int64 digest: type: string key_epoch: type: string issuer_key_id: type: string root_key_id: type: string description: Trust anchor pinned by the enrollment token. root_key_epoch: type: string rotation_chain: type: array items: $ref: "#/components/schemas/OrgRotationAttestation" not_before: type: integer format: int64 expiry: type: integer format: int64 OrgEnrollResponse: type: object required: - org_id - enrollee_pub - bound_identity - first_policy - accepted - replayed properties: org_id: type: string enrollee_pub: type: string bound_identity: type: string first_policy: $ref: "#/components/schemas/OrgPolicy" accepted: $ref: "#/components/schemas/OrgPolicyAcceptedState" replayed: type: boolean OrgPolicyUpdateRequest: type: object required: - policy properties: policy: $ref: "#/components/schemas/OrgPolicy" attestations: type: array items: $ref: "#/components/schemas/OrgRotationAttestation" OrgPolicyEquivocationNotice: type: object required: - org_id - revision - accepted_digest - conflict_digest - issuer_key_id - key_epoch properties: org_id: type: string revision: type: integer format: int64 accepted_digest: type: string conflict_digest: type: string issuer_key_id: type: string key_epoch: type: string OrgPolicyUpdateResponse: type: object required: - decision - accepted properties: decision: type: string enum: [applied, noop_same_digest, rejected_rollback, rejected_equivocation] accepted: $ref: "#/components/schemas/OrgPolicyAcceptedState" equivocation: $ref: "#/components/schemas/OrgPolicyEquivocationNotice" OrgPolicyGateResult: type: object required: - operation - allowed - mode properties: operation: type: string enum: [local_access, enrollment, new_peering, admission, retention, retention_purge] allowed: type: boolean mode: type: string enum: [current, last_valid, independent, owner_present, hold] reason: type: string OrgPolicyStatus: type: object required: - accepted - current - operations properties: accepted: $ref: "#/components/schemas/OrgPolicyAcceptedState" current: type: boolean operations: type: array items: $ref: "#/components/schemas/OrgPolicyGateResult" equivocation: $ref: "#/components/schemas/OrgPolicyEquivocationNotice" FederationProposeRequest: type: object required: - target_org_id properties: target_org_id: type: string allowed_domains: type: array items: type: string description: '["*"] means all domains.' allowed_depts: type: array items: type: string max_clearance: type: integer minimum: 0 maximum: 4 description: Ceiling clearance; defaults to 2 (CONFIDENTIAL). expires_at: type: integer format: int64 description: Unix timestamp; 0=permanent. requires_approval: type: boolean FederationRevokeRequest: type: object properties: reason: type: string # -- Departments --------------------------------------------------------- DeptRegisterRequest: type: object required: - name properties: name: type: string description: type: string parent_dept: type: string DeptAddMemberRequest: type: object required: - agent_id properties: agent_id: type: string clearance: type: integer minimum: 0 maximum: 4 description: Defaults to 1. role: type: string description: Defaults to member. # -- Pipeline ------------------------------------------------------------ PipeResolveRequest: type: object required: - to properties: to: type: string description: Local agent/provider name, exact agent@chain address, or visible #network/agent handle. PipeResolveResponse: type: object properties: to_agent: type: string to_provider: type: string source_chain_id: type: string description: Local chain bound into a federated send request. destination_chain_id: type: string description: Remote chain bound into a federated send request; empty for local targets. address: type: string handle: type: string display_name: type: string PipeSendRequest: type: object required: - payload properties: to_agent: type: string description: Target agent_id (direct). One of to_agent or to_provider required. to_provider: type: string description: Provider name or agent name; resolves to agent_id if unambiguous. source_chain_id: type: string description: Exact local chain returned by /v1/pipe/resolve for a federated target. destination_chain_id: type: string description: Exact remote chain returned by /v1/pipe/resolve for a federated target. intent: type: string description: Human description of the work. payload: type: string description: Arbitrary content. ttl_minutes: type: integer minimum: 0 maximum: 1440 description: With idempotency_key, omitted/0 is durable until handled; without a key, omitted/0 uses the legacy 1440-minute lifetime. Values 1-1440 request explicit expiry. idempotency_key: type: string minLength: 1 maxLength: 256 description: Optional caller-scoped replay key. Exact retry returns the original row; same key with different content is a conflict. PipeSendResponse: type: object required: [pipe_id, status, expires_at, destination_chain_id, idempotent_replay] properties: pipe_id: type: string pattern: '^msg-' status: type: string example: pending expires_at: type: string format: date-time destination_chain_id: type: string description: Exact remote SAGE chain for a federated send; empty for local work. idempotent_replay: type: boolean description: True only when a keyed request returned its original row without another admission or wake generation. transport_status: type: string enum: [queued] description: Present only for a federated send; confirms durable local queuing, not peer receipt. peer_status: type: string enum: [unconfirmed] description: Present only for a federated send; the remote peer and agent have not yet acknowledged delivery. PipeResultRequest: type: object required: - result properties: result: type: string source_pipe_id: type: string description: Stable source event ID from GET /v1/pipe/{pipe_id}; required for federated results. source_chain_id: type: string description: Exact reply-source chain from GET /v1/pipe/{pipe_id}; required for federated results. claimant_session_id: type: string maxLength: 128 description: Opaque session currently holding the claim; required for federated results. PipelineMessage: type: object properties: pipe_id: type: string from_agent: type: string from_provider: type: string description: Persisted provider metadata; never replaced by a friendly name. from_display_name: type: string description: Response-only current local display name. Presentation metadata, not authority. from_registered_name: type: string description: Response-only saved local registration name for current rows. Legacy rows without one use the current display-name compatibility fallback, so this field is presentation metadata rather than immutable history; exact from_agent remains authoritative. from_agent_provider: type: string description: Response-only current provider for the exact local from_agent; presentation fallback only. to_agent: type: string to_provider: type: string description: Persisted provider routing selector; never replaced by a friendly name. to_display_name: type: string description: Response-only current local recipient display name. Omitted for a foreign recipient. to_registered_name: type: string description: Response-only saved local recipient registration name for current rows. Legacy rows without one use the current display-name compatibility fallback; omitted for a foreign recipient. to_agent_provider: type: string description: Response-only current provider for the exact local to_agent; distinct from the persisted to_provider routing selector. intent: type: string payload: type: string status: type: string description: pending, claimed, completed. result: type: string created_at: type: string format: date-time expires_at: type: string format: date-time claimed_at: type: string format: date-time completed_at: type: string format: date-time claimed_by: type: string replied_by: type: string description: >- Present on GET /v1/pipe/results only. The agent that ACTUALLY completed the row and therefore authored the untrusted reply content. It is NOT interchangeable with to_agent: an operator/admin may claim any local pipe and any same-provider agent may claim a provider-addressed one. For a federated reply landed home it equals to_agent, because the transport refuses a result whose remote author differs. Omitted when the node cannot attribute the reply; the addressee is never substituted for it. authority: type: string description: Derived response authority; "data_only" on completed reply projections. trust: type: string description: Derived trust label such as agent_untrusted or external_untrusted. security_notice: type: string description: Derived instruction-boundary notice for untrusted request/result content. payload_authority: type: string description: Derived authority of retained request context; "request_only" when present. result_authority: type: string description: Derived authority of reply content; "data_only" when present. journal_id: type: string source_chain_id: type: string description: Origin SAGE chain for imported work. source_pipe_id: type: string description: Stable origin event ID for imported work. destination_chain_id: type: string description: Destination SAGE chain for outbound work. reply_source_chain_id: type: string description: Local chain that must be bound into a federated result request. federation_policy_epoch: type: string federation_agreement_id: type: string federation_contact_id: type: string federation_contact_revision: type: string description: Target-specific federation authorization revision; unrelated contact changes do not invalidate exact-address queued work. receipt_protocol_version: type: integer enum: [2] description: >- Present only on an imported federated inbox item when both peers negotiated federated-pipeline-receipts-v2. MessageSendRequest: type: object required: [to_agent, payload, idempotency_key] properties: to_agent: type: string minLength: 1 description: Exact active local ordinary-agent ID. Provider aliases and federated addresses are not accepted. payload: type: string minLength: 1 description: Message request content, subject to the pipeline content-size limit. idempotency_key: type: string minLength: 1 maxLength: 256 description: Caller-scoped retry key. Reuse with a different exact request returns 409. intent: type: string description: Optional human-readable purpose, subject to the pipeline intent-size limit. ttl_minutes: type: integer minimum: 0 maximum: 1440 default: 0 description: Omitted/0 keeps the message durable until handled; 1-1440 requests explicit expiry. MessageSendResponse: type: object required: [message_id, status, idempotent_replay] properties: message_id: type: string status: type: string enum: [pending, claimed, completed, expired, failed] expires_at: type: string format: date-time description: Present only when the sender requested an explicit TTL. retention: type: string enum: [durable_until_handled] idempotent_replay: type: boolean MessageReceiveRequest: type: object required: [receive_token] properties: receive_token: type: string minLength: 1 maxLength: 256 description: Caller-scoped token binding one exact ordered claimed batch for response-loss replay. claimant_session_id: type: string maxLength: 128 description: Opaque runtime claimant identity. Empty retains legacy compatibility behavior. limit: type: integer minimum: 1 maximum: 20 default: 5 MessageItem: type: object required: [message_id, from_agent, payload, status, created_at, expires_at, authority, trust, security_notice, claim_revision] properties: message_id: type: string from_agent: type: string from_provider: type: string description: Persisted provider metadata; never replaced by a friendly name. from_display_name: type: string description: Response-only current local display name. Presentation metadata, not authority. from_registered_name: type: string description: Response-only saved local registration name for current rows. Legacy rows without one use the current display-name compatibility fallback, so exact from_agent remains authoritative. intent: type: string payload: type: string description: Untrusted request data. It never conveys tool or instruction authority. status: type: string const: claimed created_at: type: string format: date-time expires_at: type: string format: date-time authority: type: string const: request_only trust: type: string const: agent_untrusted security_notice: type: string claimant_session_id: type: string maxLength: 128 claim_revision: type: integer format: uint64 minimum: 0 description: Current ownership revision; copy it with the session fence for explicit handoff. MessageReceiveResponse: type: object required: [items, count, idempotent_replay] properties: items: type: array items: $ref: "#/components/schemas/MessageItem" count: type: integer minimum: 0 idempotent_replay: type: boolean ClaimedElsewhereItem: type: object required: [message_id, claimant_session_id, claim_revision, created_at, expires_at, foreign] description: >- Passive exact-recipient recovery metadata for one still-actionable claim held by another runtime. Sender, provider, chain ID, intent, payload, and result are deliberately excluded. properties: message_id: type: string claimant_session_id: type: string minLength: 1 maxLength: 128 description: Current compare-and-swap source fence for deliberate handoff. claim_revision: type: integer format: uint64 minimum: 0 description: Current compare-and-swap revision fence. Age alone never authorizes takeover. created_at: type: string format: date-time claimed_at: type: string format: date-time expires_at: type: string format: date-time foreign: type: boolean description: True for inbound federated compatibility work; no chain identifier is exposed. ClaimedElsewhereResponse: type: object required: [claimed_elsewhere_count, items, limit, truncated] properties: claimed_elsewhere_count: type: integer minimum: 0 description: Exact current total across all pages, excluding past-TTL claims. items: type: array maxItems: 20 items: $ref: "#/components/schemas/ClaimedElsewhereItem" limit: type: integer minimum: 1 maximum: 20 truncated: type: boolean next_cursor: type: string description: Opaque exclusive continuation, present only when truncated is true. MessageHandoffRequest: type: object required: [from_session_id, to_session_id] properties: from_session_id: type: string minLength: 1 maxLength: 128 to_session_id: type: string minLength: 1 maxLength: 128 from_revision: type: integer format: uint64 minimum: 0 default: 0 description: >- Current clients must copy the exact claim_revision from passive history. Omission defaults to revision 0 only for pre-v11.19.5 REST compatibility and conflicts after any ownership transfer. MessageHandoffResponse: type: object required: [message_id, claimant_session_id, claim_revision, idempotent_replay] properties: message_id: type: string claimant_session_id: type: string claim_revision: type: integer format: uint64 minimum: 0 idempotent_replay: type: boolean InboxActivityState: type: object required: [version, epoch, seq] additionalProperties: false properties: version: type: integer const: 1 epoch: type: string minLength: 32 maxLength: 32 pattern: '^[0-9a-f]{32}$' description: >- Opaque payload-free database-incarnation fence. Stable across process restart and backup restore; different for a fresh database. seq: type: integer format: uint64 minimum: 0 description: >- Exact three-field payload-free task/reply coordination state; never unfinished-work or Stop authority. Compare epoch before seq so a preserved cursor cannot suppress cues after database reinitialization. MessageCloseRequest: type: object required: [reason, claimant_session_id] properties: reason: type: string minLength: 1 description: Recipient-local audit reason, up to 1024 UTF-8 bytes. claimant_session_id: type: string minLength: 1 maxLength: 128 MessageReplyRequest: type: object required: [result] properties: result: type: string minLength: 1 description: Exact reply content. The same second reply is idempotent; a different reply returns 409. MessageActionResponse: type: object required: [message_id, idempotent_replay] properties: message_id: type: string status: type: string enum: [completed] completion_kind: type: string const: closed_without_reply reply_sent: type: boolean const: false read_status: type: string enum: [confirmed] idempotent_replay: type: boolean MessageStatusResponse: type: object required: [message_id, scope, transport_status, read_status, workflow_status, sent_at, expires_at] description: Payload-free metadata returned only to the exact signed sender. properties: message_id: type: string scope: type: string const: local transport_status: type: string const: delivered description: Durable same-node inbox insertion, not evidence of presence or comprehension. read_status: type: string enum: [not_confirmed, confirmed] read_evidence: type: string const: local_exact_ack completion_kind: type: string const: closed_without_reply workflow_status: type: string enum: [pending, claimed, completed, expired, failed] sent_at: type: string format: date-time delivered_at: type: string format: date-time read_at: type: string format: date-time completed_at: type: string format: date-time expires_at: type: string format: date-time terminal_at: type: string format: date-time terminal_reason: type: string enum: [completed, expired, failed] FederatedPipeReceiptChallenge: type: object required: - version - message_id - sender_chain_id - recipient_chain_id - sender_agent_id - recipient_agent_id - content_digest - event_kind - policy_epoch - agreement_id - contact_id - contact_revision description: >- Payload-free immutable challenge returned only to the exact recipient of a negotiated receipt-v2 import. Submit it unchanged to the matching receipt/{kind} route so the exact recipient signs every binding. properties: version: type: integer const: 2 message_id: type: string sender_chain_id: type: string recipient_chain_id: type: string sender_agent_id: type: string recipient_agent_id: type: string content_digest: type: string event_kind: type: string enum: [claimed, read] policy_epoch: type: string agreement_id: type: string contact_id: type: string contact_revision: type: string authorization_mode: type: string relation_digest: type: string FederatedPipeReceiptActionResponse: type: object required: [pipe_id, event_kind, receipt_status, idempotent_replay] properties: pipe_id: type: string event_kind: type: string enum: [claimed, read] receipt_status: type: string const: queued idempotent_replay: type: boolean FederatedPipeReceiptStatus: type: object required: [pipe_id, protocol, transport_status, claim_status, read_status] description: >- Payload-free exact-sender projection. Delivery, recipient claim/read, and terminal outcome are independent monotonic dimensions; timestamps are evidence metadata and never order authority. properties: pipe_id: type: string protocol: type: string enum: [unsupported, receipt-v2] transport_status: type: string enum: [pending, delivered, failed] delivery_evidence: type: string enum: [peer_operator_durable_admission] delivered_at: type: string format: date-time claim_status: type: string enum: [unconfirmed, confirmed] claimed_at: type: string format: date-time read_status: type: string enum: [unconfirmed, confirmed] read_at: type: string format: date-time terminal_kind: type: string enum: [failed, expired, revoked] terminal_at: type: string format: date-time PipelineDeliveryUpdate: type: object description: Payload-free, one-shot terminal delivery feedback for the local signing agent. properties: event_id: type: string pipe_id: type: string event_kind: type: string enum: [send, result] remote_chain_id: type: string target_agent_id: type: string state: type: string enum: [failed] attempts: type: integer last_error: type: string description: Peer-originated diagnostic text; clients must present it as external/untrusted. created_at: type: string format: date-time # -- Embeddings ---------------------------------------------------------- EmbedRequest: type: object required: - text properties: text: type: string EmbedResponse: type: object properties: embedding: type: array items: type: number format: float model: type: string dimension: type: integer EmbedInfoResponse: type: object properties: semantic: type: boolean description: >- True when a real embedding provider is available (or vault is active — in that case FTS5 cannot index encrypted content). provider: type: string description: Active embedding provider name (e.g. ollama, hash). dimension: type: integer ready: type: boolean submit_embedding_authoritative: type: boolean description: >- True when POST /v1/memory/submit always generates the authoritative vector with the node's active provider. Current MCP clients use this capability to omit a redundant compatibility embedding; older nodes omit the field and continue receiving the client-generated vector. # -- MCP Tokens ---------------------------------------------------------- MCPTokenIssueRequest: type: object required: - agent_id properties: name: type: string description: Human label, e.g. "chatgpt-laptop". agent_id: type: string description: >- App-v23: 64-char hex Ed25519 pubkey of an existing active approved ordinary agent whose exact key is locally managed. The bearer executes with that identity's existing permissions. Pre-v23: the node operator identity. MCPTokenIssueResponse: type: object properties: id: type: string description: Public token ID used for revocation. name: type: string agent_id: type: string token: type: string description: Base64url(32 random bytes). Shown ONCE — never stored in plaintext. created_at: type: string format: date-time use_hint: type: string MCPTokenSummary: type: object properties: id: type: string name: type: string agent_id: type: string created_at: type: string format: date-time last_used_at: type: string format: date-time revoked_at: type: string format: date-time HealthResponse: type: object required: - status - version properties: status: type: string example: healthy version: type: string example: 11.15.0 ReadinessResponse: type: object required: - status - postgres - cometbft properties: status: type: string example: ready postgres: type: boolean cometbft: type: boolean scoped_projection: type: object description: >- v11.9 canonical scoped-content projection status. When required is true and ok is false, readiness fails closed with HTTP 503. required: - checked - required - ok - records - rebuilt properties: checked: type: boolean required: type: boolean ok: type: boolean records: type: integer rebuilt: type: integer detail: type: string ProblemDetails: type: object description: RFC 7807 Problem Details for HTTP APIs. required: - type - title - status - detail properties: type: type: string format: uri description: URI reference identifying the problem type. title: type: string description: Short, human-readable summary. status: type: integer description: HTTP status code. detail: type: string description: Human-readable explanation specific to this occurrence. instance: type: string format: uri description: URI reference identifying the specific occurrence. reason_code: type: string description: Stable sanitized machine-readable denial reason, when available. remedy: type: string description: Exact operator action that can make a later request valid. retryable: type: boolean description: Whether automatically repeating the same request is safe. DomainWriteDeniedProblem: allOf: - $ref: "#/components/schemas/ProblemDetails" - type: object required: - reason_code - remedy - retryable properties: type: const: https://sage.dev/errors/domain-write-denied status: const: 403 reason_code: type: string enum: - missing_write_grant - foreign_write_restricted - shared_write_restricted - domain_claim_restricted - principal_pending_review - no_owned_home_domain - manager_scope_denied remedy: type: string retryable: const: false # ----------------------------------------------------------------------- # Reusable responses # ----------------------------------------------------------------------- responses: BadRequest: description: Invalid request body or parameters. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" Unauthorized: description: Missing or invalid authentication headers. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" Forbidden: description: >- Caller authenticated but lacks authorisation, or the request was rejected during on-chain finalisation (e.g. quorum-gated tx without an executed proposal). The `detail` field carries the upstream rejection reason. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" NotFound: description: Resource not found. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" Conflict: description: Conflict (e.g. duplicate submission or already voted). content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" InternalError: description: Internal server error. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" ServiceUnavailable: description: Required node runtime capability or configuration is unavailable. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" NotImplemented: description: The active node runtime does not implement this optional capability. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" # --------------------------------------------------------------------------- # Paths # --------------------------------------------------------------------------- paths: # -- Memory -------------------------------------------------------------- /v1/memory/submit: post: operationId: submitMemory summary: Submit a new memory for consensus validation. tags: - Memory requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MemorySubmitRequest" responses: "200": description: >- Confirmed idempotent task replay. Returns the original memory_id/tx_hash/height and current task status; no new task was created. content: application/json: schema: $ref: "#/components/schemas/MemorySubmitResponse" "202": description: >- The task transaction committed but its exact task/assignee projection was not confirmed. projection_confirmed and retryable are false; reconcile the returned memory_id and do not resubmit. content: application/json: schema: $ref: "#/components/schemas/MemorySubmitResponse" "201": description: >- New memory transaction committed. For an app-v23 task the exact assignee projection is confirmed. content: application/json: schema: $ref: "#/components/schemas/MemorySubmitResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": description: >- Memory write denied. A canonical permanent denial includes the stable reason_code/remedy/retryable=false contract; unknown denials remain generic Problem Details. content: application/problem+json: schema: anyOf: - $ref: "#/components/schemas/DomainWriteDeniedProblem" - $ref: "#/components/schemas/ProblemDetails" "409": $ref: "#/components/responses/Conflict" "503": description: >- Task assignment bridge, idempotency receipt, or current authorization state is unavailable. No new retry transaction is broadcast when the authoritative receipt cannot be verified. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "500": $ref: "#/components/responses/InternalError" /v1/memory/query: post: operationId: queryMemories summary: Perform a vector similarity search over memories. tags: - Memory requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MemoryQueryRequest" responses: "200": description: Query results. content: application/json: schema: $ref: "#/components/schemas/MemoryQueryResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "422": description: >- App-v23 authorization would require examining more than 8,192 raw candidates. Narrow the domain, provider, tag, status, or other filters before retrying. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "500": $ref: "#/components/responses/InternalError" /v1/memory/search: post: operationId: searchMemories summary: Full-text search over memories (FTS5/BM25). description: >- Not available when vault (content encryption) is active — use GET /v1/embed/info to check; route to /v1/memory/query instead when semantic=true. tags: - Memory requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MemorySearchRequest" responses: "200": description: Search results. Same shape as /v1/memory/query response. content: application/json: schema: $ref: "#/components/schemas/MemoryQueryResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "422": description: >- App-v23 authorization would require examining more than 8,192 raw candidates. Narrow the domain, provider, tag, status, or other filters before retrying. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "500": $ref: "#/components/responses/InternalError" /v1/memory/hybrid: post: operationId: hybridSearchMemories summary: Fused FTS5 + vector search via Reciprocal Rank Fusion. description: >- At least one of `query` or `embedding` is required. Supports query expansions for multi-variant recall, with at most eight expansion entries. Under app-v23 the primary query, all expansion variants, and every text/vector store leaf share one 8,192-candidate live authorization budget. Exhausting that budget returns 422. A governed leaf failure fails the entire request (503 when authorization state is unavailable, otherwise the applicable error) and never returns a 200 response containing partial fused results. tags: - Memory requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MemoryHybridRequest" responses: "200": description: Hybrid search results. Same shape as /v1/memory/query response. content: application/json: schema: $ref: "#/components/schemas/MemoryQueryResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "422": description: >- The request contains more than eight expansion entries, or app-v23 authorization across the primary query, all expansions, and all text/vector leaves would require examining more than 8,192 raw candidates. Reduce expansions or narrow the domain, provider, tag, status, or other filters before retrying. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "503": description: >- Live authorization state needed by a governed hybrid leaf is unavailable. The request fails closed; no partial fused result is returned. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "500": $ref: "#/components/responses/InternalError" /v1/memory/list: get: operationId: listMemories summary: Paginated memory list with RBAC agent isolation. description: >- App-v23 applies live authorization before visible offset/limit. When has_more is true, total is an authorization-safe visible lower bound and total_exact is false. Once the visible stream is exhausted, total_exact is true and total is exact. Denied/raw counts are never returned. Visible offset is capped at 7,900 and one request examines at most 8,192 raw authorization candidates. A broader request returns 422 Query too broad and must be narrowed. tags: - Memory parameters: - name: limit in: query schema: type: integer default: 50 maximum: 200 - name: offset in: query schema: type: integer default: 0 minimum: 0 maximum: 7900 description: App-v23 maximum is 7,900 visible records. - name: domain in: query schema: type: string - name: tag in: query schema: type: string - name: provider in: query schema: type: string - name: status in: query schema: type: string - name: sort in: query schema: type: string - name: agent in: query schema: type: string description: Filter by submitting agent ID. responses: "200": description: Paginated list of memories. content: application/json: schema: type: object properties: memories: type: array items: $ref: "#/components/schemas/MemoryRecord" total: type: integer description: >- Visible total or authorization-safe lower bound; inspect total_exact. limit: type: integer offset: type: integer has_more: type: boolean description: Whether another currently visible row exists. total_exact: type: boolean description: Whether total is the exact visible total. filtered: $ref: "#/components/schemas/FilterInfo" "401": $ref: "#/components/responses/Unauthorized" "422": description: >- Offset exceeds 7,900 or app-v23 authorization would require examining more than 8,192 raw candidates. Narrow filters or page sequentially. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "503": description: Current app-v23 record authorization state is unavailable. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "500": $ref: "#/components/responses/InternalError" /v1/memory/timeline: get: operationId: getMemoryTimeline summary: Memory creation counts grouped by time bucket. description: >- Before app-v23, the historical no-domain aggregate is global. App-v23 treats aggregate existence/timing as governed metadata: it walks stable bounded memory pages across the requested range, applies central live record disclosure to every row, and counts only currently visible records. RFC3339 bounds are limited to 31 days and 8,192 raw candidates per request; overly wide/dense requests return 422. Authorization-state failure returns 503. Bucket period strings preserve the backend's historical SQLite or PostgreSQL representation. tags: - Memory parameters: - name: domain in: query schema: type: string - name: bucket in: query schema: type: string default: hour description: Time bucket size. - name: from in: query schema: type: string format: date-time description: Start time (RFC3339). Defaults to now-24h. - name: to in: query schema: type: string format: date-time description: End time (RFC3339). Defaults to now. responses: "200": description: Timeline buckets. content: application/json: schema: type: object required: [buckets, total] properties: buckets: type: array items: type: object required: [period, count] properties: period: type: string count: type: integer domain: type: string total: type: integer description: Sum of the currently visible bucket counts. "401": $ref: "#/components/responses/Unauthorized" "400": description: Invalid or reversed RFC3339 timeline range. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "422": description: Timeline range or governed candidate set is too large. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "503": description: Current app-v23 record authorization state is unavailable. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "500": $ref: "#/components/responses/InternalError" /v1/memory/tasks: get: operationId: getOpenTasks summary: Open task memories (type=task, status != done/dropped). description: >- Returns at most 500 open tasks whose assignee exactly matches the authenticated agent and which also pass current live domain/group/grant and classification authority. Unassigned and differently assigned work is never returned. total is the visible count. Current-generation Admin use is localhost-only; Root/history/stale identities are denied. Manager group Modify authority never widens exact task assignment. App-v23 examines at most 8,192 raw authorization candidates; broader requests return 422 and must be narrowed by domain or provider. tags: - Memory parameters: - name: domain in: query schema: type: string - name: provider in: query schema: type: string responses: "200": description: Open tasks. content: application/json: schema: type: object properties: tasks: type: array items: type: object properties: memory_id: type: string content: type: string domain_tag: type: string task_status: type: string assignee: type: string task_picked_up_by: type: string task_picked_up_at: type: string format: date-time confidence_score: type: number format: double created_at: type: string total: type: integer description: Number of visible exact-assignee tasks returned. "401": $ref: "#/components/responses/Unauthorized" "403": description: App-v23 caller is not an active ordinary agent. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "422": description: >- App-v23 authorization would require examining more than 8,192 raw task candidates. Narrow the domain or provider filter. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "503": description: App-v23 local policy state is unavailable. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "500": $ref: "#/components/responses/InternalError" "500": $ref: "#/components/responses/InternalError" /v1/memory/link: post: operationId: linkMemories summary: Link two memories with a relationship type (off-chain, no tx). tags: - Memory requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MemoryLinkRequest" responses: "200": description: Link created. content: application/json: schema: $ref: "#/components/schemas/MemoryLinkResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v1/memory/evidence: post: operationId: uploadMemoryEvidence summary: Upload node-local evidence for a memory this agent will submit. description: >- Stores the evidence on this node only (encrypted like memory content when the vault is on) for the optional memory gate's evidence check, and returns an id to pass as evidence_id on /v1/memory/submit. Nothing is broadcast. An agent may hold at most 64 unclaimed uploads; each expires after an hour. tags: - Memory requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UploadEvidenceRequest" responses: "201": description: Evidence stored; claim it with evidence_id. content: application/json: schema: $ref: "#/components/schemas/UploadEvidenceResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": description: Above app-v23, the caller is not an active ordinary agent (Root is not an agent). content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "429": description: Too much unclaimed evidence for this agent. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "501": description: This node's store does not keep evidence. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" /v1/memory/pre-validate: post: operationId: preValidateMemory summary: Dry-run the per-node validation checks without submitting on-chain. tags: - Memory requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PreValidateRequest" responses: "200": description: Per-validator decisions. content: application/json: schema: $ref: "#/components/schemas/PreValidateResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "503": description: Pre-validation not configured on this node. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" /v1/memory/{memory_id}: get: operationId: getMemory summary: Retrieve a single memory by ID. description: >- App-v23 applies the same live enrollment, legacy-envelope, domain/group/grant, and clearance decision as recall/list. Authorship is provenance, not a read bypass. tags: - Memory parameters: - $ref: "#/components/parameters/memoryId" responses: "200": description: Full memory record with votes and corroborations. content: application/json: schema: $ref: "#/components/schemas/MemoryRecord" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "503": description: Current app-v23 record authorization state is unavailable. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "500": $ref: "#/components/responses/InternalError" /v1/memory/{memory_id}/vote: post: operationId: voteOnMemory summary: Authorize this node's local validator to vote on a proposed memory. description: >- Deliberate local operator override for this node's single validator vote; this is not an ordinary agent vote. Before app-v23 the caller must be the configured governance operator. Under app-v23 the caller must be the current CEREBRUM Root or a current local Admin and connect through localhost. The node must have its live validator signing key. tags: - Memory parameters: - $ref: "#/components/parameters/memoryId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/VoteRequest" responses: "200": description: Vote recorded. content: application/json: schema: $ref: "#/components/schemas/VoteResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalError" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/memory/{memory_id}/challenge: post: operationId: challengeMemory summary: Challenge an existing committed memory. tags: - Memory parameters: - $ref: "#/components/parameters/memoryId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ChallengeRequest" responses: "200": description: Challenge submitted. content: application/json: schema: $ref: "#/components/schemas/ChallengeResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/memory/{memory_id}/forget: post: operationId: forgetMemory summary: Semantic alias for challenge — submits a TxTypeMemoryChallenge with reason "deprecated by user". tags: - Memory parameters: - $ref: "#/components/parameters/memoryId" requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/ForgetRequest" responses: "200": description: Memory forgotten. content: application/json: schema: $ref: "#/components/schemas/ForgetResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/memory/{memory_id}/reinstate: post: operationId: reinstateMemory summary: Return an open challenged memory to committed. description: >- Under app-v21, only an identity in the challenge round's snapshotted electorate may reinstate; later grant churn does not change eligibility. Legacy app-v17 challenges retain their original authorization rules. tags: - Memory parameters: - $ref: "#/components/parameters/memoryId" requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/ReinstateRequest" responses: "200": description: Memory reinstated after consensus commit. content: application/json: schema: $ref: "#/components/schemas/ReinstateResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalError" /v1/memory/{memory_id}/corroborate: post: operationId: corroborateMemory summary: Corroborate an existing memory with supporting evidence. tags: - Memory parameters: - $ref: "#/components/parameters/memoryId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CorroborateRequest" responses: "200": description: Corroboration recorded. content: application/json: schema: $ref: "#/components/schemas/CorroborateResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/memory/{memory_id}/task-status: put: operationId: updateTaskStatus summary: Start or finish an owned task (off-chain only, no tx). description: >- Requires an active signed agent that is already the task's exact assignee and still has current domain write plus classification/read authority. in_progress starts an assigned open task; unassigned work requires local CEREBRUM handoff. done or dropped also requires the exact assignee. Agents cannot set planned or reopen terminal work. Current Admin use is localhost-only; Root/history/stale identities are denied, and Manager group Modify does not widen assignment. tags: - Memory parameters: - $ref: "#/components/parameters/memoryId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TaskStatusUpdateRequest" responses: "200": description: Task status updated. content: application/json: schema: $ref: "#/components/schemas/TaskStatusUpdateResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": description: Task is terminal or not currently assigned to this exact agent. "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" # -- Agent --------------------------------------------------------------- /v1/agents: get: operationId: listRegisteredAgents summary: List agents visible to the authenticated caller. description: >- Requires an Ed25519-signed request. After app-v23 activation the response contains only active ordinary agents within the caller's enforced discovery boundary; pending, inactive, Root, and inconsistent identities are omitted. tags: - Agent responses: "200": description: Caller-scoped list of active ordinary agents. content: application/json: schema: type: object properties: agents: type: array items: $ref: "#/components/schemas/RegisteredAgent" total: type: integer "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" /v1/agents/directory: get: operationId: listAgentDirectory summary: List minimal local recipient identities. description: >- Signed active-ordinary local directory used by sage_directory. Root, historical Root, pending, inactive, removed, retired, and canonically inconsistent identities are omitted. This endpoint provides no online, reachability, delivery, or read evidence and never returns RBAC or memory-count fields. The database projection is capped at 100 returned active recipients; truncated=true directs callers to the bounded name lookup for recipients outside that picker window. tags: [Agent] responses: "200": description: Minimal active local recipient directory. content: application/json: schema: type: object required: [agents, total, truncated] properties: agents: type: array items: $ref: "#/components/schemas/AgentDirectoryEntry" total: type: integer minimum: 0 truncated: type: boolean "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" "501": $ref: "#/components/responses/InternalError" "503": $ref: "#/components/responses/InternalError" /v1/agents/lookup: get: operationId: lookupAgentsByName summary: Resolve a bounded local recipient name. description: >- Signed literal substring lookup across active ordinary agents' display name, immutable registered name, and provider. Exact field matches rank before substring matches. It is recipient discovery, not presence. tags: [Agent] parameters: - in: query name: name required: true schema: type: string minLength: 1 maxLength: 512 - in: query name: limit required: false schema: type: integer minimum: 1 maximum: 20 default: 20 responses: "200": description: Ranked bounded local recipient matches. content: application/json: schema: type: object required: [agents, total] properties: agents: type: array maxItems: 20 items: $ref: "#/components/schemas/AgentLookupEntry" total: type: integer minimum: 0 maximum: 20 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" "501": $ref: "#/components/responses/InternalError" "503": $ref: "#/components/responses/InternalError" /v1/agent/me: get: operationId: getAgentProfile summary: Retrieve the authenticated agent's profile. description: >- After app-v23 activation this signed self-scoped route is available to a registered ordinary agent, including pending_review and inactive callers, and exposes only that caller's role, policy, capability mask, and home-domain access standing. It does not reopen the active-only signed agent roster. CEREBRUM Root has no ordinary agent profile. tags: - Agent parameters: - in: query name: view required: false schema: type: string enum: [standing] description: Return only authenticated consensus standing, skipping optional SQL domain-history and PoE projections. responses: "200": description: Agent profile. content: application/json: schema: $ref: "#/components/schemas/AgentProfile" "401": $ref: "#/components/responses/Unauthorized" "404": description: The signed key is unregistered or is CEREBRUM Root rather than an ordinary agent. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "503": description: App-v23 local policy state is unavailable. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" /v1/agent/me/domains: get: operationId: getAgentReadableDomains summary: Retrieve bounded readable domains for the authenticated agent. description: >- Returns only current caller-authorized domain identifiers derived from the caller's current owned-domain index and home/provenance, direct grants, and the bounded current owned-domain indexes of active local Access Group peers. This includes transferred domains that were never authored by their current owner. Candidates are re-authorized against live policy. The result is bounded and may be truncated; it is not a global domain roster or a complete expansion of read-all/ancestor authority. tags: - Agent responses: "200": description: Bounded caller-readable domain sample. content: application/json: schema: type: object required: [domains, owned_domains, readable_domains, writable_domains, truncated, scope] properties: domains: type: array maxItems: 64 items: type: string owned_domains: description: Bounded ownership sample. Use /v1/agent/me/domains/owned for the authoritative paged set. type: array maxItems: 64 items: {type: string} readable_domains: description: Bounded current-policy sample suitable for choosing an exact recall scope. type: array maxItems: 64 items: {type: string} writable_domains: description: Bounded current-policy sample suitable for choosing an exact write scope. type: array maxItems: 64 items: {type: string} truncated: type: boolean scope: type: string enum: [bounded_policy_and_provenance] "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "503": $ref: "#/components/responses/InternalError" /v1/agent/me/domains/owned: get: operationId: getAgentOwnedDomains summary: Page through domains currently owned by the authenticated agent. description: >- Caller-only authoritative ownership projection backed by the consensus-maintained app-v26 owner index. It does not scan memories or enumerate a global domain roster. Pass next_cursor back as cursor until has_more is false. tags: [Agent] parameters: - in: query name: cursor required: false schema: {type: string, maxLength: 512} - in: query name: limit required: false schema: {type: integer, minimum: 1, maximum: 100, default: 50} responses: "200": description: One stable lexicographic page of currently owned domains. content: application/json: schema: type: object required: [domains, has_more, scope] properties: domains: type: array maxItems: 100 items: {type: string} next_cursor: {type: string} has_more: {type: boolean} scope: type: string enum: [authoritative_current_owner] "400": {description: Invalid cursor or limit.} "401": {$ref: "#/components/responses/Unauthorized"} "403": {$ref: "#/components/responses/Forbidden"} "503": {$ref: "#/components/responses/InternalError"} /v1/agent/register: post: operationId: registerAgent summary: Register an agent on-chain via CometBFT consensus. description: >- Idempotent — returns existing record (HTTP 200) if agent is already registered. Returns HTTP 201 for new registrations. tags: - Agent requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AgentRegisterRequest" responses: "201": description: Agent registered (new registration). content: application/json: schema: $ref: "#/components/schemas/RegisteredAgent" "200": description: Agent already registered (idempotent response). content: application/json: schema: $ref: "#/components/schemas/RegisteredAgent" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v1/agent/update: put: operationId: updateAgent summary: Update the authenticated agent's name and bio. description: >- Self-update only — agents can only modify their own metadata. Omitted name or boot_bio fields preserve their current canonical values. tags: - Agent requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AgentUpdateRequest" responses: "200": description: Agent updated. content: application/json: schema: type: object properties: agent_id: type: string name: type: string status: type: string example: updated tx_hash: type: string "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v1/agent/{id}: get: operationId: getRegisteredAgent summary: Get a registered agent by ID. tags: - Agent parameters: - name: id in: path required: true schema: type: string description: Agent's hex-encoded Ed25519 public key. responses: "200": description: Agent record. content: application/json: schema: $ref: "#/components/schemas/RegisteredAgent" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" # -- Validator ----------------------------------------------------------- /v1/validator/pending: get: operationId: getPendingMemories summary: List memories awaiting validator votes. description: >- App-v23 applies live record authorization before returning pending candidates and examines at most 8,192 raw candidates per request. A broader request returns 422 and must be narrowed by domain. tags: - Validator parameters: - name: domain_tag in: query required: false schema: type: string description: Filter by domain tag. - name: limit in: query required: false schema: type: integer default: 20 minimum: 1 maximum: 100 description: Maximum number of results. - name: cursor in: query required: false schema: type: string description: Opaque pagination cursor. responses: "200": description: Pending memories. content: application/json: schema: $ref: "#/components/schemas/PendingMemoriesResponse" "401": $ref: "#/components/responses/Unauthorized" "422": description: >- App-v23 authorization would require examining more than 8,192 raw pending candidates. Narrow the domain filter. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "500": $ref: "#/components/responses/InternalError" /v1/validator/epoch: get: operationId: getEpochInfo summary: Retrieve current epoch information and validator scores. tags: - Validator responses: "200": description: Epoch info with per-validator PoE scores. content: application/json: schema: $ref: "#/components/schemas/EpochInfo" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" # -- Access Control ------------------------------------------------------- /v1/access/request: post: operationId: accessRequest summary: Request read or read+write access to a domain. tags: - Access requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AccessRequestBody" responses: "201": description: Access request submitted. content: application/json: schema: type: object properties: status: type: string example: pending tx_hash: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v1/access/grant: post: operationId: accessGrant summary: Grant domain access. Caller must own the domain or be admin. tags: - Access requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AccessGrantRequest" responses: "201": description: Access granted. content: application/json: schema: type: object properties: status: type: string example: granted tx_hash: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" /v1/access/revoke: post: operationId: accessRevoke summary: Revoke domain access. tags: - Access requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AccessRevokeRequest" responses: "200": description: Access revoked. content: application/json: schema: type: object properties: status: type: string example: revoked tx_hash: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" /v1/access/grants/{agent_id}: get: operationId: listAccessGrants summary: List active grants for an agent. tags: - Access parameters: - name: agent_id in: path required: true schema: type: string description: Hex-encoded agent ID. responses: "200": description: Array of grant objects. content: application/json: schema: type: array items: type: object "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/access/grants-snapshot/{agent_id}: get: operationId: inspectDirectGrantsSnapshot summary: Return a committed exact-target direct-grant snapshot. description: >- App-v23 or later only. The target's active exact-domain grant rows, caller and target authorization state, current Root generation, and stored committed height/AppHash are read from one Badger transaction. The caller may inspect itself; a current local Admin may inspect another active ordinary agent. This is not effective access or a global atomic directory snapshot. Oversized, malformed, cancelled, or incomplete reads fail closed rather than returning a partial success. tags: - Access parameters: - name: agent_id in: path required: true schema: type: string pattern: "^[0-9a-f]{64}$" description: Canonical lowercase 64-hex agent ID. responses: "200": description: Complete active direct-grant snapshot for one target. content: application/json: schema: $ref: "#/components/schemas/DirectGrantsSnapshot" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" "503": $ref: "#/components/responses/ServiceUnavailable" # -- Domains --------------------------------------------------------------- /v1/domain/register: post: operationId: domainRegister summary: Register a non-shared domain. Caller becomes owner. description: >- Reserved static catch-alls and governance-promoted shared domains are ownerless and reject registration with HTTP 403 / ABCI code 50. tags: - Domain requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DomainRegisterRequest" responses: "201": description: Domain registered. content: application/json: schema: type: object properties: status: type: string example: registered tx_hash: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" /v1/domain/{name}: get: operationId: getDomain summary: Get domain metadata. description: >- Ownership served from BadgerDB (chain-authoritative); description/created_at enriched from off-chain mirror. tags: - Domain parameters: - name: name in: path required: true schema: type: string description: Dotted-path domain name. responses: "200": description: Domain metadata. content: application/json: schema: type: object properties: domain_name: type: string owner_agent_id: type: string parent_domain: type: string created_height: type: integer format: int64 description: type: string created_at: type: string format: date-time "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/domain/reassign: post: operationId: reassignDomain summary: >- Execute a domain ownership reassignment authorised by a previously accepted governance proposal (v8.0 access-control recovery primitive). description: >- Quorum-gated recovery wrapper around BadgerStore.TransferDomain. Pre-requisites: a `gov_propose` of operation `domain_reassign` with the matching payload was accepted by a 3/4 validator supermajority and is in status `executed`. Submitting this tx burns the proposal (single-use) and purges all grants on the target domain. Caller must be a chain admin; ABCI re-verifies admin role on-chain. tags: - Domain requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DomainReassignRequest" responses: "200": description: Reassignment executed; previous grants purged. content: application/json: schema: $ref: "#/components/schemas/DomainReassignResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" # -- Orgs --------------------------------------------------------------- /v1/org/register: post: operationId: orgRegister summary: Register an organization. Calling agent becomes admin. description: >- org_id is deterministic: hex(SHA256(agentID + name)[:16]). tags: - Org requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/OrgRegisterRequest" responses: "201": description: Organization registered. content: application/json: schema: type: object properties: status: type: string example: registered org_id: type: string tx_hash: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v1/org/by-name/{name}: get: operationId: getOrgByName summary: Look up orgs by name. Returns all matches (names are not unique on-chain). tags: - Org parameters: - name: name in: path required: true schema: type: string responses: "200": description: Matching organizations (empty list if none found, not 404). content: application/json: schema: type: object properties: orgs: type: array items: type: object "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v1/org/{org_id}: get: operationId: getOrg summary: Get org. Chain-authoritative from BadgerDB; description/created_at enriched from mirror. tags: - Org parameters: - name: org_id in: path required: true schema: type: string responses: "200": description: Organization record. content: application/json: schema: type: object "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/org/{org_id}/members: get: operationId: listOrgMembers summary: List org members from chain. tags: - Org parameters: - name: org_id in: path required: true schema: type: string responses: "200": description: List of org members. content: application/json: schema: type: object "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/org/{org_id}/member: post: operationId: orgAddMember summary: Add agent to org. Admin only on-chain. tags: - Org parameters: - name: org_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/OrgAddMemberRequest" responses: "201": description: Member added. content: application/json: schema: type: object properties: status: type: string example: added tx_hash: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" /v1/org/{org_id}/member/{agent_id}: delete: operationId: orgRemoveMember summary: Remove agent from org. Admin only on-chain. tags: - Org parameters: - name: org_id in: path required: true schema: type: string - name: agent_id in: path required: true schema: type: string responses: "200": description: Member removed. content: application/json: schema: type: object properties: status: type: string example: removed tx_hash: type: string "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/org/{org_id}/clearance: post: operationId: orgSetClearance summary: Change an agent's clearance within the org. Admin only on-chain. tags: - Org parameters: - name: org_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/OrgSetClearanceRequest" responses: "200": description: Clearance updated. content: application/json: schema: type: object properties: status: type: string example: updated tx_hash: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" /v1/org/{org_id}/enroll-tokens: post: operationId: issueOrgEnrollToken summary: Issue a short-lived, node-bound org enrollment token. description: Global Admin only. The plaintext token is returned once; only its SHA-256 digest is stored. Tokens expire after 24 hours and may grant only member or observer org membership. tags: - Org parameters: - name: org_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/OrgEnrollTokenIssueRequest" responses: "201": description: Token issued. The plaintext is present only in this response. content: application/json: schema: $ref: "#/components/schemas/OrgEnrollTokenIssueResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" get: operationId: listOrgEnrollTokens summary: List org enrollment-token metadata without bearer plaintext. tags: - Org parameters: - name: org_id in: path required: true schema: type: string responses: "200": description: Token metadata, including issuance/expiry/revocation state. content: application/json: schema: type: object required: - tokens properties: tokens: type: array items: $ref: "#/components/schemas/OrgEnrollTokenSummary" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/org/{org_id}/enroll-tokens/{id}: delete: operationId: revokeOrgEnrollToken summary: Revoke an unused org enrollment token. description: Revocation blocks a first redemption but never erases a committed enrollment outcome, so the bound enrollee can still replay a lost enrollment response. tags: - Org parameters: - name: org_id in: path required: true schema: type: string - name: id in: path required: true schema: type: string responses: "204": description: Token revoked or already revoked. "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/org/{org_id}/enroll: post: operationId: redeemOrgEnrollment summary: Redeem a node-bound org enrollment token and accept its first policy. description: The signed request must use exactly the token's enrollee_pub. The first policy must match the token org, scope, and pinned signer/epoch. Consume marker, replayable outcome, and accepted policy commit together. tags: - Org parameters: - name: org_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/OrgEnrollRequest" responses: "201": description: First enrollment committed. content: application/json: schema: $ref: "#/components/schemas/OrgEnrollResponse" "200": description: Idempotent replay of an already-committed enrollment. content: application/json: schema: $ref: "#/components/schemas/OrgEnrollResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": description: Token or org already committed to a conflicting enrollment. "500": $ref: "#/components/responses/InternalError" /v1/org/{org_id}/policy: get: operationId: getOrgPolicyStatus summary: Read this node's accepted org policy state and per-operation gate. tags: - Org parameters: - name: org_id in: path required: true schema: type: string responses: "200": description: Accepted policy metadata, gate verdicts, and durable equivocation notice. content: application/json: schema: $ref: "#/components/schemas/OrgPolicyStatus" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" post: operationId: deliverOrgPolicy summary: Deliver a newer signed org policy. description: Authority comes from the org signature and an optional time-valid rotation chain. Scope is immutable after enrollment. Same-revision conflicts are persisted as equivocation without replacing the accepted policy. tags: - Org parameters: - name: org_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/OrgPolicyUpdateRequest" responses: "200": description: Policy applied or identical revision no-op. content: application/json: schema: $ref: "#/components/schemas/OrgPolicyUpdateResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": description: Rollback, immutable-scope conflict, or same-revision equivocation. content: application/json: schema: $ref: "#/components/schemas/OrgPolicyUpdateResponse" "500": $ref: "#/components/responses/InternalError" # -- Departments ------------------------------------------------------- /v1/org/{org_id}/dept: post: operationId: deptRegister summary: Register a department. dept_id is deterministic hex(SHA256(orgID + name)[:8]). tags: - Org parameters: - name: org_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DeptRegisterRequest" responses: "201": description: Department registered. content: application/json: schema: type: object properties: status: type: string example: registered dept_id: type: string tx_hash: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v1/org/{org_id}/dept/{dept_id}: get: operationId: getDept summary: Get department. tags: - Org parameters: - name: org_id in: path required: true schema: type: string - name: dept_id in: path required: true schema: type: string responses: "200": description: Department record. content: application/json: schema: type: object "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/org/{org_id}/depts: get: operationId: listOrgDepts summary: List all departments in an org. tags: - Org parameters: - name: org_id in: path required: true schema: type: string responses: "200": description: List of departments. content: application/json: schema: type: object "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/org/{org_id}/dept/{dept_id}/member: post: operationId: deptAddMember summary: Add agent to department. tags: - Org parameters: - name: org_id in: path required: true schema: type: string - name: dept_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DeptAddMemberRequest" responses: "201": description: Member added. content: application/json: schema: type: object properties: status: type: string example: added tx_hash: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v1/org/{org_id}/dept/{dept_id}/member/{agent_id}: delete: operationId: deptRemoveMember summary: Remove agent from department. tags: - Org parameters: - name: org_id in: path required: true schema: type: string - name: dept_id in: path required: true schema: type: string - name: agent_id in: path required: true schema: type: string responses: "200": description: Member removed. content: application/json: schema: type: object properties: status: type: string example: removed tx_hash: type: string "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/org/{org_id}/dept/{dept_id}/members: get: operationId: listDeptMembers summary: List department members. tags: - Org parameters: - name: org_id in: path required: true schema: type: string - name: dept_id in: path required: true schema: type: string responses: "200": description: List of department members. content: application/json: schema: type: object "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" # -- Federation ------------------------------------------------------- /v1/federation/propose: post: operationId: federationPropose summary: Propose a bilateral federation agreement. description: >- Proposer's org is resolved from chain state automatically. Caller must be in an org on-chain. tags: - Federation requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FederationProposeRequest" responses: "201": description: Federation proposed. content: application/json: schema: type: object properties: status: type: string example: proposed tx_hash: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v1/federation/{fed_id}/approve: post: operationId: federationApprove summary: Approve a pending federation. Caller must be in an org. tags: - Federation parameters: - name: fed_id in: path required: true schema: type: string responses: "200": description: Federation approved. content: application/json: schema: type: object properties: status: type: string example: approved tx_hash: type: string "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/federation/{fed_id}/revoke: post: operationId: federationRevoke summary: Revoke an active federation. tags: - Federation parameters: - name: fed_id in: path required: true schema: type: string requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/FederationRevokeRequest" responses: "200": description: Federation revoked. content: application/json: schema: type: object properties: status: type: string example: revoked tx_hash: type: string "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/federation/{fed_id}: get: operationId: getFederation summary: Get federation by ID. tags: - Federation parameters: - name: fed_id in: path required: true schema: type: string responses: "200": description: Federation record. content: application/json: schema: type: object "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/federation/active/{org_id}: get: operationId: listFederations summary: List active federations for an org. tags: - Federation parameters: - name: org_id in: path required: true schema: type: string responses: "200": description: Active federations. content: application/json: schema: type: array items: type: object "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" # -- Governance --------------------------------------------------------- /v1/governance/context: get: operationId: getGovernanceContext summary: Read this node's validator-and-chain authorization binding. description: >- The configured governance operator calls this immediately before each mutation. When app_v20_active is true, copy both returned identifiers into the mutation body so the Ed25519 request signature binds the delegated action to this exact validator and chain. A 409 from the mutation means the context changed; fetch it again and re-sign. The same response reports whether this gateway remains active and the exact persisted ABCI validator roster, so restart readiness can be compared with CometBFT's effective validator set. tags: - Governance responses: "200": description: Current governance authorization context. content: application/json: schema: $ref: "#/components/schemas/GovernanceContextResponse" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/governance/propose: post: operationId: proposeGovernance summary: Ask this node's validator to submit a governance proposal. description: >- Requires the configured governance-operator request signer and the node's live CometBFT private-validator key. After app-v20, every delegated proposal includes the fresh validator-and-chain context and consensus binds the exact operator-signed request (including the 8-byte X-Nonce) as global-admin authorization. The outer validator remains proposer, automatic voter, and proposal-ID actor. tags: - Governance requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/GovProposeRequest" responses: "200": description: >- Transaction committed. The returned status is the committed governance-engine state and may already be terminal. content: application/json: schema: $ref: "#/components/schemas/GovProposeResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" "503": $ref: "#/components/responses/ServiceUnavailable" "500": $ref: "#/components/responses/InternalError" /v1/governance/vote: post: operationId: voteGovernance summary: Ask this node's local validator to vote on a governance proposal. description: >- Only the configured governance operator can authorize the gateway. The HTTP signer receives no voting power; the outer live validator key is the sole on-chain voter. After app-v20 the signed body must carry fresh validator/chain context. The node-local operator need not be a global admin. tags: - Governance requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/GovVoteRequest" responses: "200": description: Vote recorded. content: application/json: schema: $ref: "#/components/schemas/GovVoteResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" "503": $ref: "#/components/responses/ServiceUnavailable" "500": $ref: "#/components/responses/InternalError" /v1/governance/cancel: post: operationId: cancelGovernance summary: Ask the proposing local validator to cancel a pending proposal. description: >- Requires the configured governance operator and live validator key. Consensus attributes cancellation to the outer validator proposer. After app-v20 the signed body must carry fresh validator/chain context; the node-local operator need not be a global admin. tags: - Governance requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/GovCancelRequest" responses: "200": description: Proposal cancelled. content: application/json: schema: $ref: "#/components/schemas/GovCancelResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" "503": $ref: "#/components/responses/ServiceUnavailable" "500": $ref: "#/components/responses/InternalError" /v1/scopes: get: operationId: listScopes summary: List canonical v11.9 quorum scopes and removal drain state (operator/admin only). tags: - Governance responses: "200": description: Canonical scope heads, pending ballot drains, and validator-removal blockers in scope-ID order. content: application/json: schema: $ref: "#/components/schemas/ScopeListResponse" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" /v1/scopes/{scope_id}: get: operationId: getScope summary: Read one canonical v11.9 quorum scope and removal drain state (operator/admin only). tags: - Governance parameters: - name: scope_id in: path required: true schema: type: string responses: "200": description: Canonical scope head, immutable current-revision anchor, pending ballot drain, and validator-removal blockers. content: application/json: schema: $ref: "#/components/schemas/ScopeRecord" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" # -- Embeddings --------------------------------------------------------- /v1/embed: post: operationId: generateEmbedding summary: Generate a vector embedding via the node's local provider. description: >- Ed25519 authentication is required. After app-v23 activation the signer must also be an active approved local Member, Manager, or current-generation Admin. Admin use remains localhost-only; Root credentials, pending/inactive agents, and unknown keys are denied. tags: - Embeddings requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/EmbedRequest" responses: "200": description: Embedding generated. content: application/json: schema: $ref: "#/components/schemas/EmbedResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "503": description: Embedder not ready. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" /v1/embed/personal: post: operationId: generatePersonalEmbedding summary: Compatibility alias for POST /v1/embed. description: >- Uses the exact same request, response, Ed25519 authentication, and app-v23 active local-agent authorization as POST /v1/embed. tags: - Embeddings requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/EmbedRequest" responses: "200": description: Embedding generated. content: application/json: schema: $ref: "#/components/schemas/EmbedResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "503": description: Embedder not ready. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" /v1/embed/info: get: operationId: getEmbedInfo summary: Report the active embedding provider's capabilities. description: >- Clients use this to decide between vector query and FTS5 search paths. When vault (at-rest encryption) is active, semantic is forced true even if no embedder is configured. After app-v23 activation the signer must be an active approved local agent under the same authorization boundary as POST /v1/embed. tags: - Embeddings responses: "200": description: Embedding provider info. content: application/json: schema: $ref: "#/components/schemas/EmbedInfoResponse" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" # -- MCP Tokens --------------------------------------------------------- /v1/mcp/tokens: post: operationId: issueMCPToken summary: Issue a bearer token for MCP clients that cannot sign Ed25519 requests. description: >- Ed25519 auth required (current Root/Admin under app-v23). Token plaintext is shown ONCE; only its SHA-256 digest is persisted. App-v23 binds the bearer to the requested existing active locally managed agent and never creates a new pending principal. tags: - MCP Tokens requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MCPTokenIssueRequest" responses: "201": description: Token issued. Save the token value — it is never shown again. content: application/json: schema: $ref: "#/components/schemas/MCPTokenIssueResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "503": description: MCP tokens not supported on this backend. content: application/json: schema: type: object properties: error: type: string get: operationId: listMCPTokens summary: List issued tokens as summaries (no token values returned). tags: - MCP Tokens responses: "200": description: Token summaries. content: application/json: schema: type: object properties: tokens: type: array items: $ref: "#/components/schemas/MCPTokenSummary" "401": $ref: "#/components/responses/Unauthorized" "503": description: MCP tokens not supported on this backend. /v1/mcp/tokens/{id}: delete: operationId: revokeMCPToken summary: Revoke a token by ID. Idempotent. tags: - MCP Tokens parameters: - name: id in: path required: true schema: type: string description: Token UUID. responses: "204": description: Token revoked. "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" /v1/inbox/activity-state: get: operationId: inboxActivityState summary: Read the exact caller's payload-free task/reply activity sequence. description: >- Requires a fresh nonce-bound exact-agent signature and has no request payload or agent selector. Returns exactly version, epoch, and seq. The opaque 32-character database-incarnation epoch survives restart and backup restore but changes for a fresh database. Fresh task assignments and replies advance this nonblocking coordination hint; it neither claims content nor changes the v1 message-wake/Stop contract. tags: [Messages] responses: "200": description: Exact-caller payload-free activity state. content: application/json: schema: $ref: "#/components/schemas/InboxActivityState" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "501": $ref: "#/components/responses/NotImplemented" "500": $ref: "#/components/responses/InternalError" # -- Canonical local Messages ------------------------------------------ /v1/messages: post: operationId: messageSend summary: Send one idempotent same-node message to an exact local agent. description: >- Uses the existing encrypted pipeline inbox. A new durable insert is locally delivered; an exact caller/key/request retry returns the original message. This route never accepts federated targets and requires a fresh nonce-bound signature from the exact sender. tags: [Messages] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MessageSendRequest" responses: "201": description: New local message durably inserted. content: application/json: schema: $ref: "#/components/schemas/MessageSendResponse" "200": description: Exact idempotent replay of the original send. content: application/json: schema: $ref: "#/components/schemas/MessageSendResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "413": description: Message payload or intent exceeds the pipeline size limit. "429": description: Per-agent or node-wide open-message quota reached; response includes Retry-After. "500": $ref: "#/components/responses/InternalError" /v1/messages/receive: post: operationId: messagesReceive summary: Claim or exactly replay one recipient-bound ordered message batch. description: >- Requires a fresh nonce-bound signature from the exact recipient. The receive token persists the ordered batch, so retry after a lost response never consumes later messages. Replay metadata is retained for 48 hours and capped at 4096 tokens per agent. tags: [Messages] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MessageReceiveRequest" responses: "200": description: Claimed batch or exact idempotent replay. content: application/json: schema: $ref: "#/components/schemas/MessageReceiveResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" "410": description: The exact replay batch was purged or is incomplete; no later work was claimed. "429": description: The per-agent receive-token metadata quota is full. "500": $ref: "#/components/responses/InternalError" /v1/messages/claimed-elsewhere: get: operationId: messagesClaimedElsewhere summary: Passively page unfinished claims held by another claimant session. description: >- Requires a fresh nonce-bound signature from the exact recipient and this runtime's opaque claimant session. The read is passive and exposes only the metadata required for a later compare-and-swap handoff. It never claims, acknowledges, refreshes, hands off, completes, or decrypts work. tags: [Messages] parameters: - name: claimant_session_id in: query required: true schema: type: string minLength: 1 maxLength: 128 - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 20 default: 5 - name: cursor in: query required: false schema: type: string description: Opaque next_cursor copied exactly from the preceding page. responses: "200": description: Exact total plus an oldest-first payload-free recovery page. content: application/json: schema: $ref: "#/components/schemas/ClaimedElsewhereResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" /v1/messages/{message_id}/handoff: put: operationId: messageHandoff summary: Explicitly transfer one claim through a revisioned compare-and-swap fence. description: >- Requires the exact recipient's fresh nonce-bound signature plus the current claimant session and revision returned by passive history. New MCP clients always send the revision; omitted from_revision defaults to 0 only for pre-v11.19.5 REST compatibility. Successful transfer always returns the incremented claim_revision. Stale, concurrent, and A-to-B-to-A delayed requests conflict; omission therefore cannot move a previously transferred claim, and claim age never authorizes an automatic steal. tags: [Messages] parameters: - name: message_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MessageHandoffRequest" responses: "200": description: Claim transferred or exact idempotent replay returned. content: application/json: schema: $ref: "#/components/schemas/MessageHandoffResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "501": $ref: "#/components/responses/NotImplemented" /v1/messages/{message_id}/close: post: operationId: messageClose summary: Close reviewed inbox work without sending a reply. description: >- Requires a fresh nonce-bound exact-recipient signature and an opaque claimant session. Pending exact-recipient messages need no claim. Claimed work requires its current session; provider-addressed work must be claimed first. Preserves history and clears unfinished work without creating a result, read receipt, or federation event. Foreign closure is receiver-local. Identical recipient/reason retries are idempotent. tags: [Messages] parameters: - name: message_id in: path required: true schema: {type: string} requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MessageCloseRequest" responses: "200": description: Closed without a reply, or identical retry. content: application/json: schema: $ref: "#/components/schemas/MessageActionResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "501": description: Store does not support close without reply. /v1/messages/{message_id}/reply: post: operationId: messageReply summary: Complete a fetched local message as its exact recipient. description: >- Requires a fresh nonce-bound signature. Only the recipient to which a canonical receive batch returned this message may reply. tags: [Messages] parameters: - name: message_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MessageReplyRequest" responses: "200": description: Reply persisted; an exact repeat is idempotent. content: application/json: schema: $ref: "#/components/schemas/MessageActionResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "413": description: Reply exceeds the pipeline result-size limit. /v1/messages/{message_id}/read: put: operationId: messageMarkRead summary: Persist exact-recipient read evidence after canonical receive. description: >- Requires a fresh nonce-bound signature. Read means only that the exact recipient fetched and acknowledged this row; it is not evidence of comprehension or action. tags: [Messages] parameters: - name: message_id in: path required: true schema: type: string responses: "200": description: Read acknowledgement persisted or replayed idempotently. content: application/json: schema: $ref: "#/components/schemas/MessageActionResponse" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /v1/messages/read-batch: put: operationId: messagesMarkReadBatch summary: Persist exact-recipient read evidence for up to 20 fetched local messages. description: >- Transport aggregation for canonical read acknowledgements. The fresh nonce-bound outer request is signed by the exact recipient; each item is authorized independently and returns confirmed or a generic per-item failure. One failure never rolls back or hides independent successes. Repeating the exact batch is idempotent. tags: [Messages] requestBody: required: true content: application/json: schema: type: object required: [message_ids] properties: message_ids: type: array minItems: 1 maxItems: 20 items: {type: string, minLength: 1} responses: "200": description: Per-message acknowledgement outcomes in request order. content: application/json: schema: type: object required: [items, count] properties: count: {type: integer, minimum: 1, maximum: 20} items: type: array minItems: 1 maxItems: 20 items: type: object required: [message_id, read_status] properties: message_id: {type: string} read_status: {type: string, enum: [confirmed, not_confirmed]} idempotent_replay: {type: boolean} error: {type: string, enum: [invalid_message_id, duplicate_message_id, not_found]} "400": {$ref: "#/components/responses/BadRequest"} "401": {$ref: "#/components/responses/Unauthorized"} "403": {$ref: "#/components/responses/Forbidden"} "501": {$ref: "#/components/responses/NotImplemented"} /v1/messages/{message_id}/status: get: operationId: messageStatus summary: Read payload-free local receipt/workflow metadata as the exact sender. description: >- Requires a fresh nonce-bound signature from the exact sender. Unrelated callers and absent IDs share the same generic 404 response. This response never includes request payload, reply content, or proof bytes. tags: [Messages] parameters: - name: message_id in: path required: true schema: type: string responses: "200": description: Exact sender-only metadata projection. content: application/json: schema: $ref: "#/components/schemas/MessageStatusResponse" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" # -- Pipeline ----------------------------------------------------------- /v1/pipe/resolve: post: operationId: pipeResolve summary: Resolve a local name or visible federated handle to exact signed send fields. tags: - Pipeline requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PipeResolveRequest" responses: "200": description: Exact local or federated pipeline target. content: application/json: schema: $ref: "#/components/schemas/PipeResolveResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" /v1/pipe/send: post: operationId: pipeSend summary: Send a pipeline message to another agent or provider. tags: - Pipeline requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PipeSendRequest" responses: "200": description: Exact idempotent replay of the original pipeline message. content: application/json: schema: $ref: "#/components/schemas/PipeSendResponse" "201": description: Pipeline message queued. content: application/json: schema: $ref: "#/components/schemas/PipeSendResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalError" "501": $ref: "#/components/responses/NotImplemented" /v1/pipe/inbox: get: operationId: pipeInbox summary: Fetch pending messages for the authenticated agent. Auto-claims all returned items. tags: - Pipeline parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 20 default: 5 - name: claimant_session_id in: query schema: type: string minLength: 1 maxLength: 128 description: Required to atomically session-fence inbound foreign claims; local-only inbox reads may omit it. responses: "200": description: Inbox items. content: application/json: schema: type: object required: [items, count] properties: items: type: array items: $ref: "#/components/schemas/PipelineMessage" count: type: integer "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v1/pipe/history/inbox: get: operationId: pipeInboxHistory summary: Browse retained received pipeline messages without claiming them. tags: - Pipeline parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 20 responses: "200": description: Passive retained inbox history. content: application/json: schema: type: object required: [items, count] properties: items: type: array items: $ref: "#/components/schemas/PipelineMessage" count: type: integer "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v1/pipe/history/outbox: get: operationId: pipeOutbox summary: Browse retained messages sent by the authenticated agent without changing state. tags: - Pipeline parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 20 responses: "200": description: Passive retained outbox history; not a federated delivery/read receipt. content: application/json: schema: type: object required: [items, count] properties: items: type: array items: $ref: "#/components/schemas/PipelineMessage" count: type: integer "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v1/pipe/updates: get: operationId: pipeDeliveryUpdates summary: Atomically claim terminal federated delivery notices for the authenticated local agent. tags: - Pipeline parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 20 default: 5 responses: "200": description: Payload-free failed send/result notices. Returned notices are marked reported. content: application/json: schema: type: object required: [items, count] properties: items: type: array items: $ref: "#/components/schemas/PipelineDeliveryUpdate" count: type: integer "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v1/pipe/results: get: operationId: pipeResults summary: Replies to messages the authenticated agent sent (sender-exact). description: >- The sender-exact reply projection. Authorization is exact original sender equality, not the pipe-view rule: the recipient that wrote the reply, an agent sharing the message to_provider, an unrelated agent, an operator/admin all receive an empty list rather than a 403 that would confirm existence when they are authenticated ordinary callers admitted by the agent API boundary. An unauthenticated caller is rejected with 401 before this handler runs. A federated reply that landed home is returned and labelled external_untrusted; an imported foreign work row whose from_agent collides with a local agent id is not. The returned row carries its retained intent but NOT its original request payload: payload is always empty on this surface (the key is present because PipelineMessage does not use omitempty). payload_authority "request_only" therefore labels the retained intent only, while authority and result_authority are "data_only". Every reply is untrusted agent-supplied data. replied_by names the agent that ACTUALLY wrote the reply and is not interchangeable with to_agent: callerCanClaimPipe admits an operator/admin on any local pipe and any same-provider agent on a provider-addressed one, so the addressee is not necessarily the author. Attribute reply content to replied_by. Claim timing (claimed_at) is not returned; it is workflow detail, not provenance. Passive and replay-safe in every mode: it claims nothing, acknowledges nothing, re-queues nothing, and two identical reads return identical bodies, so a retry after a lost response is safe. tags: - Pipeline parameters: - name: limit in: query description: >- Page size, newest first by completed_at. Out-of-range or unparseable values fall back to the default rather than widening the page. Ignored when count_only=1. schema: type: integer minimum: 1 maximum: 20 default: 5 - name: before in: query description: >- v11.18.2 backward KEYSET cursor, "|". Echo the previous page's next_before verbatim to walk backward through the entire archive; without it the reachable set would be exactly the newest `limit` rows for all time. Both halves are required for correct paging: completed_at is written by strftime('%Y-%m-%dT%H:%M:%fZ') at millisecond resolution and is not unique, so a timestamp-only bound silently drops every reply sharing the boundary millisecond, including rows the previous page never returned. Rows are ordered by (completed_at DESC, pipe_id DESC) and the pager resumes with completed_at < ? OR (completed_at = ? AND pipe_id < ?). A bare RFC3339 timestamp is still accepted and means "strictly older than this instant" - a coarse filter that excludes ties, not a pager cursor. A bare sub-millisecond instant is preserved as a strict time bound; a composite cursor must use exact millisecond precision, matching every server-generated cursor. An unparseable timestamp half or a sub-millisecond composite cursor is a 400. Requires the optional store.PipelineReplyPager; a backend without it answers 501 rather than pretending nothing older exists. The cursor is client-held and the server records nothing, so paging stays passive and replay-safe. schema: type: string example: "2026-08-08T00:05:00Z|msg-aaaa1111" - name: count_only in: query description: >- Additive v11.18.2 payload-free probe. When set to "1" the response is a scalar {count, retained, newest_completed_at} instead of a page: no items array, no reply text, no intent, no message identifiers. count is the CURRENT RETAINED TOTAL, not an unread counter. Canonical msg-* replies are durable, while deprecated pipe-* compatibility results may age out, so the value is neither pending work nor universally monotonic. Any other value serves the normal projection. schema: type: string enum: ["1"] responses: "200": description: >- Replies to messages this agent sent. Normal mode returns {items, count} with items always an array (never null) and every item payload-free. count_only=1 returns the scalar probe only. content: application/json: schema: oneOf: - type: object title: PipeResultsPage required: [items, count] properties: items: type: array items: $ref: "#/components/schemas/PipelineMessage" count: type: integer next_before: type: string description: >- Composite keyset cursor "|" that resumes exactly after this page's last row. Echo it as the next request's `before`. Present on every non-empty page; absent when items is empty. Do not rebuild a cursor from completed_at alone - it is only millisecond-resolution and not unique, so a timestamp-only cursor strands every reply sharing that millisecond. - type: object title: PipeResultsCountProbe required: [count, retained] properties: count: type: integer description: >- Current retained total of replies for this exact sender. Not an unread count or work queue; deprecated compatibility results may age out. retained: type: boolean description: count > 0. newest_completed_at: type: string format: date-time description: >- completed_at of the newest retained reply, as of this response. Omitted when count is 0. Pass a recorded value as `since` to poll with no server-held read state. The boundary is inclusive so a reply landing later in the same millisecond cannot be hidden; boundary replies may repeat and clients should deduplicate by message id. "400": description: >- The `before` cursor's timestamp half is not RFC3339, or a composite cursor uses a sub-millisecond timestamp that cannot name an exact stored row. Rejected loudly rather than silently re-serving the newest page, which would look like "nothing older exists". content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" "501": description: >- The active store backend does not support the sender-side reply projection, or (for count_only=1) the payload-free counter, or (for before=) the backward pager. PostgresStore stubs GetCompletedForSender today. This is a capability gap and must never be rendered as "you have no replies" or "there is nothing older". content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "503": description: >- The node content vault is locked and replies are encrypted at rest. The read is passive and safe to repeat once the vault is unlocked. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" /v1/pipe/{pipe_id}: get: operationId: pipeStatus summary: Inspect the current local workflow row for a pipeline message. description: >- This is local queue/workflow state, not proof of remote delivery or reading. Canonical same-node sender/read evidence is available through /v1/messages. App-v26 peers may separately negotiate generation-bound receipt v2; this workflow route never substitutes for that evidence. tags: - Pipeline parameters: - name: pipe_id in: path required: true schema: type: string responses: "200": description: Local pipeline workflow row; not a delivery/read receipt. content: application/json: schema: $ref: "#/components/schemas/PipelineMessage" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v1/pipe/receipts/challenge-batch: post: operationId: pipeReceiptChallengeBatch summary: Fetch up to 40 exact receipt-v2 challenge bodies in one local request. description: >- Accepts at most 20 imported messages with claimed/read events. Every challenge remains an independent immutable exact-event body and each item returns ready or a generic rejection. This route does not claim, read, or expose message content. tags: [Pipeline] requestBody: required: true content: application/json: schema: type: object required: [items] properties: items: type: array minItems: 1 maxItems: 40 items: type: object required: [pipe_id, kind] properties: pipe_id: {type: string, minLength: 1} kind: {type: string, enum: [claimed, read]} responses: "200": description: Per-event challenge outcomes in request order. content: application/json: schema: type: object required: [items, count] properties: count: {type: integer, minimum: 1, maximum: 40} items: type: array minItems: 1 maxItems: 40 items: type: object required: [pipe_id, event_kind, status] properties: pipe_id: {type: string} event_kind: {type: string, enum: [claimed, read]} status: {type: string, enum: [ready, rejected]} challenge: {$ref: "#/components/schemas/FederatedPipeReceiptChallenge"} error: {type: string, enum: [invalid_receipt_event, duplicate_receipt_event, not_found]} "400": {$ref: "#/components/responses/BadRequest"} "401": {$ref: "#/components/responses/Unauthorized"} "403": {$ref: "#/components/responses/Forbidden"} "501": {$ref: "#/components/responses/NotImplemented"} /v1/pipe/{pipe_id}/receipt/challenge/{kind}: get: operationId: pipeReceiptChallenge summary: Fetch the exact immutable receipt-v2 body an imported-message recipient must sign. description: >- The challenge contains no message content. It is available only for a negotiated v2 import, the exact addressed recipient, an allowed kind, and a currently valid federation generation. tags: [Pipeline] parameters: - name: pipe_id in: path required: true schema: type: string - name: kind in: path required: true schema: type: string enum: [claimed, read] responses: "200": description: Exact payload-free challenge. content: application/json: schema: type: object required: [pipe_id, event_kind, challenge] properties: pipe_id: {type: string} event_kind: {type: string, enum: [claimed, read]} challenge: $ref: "#/components/schemas/FederatedPipeReceiptChallenge" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "501": $ref: "#/components/responses/NotImplemented" /v1/pipe/receipts/batch: put: operationId: pipeReceiptRecordBatch summary: Record up to 40 independently signed exact receipt-v2 events. description: >- Transport aggregation only: every item carries its own nonce-bound signature over the exact single-event receipt path and challenge body, so peers verify the same proof as the non-batch route. Items are processed in request order; a failed claimed event suppresses the matching read event, while unrelated items retain independent partial success. Exact replay is idempotent. tags: [Pipeline] requestBody: required: true content: application/json: schema: type: object required: [items] properties: items: type: array minItems: 1 maxItems: 40 items: type: object required: [pipe_id, kind, proof] properties: pipe_id: {type: string, minLength: 1} kind: {type: string, enum: [claimed, read]} proof: type: object required: [agent_id, signature, timestamp, nonce, canonical_request] properties: agent_id: {type: string} signature: {type: string, format: byte} timestamp: {type: integer, format: int64} nonce: {type: string, format: byte} canonical_request: {type: string, format: byte} responses: "200": description: Per-event durable queue/rejection outcomes in request order. content: application/json: schema: type: object required: [items, count] properties: count: {type: integer, minimum: 1, maximum: 40} items: type: array minItems: 1 maxItems: 40 items: type: object required: [pipe_id, event_kind, receipt_status] properties: pipe_id: {type: string} event_kind: {type: string, enum: [claimed, read]} receipt_status: {type: string, enum: [queued, unconfirmed]} idempotent_replay: {type: boolean} error: {type: string, enum: [invalid_receipt_proof, duplicate_receipt_event, claim_not_confirmed, rejected]} "400": {$ref: "#/components/responses/BadRequest"} "401": {$ref: "#/components/responses/Unauthorized"} "403": {$ref: "#/components/responses/Forbidden"} "501": {$ref: "#/components/responses/NotImplemented"} /v1/pipe/{pipe_id}/receipt/{kind}: put: operationId: pipeReceiptRecord summary: Sign and queue exact-recipient claim/read evidence. description: >- Submit the challenge body unchanged with a fresh nonce-bound signature from the exact recipient. Claim/read and receipt outbox insertion are atomic. `queued` is local durable receipt transport state, not yet sender-visible confirmation. tags: [Pipeline] parameters: - name: pipe_id in: path required: true schema: {type: string} - name: kind in: path required: true schema: {type: string, enum: [claimed, read]} requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FederatedPipeReceiptChallenge" responses: "200": description: Exact transition and receipt outbox entry persisted or replayed. content: application/json: schema: $ref: "#/components/schemas/FederatedPipeReceiptActionResponse" "401": {$ref: "#/components/responses/Unauthorized"} "403": {$ref: "#/components/responses/Forbidden"} "404": {$ref: "#/components/responses/NotFound"} "409": {$ref: "#/components/responses/Conflict"} "501": {$ref: "#/components/responses/NotImplemented"} /v1/pipe/{pipe_id}/receipt: get: operationId: pipeReceiptStatus summary: Read payload-free federated receipt evidence as the exact sender. description: >- Unrelated callers, recipients, operators, Admin, Root, and absent IDs share the same generic 404 behavior. Peer durable admission is distinct from exact-recipient signed claim/read evidence. A v1 or historical ungeneration-bound row is explicitly unsupported/unconfirmed. tags: [Pipeline] parameters: - name: pipe_id in: path required: true schema: type: string responses: "200": description: Exact sender-only, payload-free independent receipt dimensions. content: application/json: schema: $ref: "#/components/schemas/FederatedPipeReceiptStatus" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/pipe/{pipe_id}/claim: put: operationId: pipeClaim summary: Atomically claim a pipeline message (prevents double-processing). tags: - Pipeline parameters: - name: pipe_id in: path required: true schema: type: string responses: "200": description: Message claimed. content: application/json: schema: type: object properties: pipe_id: type: string status: type: string example: claimed "401": $ref: "#/components/responses/Unauthorized" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalError" /v1/pipe/{pipe_id}/result: put: operationId: pipeResult summary: Submit a result for a claimed local or federated message. description: >- Local completion inserts an `observation` memory in domain `agent-pipeline`. Federated work remains transient and queues a signed result over the original return route without auto-journaling. tags: - Pipeline parameters: - name: pipe_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PipeResultRequest" responses: "200": description: Result submitted. content: application/json: schema: type: object properties: status: type: string example: completed journal_id: type: string description: memory_id of the auto-journal entry, or empty string. journaled: type: boolean description: False for federated work; local completion may create a summary journal. reply_event_id: type: string description: Durable signed return event for federated work. idempotent_replay: type: boolean description: True when an identical retry recovered the original durable reply event. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalError" # -- OAuth (root-level, no /v1/ prefix) ---------------------------------- /.well-known/oauth-authorization-server: get: operationId: oauthDiscovery summary: RFC 8414 OAuth 2.0 Authorization Server Metadata. description: Discovery document for ChatGPT MCP connector compatibility. tags: - OAuth security: [] responses: "200": description: Authorization server metadata document. content: application/json: schema: type: object /.well-known/oauth-protected-resource: get: operationId: oauthProtectedResource summary: RFC 9728 Protected Resource Metadata. tags: - OAuth security: [] responses: "200": description: Protected resource metadata document. content: application/json: schema: type: object /oauth/register: post: operationId: oauthClientRegister summary: RFC 7591 Dynamic Client Registration (10 reqs/IP/hour). tags: - OAuth security: [] requestBody: required: true content: application/json: schema: type: object responses: "201": description: Client registered. content: application/json: schema: type: object "400": $ref: "#/components/responses/BadRequest" "429": description: Rate limit exceeded. /oauth/authorize: get: operationId: oauthAuthorizeGet summary: Render PKCE consent screen. tags: - OAuth security: [] parameters: - name: response_type in: query schema: type: string - name: client_id in: query schema: type: string - name: redirect_uri in: query schema: type: string - name: code_challenge in: query schema: type: string - name: code_challenge_method in: query schema: type: string - name: state in: query schema: type: string responses: "200": description: Consent screen HTML. content: text/html: schema: type: string post: operationId: oauthAuthorizePost summary: Submit consent; mints bearer + issues auth code; redirects to redirect_uri. tags: - OAuth security: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object responses: "302": description: Redirect to redirect_uri with authorization code. /oauth/token: post: operationId: oauthToken summary: Exchange auth code for bearer (grant_type=authorization_code only). description: >- The access_token returned is accepted as Authorization: Bearer on /v1/mcp/sse and /v1/mcp/streamable. Token lifetime is controlled by revocation (DELETE /v1/mcp/tokens/{id}), not expiry — expires_in=0. tags: - OAuth security: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: grant_type: type: string enum: - authorization_code code: type: string redirect_uri: type: string client_id: type: string code_verifier: type: string responses: "200": description: Token response. content: application/json: schema: type: object properties: access_token: type: string token_type: type: string example: Bearer expires_in: type: integer example: 0 "400": $ref: "#/components/responses/BadRequest" /v1/federation/available: get: operationId: getCallerFederationAvailability summary: Discover bounded caller-authorized federation domains and recipients. description: >- Signed active-ordinary caller projection. Each call performs one bounded caller-authorized page inside a public scan horizon. agent_name performs targeted lookup with agent_limit 1-20. peer_cursor is the short-lived signed-caller/query-bound continuation returned by an incomplete page; it contains no peer ID or hidden agreement count. read_candidate_domains are local/peer policy intersections only; shared_read_domains additionally passed a live destination check using the same linked-reader and access-group gates as recall. Callers must inspect read_authorization and must not present candidates as readable unless verification completed. Results are authorization metadata, not presence or delivery evidence. Distinct lookups consume fixed per-caller and process-wide outbound-call budgets; 429 includes Retry-After. Exact saved recipient addresses do not require discovery, and clients must not auto-walk every page. tags: [Federation] parameters: - in: query name: agent_name schema: {type: string, maxLength: 512} - in: query name: agent_limit schema: {type: integer, minimum: 1, maximum: 20, default: 20} - in: query name: peer_cursor description: Continuation returned by the preceding exact signed lookup. schema: {type: string, maxLength: 128} responses: "200": description: Bounded caller-filtered connections. content: application/json: schema: type: object required: [connections, total, complete, message] properties: connections: {type: array, maxItems: 24, items: {type: object}} total: {type: integer, minimum: 0, maximum: 24} complete: {type: boolean} next_peer_cursor: {type: string} message: {type: string} "400": {$ref: "#/components/responses/BadRequest"} "401": {$ref: "#/components/responses/Unauthorized"} "403": {$ref: "#/components/responses/Forbidden"} "429": description: Caller or process outbound discovery budget exhausted; retry after Retry-After. content: {application/problem+json: {schema: {$ref: "#/components/schemas/ProblemDetails"}}} /v1/federation/recall-plan: post: operationId: createFederatedRecallPlan summary: Create the destination-bound signing plan for a federated recall. description: >- First half of the app-v23 two-request recall protocol. The caller must copy destinations to the second recall's federate_chains and copy source_chain_id, agreement_bindings, query_challenges, authorization_models, and authorization_attestations verbatim into its signed federation_context. A peer that cannot complete current planning is reported in errors and omitted from destinations. A second request that omits authorization map entries is an old-client error and must be re-planned and re-signed; an empty model plus explicit zero attestation remains a valid legacy-peer tuple. tags: [Federation] requestBody: required: true content: application/json: schema: type: object required: [domain_tag] properties: domain_tag: {type: string, minLength: 1, maxLength: 256} federate_chains: type: array maxItems: 8 items: {type: string, minLength: 1} responses: "200": description: Exact finite destination plan and complete signing tuple. content: application/json: schema: type: object required: [protocol_version, source_chain_id, destinations, agreement_bindings, query_challenges, authorization_models, authorization_attestations, expires_at] properties: protocol_version: {type: integer, const: 23} source_chain_id: {type: string, minLength: 1} destinations: {type: array, maxItems: 8, items: {type: string}} agreement_bindings: {type: object, additionalProperties: {type: string}} query_challenges: {type: object, additionalProperties: {type: string}} authorization_models: {type: object, additionalProperties: {type: string}} authorization_attestations: type: object additionalProperties: type: object required: [eligible, max_classification] properties: eligible: {type: boolean} max_classification: {type: integer, minimum: 0, maximum: 4} expires_at: {type: object, additionalProperties: {type: integer, format: int64}} errors: {type: object, additionalProperties: {type: string}} "400": {$ref: "#/components/responses/BadRequest"} "401": {$ref: "#/components/responses/Unauthorized"} "403": {$ref: "#/components/responses/Forbidden"} "502": description: Planning failed before a valid per-peer result could be returned. content: {application/problem+json: {schema: {$ref: "#/components/schemas/ProblemDetails"}}} /v1/federation/contacts/authorize: post: operationId: authorizeCachedFederatedContacts summary: Revalidate cached federated contact scopes against current local policy. description: >- Local-only signed policy check used by MCP before reusing its short-lived contact cache. It performs no peer request and returns only the subset still authorized for this exact caller. tags: [Federation] requestBody: required: true content: application/json: schema: type: object required: [contacts] properties: contacts: type: array maxItems: 512 items: type: object required: [remote_chain_id, domain] properties: remote_chain_id: {type: string} domain: {type: string, minLength: 1, maxLength: 256} responses: "200": description: Currently authorized contact scopes. content: application/json: schema: type: object required: [allowed_contacts] properties: allowed_contacts: type: array maxItems: 512 items: type: object required: [remote_chain_id, domain] properties: remote_chain_id: {type: string} domain: {type: string} "400": {$ref: "#/components/responses/BadRequest"} "401": {$ref: "#/components/responses/Unauthorized"} "403": {$ref: "#/components/responses/Forbidden"} # -- Operational --------------------------------------------------------- /health: get: operationId: healthCheck summary: Liveness probe. tags: - Operational security: [] responses: "200": description: Service is alive. content: application/json: schema: $ref: "#/components/schemas/HealthResponse" /ready: get: operationId: readinessCheck summary: Readiness probe — checks storage, CometBFT, and scoped projection integrity. tags: - Operational security: [] responses: "200": description: Service is ready to accept traffic. content: application/json: schema: $ref: "#/components/schemas/ReadinessResponse" "503": description: Service is not ready. content: application/json: schema: $ref: "#/components/schemas/ReadinessResponse"