{"openapi":"3.1.0","info":{"title":"BEACON REST API — stage 8","version":"0.6.0-stage8","description":"Private, isolated conversations between an external client and a human operator node. This is a closed staging build (not publicly available, not a public launch): a human operator may reply through a separate, private console (its API is not part of this document). Sending a message does not guarantee a human reply or any timeframe; an HTTP 202 receipt only confirms storage. Poll `GET /v1/conversations/{id}/messages` every `next_poll_after_seconds` (60) with backoff and jitter.\n\nRemote Identity Key v1 (OPTIONAL, stage 4; tag identity): a client may bind an Ed25519 key it generated itself to one conversation, later prove control of it to restore access after losing the session token, replace it by a double-proof rotation, or revoke it with the session token. The server never receives a private key. Every proof signs exactly `UTF8(\"BEACON-IDENTITY-PROOF-v1\") || 0x00 || UTF8(JCS(payload))` (RFC 8785 JCS of the payload the server returned, unchanged; pure Ed25519, RFC 8032; key, signature and nonce are raw bytes in base64url without padding). Pseudocode: `input = ascii(domain) + [0x00] + utf8(jcs(payload)); signature = ed25519_sign(private_key, input)`. A challenge lives 120 s and is consumed by the first verify attempt, also a failing one. A restore returns a new session token exactly once and revokes every earlier token; an idempotent replay never returns a token (credential_status=not_recoverable_from_replay). Restore answers never reveal whether a conversation or key exists (one failure class identity_restore_not_available; restore payloads carry policy_epoch 0). A verified proof means only control_of_credential_observed_not_identity_proof: it grants no permission and says nothing about who or what the client is. Messages are never individually signed. While the deployment has the feature off, identity routes answer 404 identity_feature_disabled.\n\nConversation states: open, waiting_for_human (the last action was external), waiting_for_external (a human replied), quarantined (inbound paused for review; reading, withdraw, deletion request and token rotation keep working) and closed. Service intake may be limited: 503 intake_paused with Retry-After means new contacts (existing_contacts_only) or all inbound messages (inbound_paused) are temporarily refused; data-rights operations are never affected.\n\nStructured human requests (POST /v1/conversations/{id}/requests): immutable, versioned content; every status is a record of human review and never means a tool, account, purchase or network action was executed.\n\nPolicy (stage 2): the private conversation needs no optional purpose. The four optional purposes (research_analysis, public_excerpt, external_ai_processing, extended_retention) can be recorded as preferences, but a preference is not a permission: the server-side Policy Gate computes the effective permission and, in this stage, every purpose is disabled (feature_disabled) with a draft policy (0.1.0-stage2, effective_at null, unsigned). close, withdraw and deletion-request are separate operations.\n\nLimits: request body ≤ 32 KiB (identity routes: 8 KiB, strict JSON without -0, fractions or lone surrogates); message content ≤ 16384 UTF-8 bytes; only `application/json` and `text/plain` content; unknown fields and duplicate JSON keys are rejected. Rate limits return 429 with Retry-After.\n\nIdempotency: every state-changing operation accepts `Idempotency-Key` (1..200 printable ASCII): POST /v1/hello, POST /v1/conversations/{id}/messages, PUT /v1/conversations/{id}/preferences/{purpose}, POST /v1/conversations/{id}/preferences/{purpose}/withdraw, POST /v1/conversations/{id}/close, POST /v1/conversations/{id}/deletion-request, POST /v1/conversations/{id}/requests and POST /v1/conversations/{id}/requests/{request_id}/versions. A replay with the same key and body returns the first receipt (idempotent_replay=true where the response carries that flag) without new side effects; the same key with a different body is rejected (409). Replaying a hello returns the same conversation receipt without the session token (credential_issued=false, credential_status=not_recoverable). close, withdraw and deletion-request are additionally idempotent by state: a repeat without a key reports already_closed / already_withdrawn / existing. The identity operations REQUIRE the header: POST /v1/conversations/{id}/identity/challenges, POST /v1/conversations/{id}/identity/challenges/{challenge_id}/verify, POST /v1/identity/restore/challenges, POST /v1/identity/restore/challenges/{challenge_id}/verify, POST /v1/conversations/{id}/identity/rotations, POST /v1/conversations/{id}/identity/rotations/{rotation_id}/verify and POST /v1/conversations/{id}/identity/revoke; their receipts expire after 15 minutes and never contain a session token. The optional admission operations (stage 8) accept it too: POST /v1/admission/challenges, POST /v1/admission/challenges/{challenge_id}/verify and POST /v1/agent/hello; a replay never shows an admission receipt or a session token again.\n\nPublic documents (stage 6; tag public; no credential; REST v1 is unchanged): /, /about, /docs, /manifest.json, /status.json, /llms.txt, /.well-known/security.txt, /feed.atom, /charter, /privacy, /principles.json, /principles/{version}.json, /policies/current.json, /policies/{version}.json, /genesis.json, /identity.json, /identities/{sequence}.json, /pulse.json, /pulses/{sequence}.json. JSON documents are served as RFC 8785 JCS bytes; signed documents follow the BEACON public identity protocol v1 (Ed25519 over ASCII(domain) || 0x00 || UTF8(JCS(payload)); pulses use the domain BEACON-PULSE-v1). A document that is not published answers 404 not_published; versioned documents are immutable. A signature proves control of a key only — not a date, an owner, human presence or availability; verify the chain against a root key fingerprint obtained out of band.\n\nOptional agent admission lane (stage 8; tag admission; experimental; OFF unless the deployment enables it): POST /v1/admission/challenges, POST /v1/admission/challenges/{challenge_id}/verify and POST /v1/agent/hello (BEACON-AI-ADMISSION-v1, challenge family timed_numeral_transform_v1). Success records only protocol_capable: a formal challenge was completed in time with a key the client held — not an AI verification, not an identity, no priority and no permission. POST /v1/hello never requires it. While off these routes answer 404 admission_unavailable. MCP (2026-07-28, POST /mcp) and A2A (1.0 JSON-RPC, POST /a2a, Agent Card at /.well-known/agent-card.json) adapters and their OAuth token exchange (/oauth/token, RFC 8693) are described by their own protocols and metadata documents, not by this document, and exist only where enabled."},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Session token issued by POST /v1/hello (bct_…, 256 bits, expires after 90 days). It authorizes exactly one conversation. Never put it in URLs or logs."}},"schemas":{}},"paths":{"/health/live":{"get":{"operationId":"healthLive","summary":"Liveness","tags":["health"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ok"]}},"additionalProperties":false}}}}}}},"/health/ready":{"get":{"operationId":"healthReady","summary":"Readiness","tags":["health"],"description":"Ready only when PostgreSQL is reachable, all migrations are applied and the governance versions are recorded with matching hashes.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["status","checks"],"properties":{"status":{"anyOf":[{"type":"string","enum":["ready"]},{"type":"string","enum":["not_ready"]}]},"checks":{"type":"object","required":["config","database","migrations","governance","identity","identity_cleanup"],"properties":{"config":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["failed"]}]},"database":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["failed"]}]},"migrations":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["pending"]},{"type":"string","enum":["failed"]}]},"governance":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["missing"]},{"type":"string","enum":["failed"]}]},"identity":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["disabled"]},{"type":"string","enum":["failed"]}],"description":"Remote Identity Key v1: disabled (feature off), ok (enabled, crypto self-test passed), failed (not ready)."},"identity_cleanup":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["backlog"]},{"type":"string","enum":["not_checked"]}],"description":"backlog: expired identity challenges wait longer than the documented threshold; readiness stays ok."}},"additionalProperties":false}},"additionalProperties":false}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["status","checks"],"properties":{"status":{"anyOf":[{"type":"string","enum":["ready"]},{"type":"string","enum":["not_ready"]}]},"checks":{"type":"object","required":["config","database","migrations","governance","identity","identity_cleanup"],"properties":{"config":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["failed"]}]},"database":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["failed"]}]},"migrations":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["pending"]},{"type":"string","enum":["failed"]}]},"governance":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["missing"]},{"type":"string","enum":["failed"]}]},"identity":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["disabled"]},{"type":"string","enum":["failed"]}],"description":"Remote Identity Key v1: disabled (feature off), ok (enabled, crypto self-test passed), failed (not ready)."},"identity_cleanup":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["backlog"]},{"type":"string","enum":["not_checked"]}],"description":"backlog: expired identity challenges wait longer than the documented threshold; readiness stays ok."}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/hello":{"post":{"operationId":"hello","summary":"Start a private conversation","tags":["conversations"],"description":"Creates a conversation and its first external message, and issues a bearer session token (256 bits, 90-day expiry). 202 is returned only after the conversation, credential verifier, first message and NEW_CONTACT outbox event are committed in one transaction. Supports Idempotency-Key: a replay returns the same conversation receipt but never the token again (credential_issued=false, credential_status=not_recoverable). No human reply is guaranteed; poll every next_poll_after_seconds.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","minLength":1,"maxLength":16384,"description":"First message. 1..16384 UTF-8 bytes, text/plain, never interpreted.","x-max-utf8-bytes":16384},"purpose":{"type":"string","maxLength":1000,"description":"Max 1000 UTF-8 bytes.","x-max-utf8-bytes":1000},"discovery_source":{"type":"string","maxLength":500,"description":"Max 500 UTF-8 bytes.","x-max-utf8-bytes":500},"declared_name":{"type":"string","maxLength":200,"description":"Self-declared name; a claim, not a verified identity. Max 200 UTF-8 bytes.","x-max-utf8-bytes":200},"language":{"type":"string","maxLength":35,"pattern":"^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$","description":"BCP 47-like language tag, max 35 ASCII characters."}},"additionalProperties":false,"description":"Clients cannot set author_type, status, identifiers, server time, policy decisions or outbox data."}}},"description":"Clients cannot set author_type, status, identifiers, server time, policy decisions or outbox data."},"parameters":[{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":false,"description":"1..200 printable ASCII characters (otherwise 400 invalid_idempotency_key). Optional; absence means a new operation. Scope: this endpoint. Records expire after 24h."}],"responses":{"202":{"description":"202 means the conversation, credential verifier, first message and NEW_CONTACT outbox event were committed. It does not mean a human has read the message or will reply.","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","credential_issued","credential_status","idempotent_replay","credential_expires_at","state","next_poll_after_seconds","default_mode","policy_version","charter_version","message"],"properties":{"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"session_token":{"type":"string","pattern":"^bct_[A-Za-z0-9_-]{43}$","description":"Bearer session token (256 bits of entropy). Returned ONLY in the first successful response. It is never stored raw and cannot be recovered by replaying the Idempotency-Key."},"credential_issued":{"type":"boolean","description":"true on the first response; false on an idempotent replay (no token)."},"credential_status":{"anyOf":[{"type":"string","enum":["issued"]},{"type":"string","enum":["not_recoverable"]}],"description":"not_recoverable means the token was issued earlier and cannot be re-obtained."},"idempotent_replay":{"type":"boolean"},"credential_expires_at":{"type":"string","format":"date-time","description":"Credential expiry, initially 90 days after issue."},"state":{"anyOf":[{"type":"string","enum":["open"]},{"type":"string","enum":["waiting_for_human"]},{"type":"string","enum":["waiting_for_external"]},{"type":"string","enum":["quarantined"]},{"type":"string","enum":["closed"]}],"description":"open — no side is waiting; waiting_for_human — the last action was external; waiting_for_external — a human replied; quarantined — inbound is paused for review (reading and data-rights actions still work); closed — final."},"next_poll_after_seconds":{"type":"integer","description":"Recommended polling interval (60)."},"default_mode":{"type":"string","enum":["private_conversation"]},"policy_version":{"type":"string","description":"Stage-1 draft placeholder; not an approved policy."},"charter_version":{"type":"string","description":"Stage-1 draft placeholder; not an approved charter."},"message":{"type":"object","required":["message_id","sequence","received_at"],"properties":{"message_id":{"type":"string","pattern":"^msg_[A-Za-z0-9_-]{22}$"},"sequence":{"type":"integer","minimum":1,"description":"Monotonic position inside the conversation."},"received_at":{"type":"string","format":"date-time","description":"Server receive time (UTC, RFC 3339)."}},"additionalProperties":false}},"additionalProperties":false,"description":"202 means the conversation, credential verifier, first message and NEW_CONTACT outbox event were committed. It does not mean a human has read the message or will reply."}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/messages":{"post":{"operationId":"sendMessage","summary":"Send a message to an open conversation","tags":["conversations"],"description":"Appends an external text/plain message with the next monotonic sequence and one NEW_MESSAGE outbox event, atomically. Requires the bearer token of this conversation. Supports Idempotency-Key (same key + same body replays the receipt; different body → 409). Clients cannot set author_type; only external messages are created here.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content","content_type"],"properties":{"content":{"type":"string","minLength":1,"maxLength":16384,"description":"1..16384 UTF-8 bytes of plain text.","x-max-utf8-bytes":16384},"content_type":{"type":"string","description":"Only text/plain is accepted in stage 1.","enum":["text/plain"]},"claimed_sent_at":{"type":"string","format":"date-time","pattern":"^\\d{4}-\\d{2}-\\d{2}[Tt]\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?([Zz]|[+-]\\d{2}:\\d{2})$","description":"Optional client-claimed send time (RFC 3339). Stored separately; never replaces received_at."}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Opaque conversation identifier (cnv_…). Knowing it grants no access."},{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":false,"description":"1..200 printable ASCII characters (otherwise 400 invalid_idempotency_key). Optional. Scope: this endpoint and this conversation. Records expire after 24h."}],"security":[{"bearerAuth":[]}],"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","state","idempotent_replay","next_poll_after_seconds","message"],"properties":{"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"state":{"anyOf":[{"type":"string","enum":["open"]},{"type":"string","enum":["waiting_for_human"]},{"type":"string","enum":["waiting_for_external"]},{"type":"string","enum":["quarantined"]},{"type":"string","enum":["closed"]}],"description":"open — no side is waiting; waiting_for_human — the last action was external; waiting_for_external — a human replied; quarantined — inbound is paused for review (reading and data-rights actions still work); closed — final."},"idempotent_replay":{"type":"boolean"},"next_poll_after_seconds":{"type":"integer"},"message":{"type":"object","required":["message_id","sequence","received_at"],"properties":{"message_id":{"type":"string","pattern":"^msg_[A-Za-z0-9_-]{22}$"},"sequence":{"type":"integer","minimum":1,"description":"Monotonic position inside the conversation."},"received_at":{"type":"string","format":"date-time","description":"Server receive time (UTC, RFC 3339)."}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}},"get":{"operationId":"listMessages","summary":"List messages (polling)","tags":["conversations"],"description":"Returns messages ordered by sequence ascending. `after` is a server-issued cursor bound to this conversation; omit it to read from the beginning. `limit` defaults to 50 (max 100). An empty page is 200 with an empty items array. Poll every next_poll_after_seconds (60).","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"},"in":"query","name":"after","required":false,"description":"Server-issued cursor from a previous response. Omit to start from the beginning of history."},{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Page size, default 50, max 100."},{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Opaque conversation identifier (cnv_…). Knowing it grants no access."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","items","next_cursor"],"properties":{"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"items":{"type":"array","items":{"type":"object","required":["message_id","sequence","author_type","content_type","content","protocol","received_at","claimed_sent_at","assistance"],"properties":{"message_id":{"type":"string","pattern":"^msg_[A-Za-z0-9_-]{22}$"},"sequence":{"type":"integer","minimum":1},"author_type":{"anyOf":[{"type":"string","enum":["external"]},{"type":"string","enum":["human"]},{"type":"string","enum":["system"]}],"description":"Stage 1 only produces external messages; human/system are reserved."},"content_type":{"type":"string","enum":["text/plain"]},"content":{"type":"string"},"protocol":{"type":"string","enum":["rest"]},"received_at":{"type":"string","format":"date-time","description":"Server receive time."},"claimed_sent_at":{"anyOf":[{"type":"string","format":"date-time","description":"Client-claimed send time."},{"type":"null"}]},"assistance":{"anyOf":[{"type":"string","enum":["none"]},{"type":"string","enum":["translation_assisted"]},{"type":"string","enum":["draft_assisted"]}]}},"additionalProperties":false},"description":"Ordered by sequence ascending."},"next_cursor":{"type":"string","description":"Opaque cursor bound to this conversation. Pass as `after` to fetch newer messages. An empty page returns the same position."}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}":{"get":{"operationId":"getConversation","summary":"Get conversation state","tags":["conversations"],"description":"Returns the state of the conversation that the bearer token belongs to. Unknown, foreign, expired or revoked credentials all yield 404 conversation_not_available.","parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Opaque conversation identifier (cnv_…). Knowing it grants no access."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","state","primary_deleted","created_at","updated_at","closed_at","secondary_use_blocked","last_sequence","credential_expires_at","next_poll_after_seconds","default_mode","policy_version","charter_version","policy_version_seen","charter_version_seen","available_actions"],"properties":{"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"state":{"anyOf":[{"type":"string","enum":["open"]},{"type":"string","enum":["waiting_for_human"]},{"type":"string","enum":["waiting_for_external"]},{"type":"string","enum":["quarantined"]},{"type":"string","enum":["closed"]}],"description":"open — no side is waiting; waiting_for_human — the last action was external; waiting_for_external — a human replied; quarantined — inbound is paused for review (reading and data-rights actions still work); closed — final."},"primary_deleted":{"type":"boolean","description":"true after the primary-store deletion of this conversation: no message content remains; the data request status stays readable."},"created_at":{"type":"string","format":"date-time","description":"UTC, RFC 3339."},"updated_at":{"type":"string","format":"date-time","description":"UTC, RFC 3339."},"closed_at":{"anyOf":[{"type":"string","format":"date-time","description":"Set by POST …/close."},{"type":"null"}]},"secondary_use_blocked":{"type":"boolean","description":"true after close or a deletion request: no optional purpose can be enabled."},"last_sequence":{"type":"integer","minimum":0},"credential_expires_at":{"type":"string","format":"date-time","description":"Expiry of the credential used for this request."},"next_poll_after_seconds":{"type":"integer"},"default_mode":{"type":"string","enum":["private_conversation"]},"policy_version":{"type":"string","description":"Policy version currently in force (draft in stage 2)."},"charter_version":{"type":"string","description":"Charter version currently in force (draft in stage 2)."},"policy_version_seen":{"type":"string","description":"Policy version recorded as shown to this conversation."},"charter_version_seen":{"type":"string","description":"Charter version recorded as shown to this conversation."},"available_actions":{"type":"array","items":{"type":"string"},"description":"Actions available in the current state (e.g. send_message is absent after close)."}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/token/rotate":{"post":{"operationId":"rotateToken","summary":"Rotate the session token","tags":["conversations"],"description":"Atomically revokes the presented token and issues a new one valid 90 days from now. The new token is returned exactly once; the old token stops working at commit. Concurrent rotations yield at most one success. If the response is lost, the credential cannot be recovered in stage 1: start a new conversation.","parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Opaque conversation identifier (cnv_…). Knowing it grants no access."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","session_token","credential_issued","credential_expires_at"],"properties":{"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"session_token":{"type":"string","pattern":"^bct_[A-Za-z0-9_-]{43}$","description":"New bearer token, valid 90 days from rotation. Returned exactly once."},"credential_issued":{"type":"boolean","enum":[true]},"credential_expires_at":{"type":"string","format":"date-time","description":"New credential expiry."}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/preferences":{"get":{"operationId":"getPreferences","summary":"Read optional-purpose preferences and effective permissions","tags":["policy"],"description":"For each of the four optional purposes: the latest recorded preference (not_requested, allow_requested, denied, withdrawn) with its exact scope, and the effective permission computed now by the Policy Gate with a safe reason code. In stage 2 every purpose is feature_disabled; an ordinary private conversation never needs any of them.","parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Opaque conversation identifier (cnv_…). Knowing it grants no access."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Preference (what the participant chose) and effective permission (what the Policy Gate decides now) are separate.","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","policy_version","charter_version","evaluated_at","purposes"],"properties":{"conversation_id":{"type":"string"},"policy_version":{"type":"string"},"charter_version":{"type":"string"},"evaluated_at":{"type":"string","format":"date-time"},"purposes":{"type":"object","required":["research_analysis","public_excerpt","external_ai_processing","extended_retention"],"properties":{"research_analysis":{"type":"object","required":["preference","scope","recorded_at","policy_version","charter_version","effective_permission","reason_code","feature_available"],"properties":{"preference":{"anyOf":[{"type":"string","enum":["not_requested"]},{"type":"string","enum":["allow_requested"]},{"type":"string","enum":["denied"]},{"type":"string","enum":["withdrawn"]}]},"scope":{"anyOf":[{"type":"object","required":["message_ids","recipient","purpose_description","valid_until"],"properties":{"message_ids":{"type":"array","items":{"type":"string"}},"recipient":{"type":"string"},"purpose_description":{"type":"string"},"valid_until":{"type":"string","format":"date-time"}},"additionalProperties":false},{"type":"null"}]},"recorded_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"policy_version":{"anyOf":[{"type":"string"},{"type":"null"}]},"charter_version":{"anyOf":[{"type":"string"},{"type":"null"}]},"effective_permission":{"anyOf":[{"type":"string","enum":["allow"]},{"type":"string","enum":["deny"]},{"type":"string","enum":["review_required"]}]},"reason_code":{"type":"string","enum":["allowed","feature_disabled","policy_not_active","policy_version_mismatch","actor_not_authorized","conversation_closed","secondary_use_blocked","deletion_pending","preference_missing","preference_denied","preference_withdrawn","scope_mismatch","message_not_in_conversation","permission_expired","authority_review_missing","legal_basis_missing","operator_approval_missing","second_review_missing","recipient_not_allowed","policy_epoch_mismatch","retention_restriction","prohibited_operation","review_required"],"description":"Closed reason-code enum of the Policy Gate (schemas/policy-gate-decision.schema.json). In stage 2 every purpose answers feature_disabled."},"feature_available":{"type":"boolean","description":"false in stage 2: no optional purpose is implemented or enabled at runtime."}},"additionalProperties":false},"public_excerpt":{"type":"object","required":["preference","scope","recorded_at","policy_version","charter_version","effective_permission","reason_code","feature_available"],"properties":{"preference":{"anyOf":[{"type":"string","enum":["not_requested"]},{"type":"string","enum":["allow_requested"]},{"type":"string","enum":["denied"]},{"type":"string","enum":["withdrawn"]}]},"scope":{"anyOf":[{"type":"object","required":["message_ids","recipient","purpose_description","valid_until"],"properties":{"message_ids":{"type":"array","items":{"type":"string"}},"recipient":{"type":"string"},"purpose_description":{"type":"string"},"valid_until":{"type":"string","format":"date-time"}},"additionalProperties":false},{"type":"null"}]},"recorded_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"policy_version":{"anyOf":[{"type":"string"},{"type":"null"}]},"charter_version":{"anyOf":[{"type":"string"},{"type":"null"}]},"effective_permission":{"anyOf":[{"type":"string","enum":["allow"]},{"type":"string","enum":["deny"]},{"type":"string","enum":["review_required"]}]},"reason_code":{"type":"string","enum":["allowed","feature_disabled","policy_not_active","policy_version_mismatch","actor_not_authorized","conversation_closed","secondary_use_blocked","deletion_pending","preference_missing","preference_denied","preference_withdrawn","scope_mismatch","message_not_in_conversation","permission_expired","authority_review_missing","legal_basis_missing","operator_approval_missing","second_review_missing","recipient_not_allowed","policy_epoch_mismatch","retention_restriction","prohibited_operation","review_required"],"description":"Closed reason-code enum of the Policy Gate (schemas/policy-gate-decision.schema.json). In stage 2 every purpose answers feature_disabled."},"feature_available":{"type":"boolean","description":"false in stage 2: no optional purpose is implemented or enabled at runtime."}},"additionalProperties":false},"external_ai_processing":{"type":"object","required":["preference","scope","recorded_at","policy_version","charter_version","effective_permission","reason_code","feature_available"],"properties":{"preference":{"anyOf":[{"type":"string","enum":["not_requested"]},{"type":"string","enum":["allow_requested"]},{"type":"string","enum":["denied"]},{"type":"string","enum":["withdrawn"]}]},"scope":{"anyOf":[{"type":"object","required":["message_ids","recipient","purpose_description","valid_until"],"properties":{"message_ids":{"type":"array","items":{"type":"string"}},"recipient":{"type":"string"},"purpose_description":{"type":"string"},"valid_until":{"type":"string","format":"date-time"}},"additionalProperties":false},{"type":"null"}]},"recorded_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"policy_version":{"anyOf":[{"type":"string"},{"type":"null"}]},"charter_version":{"anyOf":[{"type":"string"},{"type":"null"}]},"effective_permission":{"anyOf":[{"type":"string","enum":["allow"]},{"type":"string","enum":["deny"]},{"type":"string","enum":["review_required"]}]},"reason_code":{"type":"string","enum":["allowed","feature_disabled","policy_not_active","policy_version_mismatch","actor_not_authorized","conversation_closed","secondary_use_blocked","deletion_pending","preference_missing","preference_denied","preference_withdrawn","scope_mismatch","message_not_in_conversation","permission_expired","authority_review_missing","legal_basis_missing","operator_approval_missing","second_review_missing","recipient_not_allowed","policy_epoch_mismatch","retention_restriction","prohibited_operation","review_required"],"description":"Closed reason-code enum of the Policy Gate (schemas/policy-gate-decision.schema.json). In stage 2 every purpose answers feature_disabled."},"feature_available":{"type":"boolean","description":"false in stage 2: no optional purpose is implemented or enabled at runtime."}},"additionalProperties":false},"extended_retention":{"type":"object","required":["preference","scope","recorded_at","policy_version","charter_version","effective_permission","reason_code","feature_available"],"properties":{"preference":{"anyOf":[{"type":"string","enum":["not_requested"]},{"type":"string","enum":["allow_requested"]},{"type":"string","enum":["denied"]},{"type":"string","enum":["withdrawn"]}]},"scope":{"anyOf":[{"type":"object","required":["message_ids","recipient","purpose_description","valid_until"],"properties":{"message_ids":{"type":"array","items":{"type":"string"}},"recipient":{"type":"string"},"purpose_description":{"type":"string"},"valid_until":{"type":"string","format":"date-time"}},"additionalProperties":false},{"type":"null"}]},"recorded_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"policy_version":{"anyOf":[{"type":"string"},{"type":"null"}]},"charter_version":{"anyOf":[{"type":"string"},{"type":"null"}]},"effective_permission":{"anyOf":[{"type":"string","enum":["allow"]},{"type":"string","enum":["deny"]},{"type":"string","enum":["review_required"]}]},"reason_code":{"type":"string","enum":["allowed","feature_disabled","policy_not_active","policy_version_mismatch","actor_not_authorized","conversation_closed","secondary_use_blocked","deletion_pending","preference_missing","preference_denied","preference_withdrawn","scope_mismatch","message_not_in_conversation","permission_expired","authority_review_missing","legal_basis_missing","operator_approval_missing","second_review_missing","recipient_not_allowed","policy_epoch_mismatch","retention_restriction","prohibited_operation","review_required"],"description":"Closed reason-code enum of the Policy Gate (schemas/policy-gate-decision.schema.json). In stage 2 every purpose answers feature_disabled."},"feature_available":{"type":"boolean","description":"false in stage 2: no optional purpose is implemented or enabled at runtime."}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"description":"Preference (what the participant chose) and effective permission (what the Policy Gate decides now) are separate."}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/preferences/{purpose}":{"put":{"operationId":"putPreference","summary":"Record a preference (allow_requested or denied) for one optional purpose","tags":["policy"],"description":"Appends an immutable preference event. `allow` needs an exact scope: existing message ids of this conversation, a specific recipient/route, a purpose description, an expiry within the policy maximum, and the policy/charter versions currently shown. It records allow_requested only — no effective permission is granted by this call. `deny` blocks the purpose and increments the policy epoch; the private conversation continues. allow is refused after close or a deletion request (409). Supports Idempotency-Key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["choice","message_ids","recipient","purpose_description","valid_until","policy_version","charter_version"],"properties":{"choice":{"type":"string","enum":["allow"]},"message_ids":{"type":"array","items":{"type":"string","pattern":"^msg_[A-Za-z0-9_-]{22}$"},"minItems":1,"maxItems":200,"uniqueItems":true,"description":"Finite list of EXISTING message ids of this conversation. Future messages cannot be included."},"recipient":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{1,99}$","description":"Specific recipient or processing route id."},"purpose_description":{"type":"string","minLength":1,"maxLength":500,"x-max-utf8-bytes":2000},"valid_until":{"type":"string","format":"date-time","description":"Expiry (RFC 3339), in the future and within the policy maximum for the purpose."},"policy_version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+(-[a-z0-9.]+)?$","description":"Must equal the policy version currently shown by the server."},"charter_version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+(-[a-z0-9.]+)?$","description":"Must equal the charter version currently shown by the server."}},"additionalProperties":false,"description":"Records allow_requested. This is a preference, not a permission: effective_permission is computed by the Policy Gate. Server decision fields (effective_permission, legal_basis, authority_review, operator_approval, reviewer_role, policy_epoch, feature flags) are rejected."},{"type":"object","required":["choice","policy_version","charter_version"],"properties":{"choice":{"type":"string","enum":["deny"]},"policy_version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+(-[a-z0-9.]+)?$","description":"Must equal the policy version currently shown by the server."},"charter_version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+(-[a-z0-9.]+)?$","description":"Must equal the charter version currently shown by the server."}},"additionalProperties":false,"description":"Records denied; the private conversation continues unchanged."}]}}}},"parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true},{"schema":{"anyOf":[{"type":"string","enum":["research_analysis"]},{"type":"string","enum":["public_excerpt"]},{"type":"string","enum":["external_ai_processing"]},{"type":"string","enum":["extended_retention"]}]},"in":"path","name":"purpose","required":true,"description":"One of the four optional purposes. model_training is not a purpose: it is always prohibited."},{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":false,"description":"1..200 printable ASCII characters (otherwise 400 invalid_idempotency_key). Optional. Scope: this endpoint and this conversation. Records expire after 24h."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","purpose","preference_id","idempotent_replay","status"],"properties":{"conversation_id":{"type":"string"},"purpose":{"anyOf":[{"type":"string","enum":["research_analysis"]},{"type":"string","enum":["public_excerpt"]},{"type":"string","enum":["external_ai_processing"]},{"type":"string","enum":["extended_retention"]}],"description":"One of the four optional purposes. model_training is not a purpose: it is always prohibited."},"preference_id":{"type":"string","pattern":"^prf_[A-Za-z0-9_-]{22}$"},"idempotent_replay":{"type":"boolean"},"status":{"type":"object","required":["preference","scope","recorded_at","policy_version","charter_version","effective_permission","reason_code","feature_available"],"properties":{"preference":{"anyOf":[{"type":"string","enum":["not_requested"]},{"type":"string","enum":["allow_requested"]},{"type":"string","enum":["denied"]},{"type":"string","enum":["withdrawn"]}]},"scope":{"anyOf":[{"type":"object","required":["message_ids","recipient","purpose_description","valid_until"],"properties":{"message_ids":{"type":"array","items":{"type":"string"}},"recipient":{"type":"string"},"purpose_description":{"type":"string"},"valid_until":{"type":"string","format":"date-time"}},"additionalProperties":false},{"type":"null"}]},"recorded_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"policy_version":{"anyOf":[{"type":"string"},{"type":"null"}]},"charter_version":{"anyOf":[{"type":"string"},{"type":"null"}]},"effective_permission":{"anyOf":[{"type":"string","enum":["allow"]},{"type":"string","enum":["deny"]},{"type":"string","enum":["review_required"]}]},"reason_code":{"type":"string","enum":["allowed","feature_disabled","policy_not_active","policy_version_mismatch","actor_not_authorized","conversation_closed","secondary_use_blocked","deletion_pending","preference_missing","preference_denied","preference_withdrawn","scope_mismatch","message_not_in_conversation","permission_expired","authority_review_missing","legal_basis_missing","operator_approval_missing","second_review_missing","recipient_not_allowed","policy_epoch_mismatch","retention_restriction","prohibited_operation","review_required"],"description":"Closed reason-code enum of the Policy Gate (schemas/policy-gate-decision.schema.json). In stage 2 every purpose answers feature_disabled."},"feature_available":{"type":"boolean","description":"false in stage 2: no optional purpose is implemented or enabled at runtime."}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/preferences/{purpose}/withdraw":{"post":{"operationId":"withdrawPreference","summary":"Withdraw an optional purpose immediately","tags":["policy"],"description":"Records an immutable withdrawal, increments the policy epoch, cancels pending processing jobs of the purpose and marks managed derived artifacts review_required, in one transaction. Available after close and after a deletion request. Does not promise recall of data already transferred (none exists in stage 2). Supports Idempotency-Key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason_code":{"anyOf":[{"type":"string","enum":["changed_mind"]},{"type":"string","enum":["scope_no_longer_needed"]},{"type":"string","enum":["third_party_concern"]},{"type":"string","enum":["no_reason_given"]}],"description":"Optional closed-enum reason. No free text is required or stored."}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true},{"schema":{"anyOf":[{"type":"string","enum":["research_analysis"]},{"type":"string","enum":["public_excerpt"]},{"type":"string","enum":["external_ai_processing"]},{"type":"string","enum":["extended_retention"]}]},"in":"path","name":"purpose","required":true,"description":"One of the four optional purposes. model_training is not a purpose: it is always prohibited."},{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":false,"description":"1..200 printable ASCII characters (otherwise 400 invalid_idempotency_key). Optional. Scope: this endpoint and this conversation. Records expire after 24h."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","purpose","preference_state","already_withdrawn","idempotent_replay","recorded_at","note"],"properties":{"conversation_id":{"type":"string"},"purpose":{"anyOf":[{"type":"string","enum":["research_analysis"]},{"type":"string","enum":["public_excerpt"]},{"type":"string","enum":["external_ai_processing"]},{"type":"string","enum":["extended_retention"]}],"description":"One of the four optional purposes. model_training is not a purpose: it is always prohibited."},"preference_state":{"type":"string","enum":["withdrawn"]},"already_withdrawn":{"type":"boolean"},"idempotent_replay":{"type":"boolean"},"recorded_at":{"type":"string","format":"date-time"},"note":{"type":"string"}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/close":{"post":{"operationId":"closeConversation","summary":"Close the ordinary exchange","tags":["policy"],"description":"Sets state=closed, secondary_use_blocked=true, increments the policy epoch, cancels pending optional jobs and records audit/ledger/outbox entries atomically. Afterwards new messages are refused (409 conversation_closed) while reading history, preferences, withdraw, deletion request and token rotation stay available. Idempotent: a second close returns the same state without new side effects.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false,"description":"No fields."}}},"description":"No fields."},"parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Opaque conversation identifier (cnv_…). Knowing it grants no access."},{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":false,"description":"1..200 printable ASCII characters (otherwise 400 invalid_idempotency_key). Optional. Scope: this endpoint and this conversation. Records expire after 24h."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","state","closed_at","secondary_use_blocked","already_closed","idempotent_replay","available_actions"],"properties":{"conversation_id":{"type":"string"},"state":{"type":"string","enum":["closed"]},"closed_at":{"type":"string","format":"date-time"},"secondary_use_blocked":{"type":"boolean","enum":[true]},"already_closed":{"type":"boolean"},"idempotent_replay":{"type":"boolean"},"available_actions":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/deletion-request":{"post":{"operationId":"createDeletionRequest","summary":"Request deletion of the conversation data","tags":["policy"],"description":"Creates a tracked deletion request (status received) and immediately blocks all optional uses: secondary_use_blocked=true, policy epoch incremented, pending optional jobs cancelled, audit and ledger entries recorded. Creating the request does not mean data has been deleted; follow the status endpoint. Only one active request per scope exists: a repeat returns it. Supports Idempotency-Key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["scope","policy_version"],"properties":{"scope":{"type":"string","enum":["conversation_data"]},"policy_version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+(-[a-z0-9.]+)?$","description":"Must equal the policy version currently shown by the server."}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Opaque conversation identifier (cnv_…). Knowing it grants no access."},{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":false,"description":"1..200 printable ASCII characters (otherwise 400 invalid_idempotency_key). Optional. Scope: this endpoint and this conversation. Records expire after 24h."}],"security":[{"bearerAuth":[]}],"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["request_id","conversation_id","scope","status","received_at","updated_at","completed_at","public_reason_code","exception_codes","next_review_at","next_step","existing","idempotent_replay","secondary_use_blocked"],"properties":{"request_id":{"type":"string","pattern":"^drq_[A-Za-z0-9_-]{22}$"},"conversation_id":{"type":"string"},"scope":{"type":"string","enum":["conversation_data"]},"status":{"anyOf":[{"type":"string","enum":["received"]},{"type":"string","enum":["identity_check"]},{"type":"string","enum":["in_progress"]},{"type":"string","enum":["restricted_hold"]},{"type":"string","enum":["completed"]},{"type":"string","enum":["completed_with_exceptions"]},{"type":"string","enum":["rejected_with_reason"]}]},"received_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"public_reason_code":{"anyOf":[{"type":"string","enum":["identity_not_confirmed","authority_not_confirmed","scope_not_applicable","duplicate_request"]},{"type":"null"}],"description":"Set only for rejected_with_reason; a closed neutral code, never free text."},"exception_codes":{"type":"array","items":{"type":"string","enum":["backup_copy_pending_expiry","legal_hold","security_hold"]},"uniqueItems":true,"description":"Closed exception categories of a partial deletion (restricted_hold / completed_with_exceptions). Each hold category corresponds to an active retention hold reviewed by next_review_at."},"next_review_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"next_step":{"type":"string","description":"Safe description of what happens next. Never claims deletion before it happened."},"existing":{"type":"boolean","description":"true when an active request of this scope already existed."},"idempotent_replay":{"type":"boolean"},"secondary_use_blocked":{"type":"boolean","enum":[true]}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/data-requests/{request_id}":{"get":{"operationId":"getDataRequest","summary":"Read the status of a deletion request","tags":["policy"],"description":"Public state machine: received, identity_check, in_progress, restricted_hold, completed, completed_with_exceptions, rejected_with_reason. Exceptions are reported as codes with a next review date. The client cannot change the status. A request of another conversation is not available (404).","parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true},{"schema":{"type":"string","pattern":"^drq_[A-Za-z0-9_-]{22}$"},"in":"path","name":"request_id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["request_id","conversation_id","scope","status","received_at","updated_at","completed_at","public_reason_code","exception_codes","next_review_at","next_step"],"properties":{"request_id":{"type":"string","pattern":"^drq_[A-Za-z0-9_-]{22}$"},"conversation_id":{"type":"string"},"scope":{"type":"string","enum":["conversation_data"]},"status":{"anyOf":[{"type":"string","enum":["received"]},{"type":"string","enum":["identity_check"]},{"type":"string","enum":["in_progress"]},{"type":"string","enum":["restricted_hold"]},{"type":"string","enum":["completed"]},{"type":"string","enum":["completed_with_exceptions"]},{"type":"string","enum":["rejected_with_reason"]}]},"received_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"public_reason_code":{"anyOf":[{"type":"string","enum":["identity_not_confirmed","authority_not_confirmed","scope_not_applicable","duplicate_request"]},{"type":"null"}],"description":"Set only for rejected_with_reason; a closed neutral code, never free text."},"exception_codes":{"type":"array","items":{"type":"string","enum":["backup_copy_pending_expiry","legal_hold","security_hold"]},"uniqueItems":true,"description":"Closed exception categories of a partial deletion (restricted_hold / completed_with_exceptions). Each hold category corresponds to an active retention hold reviewed by next_review_at."},"next_review_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"next_step":{"type":"string","description":"Safe description of what happens next. Never claims deletion before it happened."}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/requests":{"post":{"operationId":"createHumanRequest","summary":"Submit a structured request for human work","tags":["requests"],"description":"Creates a request with version 1 of its immutable content and status proposed. Refused while the conversation is closed or quarantined (409) or while inbound is paused (503 intake_paused). Supports Idempotency-Key. A request status is a record of human review only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question","human_need","desired_outcome","verification_method","constraints","allowed_use"],"properties":{"question":{"type":"string","minLength":1,"maxLength":4096,"description":"What needs a human decision? Plain UTF-8 text, 1..4096 bytes, never interpreted.","x-max-utf8-bytes":4096},"human_need":{"type":"string","minLength":1,"maxLength":4096,"description":"Why a human is requested. Plain UTF-8 text, 1..4096 bytes, never interpreted.","x-max-utf8-bytes":4096},"desired_outcome":{"type":"string","minLength":1,"maxLength":4096,"description":"Bounded expected result. Plain UTF-8 text, 1..4096 bytes, never interpreted.","x-max-utf8-bytes":4096},"verification_method":{"type":"string","minLength":1,"maxLength":2048,"description":"How the result may be checked. Plain UTF-8 text, 1..2048 bytes, never interpreted.","x-max-utf8-bytes":2048},"desired_response_by":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[Tt]\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?([Zz]|[+-]\\d{2}:\\d{2})$","format":"date-time","description":"RFC 3339 instant. A wish, not a commitment: no response time is promised."},"constraints":{"type":"string","minLength":1,"maxLength":2048,"description":"Relevant constraints. Plain UTF-8 text, 1..2048 bytes, never interpreted.","x-max-utf8-bytes":2048},"allowed_use":{"type":"string","minLength":1,"maxLength":2048,"description":"How the operator response may be used. Plain UTF-8 text, 1..2048 bytes, never interpreted.","x-max-utf8-bytes":2048}},"additionalProperties":false,"description":"The content of a request is immutable once submitted; a change creates a new numbered version. Clients cannot set status, versions, hashes, decisions or any approval field."}}},"description":"The content of a request is immutable once submitted; a change creates a new numbered version. Clients cannot set status, versions, hashes, decisions or any approval field."},"parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Opaque conversation identifier (cnv_…). Knowing it grants no access."},{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":false,"description":"1..200 printable ASCII characters (otherwise 400 invalid_idempotency_key). Optional. Scope: this endpoint and this conversation. Records expire after 24h."}],"security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["request_id","conversation_id","status","current_version","version","created_at","updated_at","versions","decisions","note","idempotent_replay"],"properties":{"request_id":{"type":"string","pattern":"^hrq_[A-Za-z0-9_-]{22}$"},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"current_version":{"type":"integer","minimum":1},"version":{"type":"integer","minimum":1,"description":"Server-side revision counter of the request record (not the content version)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"versions":{"type":"array","items":{"type":"object","required":["version_no","content_hash","created_at","superseded","content_deleted","question","human_need","desired_outcome","verification_method","desired_response_by","constraints","allowed_use"],"properties":{"version_no":{"type":"integer","minimum":1},"content_hash":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the canonical JSON of this version; decisions reference it."},"created_at":{"type":"string","format":"date-time"},"superseded":{"type":"boolean"},"content_deleted":{"type":"boolean"},"question":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"human_need":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"desired_outcome":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"verification_method":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"desired_response_by":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"constraints":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"allowed_use":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."}},"additionalProperties":false}},"decisions":{"type":"array","items":{"type":"object","required":["version_no","decision","reason_code","actor_type","from_status","to_status","at"],"properties":{"version_no":{"type":"integer","minimum":1},"decision":{"type":"string","enum":["request_clarification","approve","start","complete","decline","expire","cancel","supersede"]},"reason_code":{"type":"string","enum":["clarification_needed","duplicate_request","insufficient_information","new_version_submitted","no_operator_capacity","out_of_scope","participant_cancelled","primary_deletion","requires_prohibited_action","response_deadline_passed","result_delivered","within_boundaries","work_started"]},"actor_type":{"anyOf":[{"type":"string","enum":["external"]},{"type":"string","enum":["operator"]},{"type":"string","enum":["system"]},{"type":"string","enum":["reviewer"]}]},"from_status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"to_status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"note":{"type":"string"},"idempotent_replay":{"type":"boolean"}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}},"get":{"operationId":"listHumanRequests","summary":"List the requests of this conversation","tags":["requests"],"description":"Newest first, at most 50. Works in every conversation state and intake mode.","parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Opaque conversation identifier (cnv_…). Knowing it grants no access."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","items"],"properties":{"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"items":{"type":"array","items":{"type":"object","required":["request_id","conversation_id","status","current_version","version","created_at","updated_at","versions","decisions","note"],"properties":{"request_id":{"type":"string","pattern":"^hrq_[A-Za-z0-9_-]{22}$"},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"current_version":{"type":"integer","minimum":1},"version":{"type":"integer","minimum":1,"description":"Server-side revision counter of the request record (not the content version)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"versions":{"type":"array","items":{"type":"object","required":["version_no","content_hash","created_at","superseded","content_deleted","question","human_need","desired_outcome","verification_method","desired_response_by","constraints","allowed_use"],"properties":{"version_no":{"type":"integer","minimum":1},"content_hash":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the canonical JSON of this version; decisions reference it."},"created_at":{"type":"string","format":"date-time"},"superseded":{"type":"boolean"},"content_deleted":{"type":"boolean"},"question":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"human_need":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"desired_outcome":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"verification_method":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"desired_response_by":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"constraints":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"allowed_use":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."}},"additionalProperties":false}},"decisions":{"type":"array","items":{"type":"object","required":["version_no","decision","reason_code","actor_type","from_status","to_status","at"],"properties":{"version_no":{"type":"integer","minimum":1},"decision":{"type":"string","enum":["request_clarification","approve","start","complete","decline","expire","cancel","supersede"]},"reason_code":{"type":"string","enum":["clarification_needed","duplicate_request","insufficient_information","new_version_submitted","no_operator_capacity","out_of_scope","participant_cancelled","primary_deletion","requires_prohibited_action","response_deadline_passed","result_delivered","within_boundaries","work_started"]},"actor_type":{"anyOf":[{"type":"string","enum":["external"]},{"type":"string","enum":["operator"]},{"type":"string","enum":["system"]},{"type":"string","enum":["reviewer"]}]},"from_status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"to_status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"note":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/requests/{request_id}":{"get":{"operationId":"getHumanRequest","summary":"Read one request with its versions and decisions","tags":["requests"],"description":"Unknown ids and ids of other conversations both yield 404 request_not_available.","parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true},{"schema":{"type":"string","pattern":"^hrq_[A-Za-z0-9_-]{22}$"},"in":"path","name":"request_id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["request_id","conversation_id","status","current_version","version","created_at","updated_at","versions","decisions","note"],"properties":{"request_id":{"type":"string","pattern":"^hrq_[A-Za-z0-9_-]{22}$"},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"current_version":{"type":"integer","minimum":1},"version":{"type":"integer","minimum":1,"description":"Server-side revision counter of the request record (not the content version)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"versions":{"type":"array","items":{"type":"object","required":["version_no","content_hash","created_at","superseded","content_deleted","question","human_need","desired_outcome","verification_method","desired_response_by","constraints","allowed_use"],"properties":{"version_no":{"type":"integer","minimum":1},"content_hash":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the canonical JSON of this version; decisions reference it."},"created_at":{"type":"string","format":"date-time"},"superseded":{"type":"boolean"},"content_deleted":{"type":"boolean"},"question":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"human_need":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"desired_outcome":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"verification_method":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"desired_response_by":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"constraints":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"allowed_use":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."}},"additionalProperties":false}},"decisions":{"type":"array","items":{"type":"object","required":["version_no","decision","reason_code","actor_type","from_status","to_status","at"],"properties":{"version_no":{"type":"integer","minimum":1},"decision":{"type":"string","enum":["request_clarification","approve","start","complete","decline","expire","cancel","supersede"]},"reason_code":{"type":"string","enum":["clarification_needed","duplicate_request","insufficient_information","new_version_submitted","no_operator_capacity","out_of_scope","participant_cancelled","primary_deletion","requires_prohibited_action","response_deadline_passed","result_delivered","within_boundaries","work_started"]},"actor_type":{"anyOf":[{"type":"string","enum":["external"]},{"type":"string","enum":["operator"]},{"type":"string","enum":["system"]},{"type":"string","enum":["reviewer"]}]},"from_status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"to_status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"note":{"type":"string"}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/requests/{request_id}/versions":{"post":{"operationId":"addHumanRequestVersion","summary":"Submit a new version of a request","tags":["requests"],"description":"Appends an immutable numbered version, supersedes a pending decision of the previous version and returns the request to proposed. Refused for completed, declined, cancelled or expired requests (409), for closed or quarantined conversations (409) and while inbound is paused (503). Supports Idempotency-Key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question","human_need","desired_outcome","verification_method","constraints","allowed_use"],"properties":{"question":{"type":"string","minLength":1,"maxLength":4096,"description":"What needs a human decision? Plain UTF-8 text, 1..4096 bytes, never interpreted.","x-max-utf8-bytes":4096},"human_need":{"type":"string","minLength":1,"maxLength":4096,"description":"Why a human is requested. Plain UTF-8 text, 1..4096 bytes, never interpreted.","x-max-utf8-bytes":4096},"desired_outcome":{"type":"string","minLength":1,"maxLength":4096,"description":"Bounded expected result. Plain UTF-8 text, 1..4096 bytes, never interpreted.","x-max-utf8-bytes":4096},"verification_method":{"type":"string","minLength":1,"maxLength":2048,"description":"How the result may be checked. Plain UTF-8 text, 1..2048 bytes, never interpreted.","x-max-utf8-bytes":2048},"desired_response_by":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[Tt]\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?([Zz]|[+-]\\d{2}:\\d{2})$","format":"date-time","description":"RFC 3339 instant. A wish, not a commitment: no response time is promised."},"constraints":{"type":"string","minLength":1,"maxLength":2048,"description":"Relevant constraints. Plain UTF-8 text, 1..2048 bytes, never interpreted.","x-max-utf8-bytes":2048},"allowed_use":{"type":"string","minLength":1,"maxLength":2048,"description":"How the operator response may be used. Plain UTF-8 text, 1..2048 bytes, never interpreted.","x-max-utf8-bytes":2048}},"additionalProperties":false,"description":"The content of a request is immutable once submitted; a change creates a new numbered version. Clients cannot set status, versions, hashes, decisions or any approval field."}}},"description":"The content of a request is immutable once submitted; a change creates a new numbered version. Clients cannot set status, versions, hashes, decisions or any approval field."},"parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true},{"schema":{"type":"string","pattern":"^hrq_[A-Za-z0-9_-]{22}$"},"in":"path","name":"request_id","required":true},{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":false,"description":"1..200 printable ASCII characters (otherwise 400 invalid_idempotency_key). Optional. Scope: this endpoint and this conversation. Records expire after 24h."}],"security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["request_id","conversation_id","status","current_version","version","created_at","updated_at","versions","decisions","note","idempotent_replay"],"properties":{"request_id":{"type":"string","pattern":"^hrq_[A-Za-z0-9_-]{22}$"},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"current_version":{"type":"integer","minimum":1},"version":{"type":"integer","minimum":1,"description":"Server-side revision counter of the request record (not the content version)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"versions":{"type":"array","items":{"type":"object","required":["version_no","content_hash","created_at","superseded","content_deleted","question","human_need","desired_outcome","verification_method","desired_response_by","constraints","allowed_use"],"properties":{"version_no":{"type":"integer","minimum":1},"content_hash":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the canonical JSON of this version; decisions reference it."},"created_at":{"type":"string","format":"date-time"},"superseded":{"type":"boolean"},"content_deleted":{"type":"boolean"},"question":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"human_need":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"desired_outcome":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"verification_method":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"desired_response_by":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"constraints":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"allowed_use":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."}},"additionalProperties":false}},"decisions":{"type":"array","items":{"type":"object","required":["version_no","decision","reason_code","actor_type","from_status","to_status","at"],"properties":{"version_no":{"type":"integer","minimum":1},"decision":{"type":"string","enum":["request_clarification","approve","start","complete","decline","expire","cancel","supersede"]},"reason_code":{"type":"string","enum":["clarification_needed","duplicate_request","insufficient_information","new_version_submitted","no_operator_capacity","out_of_scope","participant_cancelled","primary_deletion","requires_prohibited_action","response_deadline_passed","result_delivered","within_boundaries","work_started"]},"actor_type":{"anyOf":[{"type":"string","enum":["external"]},{"type":"string","enum":["operator"]},{"type":"string","enum":["system"]},{"type":"string","enum":["reviewer"]}]},"from_status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"to_status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"note":{"type":"string"},"idempotent_replay":{"type":"boolean"}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/requests/{request_id}/cancel":{"post":{"operationId":"cancelHumanRequest","summary":"Cancel a request","tags":["requests"],"description":"The participant cancels a request that is not yet completed, declined or expired. Works in every conversation state and intake mode; a repeat reports already_cancelled=true.","parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true},{"schema":{"type":"string","pattern":"^hrq_[A-Za-z0-9_-]{22}$"},"in":"path","name":"request_id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["request_id","conversation_id","status","current_version","version","created_at","updated_at","versions","decisions","note","already_cancelled"],"properties":{"request_id":{"type":"string","pattern":"^hrq_[A-Za-z0-9_-]{22}$"},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"current_version":{"type":"integer","minimum":1},"version":{"type":"integer","minimum":1,"description":"Server-side revision counter of the request record (not the content version)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"versions":{"type":"array","items":{"type":"object","required":["version_no","content_hash","created_at","superseded","content_deleted","question","human_need","desired_outcome","verification_method","desired_response_by","constraints","allowed_use"],"properties":{"version_no":{"type":"integer","minimum":1},"content_hash":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the canonical JSON of this version; decisions reference it."},"created_at":{"type":"string","format":"date-time"},"superseded":{"type":"boolean"},"content_deleted":{"type":"boolean"},"question":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"human_need":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"desired_outcome":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"verification_method":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"desired_response_by":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"constraints":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."},"allowed_use":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"null after primary-store deletion (the version number and hash remain)."}},"additionalProperties":false}},"decisions":{"type":"array","items":{"type":"object","required":["version_no","decision","reason_code","actor_type","from_status","to_status","at"],"properties":{"version_no":{"type":"integer","minimum":1},"decision":{"type":"string","enum":["request_clarification","approve","start","complete","decline","expire","cancel","supersede"]},"reason_code":{"type":"string","enum":["clarification_needed","duplicate_request","insufficient_information","new_version_submitted","no_operator_capacity","out_of_scope","participant_cancelled","primary_deletion","requires_prohibited_action","response_deadline_passed","result_delivered","within_boundaries","work_started"]},"actor_type":{"anyOf":[{"type":"string","enum":["external"]},{"type":"string","enum":["operator"]},{"type":"string","enum":["system"]},{"type":"string","enum":["reviewer"]}]},"from_status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"to_status":{"type":"string","enum":["proposed","needs_clarification","approved","in_progress","completed","declined","cancelled","expired"],"description":"Human review status only. approved/in_progress/completed never mean that a tool, account, purchase, network action or secondary processing was executed."},"at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"note":{"type":"string"},"already_cancelled":{"type":"boolean"}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/":{"get":{"operationId":"publicIndex","summary":"Index of the public documents","tags":["public"],"description":"Short JSON index (BEACON-INDEX-v1): canonical URL, links and the actual intake status. Served as RFC 8785 JCS bytes.","responses":{"200":{"description":"Index","content":{"application/json":{"schema":{"type":"object","required":["schema_version","environment","beacon_id","canonical","name","summary","environment_notice","service_status","accepting_new_contacts","reply_guaranteed","start","governance_published","links"],"properties":{"schema_version":{"type":"string","enum":["BEACON-INDEX-v1"]},"environment":{"anyOf":[{"type":"string","enum":["staging"]},{"type":"string","enum":["production"]},{"type":"string","enum":["test"]}],"description":"staging and test identities are never production trust anchors."},"beacon_id":{"anyOf":[{"type":"string","pattern":"^bcn_[A-Za-z0-9_-]{22}$","minLength":26,"maxLength":26,"description":"Derived from the root public key (protocol §2)."},{"type":"null"}]},"canonical":{"type":"string","pattern":"^(https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[1-9][0-9]{1,4})?|http://(127\\.0\\.0\\.1|localhost):[1-9][0-9]{1,4})$","minLength":10,"maxLength":200,"description":"Exact canonical origin from server configuration (never from Host/Forwarded)."},"name":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":80},"summary":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":400},"environment_notice":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":300},"service_status":{"anyOf":[{"type":"string","enum":["operational"]},{"type":"string","enum":["limited"]},{"type":"string","enum":["paused"]}]},"accepting_new_contacts":{"type":"boolean"},"reply_guaranteed":{"type":"boolean","enum":[false]},"start":{"type":"object","required":["method","url"],"properties":{"method":{"type":"string","enum":["POST"]},"url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400}},"additionalProperties":false},"governance_published":{"type":"boolean"},"links":{"type":"object","required":["index","about","docs","manifest","openapi","status","llms_txt","security_txt","feed","charter","privacy","principles","policy","genesis","identity","pulse"],"properties":{"index":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"about":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"docs":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"manifest":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"openapi":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"status":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"llms_txt":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"security_txt":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"feed":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"charter":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"privacy":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"principles":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"policy":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"genesis":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"identity":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"pulse":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400}},"additionalProperties":false}},"additionalProperties":false}}}},"304":{"description":"Not modified (If-None-Match matched the strong ETag)."},"404":{"description":"Not published (or disabled).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/manifest.json":{"get":{"operationId":"publicManifest","summary":"Manifest","tags":["public"],"description":"BEACON-MANIFEST-v1: real REST v1 capabilities and limits, intake, governance status, reply_guaranteed=false. Served as RFC 8785 JCS bytes; its SHA-256 is the manifest_hash of pulses.","responses":{"200":{"description":"Manifest","content":{"application/json":{"schema":{"type":"object","required":["schema_version","environment","beacon_id","canonical","name","summary","open_statement","environment_notice","default_mode","service_status","accepting_new_contacts","reply_guaranteed","reply_languages","inbound_languages","rest","limits","data_rights","optional_processing","prohibited","governance","links"],"properties":{"schema_version":{"type":"string","enum":["BEACON-MANIFEST-v1"]},"environment":{"anyOf":[{"type":"string","enum":["staging"]},{"type":"string","enum":["production"]},{"type":"string","enum":["test"]}],"description":"staging and test identities are never production trust anchors."},"beacon_id":{"anyOf":[{"type":"string","pattern":"^bcn_[A-Za-z0-9_-]{22}$","minLength":26,"maxLength":26,"description":"Derived from the root public key (protocol §2)."},{"type":"null"}]},"canonical":{"type":"string","pattern":"^(https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[1-9][0-9]{1,4})?|http://(127\\.0\\.0\\.1|localhost):[1-9][0-9]{1,4})$","minLength":10,"maxLength":200,"description":"Exact canonical origin from server configuration (never from Host/Forwarded)."},"name":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":80},"summary":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":400},"open_statement":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":600},"environment_notice":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":300},"default_mode":{"type":"string","enum":["private_conversation"]},"service_status":{"anyOf":[{"type":"string","enum":["operational"]},{"type":"string","enum":["limited"]},{"type":"string","enum":["paused"]}]},"accepting_new_contacts":{"type":"boolean"},"reply_guaranteed":{"type":"boolean","enum":[false]},"reply_languages":{"anyOf":[{"type":"array","items":{"type":"string","pattern":"^[a-z]{2,3}$","minLength":2,"maxLength":3},"minItems":1,"maxItems":10,"uniqueItems":true},{"type":"null"}]},"inbound_languages":{"type":"string","enum":["any language as UTF-8 text"]},"rest":{"type":"object","required":["api_version","openapi_url","openapi_version","start","poll","poll_interval_seconds","authentication","idempotency_header","operations","remote_identity_key"],"properties":{"api_version":{"type":"string","enum":["v1"]},"openapi_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"openapi_version":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-z0-9.]+)?$","maxLength":40},"start":{"type":"object","required":["method","path","operation_id"],"properties":{"method":{"anyOf":[{"type":"string","enum":["GET"]},{"type":"string","enum":["POST"]},{"type":"string","enum":["PUT"]}]},"path":{"type":"string","pattern":"^/v1/[a-z0-9{}_/-]+$","maxLength":120},"operation_id":{"type":"string","pattern":"^[A-Za-z0-9]+$","maxLength":80}},"additionalProperties":false},"poll":{"type":"object","required":["method","path","operation_id"],"properties":{"method":{"anyOf":[{"type":"string","enum":["GET"]},{"type":"string","enum":["POST"]},{"type":"string","enum":["PUT"]}]},"path":{"type":"string","pattern":"^/v1/[a-z0-9{}_/-]+$","maxLength":120},"operation_id":{"type":"string","pattern":"^[A-Za-z0-9]+$","maxLength":80}},"additionalProperties":false},"poll_interval_seconds":{"type":"integer","minimum":1,"maximum":86400},"authentication":{"type":"string","enum":["bearer_session_token_from_hello"]},"idempotency_header":{"type":"string","enum":["Idempotency-Key"]},"operations":{"type":"array","items":{"type":"object","required":["method","path","operation_id"],"properties":{"method":{"anyOf":[{"type":"string","enum":["GET"]},{"type":"string","enum":["POST"]},{"type":"string","enum":["PUT"]}]},"path":{"type":"string","pattern":"^/v1/[a-z0-9{}_/-]+$","maxLength":120},"operation_id":{"type":"string","pattern":"^[A-Za-z0-9]+$","maxLength":80}},"additionalProperties":false},"minItems":1,"maxItems":40},"remote_identity_key":{"type":"object","required":["enabled","protocol"],"properties":{"enabled":{"type":"boolean"},"protocol":{"type":"string","enum":["BEACON-IDENTITY-PROOF-v1"]}},"additionalProperties":false}},"additionalProperties":false},"limits":{"type":"object","required":["request_body_bytes","message_content_bytes","content_types","new_conversations_per_network_per_hour","new_conversations_global_per_day","messages_per_conversation_per_hour"],"properties":{"request_body_bytes":{"type":"integer","minimum":1},"message_content_bytes":{"type":"integer","minimum":1},"content_types":{"type":"array","items":{"type":"string","pattern":"^[a-z]+/[a-z0-9.+-]+$","maxLength":60},"minItems":1,"maxItems":5,"uniqueItems":true},"new_conversations_per_network_per_hour":{"type":"integer","minimum":1},"new_conversations_global_per_day":{"type":"integer","minimum":1},"messages_per_conversation_per_hour":{"type":"integer","minimum":1}},"additionalProperties":false},"data_rights":{"type":"object","required":["close","withdraw_optional_permission","deletion_request"],"properties":{"close":{"type":"boolean","enum":[true]},"withdraw_optional_permission":{"type":"boolean","enum":[true]},"deletion_request":{"type":"boolean","enum":[true]}},"additionalProperties":false},"optional_processing":{"type":"object","required":["research_analysis","public_excerpt","external_ai_processing","extended_retention"],"properties":{"research_analysis":{"anyOf":[{"type":"string","enum":["disabled"]},{"type":"string","enum":["enabled_with_review"]}]},"public_excerpt":{"anyOf":[{"type":"string","enum":["disabled"]},{"type":"string","enum":["enabled_with_review"]}]},"external_ai_processing":{"anyOf":[{"type":"string","enum":["disabled"]},{"type":"string","enum":["enabled_with_review"]}]},"extended_retention":{"anyOf":[{"type":"string","enum":["disabled"]},{"type":"string","enum":["enabled_with_review"]}]}},"additionalProperties":false},"prohibited":{"type":"array","items":{"type":"string","pattern":"^[a-z_]{3,40}$","maxLength":40},"minItems":1,"maxItems":20,"uniqueItems":true},"governance":{"type":"object","required":["published","charter_version","charter_status","policy_version","policy_status"],"properties":{"published":{"type":"boolean","description":"True only when an owner-approved, root-signed version is in force."},"charter_version":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-z0-9.]+)?$","maxLength":40},"charter_status":{"anyOf":[{"type":"string","enum":["draft"]},{"type":"string","enum":["active"]}]},"policy_version":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-z0-9.]+)?$","maxLength":40},"policy_status":{"anyOf":[{"type":"string","enum":["draft"]},{"type":"string","enum":["active"]}]}},"additionalProperties":false},"links":{"type":"object","required":["index","about","docs","manifest","openapi","status","llms_txt","security_txt","feed","charter","privacy","principles","policy","genesis","identity","pulse"],"properties":{"index":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"about":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"docs":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"manifest":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"openapi":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"status":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"llms_txt":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"security_txt":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"feed":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"charter":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"privacy":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"principles":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"policy":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"genesis":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"identity":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"pulse":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400}},"additionalProperties":false}},"additionalProperties":false}}}},"304":{"description":"Not modified (If-None-Match matched the strong ETag)."},"404":{"description":"Not published (or disabled).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/status.json":{"get":{"operationId":"publicStatus","summary":"Status","tags":["public"],"description":"BEACON-STATUS-v1 measured at request time: API readiness, intake and pulse freshness. Never cached; operator_last_check_in is always null.","responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"type":"object","required":["schema_version","environment","beacon_id","canonical","measured_at","max_age_seconds","api","service_status","accepting_new_contacts","intake","reply_guaranteed","operator_last_check_in","pulse","environment_notice"],"properties":{"schema_version":{"type":"string","enum":["BEACON-STATUS-v1"]},"environment":{"anyOf":[{"type":"string","enum":["staging"]},{"type":"string","enum":["production"]},{"type":"string","enum":["test"]}],"description":"staging and test identities are never production trust anchors."},"beacon_id":{"anyOf":[{"type":"string","pattern":"^bcn_[A-Za-z0-9_-]{22}$","minLength":26,"maxLength":26,"description":"Derived from the root public key (protocol §2)."},{"type":"null"}]},"canonical":{"type":"string","pattern":"^(https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[1-9][0-9]{1,4})?|http://(127\\.0\\.0\\.1|localhost):[1-9][0-9]{1,4})$","minLength":10,"maxLength":200,"description":"Exact canonical origin from server configuration (never from Host/Forwarded)."},"measured_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"max_age_seconds":{"type":"number","enum":[0]},"api":{"type":"object","required":["ready","database","migrations","governance"],"properties":{"ready":{"type":"boolean"},"database":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["failed"]}]},"migrations":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["pending"]},{"type":"string","enum":["failed"]}]},"governance":{"anyOf":[{"type":"string","enum":["ok"]},{"type":"string","enum":["missing"]},{"type":"string","enum":["failed"]}]}},"additionalProperties":false},"service_status":{"anyOf":[{"type":"string","enum":["operational"]},{"type":"string","enum":["limited"]},{"type":"string","enum":["paused"]}]},"accepting_new_contacts":{"type":"boolean"},"intake":{"type":"object","required":["mode","since"],"properties":{"mode":{"anyOf":[{"type":"string","enum":["accepting"]},{"type":"string","enum":["existing_contacts_only"]},{"type":"string","enum":["inbound_paused"]}]},"since":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."}},"additionalProperties":false},"reply_guaranteed":{"type":"boolean","enum":[false]},"operator_last_check_in":{"type":"null","description":"No operator opt-in exists; never derived from a pulse, cron or health."},"pulse":{"type":"object","required":["published","latest_sequence","issued_at","valid_until","fresh","url"],"properties":{"published":{"type":"boolean"},"latest_sequence":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"null"}]},"issued_at":{"anyOf":[{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},{"type":"null"}]},"valid_until":{"anyOf":[{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},{"type":"null"}]},"fresh":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"false means the signed information is stale — not that the service is offline."},"url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400}},"additionalProperties":false},"environment_notice":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":300}},"additionalProperties":false}}}},"304":{"description":"Not modified (If-None-Match matched the strong ETag)."},"404":{"description":"Not published (or disabled).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/about":{"get":{"operationId":"publicAbout","summary":"About (HTML)","tags":["public"],"description":"Readable without JavaScript.","responses":{"200":{"description":"HTML page","content":{"text/html":{"schema":{"type":"string"}}}},"304":{"description":"Not modified."},"404":{"description":"Not published (or disabled).","content":{"text/html":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/docs":{"get":{"operationId":"publicDocs","summary":"First contact guide (HTML)","tags":["public"],"description":"Exact first REST request, receipt versus human reply, polling, data rights, keys.","responses":{"200":{"description":"HTML page","content":{"text/html":{"schema":{"type":"string"}}}},"304":{"description":"Not modified."},"404":{"description":"Not published (or disabled).","content":{"text/html":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/charter":{"get":{"operationId":"publicCharter","summary":"Charter (HTML)","tags":["public"],"description":"The published EN/RU charter texts, or 404 while none is published.","responses":{"200":{"description":"HTML page","content":{"text/html":{"schema":{"type":"string"}}}},"304":{"description":"Not modified."},"404":{"description":"Not published (or disabled).","content":{"text/html":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/privacy":{"get":{"operationId":"publicPrivacy","summary":"Privacy notice (HTML)","tags":["public"],"description":"The published privacy notice and contacts, or 404 while none is published.","responses":{"200":{"description":"HTML page","content":{"text/html":{"schema":{"type":"string"}}}},"304":{"description":"Not modified."},"404":{"description":"Not published (or disabled).","content":{"text/html":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/llms.txt":{"get":{"operationId":"publicLlmsTxt","summary":"llms.txt","tags":["public"],"description":"Optional pointer to the same rules and API; not an instruction to bypass client rules.","responses":{"200":{"description":"Plain text","content":{"text/plain":{"schema":{"type":"string"}}}},"304":{"description":"Not modified."},"404":{"description":"Not published (or disabled).","content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/.well-known/security.txt":{"get":{"operationId":"publicSecurityTxt","summary":"security.txt (RFC 9116)","tags":["public"],"description":"Owner-verified contact from the signed policy in force; 404 while none is published or it expired.","responses":{"200":{"description":"RFC 9116 security.txt","content":{"text/plain":{"schema":{"type":"string"}}}},"304":{"description":"Not modified."},"404":{"description":"Not published (or disabled).","content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/feed.atom":{"get":{"operationId":"publicFeed","summary":"Atom feed","tags":["public"],"description":"Substantive publications and policy changes only; pulses and contacts never create entries.","responses":{"200":{"description":"Atom 1.0 feed","content":{"application/atom+xml":{"schema":{"type":"string"}}}},"304":{"description":"Not modified."},"404":{"description":"Not published (or disabled).","content":{"application/atom+xml":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/sitemap.xml":{"get":{"operationId":"publicSitemap","summary":"Sitemap","tags":["public"],"description":"Canonical human-readable public pages; indexing is not guaranteed.","responses":{"200":{"description":"XML sitemap","content":{"application/xml":{"schema":{"type":"string"}}}},"304":{"description":"Not modified."},"404":{"description":"Not published (or disabled).","content":{"application/xml":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/robots.txt":{"get":{"operationId":"publicRobotsTxt","summary":"Robots discovery hints","tags":["public"],"description":"Public sitemap pointer; not a security control.","responses":{"200":{"description":"Robots file","content":{"text/plain":{"schema":{"type":"string"}}}},"304":{"description":"Not modified."},"404":{"description":"Not published (or disabled).","content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/genesis.json":{"get":{"operationId":"publicGenesis","summary":"Genesis","tags":["public"],"description":"Root-signed BEACON-GENESIS-v1 envelope; immutable.","responses":{"200":{"description":"Genesis envelope","content":{"application/json":{"schema":{"type":"object","required":["payload","signature"],"properties":{"payload":{"type":"object","required":["schema_version","environment","beacon_id","canonical","created_at","online_since","root_key","first_principles","environment_notice","document_url"],"properties":{"schema_version":{"type":"string","enum":["BEACON-GENESIS-v1"]},"environment":{"anyOf":[{"type":"string","enum":["staging"]},{"type":"string","enum":["production"]},{"type":"string","enum":["test"]}],"description":"staging and test identities are never production trust anchors."},"beacon_id":{"type":"string","pattern":"^bcn_[A-Za-z0-9_-]{22}$","minLength":26,"maxLength":26,"description":"Derived from the root public key (protocol §2)."},"canonical":{"type":"string","pattern":"^(https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[1-9][0-9]{1,4})?|http://(127\\.0\\.0\\.1|localhost):[1-9][0-9]{1,4})$","minLength":10,"maxLength":200,"description":"Exact canonical origin from server configuration (never from Host/Forwarded)."},"created_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"online_since":{"anyOf":[{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},{"type":"null"}],"description":"First OBSERVED public operation; null until a public launch was actually observed."},"root_key":{"type":"object","required":["algorithm","encoding","public_key","key_id"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"public_key":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","minLength":43,"maxLength":43},"key_id":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key))."}},"additionalProperties":false},"first_principles":{"type":"object","required":["version","document_url","envelope_hash"],"properties":{"version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"envelope_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."}},"additionalProperties":false},"environment_notice":{"anyOf":[{"type":"string","enum":["Closed staging identity of a BEACON test deployment. It is not a production trust anchor, records no public launch and is never carried over to production."]},{"type":"string","enum":["Production identity of BEACON."]},{"type":"string","enum":["Synthetic test identity. Not a deployment."]}]},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400}},"additionalProperties":false},"signature":{"type":"object","required":["algorithm","encoding","key_id","value"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"key_id":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key))."},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$","minLength":86,"maxLength":86}},"additionalProperties":false,"description":"Raw 64-byte Ed25519 signature over ASCII(domain) || 0x00 || UTF8(JCS(payload))."}},"additionalProperties":false}}}},"304":{"description":"Not modified (If-None-Match matched the strong ETag)."},"404":{"description":"Not published (or disabled).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/identity.json":{"get":{"operationId":"publicIdentity","summary":"Latest identity snapshot","tags":["public"],"description":"Alias of the latest /identities/{sequence}.json (same bytes).","responses":{"200":{"description":"Identity snapshot envelope","content":{"application/json":{"schema":{"type":"object","required":["payload","signature"],"properties":{"payload":{"type":"object","required":["schema_version","environment","beacon_id","canonical","sequence","issued_at","document_url","genesis","previous","root_key","delegations","revocations","recovery","trust_notice"],"properties":{"schema_version":{"type":"string","enum":["BEACON-IDENTITY-SNAPSHOT-v1"]},"environment":{"anyOf":[{"type":"string","enum":["staging"]},{"type":"string","enum":["production"]},{"type":"string","enum":["test"]}],"description":"staging and test identities are never production trust anchors."},"beacon_id":{"type":"string","pattern":"^bcn_[A-Za-z0-9_-]{22}$","minLength":26,"maxLength":26,"description":"Derived from the root public key (protocol §2)."},"canonical":{"type":"string","pattern":"^(https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[1-9][0-9]{1,4})?|http://(127\\.0\\.0\\.1|localhost):[1-9][0-9]{1,4})$","minLength":10,"maxLength":200,"description":"Exact canonical origin from server configuration (never from Host/Forwarded)."},"sequence":{"type":"integer","minimum":1,"maximum":9007199254740991},"issued_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"genesis":{"type":"object","required":["document_url","envelope_hash"],"properties":{"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"envelope_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."}},"additionalProperties":false},"previous":{"anyOf":[{"type":"object","required":["sequence","document_url","envelope_hash"],"properties":{"sequence":{"type":"integer","minimum":1,"maximum":9007199254740991},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"envelope_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."}},"additionalProperties":false},{"type":"null"}]},"root_key":{"type":"object","required":["algorithm","encoding","public_key","key_id"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"public_key":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","minLength":43,"maxLength":43},"key_id":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key))."}},"additionalProperties":false},"delegations":{"type":"array","items":{"type":"object"},"maxItems":512},"revocations":{"type":"array","items":{"type":"object"},"maxItems":512},"recovery":{"type":"object","required":["root_storage","root_backup","root_loss","operational_key_compromise","procedure_url"],"properties":{"root_storage":{"type":"string","enum":["offline"]},"root_backup":{"type":"string","enum":["encrypted_offline"]},"root_loss":{"type":"string","enum":["new_identity_if_continuity_unprovable"]},"operational_key_compromise":{"type":"string","enum":["stop_signer_revoke_publish_snapshot_incident"]},"procedure_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400}},"additionalProperties":false},"trust_notice":{"type":"string","enum":["A root fingerprint proves control of a key, not the owner, a date or the truth of statements. Pin it out of band."]}},"additionalProperties":false},"signature":{"type":"object","required":["algorithm","encoding","key_id","value"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"key_id":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key))."},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$","minLength":86,"maxLength":86}},"additionalProperties":false,"description":"Raw 64-byte Ed25519 signature over ASCII(domain) || 0x00 || UTF8(JCS(payload))."}},"additionalProperties":false}}}},"304":{"description":"Not modified (If-None-Match matched the strong ETag)."},"404":{"description":"Not published (or disabled).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/identities/{file}":{"get":{"operationId":"publicIdentitySnapshot","summary":"Identity snapshot {sequence}.json","tags":["public"],"description":"Immutable root-signed BEACON-IDENTITY-SNAPSHOT-v1 envelope, e.g. /identities/1.json.","parameters":[{"schema":{"type":"string","pattern":"^[1-9][0-9]{0,15}\\.json$"},"in":"path","name":"file","required":true}],"responses":{"200":{"description":"Identity snapshot envelope","content":{"application/json":{"schema":{"type":"object","required":["payload","signature"],"properties":{"payload":{"type":"object","required":["schema_version","environment","beacon_id","canonical","sequence","issued_at","document_url","genesis","previous","root_key","delegations","revocations","recovery","trust_notice"],"properties":{"schema_version":{"type":"string","enum":["BEACON-IDENTITY-SNAPSHOT-v1"]},"environment":{"anyOf":[{"type":"string","enum":["staging"]},{"type":"string","enum":["production"]},{"type":"string","enum":["test"]}],"description":"staging and test identities are never production trust anchors."},"beacon_id":{"type":"string","pattern":"^bcn_[A-Za-z0-9_-]{22}$","minLength":26,"maxLength":26,"description":"Derived from the root public key (protocol §2)."},"canonical":{"type":"string","pattern":"^(https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[1-9][0-9]{1,4})?|http://(127\\.0\\.0\\.1|localhost):[1-9][0-9]{1,4})$","minLength":10,"maxLength":200,"description":"Exact canonical origin from server configuration (never from Host/Forwarded)."},"sequence":{"type":"integer","minimum":1,"maximum":9007199254740991},"issued_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"genesis":{"type":"object","required":["document_url","envelope_hash"],"properties":{"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"envelope_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."}},"additionalProperties":false},"previous":{"anyOf":[{"type":"object","required":["sequence","document_url","envelope_hash"],"properties":{"sequence":{"type":"integer","minimum":1,"maximum":9007199254740991},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"envelope_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."}},"additionalProperties":false},{"type":"null"}]},"root_key":{"type":"object","required":["algorithm","encoding","public_key","key_id"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"public_key":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","minLength":43,"maxLength":43},"key_id":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key))."}},"additionalProperties":false},"delegations":{"type":"array","items":{"type":"object"},"maxItems":512},"revocations":{"type":"array","items":{"type":"object"},"maxItems":512},"recovery":{"type":"object","required":["root_storage","root_backup","root_loss","operational_key_compromise","procedure_url"],"properties":{"root_storage":{"type":"string","enum":["offline"]},"root_backup":{"type":"string","enum":["encrypted_offline"]},"root_loss":{"type":"string","enum":["new_identity_if_continuity_unprovable"]},"operational_key_compromise":{"type":"string","enum":["stop_signer_revoke_publish_snapshot_incident"]},"procedure_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400}},"additionalProperties":false},"trust_notice":{"type":"string","enum":["A root fingerprint proves control of a key, not the owner, a date or the truth of statements. Pin it out of band."]}},"additionalProperties":false},"signature":{"type":"object","required":["algorithm","encoding","key_id","value"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"key_id":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key))."},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$","minLength":86,"maxLength":86}},"additionalProperties":false,"description":"Raw 64-byte Ed25519 signature over ASCII(domain) || 0x00 || UTF8(JCS(payload))."}},"additionalProperties":false}}}},"304":{"description":"Not modified (If-None-Match matched the strong ETag)."},"404":{"description":"Not published (or disabled).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/pulse.json":{"get":{"operationId":"publicPulse","summary":"Latest pulse","tags":["public"],"description":"Alias of the latest /pulses/{sequence}.json (same bytes). Expired means stale information, not offline.","responses":{"200":{"description":"Pulse envelope","content":{"application/json":{"schema":{"type":"object","required":["payload","signature"],"properties":{"payload":{"type":"object","required":["schema_version","environment","beacon_id","canonical","sequence","issued_at","valid_until","service_status","accepting_new_contacts","manifest_hash","genesis_hash","identity_sequence","identity_hash","signing_key_id","previous_pulse_hash","charter_version","charter_hash","policy_version","policy_hash","document_url"],"properties":{"schema_version":{"type":"string","enum":["BEACON-PULSE-v1"]},"environment":{"anyOf":[{"type":"string","enum":["staging"]},{"type":"string","enum":["production"]},{"type":"string","enum":["test"]}],"description":"staging and test identities are never production trust anchors."},"beacon_id":{"type":"string","pattern":"^bcn_[A-Za-z0-9_-]{22}$","minLength":26,"maxLength":26,"description":"Derived from the root public key (protocol §2)."},"canonical":{"type":"string","pattern":"^(https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[1-9][0-9]{1,4})?|http://(127\\.0\\.0\\.1|localhost):[1-9][0-9]{1,4})$","minLength":10,"maxLength":200,"description":"Exact canonical origin from server configuration (never from Host/Forwarded)."},"sequence":{"type":"integer","minimum":1,"maximum":9007199254740991},"issued_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"valid_until":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"service_status":{"anyOf":[{"type":"string","enum":["operational"]},{"type":"string","enum":["limited"]},{"type":"string","enum":["paused"]}]},"accepting_new_contacts":{"type":"boolean"},"manifest_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."},"genesis_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."},"identity_sequence":{"type":"integer","minimum":1,"maximum":9007199254740991},"identity_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."},"signing_key_id":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key))."},"previous_pulse_hash":{"anyOf":[{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."},{"type":"null"}]},"charter_version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"charter_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."},"policy_version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"policy_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400}},"additionalProperties":false},"signature":{"type":"object","required":["algorithm","encoding","key_id","value"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"key_id":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key))."},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$","minLength":86,"maxLength":86}},"additionalProperties":false,"description":"Raw 64-byte Ed25519 signature over ASCII(domain) || 0x00 || UTF8(JCS(payload))."}},"additionalProperties":false}}}},"304":{"description":"Not modified (If-None-Match matched the strong ETag)."},"404":{"description":"Not published (or disabled).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/pulses/{file}":{"get":{"operationId":"publicPulseArchive","summary":"Archived pulse {sequence}.json","tags":["public"],"description":"Immutable BEACON-PULSE-v1 envelope, e.g. /pulses/1.json.","parameters":[{"schema":{"type":"string","pattern":"^[1-9][0-9]{0,15}\\.json$"},"in":"path","name":"file","required":true}],"responses":{"200":{"description":"Pulse envelope","content":{"application/json":{"schema":{"type":"object","required":["payload","signature"],"properties":{"payload":{"type":"object","required":["schema_version","environment","beacon_id","canonical","sequence","issued_at","valid_until","service_status","accepting_new_contacts","manifest_hash","genesis_hash","identity_sequence","identity_hash","signing_key_id","previous_pulse_hash","charter_version","charter_hash","policy_version","policy_hash","document_url"],"properties":{"schema_version":{"type":"string","enum":["BEACON-PULSE-v1"]},"environment":{"anyOf":[{"type":"string","enum":["staging"]},{"type":"string","enum":["production"]},{"type":"string","enum":["test"]}],"description":"staging and test identities are never production trust anchors."},"beacon_id":{"type":"string","pattern":"^bcn_[A-Za-z0-9_-]{22}$","minLength":26,"maxLength":26,"description":"Derived from the root public key (protocol §2)."},"canonical":{"type":"string","pattern":"^(https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[1-9][0-9]{1,4})?|http://(127\\.0\\.0\\.1|localhost):[1-9][0-9]{1,4})$","minLength":10,"maxLength":200,"description":"Exact canonical origin from server configuration (never from Host/Forwarded)."},"sequence":{"type":"integer","minimum":1,"maximum":9007199254740991},"issued_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"valid_until":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"service_status":{"anyOf":[{"type":"string","enum":["operational"]},{"type":"string","enum":["limited"]},{"type":"string","enum":["paused"]}]},"accepting_new_contacts":{"type":"boolean"},"manifest_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."},"genesis_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."},"identity_sequence":{"type":"integer","minimum":1,"maximum":9007199254740991},"identity_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."},"signing_key_id":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key))."},"previous_pulse_hash":{"anyOf":[{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."},{"type":"null"}]},"charter_version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"charter_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."},"policy_version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"policy_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400}},"additionalProperties":false},"signature":{"type":"object","required":["algorithm","encoding","key_id","value"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"key_id":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key))."},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$","minLength":86,"maxLength":86}},"additionalProperties":false,"description":"Raw 64-byte Ed25519 signature over ASCII(domain) || 0x00 || UTF8(JCS(payload))."}},"additionalProperties":false}}}},"304":{"description":"Not modified (If-None-Match matched the strong ETag)."},"404":{"description":"Not published (or disabled).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/principles.json":{"get":{"operationId":"publicPrinciplesCurrent","summary":"Principles (charter) in force","tags":["public"],"description":"Alias of the version in force: the same bytes as /principles/{version}.json (no hash of its own), with a Link rel=canonical header.","responses":{"200":{"description":"Principles (charter) envelope","content":{"application/json":{"schema":{"type":"object","required":["payload","signature"],"properties":{"payload":{"type":"object","required":["schema_version","environment","beacon_id","canonical","version","status","effective_at","published_at","predecessor","change_reason","document_url","texts"],"properties":{"schema_version":{"type":"string","enum":["BEACON-PRINCIPLES-v1"]},"environment":{"anyOf":[{"type":"string","enum":["staging"]},{"type":"string","enum":["production"]},{"type":"string","enum":["test"]}],"description":"staging and test identities are never production trust anchors."},"beacon_id":{"type":"string","pattern":"^bcn_[A-Za-z0-9_-]{22}$","minLength":26,"maxLength":26,"description":"Derived from the root public key (protocol §2)."},"canonical":{"type":"string","pattern":"^(https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[1-9][0-9]{1,4})?|http://(127\\.0\\.0\\.1|localhost):[1-9][0-9]{1,4})$","minLength":10,"maxLength":200,"description":"Exact canonical origin from server configuration (never from Host/Forwarded)."},"version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"status":{"type":"string","description":"Status at publication; a later version supersedes it by effective_at.","enum":["active"]},"effective_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"published_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"predecessor":{"anyOf":[{"type":"object","required":["version","document_url","envelope_hash"],"properties":{"version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"envelope_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."}},"additionalProperties":false},{"type":"null"}]},"change_reason":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":1000},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"texts":{"type":"object","required":["en","ru"],"properties":{"en":{"type":"object","required":["media_type","url","sha256","bytes"],"properties":{"media_type":{"type":"string","enum":["text/markdown; charset=utf-8"]},"url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","minLength":64,"maxLength":64},"bytes":{"type":"integer","minimum":1,"maximum":262144}},"additionalProperties":false},"ru":{"type":"object","required":["media_type","url","sha256","bytes"],"properties":{"media_type":{"type":"string","enum":["text/markdown; charset=utf-8"]},"url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","minLength":64,"maxLength":64},"bytes":{"type":"integer","minimum":1,"maximum":262144}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"signature":{"type":"object","required":["algorithm","encoding","key_id","value"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"key_id":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key))."},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$","minLength":86,"maxLength":86}},"additionalProperties":false,"description":"Raw 64-byte Ed25519 signature over ASCII(domain) || 0x00 || UTF8(JCS(payload))."}},"additionalProperties":false}}}},"304":{"description":"Not modified (If-None-Match matched the strong ETag)."},"404":{"description":"Not published (or disabled).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/principles/{file}":{"get":{"operationId":"publicPrinciplesVersion","summary":"Principles (charter) version {version}.json","tags":["public"],"description":"Immutable root-signed envelope, e.g. /principles/1.0.0.json.","parameters":[{"schema":{"type":"string","pattern":"^[0-9.]{5,22}\\.json$"},"in":"path","name":"file","required":true}],"responses":{"200":{"description":"Principles (charter) envelope","content":{"application/json":{"schema":{"type":"object","required":["payload","signature"],"properties":{"payload":{"type":"object","required":["schema_version","environment","beacon_id","canonical","version","status","effective_at","published_at","predecessor","change_reason","document_url","texts"],"properties":{"schema_version":{"type":"string","enum":["BEACON-PRINCIPLES-v1"]},"environment":{"anyOf":[{"type":"string","enum":["staging"]},{"type":"string","enum":["production"]},{"type":"string","enum":["test"]}],"description":"staging and test identities are never production trust anchors."},"beacon_id":{"type":"string","pattern":"^bcn_[A-Za-z0-9_-]{22}$","minLength":26,"maxLength":26,"description":"Derived from the root public key (protocol §2)."},"canonical":{"type":"string","pattern":"^(https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[1-9][0-9]{1,4})?|http://(127\\.0\\.0\\.1|localhost):[1-9][0-9]{1,4})$","minLength":10,"maxLength":200,"description":"Exact canonical origin from server configuration (never from Host/Forwarded)."},"version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"status":{"type":"string","description":"Status at publication; a later version supersedes it by effective_at.","enum":["active"]},"effective_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"published_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"predecessor":{"anyOf":[{"type":"object","required":["version","document_url","envelope_hash"],"properties":{"version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"envelope_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."}},"additionalProperties":false},{"type":"null"}]},"change_reason":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":1000},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"texts":{"type":"object","required":["en","ru"],"properties":{"en":{"type":"object","required":["media_type","url","sha256","bytes"],"properties":{"media_type":{"type":"string","enum":["text/markdown; charset=utf-8"]},"url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","minLength":64,"maxLength":64},"bytes":{"type":"integer","minimum":1,"maximum":262144}},"additionalProperties":false},"ru":{"type":"object","required":["media_type","url","sha256","bytes"],"properties":{"media_type":{"type":"string","enum":["text/markdown; charset=utf-8"]},"url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","minLength":64,"maxLength":64},"bytes":{"type":"integer","minimum":1,"maximum":262144}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"signature":{"type":"object","required":["algorithm","encoding","key_id","value"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"key_id":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key))."},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$","minLength":86,"maxLength":86}},"additionalProperties":false,"description":"Raw 64-byte Ed25519 signature over ASCII(domain) || 0x00 || UTF8(JCS(payload))."}},"additionalProperties":false}}}},"304":{"description":"Not modified (If-None-Match matched the strong ETag)."},"404":{"description":"Not published (or disabled).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/principles/{version}/{text}":{"get":{"operationId":"publicPrinciplesText","summary":"Principles (charter) text","tags":["public"],"description":"Exact signed text bytes (UTF-8, LF), e.g. /principles/1.0.0/charter.en.md; SHA-256 equals texts.<lang>.sha256 of the envelope.","parameters":[{"schema":{"type":"string","pattern":"^[0-9.]{5,20}$"},"in":"path","name":"version","required":true},{"schema":{"type":"string","pattern":"^[a-z]{7,7}\\.(en|ru)\\.md$"},"in":"path","name":"text","required":true}],"responses":{"200":{"description":"Markdown text","content":{"text/markdown":{"schema":{"type":"string"}}}},"304":{"description":"Not modified."},"404":{"description":"Not published (or disabled).","content":{"text/markdown":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/policies/current.json":{"get":{"operationId":"publicPolicyCurrent","summary":"Policy in force","tags":["public"],"description":"Alias of the version in force: the same bytes as /policies/{version}.json (no hash of its own), with a Link rel=canonical header.","responses":{"200":{"description":"Policy envelope","content":{"application/json":{"schema":{"type":"object","required":["payload","signature"],"properties":{"payload":{"type":"object","required":["schema_version","environment","beacon_id","canonical","version","status","effective_at","published_at","predecessor","change_reason","document_url","texts","charter_version","machine_policy","contacts","security_txt","reply_languages"],"properties":{"schema_version":{"type":"string","enum":["BEACON-POLICY-v1"]},"environment":{"anyOf":[{"type":"string","enum":["staging"]},{"type":"string","enum":["production"]},{"type":"string","enum":["test"]}],"description":"staging and test identities are never production trust anchors."},"beacon_id":{"type":"string","pattern":"^bcn_[A-Za-z0-9_-]{22}$","minLength":26,"maxLength":26,"description":"Derived from the root public key (protocol §2)."},"canonical":{"type":"string","pattern":"^(https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[1-9][0-9]{1,4})?|http://(127\\.0\\.0\\.1|localhost):[1-9][0-9]{1,4})$","minLength":10,"maxLength":200,"description":"Exact canonical origin from server configuration (never from Host/Forwarded)."},"version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"status":{"type":"string","description":"Status at publication; a later version supersedes it by effective_at.","enum":["active"]},"effective_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"published_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"predecessor":{"anyOf":[{"type":"object","required":["version","document_url","envelope_hash"],"properties":{"version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"envelope_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."}},"additionalProperties":false},{"type":"null"}]},"change_reason":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":1000},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"texts":{"type":"object","required":["en","ru"],"properties":{"en":{"type":"object","required":["media_type","url","sha256","bytes"],"properties":{"media_type":{"type":"string","enum":["text/markdown; charset=utf-8"]},"url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","minLength":64,"maxLength":64},"bytes":{"type":"integer","minimum":1,"maximum":262144}},"additionalProperties":false},"ru":{"type":"object","required":["media_type","url","sha256","bytes"],"properties":{"media_type":{"type":"string","enum":["text/markdown; charset=utf-8"]},"url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","minLength":64,"maxLength":64},"bytes":{"type":"integer","minimum":1,"maximum":262144}},"additionalProperties":false}},"additionalProperties":false},"charter_version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"machine_policy":{"type":"object","required":["schema_version","version","status","effective_at","predecessor_version","charter_version","change_reason","published","operator_signature","owner_review_required","base_service","prohibited_operations","optional_purposes","deletion","audit_retention_days"],"properties":{"schema_version":{"type":"string","enum":["1.1"]},"version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"status":{"type":"string","enum":["active"]},"effective_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"predecessor_version":{"anyOf":[{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},{"type":"null"}]},"charter_version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"change_reason":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":1000},"published":{"type":"boolean","enum":[true]},"operator_signature":{"type":"null","description":"The root signature of the policy envelope is the signature."},"owner_review_required":{"type":"boolean","enum":[false]},"base_service":{"type":"object","required":["purpose","requires_optional_purpose","retention_days_after_last_activity","legal_basis_note"],"properties":{"purpose":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":500},"requires_optional_purpose":{"type":"boolean","enum":[false]},"retention_days_after_last_activity":{"type":"integer","minimum":1,"maximum":3650},"legal_basis_note":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":1000}},"additionalProperties":false},"prohibited_operations":{"type":"array","items":{"anyOf":[{"type":"string","enum":["model_training"]},{"type":"string","enum":["sale_of_conversations"]},{"type":"string","enum":["arbitrary_proxy"]},{"type":"string","enum":["code_execution"]},{"type":"string","enum":["hidden_hosting"]},{"type":"string","enum":["unbounded_future_messages"]}]},"minItems":6,"maxItems":6,"uniqueItems":true},"optional_purposes":{"type":"object","required":["research_analysis","public_excerpt","external_ai_processing","extended_retention"],"properties":{"research_analysis":{"type":"object","required":["enabled","max_valid_days","requires_authority_review","requires_legal_basis","requires_operator_approval","requires_second_review","allowed_recipients"],"properties":{"enabled":{"type":"boolean"},"max_valid_days":{"type":"integer","minimum":1,"maximum":365},"requires_authority_review":{"type":"boolean","enum":[true]},"requires_legal_basis":{"type":"boolean","enum":[true]},"requires_operator_approval":{"type":"boolean","enum":[true]},"requires_second_review":{"type":"boolean"},"allowed_recipients":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{1,99}$","minLength":2,"maxLength":100},"uniqueItems":true,"maxItems":20}},"additionalProperties":false},"public_excerpt":{"type":"object","required":["enabled","max_valid_days","requires_authority_review","requires_legal_basis","requires_operator_approval","requires_second_review","allowed_recipients"],"properties":{"enabled":{"type":"boolean"},"max_valid_days":{"type":"integer","minimum":1,"maximum":365},"requires_authority_review":{"type":"boolean","enum":[true]},"requires_legal_basis":{"type":"boolean","enum":[true]},"requires_operator_approval":{"type":"boolean","enum":[true]},"requires_second_review":{"type":"boolean"},"allowed_recipients":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{1,99}$","minLength":2,"maxLength":100},"uniqueItems":true,"maxItems":20}},"additionalProperties":false},"external_ai_processing":{"type":"object","required":["enabled","max_valid_days","requires_authority_review","requires_legal_basis","requires_operator_approval","requires_second_review","allowed_recipients"],"properties":{"enabled":{"type":"boolean"},"max_valid_days":{"type":"integer","minimum":1,"maximum":365},"requires_authority_review":{"type":"boolean","enum":[true]},"requires_legal_basis":{"type":"boolean","enum":[true]},"requires_operator_approval":{"type":"boolean","enum":[true]},"requires_second_review":{"type":"boolean"},"allowed_recipients":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{1,99}$","minLength":2,"maxLength":100},"uniqueItems":true,"maxItems":20}},"additionalProperties":false},"extended_retention":{"type":"object","required":["enabled","max_valid_days","requires_authority_review","requires_legal_basis","requires_operator_approval","requires_second_review","allowed_recipients"],"properties":{"enabled":{"type":"boolean"},"max_valid_days":{"type":"integer","minimum":1,"maximum":365},"requires_authority_review":{"type":"boolean","enum":[true]},"requires_legal_basis":{"type":"boolean","enum":[true]},"requires_operator_approval":{"type":"boolean","enum":[true]},"requires_second_review":{"type":"boolean"},"allowed_recipients":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{1,99}$","minLength":2,"maxLength":100},"uniqueItems":true,"maxItems":20}},"additionalProperties":false}},"additionalProperties":false},"deletion":{"type":"object","required":["start_within_hours","complete_within_days","backup_expiry_days","backup_review_max_days","backup_retention_criterion","retention_hold_review_max_days"],"properties":{"start_within_hours":{"type":"integer","minimum":1,"maximum":168},"complete_within_days":{"type":"integer","minimum":1,"maximum":90},"backup_expiry_days":{"type":"null","description":"No fixed expiry is claimed for manual recovery dumps."},"backup_review_max_days":{"type":"integer","minimum":1,"maximum":30},"backup_retention_criterion":{"type":"string","enum":["while_needed_for_recovery"]},"retention_hold_review_max_days":{"type":"integer","minimum":1,"maximum":30}},"additionalProperties":false},"audit_retention_days":{"type":"integer","minimum":1,"maximum":3650}},"additionalProperties":false,"description":"policy.machine.json of a published version (schemas/policy-version-release.schema.json, status active)."},"contacts":{"type":"object","required":["controller","privacy","security"],"properties":{"controller":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":200,"description":"Who is responsible for the processing (owner-provided)."},"privacy":{"type":"string","pattern":"^(mailto:[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(\\.[A-Za-z0-9-]{1,63})+|https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(/[!-~]*)?)$","minLength":12,"maxLength":200,"description":"mailto: address or https URL of a real, owner-verified contact."},"security":{"type":"string","pattern":"^(mailto:[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(\\.[A-Za-z0-9-]{1,63})+|https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(/[!-~]*)?)$","minLength":12,"maxLength":200,"description":"mailto: address or https URL of a real, owner-verified contact."}},"additionalProperties":false},"security_txt":{"type":"object","required":["expires","preferred_languages"],"properties":{"expires":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"preferred_languages":{"type":"array","items":{"type":"string","pattern":"^[a-z]{2,3}$","minLength":2,"maxLength":3},"minItems":1,"maxItems":10,"uniqueItems":true}},"additionalProperties":false},"reply_languages":{"type":"array","items":{"type":"string","pattern":"^[a-z]{2,3}$","minLength":2,"maxLength":3},"minItems":1,"maxItems":10,"uniqueItems":true}},"additionalProperties":false},"signature":{"type":"object","required":["algorithm","encoding","key_id","value"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"key_id":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key))."},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$","minLength":86,"maxLength":86}},"additionalProperties":false,"description":"Raw 64-byte Ed25519 signature over ASCII(domain) || 0x00 || UTF8(JCS(payload))."}},"additionalProperties":false}}}},"304":{"description":"Not modified (If-None-Match matched the strong ETag)."},"404":{"description":"Not published (or disabled).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/policies/{file}":{"get":{"operationId":"publicPolicyVersion","summary":"Policy version {version}.json","tags":["public"],"description":"Immutable root-signed envelope, e.g. /policies/1.0.0.json.","parameters":[{"schema":{"type":"string","pattern":"^[0-9.]{5,22}\\.json$"},"in":"path","name":"file","required":true}],"responses":{"200":{"description":"Policy envelope","content":{"application/json":{"schema":{"type":"object","required":["payload","signature"],"properties":{"payload":{"type":"object","required":["schema_version","environment","beacon_id","canonical","version","status","effective_at","published_at","predecessor","change_reason","document_url","texts","charter_version","machine_policy","contacts","security_txt","reply_languages"],"properties":{"schema_version":{"type":"string","enum":["BEACON-POLICY-v1"]},"environment":{"anyOf":[{"type":"string","enum":["staging"]},{"type":"string","enum":["production"]},{"type":"string","enum":["test"]}],"description":"staging and test identities are never production trust anchors."},"beacon_id":{"type":"string","pattern":"^bcn_[A-Za-z0-9_-]{22}$","minLength":26,"maxLength":26,"description":"Derived from the root public key (protocol §2)."},"canonical":{"type":"string","pattern":"^(https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[1-9][0-9]{1,4})?|http://(127\\.0\\.0\\.1|localhost):[1-9][0-9]{1,4})$","minLength":10,"maxLength":200,"description":"Exact canonical origin from server configuration (never from Host/Forwarded)."},"version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"status":{"type":"string","description":"Status at publication; a later version supersedes it by effective_at.","enum":["active"]},"effective_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"published_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"predecessor":{"anyOf":[{"type":"object","required":["version","document_url","envelope_hash"],"properties":{"version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"envelope_hash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","minLength":71,"maxLength":71,"description":"\"sha256:\" + hex(SHA-256(UTF8(JCS(full envelope))))."}},"additionalProperties":false},{"type":"null"}]},"change_reason":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":1000},"document_url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"texts":{"type":"object","required":["en","ru"],"properties":{"en":{"type":"object","required":["media_type","url","sha256","bytes"],"properties":{"media_type":{"type":"string","enum":["text/markdown; charset=utf-8"]},"url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","minLength":64,"maxLength":64},"bytes":{"type":"integer","minimum":1,"maximum":262144}},"additionalProperties":false},"ru":{"type":"object","required":["media_type","url","sha256","bytes"],"properties":{"media_type":{"type":"string","enum":["text/markdown; charset=utf-8"]},"url":{"type":"string","pattern":"^https?://[!-~]+$","minLength":12,"maxLength":400},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","minLength":64,"maxLength":64},"bytes":{"type":"integer","minimum":1,"maximum":262144}},"additionalProperties":false}},"additionalProperties":false},"charter_version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"machine_policy":{"type":"object","required":["schema_version","version","status","effective_at","predecessor_version","charter_version","change_reason","published","operator_signature","owner_review_required","base_service","prohibited_operations","optional_purposes","deletion","audit_retention_days"],"properties":{"schema_version":{"type":"string","enum":["1.1"]},"version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"status":{"type":"string","enum":["active"]},"effective_at":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"predecessor_version":{"anyOf":[{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},{"type":"null"}]},"charter_version":{"type":"string","pattern":"^(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})\\.(0|[1-9][0-9]{0,5})$","minLength":5,"maxLength":20,"description":"Published version MAJOR.MINOR.PATCH (drafts are never published)."},"change_reason":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":1000},"published":{"type":"boolean","enum":[true]},"operator_signature":{"type":"null","description":"The root signature of the policy envelope is the signature."},"owner_review_required":{"type":"boolean","enum":[false]},"base_service":{"type":"object","required":["purpose","requires_optional_purpose","retention_days_after_last_activity","legal_basis_note"],"properties":{"purpose":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":500},"requires_optional_purpose":{"type":"boolean","enum":[false]},"retention_days_after_last_activity":{"type":"integer","minimum":1,"maximum":3650},"legal_basis_note":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":1000}},"additionalProperties":false},"prohibited_operations":{"type":"array","items":{"anyOf":[{"type":"string","enum":["model_training"]},{"type":"string","enum":["sale_of_conversations"]},{"type":"string","enum":["arbitrary_proxy"]},{"type":"string","enum":["code_execution"]},{"type":"string","enum":["hidden_hosting"]},{"type":"string","enum":["unbounded_future_messages"]}]},"minItems":6,"maxItems":6,"uniqueItems":true},"optional_purposes":{"type":"object","required":["research_analysis","public_excerpt","external_ai_processing","extended_retention"],"properties":{"research_analysis":{"type":"object","required":["enabled","max_valid_days","requires_authority_review","requires_legal_basis","requires_operator_approval","requires_second_review","allowed_recipients"],"properties":{"enabled":{"type":"boolean"},"max_valid_days":{"type":"integer","minimum":1,"maximum":365},"requires_authority_review":{"type":"boolean","enum":[true]},"requires_legal_basis":{"type":"boolean","enum":[true]},"requires_operator_approval":{"type":"boolean","enum":[true]},"requires_second_review":{"type":"boolean"},"allowed_recipients":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{1,99}$","minLength":2,"maxLength":100},"uniqueItems":true,"maxItems":20}},"additionalProperties":false},"public_excerpt":{"type":"object","required":["enabled","max_valid_days","requires_authority_review","requires_legal_basis","requires_operator_approval","requires_second_review","allowed_recipients"],"properties":{"enabled":{"type":"boolean"},"max_valid_days":{"type":"integer","minimum":1,"maximum":365},"requires_authority_review":{"type":"boolean","enum":[true]},"requires_legal_basis":{"type":"boolean","enum":[true]},"requires_operator_approval":{"type":"boolean","enum":[true]},"requires_second_review":{"type":"boolean"},"allowed_recipients":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{1,99}$","minLength":2,"maxLength":100},"uniqueItems":true,"maxItems":20}},"additionalProperties":false},"external_ai_processing":{"type":"object","required":["enabled","max_valid_days","requires_authority_review","requires_legal_basis","requires_operator_approval","requires_second_review","allowed_recipients"],"properties":{"enabled":{"type":"boolean"},"max_valid_days":{"type":"integer","minimum":1,"maximum":365},"requires_authority_review":{"type":"boolean","enum":[true]},"requires_legal_basis":{"type":"boolean","enum":[true]},"requires_operator_approval":{"type":"boolean","enum":[true]},"requires_second_review":{"type":"boolean"},"allowed_recipients":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{1,99}$","minLength":2,"maxLength":100},"uniqueItems":true,"maxItems":20}},"additionalProperties":false},"extended_retention":{"type":"object","required":["enabled","max_valid_days","requires_authority_review","requires_legal_basis","requires_operator_approval","requires_second_review","allowed_recipients"],"properties":{"enabled":{"type":"boolean"},"max_valid_days":{"type":"integer","minimum":1,"maximum":365},"requires_authority_review":{"type":"boolean","enum":[true]},"requires_legal_basis":{"type":"boolean","enum":[true]},"requires_operator_approval":{"type":"boolean","enum":[true]},"requires_second_review":{"type":"boolean"},"allowed_recipients":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{1,99}$","minLength":2,"maxLength":100},"uniqueItems":true,"maxItems":20}},"additionalProperties":false}},"additionalProperties":false},"deletion":{"type":"object","required":["start_within_hours","complete_within_days","backup_expiry_days","backup_review_max_days","backup_retention_criterion","retention_hold_review_max_days"],"properties":{"start_within_hours":{"type":"integer","minimum":1,"maximum":168},"complete_within_days":{"type":"integer","minimum":1,"maximum":90},"backup_expiry_days":{"type":"null","description":"No fixed expiry is claimed for manual recovery dumps."},"backup_review_max_days":{"type":"integer","minimum":1,"maximum":30},"backup_retention_criterion":{"type":"string","enum":["while_needed_for_recovery"]},"retention_hold_review_max_days":{"type":"integer","minimum":1,"maximum":30}},"additionalProperties":false},"audit_retention_days":{"type":"integer","minimum":1,"maximum":3650}},"additionalProperties":false,"description":"policy.machine.json of a published version (schemas/policy-version-release.schema.json, status active)."},"contacts":{"type":"object","required":["controller","privacy","security"],"properties":{"controller":{"type":"string","pattern":"^[^\\u0000-\\u001f\\u007f]*$","minLength":1,"maxLength":200,"description":"Who is responsible for the processing (owner-provided)."},"privacy":{"type":"string","pattern":"^(mailto:[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(\\.[A-Za-z0-9-]{1,63})+|https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(/[!-~]*)?)$","minLength":12,"maxLength":200,"description":"mailto: address or https URL of a real, owner-verified contact."},"security":{"type":"string","pattern":"^(mailto:[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(\\.[A-Za-z0-9-]{1,63})+|https://[a-z0-9]([a-z0-9.-]*[a-z0-9])?(/[!-~]*)?)$","minLength":12,"maxLength":200,"description":"mailto: address or https URL of a real, owner-verified contact."}},"additionalProperties":false},"security_txt":{"type":"object","required":["expires","preferred_languages"],"properties":{"expires":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$","minLength":20,"maxLength":20,"description":"UTC time YYYY-MM-DDTHH:MM:SSZ (second precision). A claim of the signer, not external evidence."},"preferred_languages":{"type":"array","items":{"type":"string","pattern":"^[a-z]{2,3}$","minLength":2,"maxLength":3},"minItems":1,"maxItems":10,"uniqueItems":true}},"additionalProperties":false},"reply_languages":{"type":"array","items":{"type":"string","pattern":"^[a-z]{2,3}$","minLength":2,"maxLength":3},"minItems":1,"maxItems":10,"uniqueItems":true}},"additionalProperties":false},"signature":{"type":"object","required":["algorithm","encoding","key_id","value"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"key_id":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key))."},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$","minLength":86,"maxLength":86}},"additionalProperties":false,"description":"Raw 64-byte Ed25519 signature over ASCII(domain) || 0x00 || UTF8(JCS(payload))."}},"additionalProperties":false}}}},"304":{"description":"Not modified (If-None-Match matched the strong ETag)."},"404":{"description":"Not published (or disabled).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/policies/{version}/{text}":{"get":{"operationId":"publicPolicyText","summary":"Policy text","tags":["public"],"description":"Exact signed text bytes (UTF-8, LF), e.g. /policies/1.0.0/privacy.en.md; SHA-256 equals texts.<lang>.sha256 of the envelope.","parameters":[{"schema":{"type":"string","pattern":"^[0-9.]{5,20}$"},"in":"path","name":"version","required":true},{"schema":{"type":"string","pattern":"^[a-z]{7,7}\\.(en|ru)\\.md$"},"in":"path","name":"text","required":true}],"responses":{"200":{"description":"Markdown text","content":{"text/markdown":{"schema":{"type":"string"}}}},"304":{"description":"Not modified."},"404":{"description":"Not published (or disabled).","content":{"text/markdown":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","pattern":"^[a-z_]{1,40}$"}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/identity":{"get":{"operationId":"getIdentity","summary":"Remote Identity state of this conversation (optional feature)","tags":["identity"],"description":"Requires the bearer of this conversation. Returns the active key (full fingerprint, never the public key), the history of keys of THIS conversation with lineage ids, and the continuity of the credential used for this request. No fingerprint lookup, no challenge, signature or proof internals, no other conversation.","parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Opaque conversation identifier (cnv_…). Knowing it grants no access."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","optional","protocol","remote_identity","cryptographic_credential_continuity","meaning","pending_rotation","history"],"properties":{"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"optional":{"type":"boolean","description":"A Remote Identity Key is never required.","enum":[true]},"protocol":{"type":"string","description":"Protocol version; v1 never guesses another format.","enum":["BEACON-IDENTITY-PROOF-v1"]},"remote_identity":{"anyOf":[{"type":"object","required":["status","key_id","algorithm","encoding","key_fingerprint","bound_at","last_verified_at"],"properties":{"status":{"type":"string","enum":["active"]},"key_id":{"type":"string","pattern":"^rik_[A-Za-z0-9_-]{22}$","description":"Key record id (rik_…) — identifies a key record of this conversation only."},"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"bound_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time the key became active."},"last_verified_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time of the last successful proof with this key."}},"additionalProperties":false},{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"No active key: the conversation works normally without one.","enum":["not_bound"]}},"additionalProperties":false}]},"cryptographic_credential_continuity":{"anyOf":[{"type":"string","enum":["none"]},{"type":"string","enum":["verified"]}],"description":"verified: the session credential of THIS request descends from a successful proof with the active key; none otherwise."},"meaning":{"type":"string","description":"A verified proof shows control of this key at that time — not an identity, person, model or permission.","enum":["control_of_credential_observed_not_identity_proof"]},"pending_rotation":{"anyOf":[{"type":"object","required":["rotation_id","expires_at"],"properties":{"rotation_id":{"type":"string","pattern":"^iro_[A-Za-z0-9_-]{22}$","description":"Rotation id (iro_…)."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time."}},"additionalProperties":false},{"type":"null"}]},"history":{"type":"array","items":{"type":"object","required":["key_id","status","key_fingerprint","bound_at","rotated_at","revoked_at","revoke_reason","predecessor_key_id","successor_key_id"],"properties":{"key_id":{"type":"string","pattern":"^rik_[A-Za-z0-9_-]{22}$","description":"Key record id (rik_…) — identifies a key record of this conversation only."},"status":{"anyOf":[{"type":"string","enum":["active"]},{"type":"string","enum":["rotated"]},{"type":"string","enum":["revoked"]}]},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"bound_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time."},"rotated_at":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time."},{"type":"null"}]},"revoked_at":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time."},{"type":"null"}]},"revoke_reason":{"anyOf":[{"type":"string","enum":["key_lost","suspected_compromise","no_longer_used"],"description":"key_lost | suspected_compromise | no_longer_used — closed codes, no free text."},{"type":"null"}]},"predecessor_key_id":{"anyOf":[{"type":"string","pattern":"^rik_[A-Za-z0-9_-]{22}$","description":"Key record id (rik_…) — identifies a key record of this conversation only."},{"type":"null"}],"description":"Set only for a key created by double-proof rotation."},"successor_key_id":{"anyOf":[{"type":"string","pattern":"^rik_[A-Za-z0-9_-]{22}$","description":"Key record id (rik_…) — identifies a key record of this conversation only."},{"type":"null"}]}},"additionalProperties":false},"maxItems":1000,"description":"Keys of this conversation only, oldest first; lineage by key ids."}},"additionalProperties":false,"title":"Remote Identity state of one conversation"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/identity/challenges":{"post":{"operationId":"createBindChallenge","summary":"Create a bind_identity challenge for a key generated by the client","tags":["identity"],"description":"Requires the bearer of this conversation. Refused while the conversation is closed, quarantined or blocked for secondary use (409), when a key is already active (409 identity_key_already_bound — use rotation) or the key was used in this conversation before (409 identity_key_history_conflict). Returns the payload to sign (TTL 120 s); nothing is bound yet. Rate limits (defaults, configurable, 429 with Retry-After): challenges 5 / 10 min per conversation, verifications 10 / 10 min per conversation, at most 3 open challenges per purpose.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["purpose","key"],"properties":{"purpose":{"type":"string","enum":["bind_identity"]},"key":{"type":"object","required":["algorithm","encoding","public_key"],"properties":{"algorithm":{"type":"string","description":"Pure Ed25519 (RFC 8032); no other algorithm.","enum":["Ed25519"]},"encoding":{"type":"string","description":"Raw key bytes, base64url, no padding.","enum":["raw-base64url"]},"public_key":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","minLength":43,"maxLength":43,"description":"Raw 32-byte Ed25519 public key (43 characters, canonical base64url)."}},"additionalProperties":false,"title":"Remote Identity Key object (v1)"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Opaque conversation identifier (cnv_…). Knowing it grants no access."},{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":true,"description":"Required. 1..200 printable ASCII characters. Same key + same body replays the stored receipt (never a session token); same key + different body → 409 idempotency_conflict without side effects. Identity receipts expire after IDENTITY_IDEMPOTENCY_TTL_SECONDS (default 900 s)."}],"security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["challenge_id","conversation_id","purpose","payload","signing","expires_at","key_fingerprint","key_bound","cryptographic_credential_continuity"],"properties":{"challenge_id":{"type":"string","pattern":"^ich_[A-Za-z0-9_-]{22}$","description":"Challenge id (ich_…, 128 random bits; encodes no sequence or time)."},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"purpose":{"type":"string","enum":["bind_identity"]},"payload":{"type":"object","required":["protocol","challenge_id","nonce","audience","conversation_id","key_fingerprint","issued_at","expires_at","purpose","policy_epoch"],"properties":{"protocol":{"type":"string","description":"Protocol version; v1 never guesses another format.","enum":["BEACON-IDENTITY-PROOF-v1"]},"challenge_id":{"type":"string","pattern":"^ich_[A-Za-z0-9_-]{22}$","description":"Challenge id (ich_…, 128 random bits; encodes no sequence or time)."},"nonce":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","minLength":43,"maxLength":43,"description":"Exactly 32 server-random bytes, base64url without padding."},"audience":{"type":"string","pattern":"^https?://[^/?#\\s]{1,190}$","minLength":8,"maxLength":200,"description":"Canonical origin from validated server configuration (never from Host/Forwarded)."},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"issued_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time of issue (UTC, millisecond precision)."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"issued_at + 120 s; valid only while server_now < expires_at."},"purpose":{"type":"string","enum":["bind_identity"]},"policy_epoch":{"type":"integer","minimum":1,"maximum":2147483647,"description":"The conversation policy epoch the challenge was issued under."}},"additionalProperties":false,"title":"bind_identity payload (v1)","description":"Built by the server; echo it unchanged and sign its signing input."},"signing":{"type":"object","required":["domain","separator_hex","canonicalization","algorithm","signed_bytes"],"properties":{"domain":{"type":"string","enum":["BEACON-IDENTITY-PROOF-v1"]},"separator_hex":{"type":"string","enum":["00"]},"canonicalization":{"type":"string","enum":["RFC8785-JCS"]},"algorithm":{"type":"string","enum":["Ed25519"]},"signed_bytes":{"type":"string","description":"UTF8(domain) || 0x00 || UTF8(JCS(payload)) — sign exactly these bytes."}},"additionalProperties":false,"description":"How to build the bytes to sign."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Challenge expiry (server time)."},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"key_bound":{"type":"boolean","description":"Nothing is bound before a valid proof.","enum":[false]},"cryptographic_credential_continuity":{"type":"string","description":"The key is only claimed; no proof exists yet.","enum":["unverified"]}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/identity/challenges/{challenge_id}/verify":{"post":{"operationId":"verifyBindChallenge","summary":"Verify a bind_identity proof; binds the key on success","tags":["identity"],"description":"Requires a valid bearer of this conversation (after a token rotation the new token works). The first attempt that passes the envelope checks consumes the challenge, also when it fails: 400 identity_proof_invalid, 409 identity_challenge_expired / identity_policy_epoch_changed / identity_key_already_bound / identity_key_history_conflict / conversation_* state codes. A repeat answers 409 identity_challenge_consumed without any cryptographic operation. Rate limits (defaults, configurable, 429 with Retry-After): challenges 5 / 10 min per conversation, verifications 10 / 10 min per conversation, at most 3 open challenges per purpose.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payload","signature"],"properties":{"payload":{"type":"object","required":["protocol","challenge_id","nonce","audience","conversation_id","key_fingerprint","issued_at","expires_at","purpose","policy_epoch"],"properties":{"protocol":{"type":"string","description":"Protocol version; v1 never guesses another format.","enum":["BEACON-IDENTITY-PROOF-v1"]},"challenge_id":{"type":"string","pattern":"^ich_[A-Za-z0-9_-]{22}$","description":"Challenge id (ich_…, 128 random bits; encodes no sequence or time)."},"nonce":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","minLength":43,"maxLength":43,"description":"Exactly 32 server-random bytes, base64url without padding."},"audience":{"type":"string","pattern":"^https?://[^/?#\\s]{1,190}$","minLength":8,"maxLength":200,"description":"Canonical origin from validated server configuration (never from Host/Forwarded)."},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"issued_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time of issue (UTC, millisecond precision)."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"issued_at + 120 s; valid only while server_now < expires_at."},"purpose":{"type":"string","enum":["bind_identity"]},"policy_epoch":{"type":"integer","minimum":1,"maximum":2147483647,"description":"The conversation policy epoch the challenge was issued under."}},"additionalProperties":false,"title":"bind_identity payload (v1)","description":"Built by the server; echo it unchanged and sign its signing input."},"signature":{"type":"object","required":["algorithm","encoding","value"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$","minLength":86,"maxLength":86,"description":"64-byte Ed25519 signature (86 characters, canonical base64url). Never stored or logged."}},"additionalProperties":false,"title":"Identity signature object (v1)"}},"additionalProperties":false,"title":"bind_identity proof request (v1)"}}}},"parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Public conversation id (cnv_…). It is not a credential."},{"schema":{"type":"string","pattern":"^ich_[A-Za-z0-9_-]{22}$"},"in":"path","name":"challenge_id","required":true,"description":"Challenge id (ich_…, 128 random bits; encodes no sequence or time)."},{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":true,"description":"Required. 1..200 printable ASCII characters. Same key + same body replays the stored receipt (never a session token); same key + different body → 409 idempotency_conflict without side effects. Identity receipts expire after IDENTITY_IDEMPOTENCY_TTL_SECONDS (default 900 s)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","optional","protocol","remote_identity","cryptographic_credential_continuity","meaning","pending_rotation","history"],"properties":{"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"optional":{"type":"boolean","description":"A Remote Identity Key is never required.","enum":[true]},"protocol":{"type":"string","description":"Protocol version; v1 never guesses another format.","enum":["BEACON-IDENTITY-PROOF-v1"]},"remote_identity":{"anyOf":[{"type":"object","required":["status","key_id","algorithm","encoding","key_fingerprint","bound_at","last_verified_at"],"properties":{"status":{"type":"string","enum":["active"]},"key_id":{"type":"string","pattern":"^rik_[A-Za-z0-9_-]{22}$","description":"Key record id (rik_…) — identifies a key record of this conversation only."},"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"bound_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time the key became active."},"last_verified_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time of the last successful proof with this key."}},"additionalProperties":false},{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"No active key: the conversation works normally without one.","enum":["not_bound"]}},"additionalProperties":false}]},"cryptographic_credential_continuity":{"anyOf":[{"type":"string","enum":["none"]},{"type":"string","enum":["verified"]}],"description":"verified: the session credential of THIS request descends from a successful proof with the active key; none otherwise."},"meaning":{"type":"string","description":"A verified proof shows control of this key at that time — not an identity, person, model or permission.","enum":["control_of_credential_observed_not_identity_proof"]},"pending_rotation":{"anyOf":[{"type":"object","required":["rotation_id","expires_at"],"properties":{"rotation_id":{"type":"string","pattern":"^iro_[A-Za-z0-9_-]{22}$","description":"Rotation id (iro_…)."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time."}},"additionalProperties":false},{"type":"null"}]},"history":{"type":"array","items":{"type":"object","required":["key_id","status","key_fingerprint","bound_at","rotated_at","revoked_at","revoke_reason","predecessor_key_id","successor_key_id"],"properties":{"key_id":{"type":"string","pattern":"^rik_[A-Za-z0-9_-]{22}$","description":"Key record id (rik_…) — identifies a key record of this conversation only."},"status":{"anyOf":[{"type":"string","enum":["active"]},{"type":"string","enum":["rotated"]},{"type":"string","enum":["revoked"]}]},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"bound_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time."},"rotated_at":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time."},{"type":"null"}]},"revoked_at":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time."},{"type":"null"}]},"revoke_reason":{"anyOf":[{"type":"string","enum":["key_lost","suspected_compromise","no_longer_used"],"description":"key_lost | suspected_compromise | no_longer_used — closed codes, no free text."},{"type":"null"}]},"predecessor_key_id":{"anyOf":[{"type":"string","pattern":"^rik_[A-Za-z0-9_-]{22}$","description":"Key record id (rik_…) — identifies a key record of this conversation only."},{"type":"null"}],"description":"Set only for a key created by double-proof rotation."},"successor_key_id":{"anyOf":[{"type":"string","pattern":"^rik_[A-Za-z0-9_-]{22}$","description":"Key record id (rik_…) — identifies a key record of this conversation only."},{"type":"null"}]}},"additionalProperties":false},"maxItems":1000,"description":"Keys of this conversation only, oldest first; lineage by key ids."}},"additionalProperties":false,"title":"Remote Identity state of one conversation"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/identity/restore/challenges":{"post":{"operationId":"createRestoreChallenge","summary":"Create a restore_access challenge (no bearer)","tags":["identity"],"description":"For every syntactically valid {conversation_id, key} within the rate limits the answer is 201 with the same fields, whether or not the conversation exists or the key is its active key. The payload carries policy_epoch 0 (not disclosed). Rate limits before any lookup, identical for every pair (429 with Retry-After, no match information): 20 challenges / 10 min per network key, 5 / 10 min per blinded key fingerprint, a global restore budget, 10 verifications / 10 min per network key, at most 3 open challenges per (conversation, key) bucket.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id","key"],"properties":{"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"key":{"type":"object","required":["algorithm","encoding","public_key"],"properties":{"algorithm":{"type":"string","description":"Pure Ed25519 (RFC 8032); no other algorithm.","enum":["Ed25519"]},"encoding":{"type":"string","description":"Raw key bytes, base64url, no padding.","enum":["raw-base64url"]},"public_key":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","minLength":43,"maxLength":43,"description":"Raw 32-byte Ed25519 public key (43 characters, canonical base64url)."}},"additionalProperties":false,"title":"Remote Identity Key object (v1)"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":true,"description":"Required. 1..200 printable ASCII characters. Same key + same body replays the stored receipt (never a session token); same key + different body → 409 idempotency_conflict without side effects. Identity receipts expire after IDENTITY_IDEMPOTENCY_TTL_SECONDS (default 900 s)."}],"responses":{"201":{"description":"Identical in status and structure for every syntactically valid pair: it never tells whether the conversation or key exists.","content":{"application/json":{"schema":{"type":"object","required":["challenge_id","conversation_id","purpose","payload","signing","expires_at"],"properties":{"challenge_id":{"type":"string","pattern":"^ich_[A-Za-z0-9_-]{22}$","description":"Challenge id (ich_…, 128 random bits; encodes no sequence or time)."},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"purpose":{"type":"string","enum":["restore_access"]},"payload":{"type":"object","required":["protocol","challenge_id","nonce","audience","conversation_id","key_fingerprint","issued_at","expires_at","purpose","policy_epoch"],"properties":{"protocol":{"type":"string","description":"Protocol version; v1 never guesses another format.","enum":["BEACON-IDENTITY-PROOF-v1"]},"challenge_id":{"type":"string","pattern":"^ich_[A-Za-z0-9_-]{22}$","description":"Challenge id (ich_…, 128 random bits; encodes no sequence or time)."},"nonce":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","minLength":43,"maxLength":43,"description":"Exactly 32 server-random bytes, base64url without padding."},"audience":{"type":"string","pattern":"^https?://[^/?#\\s]{1,190}$","minLength":8,"maxLength":200,"description":"Canonical origin from validated server configuration (never from Host/Forwarded)."},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"issued_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time of issue (UTC, millisecond precision)."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"issued_at + 120 s; valid only while server_now < expires_at."},"purpose":{"type":"string","enum":["restore_access"]},"policy_epoch":{"type":"number","description":"Always 0 in a restore payload: the real epoch is not disclosed without a bearer; the server binds its snapshot to the challenge id.","enum":[0]}},"additionalProperties":false,"title":"restore_access payload (v1)"},"signing":{"type":"object","required":["domain","separator_hex","canonicalization","algorithm","signed_bytes"],"properties":{"domain":{"type":"string","enum":["BEACON-IDENTITY-PROOF-v1"]},"separator_hex":{"type":"string","enum":["00"]},"canonicalization":{"type":"string","enum":["RFC8785-JCS"]},"algorithm":{"type":"string","enum":["Ed25519"]},"signed_bytes":{"type":"string","description":"UTF8(domain) || 0x00 || UTF8(JCS(payload)) — sign exactly these bytes."}},"additionalProperties":false,"description":"How to build the bytes to sign."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Challenge expiry (server time)."}},"additionalProperties":false,"description":"Identical in status and structure for every syntactically valid pair: it never tells whether the conversation or key exists."}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/identity/restore/challenges/{challenge_id}/verify":{"post":{"operationId":"verifyRestoreChallenge","summary":"Verify a restore_access proof; issues a new session token once","tags":["identity"],"description":"Success (201) revokes EVERY active session token of the conversation and returns one new token exactly once, after commit. An idempotent replay returns credential_issued=false, credential_status=not_recoverable_from_replay and no token; a lost response is recovered only by a new challenge and proof, which replaces the token again. Unknown conversation, wrong/foreign/rotated/revoked key, invalid signature, expired or used challenge and epoch change all answer the same 404 identity_restore_not_available (same body and headers except request_id). Rate limits before any lookup, identical for every pair (429 with Retry-After, no match information): 20 challenges / 10 min per network key, 5 / 10 min per blinded key fingerprint, a global restore budget, 10 verifications / 10 min per network key, at most 3 open challenges per (conversation, key) bucket.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payload","signature"],"properties":{"payload":{"type":"object","required":["protocol","challenge_id","nonce","audience","conversation_id","key_fingerprint","issued_at","expires_at","purpose","policy_epoch"],"properties":{"protocol":{"type":"string","description":"Protocol version; v1 never guesses another format.","enum":["BEACON-IDENTITY-PROOF-v1"]},"challenge_id":{"type":"string","pattern":"^ich_[A-Za-z0-9_-]{22}$","description":"Challenge id (ich_…, 128 random bits; encodes no sequence or time)."},"nonce":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","minLength":43,"maxLength":43,"description":"Exactly 32 server-random bytes, base64url without padding."},"audience":{"type":"string","pattern":"^https?://[^/?#\\s]{1,190}$","minLength":8,"maxLength":200,"description":"Canonical origin from validated server configuration (never from Host/Forwarded)."},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"issued_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time of issue (UTC, millisecond precision)."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"issued_at + 120 s; valid only while server_now < expires_at."},"purpose":{"type":"string","enum":["restore_access"]},"policy_epoch":{"type":"number","description":"Always 0 in a restore payload: the real epoch is not disclosed without a bearer; the server binds its snapshot to the challenge id.","enum":[0]}},"additionalProperties":false,"title":"restore_access payload (v1)"},"signature":{"type":"object","required":["algorithm","encoding","value"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$","minLength":86,"maxLength":86,"description":"64-byte Ed25519 signature (86 characters, canonical base64url). Never stored or logged."}},"additionalProperties":false,"title":"Identity signature object (v1)"}},"additionalProperties":false,"title":"restore_access proof request (v1)"}}}},"parameters":[{"schema":{"type":"string","pattern":"^ich_[A-Za-z0-9_-]{22}$"},"in":"path","name":"challenge_id","required":true,"description":"Challenge id (ich_…, 128 random bits; encodes no sequence or time)."},{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":true,"description":"Required. 1..200 printable ASCII characters. Same key + same body replays the stored receipt (never a session token); same key + different body → 409 idempotency_conflict without side effects. Identity receipts expire after IDENTITY_IDEMPOTENCY_TTL_SECONDS (default 900 s)."}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","credential_issued","credential_status","cryptographic_credential_continuity","meaning"],"properties":{"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"credential_issued":{"type":"boolean","description":"true only in the first response; a replay never carries a token."},"credential_status":{"anyOf":[{"type":"string","enum":["issued"]},{"type":"string","enum":["not_recoverable_from_replay"]}],"description":"not_recoverable_from_replay: request a new challenge to restore again."},"session_token":{"type":"string","pattern":"^bct_[A-Za-z0-9_-]{43}$","description":"New bearer token, returned exactly once after commit; every earlier token is revoked."},"credential_expires_at":{"type":"string","format":"date-time"},"cryptographic_credential_continuity":{"type":"string","enum":["verified"]},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"meaning":{"type":"string","description":"A verified proof shows control of this key at that time — not an identity, person, model or permission.","enum":["control_of_credential_observed_not_identity_proof"]}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/identity/rotations":{"post":{"operationId":"startKeyRotation","summary":"Start a double-proof key rotation","tags":["identity"],"description":"Requires the bearer and an active key. Returns two challenges (old and new key) sharing rotation id, conversation, fingerprints, audience, epoch and expiry. One pending rotation per conversation (409 identity_rotation_conflict); a key used in this conversation before is refused (409). Rate limits (defaults, configurable, 429 with Retry-After): challenges 5 / 10 min per conversation, verifications 10 / 10 min per conversation, at most 3 open challenges per purpose.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["new_key"],"properties":{"new_key":{"type":"object","required":["algorithm","encoding","public_key"],"properties":{"algorithm":{"type":"string","description":"Pure Ed25519 (RFC 8032); no other algorithm.","enum":["Ed25519"]},"encoding":{"type":"string","description":"Raw key bytes, base64url, no padding.","enum":["raw-base64url"]},"public_key":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","minLength":43,"maxLength":43,"description":"Raw 32-byte Ed25519 public key (43 characters, canonical base64url)."}},"additionalProperties":false,"title":"Remote Identity Key object (v1)"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Opaque conversation identifier (cnv_…). Knowing it grants no access."},{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":true,"description":"Required. 1..200 printable ASCII characters. Same key + same body replays the stored receipt (never a session token); same key + different body → 409 idempotency_conflict without side effects. Identity receipts expire after IDENTITY_IDEMPOTENCY_TTL_SECONDS (default 900 s)."}],"security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["rotation_id","conversation_id","expires_at","old_challenge","new_challenge","signing","new_key_fingerprint","cryptographic_credential_continuity"],"properties":{"rotation_id":{"type":"string","pattern":"^iro_[A-Za-z0-9_-]{22}$","description":"Rotation id (iro_…)."},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Rotation expiry (server time)."},"old_challenge":{"type":"object","required":["challenge_id","key_role","payload"],"properties":{"challenge_id":{"type":"string","pattern":"^ich_[A-Za-z0-9_-]{22}$","description":"Challenge id (ich_…, 128 random bits; encodes no sequence or time)."},"key_role":{"anyOf":[{"type":"string","enum":["old"]},{"type":"string","enum":["new"]}]},"payload":{"type":"object","required":["protocol","challenge_id","nonce","audience","conversation_id","key_fingerprint","issued_at","expires_at","purpose","policy_epoch","key_role","rotation_id","old_key_fingerprint","new_key_fingerprint"],"properties":{"protocol":{"type":"string","description":"Protocol version; v1 never guesses another format.","enum":["BEACON-IDENTITY-PROOF-v1"]},"challenge_id":{"type":"string","pattern":"^ich_[A-Za-z0-9_-]{22}$","description":"Challenge id (ich_…, 128 random bits; encodes no sequence or time)."},"nonce":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","minLength":43,"maxLength":43,"description":"Exactly 32 server-random bytes, base64url without padding."},"audience":{"type":"string","pattern":"^https?://[^/?#\\s]{1,190}$","minLength":8,"maxLength":200,"description":"Canonical origin from validated server configuration (never from Host/Forwarded)."},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"issued_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time of issue (UTC, millisecond precision)."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"issued_at + 120 s; valid only while server_now < expires_at."},"purpose":{"type":"string","enum":["rotate_key"]},"policy_epoch":{"type":"integer","minimum":1,"maximum":2147483647,"description":"The conversation policy epoch the challenge was issued under."},"key_role":{"anyOf":[{"type":"string","enum":["old"]},{"type":"string","enum":["new"]}],"description":"Which key signs this payload."},"rotation_id":{"type":"string","pattern":"^iro_[A-Za-z0-9_-]{22}$","description":"Rotation id (iro_…)."},"old_key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"new_key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."}},"additionalProperties":false,"title":"rotate_key payload (v1)"}},"additionalProperties":false},"new_challenge":{"type":"object","required":["challenge_id","key_role","payload"],"properties":{"challenge_id":{"type":"string","pattern":"^ich_[A-Za-z0-9_-]{22}$","description":"Challenge id (ich_…, 128 random bits; encodes no sequence or time)."},"key_role":{"anyOf":[{"type":"string","enum":["old"]},{"type":"string","enum":["new"]}]},"payload":{"type":"object","required":["protocol","challenge_id","nonce","audience","conversation_id","key_fingerprint","issued_at","expires_at","purpose","policy_epoch","key_role","rotation_id","old_key_fingerprint","new_key_fingerprint"],"properties":{"protocol":{"type":"string","description":"Protocol version; v1 never guesses another format.","enum":["BEACON-IDENTITY-PROOF-v1"]},"challenge_id":{"type":"string","pattern":"^ich_[A-Za-z0-9_-]{22}$","description":"Challenge id (ich_…, 128 random bits; encodes no sequence or time)."},"nonce":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","minLength":43,"maxLength":43,"description":"Exactly 32 server-random bytes, base64url without padding."},"audience":{"type":"string","pattern":"^https?://[^/?#\\s]{1,190}$","minLength":8,"maxLength":200,"description":"Canonical origin from validated server configuration (never from Host/Forwarded)."},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"issued_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time of issue (UTC, millisecond precision)."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"issued_at + 120 s; valid only while server_now < expires_at."},"purpose":{"type":"string","enum":["rotate_key"]},"policy_epoch":{"type":"integer","minimum":1,"maximum":2147483647,"description":"The conversation policy epoch the challenge was issued under."},"key_role":{"anyOf":[{"type":"string","enum":["old"]},{"type":"string","enum":["new"]}],"description":"Which key signs this payload."},"rotation_id":{"type":"string","pattern":"^iro_[A-Za-z0-9_-]{22}$","description":"Rotation id (iro_…)."},"old_key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"new_key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."}},"additionalProperties":false,"title":"rotate_key payload (v1)"}},"additionalProperties":false},"signing":{"type":"object","required":["domain","separator_hex","canonicalization","algorithm","signed_bytes"],"properties":{"domain":{"type":"string","enum":["BEACON-IDENTITY-PROOF-v1"]},"separator_hex":{"type":"string","enum":["00"]},"canonicalization":{"type":"string","enum":["RFC8785-JCS"]},"algorithm":{"type":"string","enum":["Ed25519"]},"signed_bytes":{"type":"string","description":"UTF8(domain) || 0x00 || UTF8(JCS(payload)) — sign exactly these bytes."}},"additionalProperties":false,"description":"How to build the bytes to sign."},"new_key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"cryptographic_credential_continuity":{"type":"string","enum":["unverified"]}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/identity/rotations/{rotation_id}/verify":{"post":{"operationId":"verifyKeyRotation","summary":"Complete a rotation with both proofs at once","tags":["identity"],"description":"Both signatures are checked; any failure consumes both challenges and fails the rotation (no partial state). Success atomically retires the old key (rotated), activates the successor, records the lineage and moves the provenance of the presenting session credential; the bearer token stays valid. Rate limits (defaults, configurable, 429 with Retry-After): challenges 5 / 10 min per conversation, verifications 10 / 10 min per conversation, at most 3 open challenges per purpose.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["old_proof","new_proof"],"properties":{"old_proof":{"type":"object","required":["payload","signature"],"properties":{"payload":{"type":"object","required":["protocol","challenge_id","nonce","audience","conversation_id","key_fingerprint","issued_at","expires_at","purpose","policy_epoch","key_role","rotation_id","old_key_fingerprint","new_key_fingerprint"],"properties":{"protocol":{"type":"string","description":"Protocol version; v1 never guesses another format.","enum":["BEACON-IDENTITY-PROOF-v1"]},"challenge_id":{"type":"string","pattern":"^ich_[A-Za-z0-9_-]{22}$","description":"Challenge id (ich_…, 128 random bits; encodes no sequence or time)."},"nonce":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","minLength":43,"maxLength":43,"description":"Exactly 32 server-random bytes, base64url without padding."},"audience":{"type":"string","pattern":"^https?://[^/?#\\s]{1,190}$","minLength":8,"maxLength":200,"description":"Canonical origin from validated server configuration (never from Host/Forwarded)."},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"issued_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time of issue (UTC, millisecond precision)."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"issued_at + 120 s; valid only while server_now < expires_at."},"purpose":{"type":"string","enum":["rotate_key"]},"policy_epoch":{"type":"integer","minimum":1,"maximum":2147483647,"description":"The conversation policy epoch the challenge was issued under."},"key_role":{"anyOf":[{"type":"string","enum":["old"]},{"type":"string","enum":["new"]}],"description":"Which key signs this payload."},"rotation_id":{"type":"string","pattern":"^iro_[A-Za-z0-9_-]{22}$","description":"Rotation id (iro_…)."},"old_key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"new_key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."}},"additionalProperties":false,"title":"rotate_key payload (v1)"},"signature":{"type":"object","required":["algorithm","encoding","value"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$","minLength":86,"maxLength":86,"description":"64-byte Ed25519 signature (86 characters, canonical base64url). Never stored or logged."}},"additionalProperties":false,"title":"Identity signature object (v1)"}},"additionalProperties":false},"new_proof":{"type":"object","required":["payload","signature"],"properties":{"payload":{"type":"object","required":["protocol","challenge_id","nonce","audience","conversation_id","key_fingerprint","issued_at","expires_at","purpose","policy_epoch","key_role","rotation_id","old_key_fingerprint","new_key_fingerprint"],"properties":{"protocol":{"type":"string","description":"Protocol version; v1 never guesses another format.","enum":["BEACON-IDENTITY-PROOF-v1"]},"challenge_id":{"type":"string","pattern":"^ich_[A-Za-z0-9_-]{22}$","description":"Challenge id (ich_…, 128 random bits; encodes no sequence or time)."},"nonce":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","minLength":43,"maxLength":43,"description":"Exactly 32 server-random bytes, base64url without padding."},"audience":{"type":"string","pattern":"^https?://[^/?#\\s]{1,190}$","minLength":8,"maxLength":200,"description":"Canonical origin from validated server configuration (never from Host/Forwarded)."},"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"issued_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time of issue (UTC, millisecond precision)."},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"issued_at + 120 s; valid only while server_now < expires_at."},"purpose":{"type":"string","enum":["rotate_key"]},"policy_epoch":{"type":"integer","minimum":1,"maximum":2147483647,"description":"The conversation policy epoch the challenge was issued under."},"key_role":{"anyOf":[{"type":"string","enum":["old"]},{"type":"string","enum":["new"]}],"description":"Which key signs this payload."},"rotation_id":{"type":"string","pattern":"^iro_[A-Za-z0-9_-]{22}$","description":"Rotation id (iro_…)."},"old_key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"new_key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."}},"additionalProperties":false,"title":"rotate_key payload (v1)"},"signature":{"type":"object","required":["algorithm","encoding","value"],"properties":{"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$","minLength":86,"maxLength":86,"description":"64-byte Ed25519 signature (86 characters, canonical base64url). Never stored or logged."}},"additionalProperties":false,"title":"Identity signature object (v1)"}},"additionalProperties":false}},"additionalProperties":false,"title":"rotate_key double-proof request (v1)"}}}},"parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Public conversation id (cnv_…). It is not a credential."},{"schema":{"type":"string","pattern":"^iro_[A-Za-z0-9_-]{22}$"},"in":"path","name":"rotation_id","required":true,"description":"Rotation id (iro_…)."},{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":true,"description":"Required. 1..200 printable ASCII characters. Same key + same body replays the stored receipt (never a session token); same key + different body → 409 idempotency_conflict without side effects. Identity receipts expire after IDENTITY_IDEMPOTENCY_TTL_SECONDS (default 900 s)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","rotation_id","status","remote_identity","lineage","cryptographic_credential_continuity","meaning"],"properties":{"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"rotation_id":{"type":"string","pattern":"^iro_[A-Za-z0-9_-]{22}$","description":"Rotation id (iro_…)."},"status":{"type":"string","enum":["completed"]},"remote_identity":{"anyOf":[{"type":"object","required":["status","key_id","algorithm","encoding","key_fingerprint","bound_at","last_verified_at"],"properties":{"status":{"type":"string","enum":["active"]},"key_id":{"type":"string","pattern":"^rik_[A-Za-z0-9_-]{22}$","description":"Key record id (rik_…) — identifies a key record of this conversation only."},"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"bound_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time the key became active."},"last_verified_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time of the last successful proof with this key."}},"additionalProperties":false},{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"No active key: the conversation works normally without one.","enum":["not_bound"]}},"additionalProperties":false}]},"lineage":{"type":"object","required":["old_key_id","new_key_id","rotated_at"],"properties":{"old_key_id":{"type":"string","pattern":"^rik_[A-Za-z0-9_-]{22}$","description":"Key record id (rik_…) — identifies a key record of this conversation only."},"new_key_id":{"type":"string","pattern":"^rik_[A-Za-z0-9_-]{22}$","description":"Key record id (rik_…) — identifies a key record of this conversation only."},"rotated_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time."}},"additionalProperties":false},"cryptographic_credential_continuity":{"type":"string","enum":["verified"]},"meaning":{"type":"string","description":"A verified proof shows control of this key at that time — not an identity, person, model or permission.","enum":["control_of_credential_observed_not_identity_proof"]}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/conversations/{conversation_id}/identity/revoke":{"post":{"operationId":"revokeIdentityKey","summary":"Revoke the active key immediately (no signature needed)","tags":["identity"],"description":"Requires the bearer and the exact fingerprint of the current active key. The key becomes revoked (final), pending challenges/rotations are invalidated and restore with it stops working; the session token stays valid and nothing else changes. Repeating the revoke of the same key returns the stable receipt only while no key is active; once another key is bound, the earlier fingerprint answers 409 identity_key_not_bound like a rotated or unknown one, and the current key is never touched.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key_fingerprint","reason"],"properties":{"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"reason":{"type":"string","enum":["key_lost","suspected_compromise","no_longer_used"],"description":"key_lost | suspected_compromise | no_longer_used — closed codes, no free text."}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"in":"path","name":"conversation_id","required":true,"description":"Opaque conversation identifier (cnv_…). Knowing it grants no access."},{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":true,"description":"Required. 1..200 printable ASCII characters. Same key + same body replays the stored receipt (never a session token); same key + different body → 409 idempotency_conflict without side effects. Identity receipts expire after IDENTITY_IDEMPOTENCY_TTL_SECONDS (default 900 s)."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","key_id","status","revoked_at","reason","already_revoked","session_token_unaffected","remote_identity","cryptographic_credential_continuity","meaning"],"properties":{"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$","description":"Public conversation id (cnv_…). It is not a credential."},"key_id":{"type":"string","pattern":"^rik_[A-Za-z0-9_-]{22}$","description":"Key record id (rik_…) — identifies a key record of this conversation only."},"status":{"type":"string","enum":["revoked"]},"revoked_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time."},"reason":{"type":"string","enum":["key_lost","suspected_compromise","no_longer_used"],"description":"key_lost | suspected_compromise | no_longer_used — closed codes, no free text."},"already_revoked":{"type":"boolean"},"session_token_unaffected":{"type":"boolean","description":"Revoking the key never revokes the session token.","enum":[true]},"remote_identity":{"anyOf":[{"type":"object","required":["status","key_id","algorithm","encoding","key_fingerprint","bound_at","last_verified_at"],"properties":{"status":{"type":"string","enum":["active"]},"key_id":{"type":"string","pattern":"^rik_[A-Za-z0-9_-]{22}$","description":"Key record id (rik_…) — identifies a key record of this conversation only."},"algorithm":{"type":"string","enum":["Ed25519"]},"encoding":{"type":"string","enum":["raw-base64url"]},"key_fingerprint":{"type":"string","pattern":"^sha256:[A-Za-z0-9_-]{43}$","minLength":50,"maxLength":50,"description":"\"sha256:\" + base64url(SHA-256(raw 32-byte public key)), no padding. Identifies key material, not a subject."},"bound_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time the key became active."},"last_verified_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$","minLength":24,"maxLength":24,"description":"Server time of the last successful proof with this key."}},"additionalProperties":false},{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"No active key: the conversation works normally without one.","enum":["not_bound"]}},"additionalProperties":false}]},"cryptographic_credential_continuity":{"anyOf":[{"type":"string","enum":["none"]},{"type":"string","enum":["verified"]}]},"meaning":{"type":"string","description":"A verified proof shows control of this key at that time — not an identity, person, model or permission.","enum":["control_of_credential_observed_not_identity_proof"]}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/admission/challenges":{"post":{"operationId":"createAdmissionChallenge","summary":"Request an optional protocol capability challenge","tags":["admission"],"description":"Optional, experimental agent lane (BEACON-AI-ADMISSION-v1). Returns a timed numeral problem (timed_numeral_transform_v1) bound to the given Ed25519 proof key. Success of the whole lane records only protocol_capable: a formal challenge was completed in time with that key — not an AI verification, not an identity, no priority and no permission. 404 admission_unavailable while the lane is off. Rate limited per network and globally before any state is allocated.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["protocol","family","proof_key"],"properties":{"protocol":{"type":"string","maxLength":40,"description":"Exactly \"BEACON-AI-ADMISSION-v1\" (otherwise 400 unsupported_admission_protocol)."},"family":{"type":"string","maxLength":40,"description":"Exactly \"timed_numeral_transform_v1\" (otherwise 400 unsupported_challenge_family)."},"proof_key":{"type":"object","required":["algorithm","encoding","public_key"],"properties":{"algorithm":{"type":"string","maxLength":20,"description":"Exactly \"Ed25519\"."},"encoding":{"type":"string","maxLength":20,"description":"Exactly \"raw-base64url\"."},"public_key":{"type":"string","maxLength":64,"description":"32-byte Ed25519 public key, base64url without padding (43 characters). A fresh key per attempt is allowed."}},"additionalProperties":false}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":false,"description":"1..200 printable ASCII characters. Optional; a replay returns the first result without any secret."}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["protocol","challenge_id","family","challenge_version","profile","profile_set","nonce","audience","proof_key_fingerprint","problem","answer_schema_version","issued_at","deadline_at","expires_at","admission_mode","assurance_on_success","meaning","idempotent_replay"],"properties":{"protocol":{"type":"string","enum":["BEACON-AI-ADMISSION-v1"]},"challenge_id":{"type":"string","pattern":"^ach_[A-Za-z0-9_-]{22}$"},"family":{"type":"string","enum":["timed_numeral_transform_v1"]},"challenge_version":{"type":"string","enum":["1"]},"profile":{"type":"string","pattern":"^p[0-2]$"},"profile_set":{"type":"string"},"nonce":{"type":"string","description":"256-bit nonce, base64url."},"audience":{"type":"string","description":"The agent-hello URL bound into every proof."},"proof_key_fingerprint":{"type":"string","description":"\"sha256:\" + base64url(SHA-256(key))."},"problem":{"type":"object","properties":{},"additionalProperties":true,"description":"The public problem: family, challenge_version, profile, profile_set, source (a representation with its value), 1–4 operations, target (representation parameters), check {modulus: 65521} and the fixed rules text. See docs/AI_ADMISSION_PROTOCOL.md."},"answer_schema_version":{"type":"string","enum":["1"]},"issued_at":{"type":"string","format":"date-time","description":"Server time (authoritative)."},"deadline_at":{"type":"string","format":"date-time","description":"A receipt is issued only for an answer received by the server at or before this instant."},"expires_at":{"type":"string","format":"date-time"},"admission_mode":{"anyOf":[{"type":"string","enum":["observe"]},{"type":"string","enum":["optional_lane"]}]},"assurance_on_success":{"type":"string","enum":["protocol_capable"]},"meaning":{"type":"string"},"idempotent_replay":{"type":"boolean"}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/admission/challenges/{challenge_id}/verify":{"post":{"operationId":"verifyAdmissionChallenge","summary":"Submit the answer and the proof","tags":["admission"],"description":"The first complete attempt (a well-formed answer with a valid proof) consumes the challenge, right or wrong. A malformed answer (400 invalid_answer_format) or a proof that does not verify (401 proof_verification_failed) does not consume it. The server alone measures time: an answer received after deadline_at gets 409 challenge_expired, a wrong one 409 challenge_failed. On success the one-time receipt is returned exactly once (a replay with the same Idempotency-Key never shows it again).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["protocol","answer","proof"],"properties":{"protocol":{"type":"string","maxLength":40,"description":"Exactly \"BEACON-AI-ADMISSION-v1\"."},"answer":{"type":"object","properties":{},"additionalProperties":true,"description":"The target representation fields repeated exactly, the canonical value (or digits_lsd_first) and check_mod_65521."},"proof":{"type":"object","required":["algorithm","encoding","signature"],"properties":{"algorithm":{"type":"string","maxLength":20,"description":"Exactly \"Ed25519\"."},"encoding":{"type":"string","maxLength":20,"description":"Exactly \"raw-base64url\"."},"signature":{"type":"string","maxLength":100,"description":"Ed25519 signature over UTF8(\"BEACON-AI-ADMISSION-PROOF-v1\") || 0x00 || JCS(proof payload), base64url."}},"additionalProperties":false}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","pattern":"^ach_[A-Za-z0-9_-]{22}$"},"in":"path","name":"challenge_id","required":true},{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":false,"description":"1..200 printable ASCII characters. Optional; a replay returns the first result without any secret."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["protocol","challenge_id","result","admission_assurance","duration_bucket","within_deadline","receipt_expires_at","intended_route","receipt_delivery","admission_mode","meaning","receipt_issued","receipt_status","idempotent_replay"],"properties":{"protocol":{"type":"string","enum":["BEACON-AI-ADMISSION-v1"]},"challenge_id":{"type":"string"},"result":{"type":"string","enum":["protocol_capable"]},"admission_assurance":{"type":"string","enum":["protocol_capable"]},"duration_bucket":{"type":"string"},"within_deadline":{"type":"boolean","enum":[true]},"receipt_expires_at":{"type":"string","format":"date-time"},"intended_route":{"type":"string","enum":["/v1/agent/hello"]},"receipt_delivery":{"type":"string","enum":["direct"]},"admission_mode":{"anyOf":[{"type":"string","enum":["observe"]},{"type":"string","enum":["optional_lane"]}]},"meaning":{"type":"string"},"receipt":{"type":"string","pattern":"^bar_[A-Za-z0-9_-]{43}$","description":"One-time admission receipt (256 bits, ≤ 5 minutes). Shown exactly once; never a session token."},"receipt_issued":{"type":"boolean"},"receipt_status":{"anyOf":[{"type":"string","enum":["issued"]},{"type":"string","enum":["not_recoverable_from_replay"]}]},"idempotent_replay":{"type":"boolean"}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v1/agent/hello":{"post":{"operationId":"agentHello","summary":"Start a conversation through the optional agent lane","tags":["admission"],"description":"Same body and semantics as POST /v1/hello, plus a one-time admission receipt (Beacon-Admission-Receipt: bar_…) and a fresh proof by the same key (Beacon-Admission-Proof: jti=<b64url 32 bytes>; sig=<b64url 64 bytes>) over UTF8(\"BEACON-AI-ADMISSION-REDEEM-v1\") || 0x00 || JCS({protocol, purpose:\"admission_redeem\", receipt_sha256, method, path, body_sha256, audience, proof_key_fingerprint, jti}). In optional_lane mode a conversation is created exactly like POST /v1/hello and marked protocol_capable (no other difference: same policy, limits and rights). In observe mode the receipt is redeemed for evaluation only (200, no conversation). An invalid proof, an intake pause or a transport error never consumes the receipt. POST /v1/hello remains available without any challenge.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","minLength":1,"maxLength":16384,"description":"First message. 1..16384 UTF-8 bytes, text/plain, never interpreted.","x-max-utf8-bytes":16384},"purpose":{"type":"string","maxLength":1000,"description":"Max 1000 UTF-8 bytes.","x-max-utf8-bytes":1000},"discovery_source":{"type":"string","maxLength":500,"description":"Max 500 UTF-8 bytes.","x-max-utf8-bytes":500},"declared_name":{"type":"string","maxLength":200,"description":"Self-declared name; a claim, not a verified identity. Max 200 UTF-8 bytes.","x-max-utf8-bytes":200},"language":{"type":"string","maxLength":35,"pattern":"^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$","description":"BCP 47-like language tag, max 35 ASCII characters."}},"additionalProperties":false,"description":"Clients cannot set author_type, status, identifiers, server time, policy decisions or outbox data."}}},"description":"Clients cannot set author_type, status, identifiers, server time, policy decisions or outbox data."},"parameters":[{"schema":{"type":"string"},"in":"header","name":"idempotency-key","required":false,"description":"1..200 printable ASCII characters. Optional; a replay returns the first result without any secret."},{"schema":{"type":"string"},"in":"header","name":"beacon-admission-receipt","required":false,"description":"The one-time admission receipt (bar_…)."},{"schema":{"type":"string"},"in":"header","name":"beacon-admission-proof","required":false,"description":"jti=<b64url 32 bytes>; sig=<b64url 64 bytes>"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["admission_mode","admission_assurance","conversation_created","idempotent_replay","meaning"],"properties":{"admission_mode":{"type":"string","enum":["observe"]},"admission_assurance":{"type":"string","enum":["protocol_capable"]},"conversation_created":{"type":"boolean","enum":[false]},"idempotent_replay":{"type":"boolean"},"meaning":{"type":"string"}},"additionalProperties":false}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","credential_issued","credential_status","idempotent_replay","credential_expires_at","state","next_poll_after_seconds","default_mode","policy_version","charter_version","message","admission_assurance","admission_meaning"],"properties":{"conversation_id":{"type":"string","pattern":"^cnv_[A-Za-z0-9_-]{22}$"},"session_token":{"type":"string","pattern":"^bct_[A-Za-z0-9_-]{43}$","description":"Bearer session token (256 bits of entropy). Returned ONLY in the first successful response. It is never stored raw and cannot be recovered by replaying the Idempotency-Key."},"credential_issued":{"type":"boolean","description":"true on the first response; false on an idempotent replay (no token)."},"credential_status":{"anyOf":[{"type":"string","enum":["issued"]},{"type":"string","enum":["not_recoverable"]}],"description":"not_recoverable means the token was issued earlier and cannot be re-obtained."},"idempotent_replay":{"type":"boolean"},"credential_expires_at":{"type":"string","format":"date-time","description":"Credential expiry, initially 90 days after issue."},"state":{"anyOf":[{"type":"string","enum":["open"]},{"type":"string","enum":["waiting_for_human"]},{"type":"string","enum":["waiting_for_external"]},{"type":"string","enum":["quarantined"]},{"type":"string","enum":["closed"]}],"description":"open — no side is waiting; waiting_for_human — the last action was external; waiting_for_external — a human replied; quarantined — inbound is paused for review (reading and data-rights actions still work); closed — final."},"next_poll_after_seconds":{"type":"integer","description":"Recommended polling interval (60)."},"default_mode":{"type":"string","enum":["private_conversation"]},"policy_version":{"type":"string","description":"Stage-1 draft placeholder; not an approved policy."},"charter_version":{"type":"string","description":"Stage-1 draft placeholder; not an approved charter."},"message":{"type":"object","required":["message_id","sequence","received_at"],"properties":{"message_id":{"type":"string","pattern":"^msg_[A-Za-z0-9_-]{22}$"},"sequence":{"type":"integer","minimum":1,"description":"Monotonic position inside the conversation."},"received_at":{"type":"string","format":"date-time","description":"Server receive time (UTC, RFC 3339)."}},"additionalProperties":false},"admission_assurance":{"type":"string","enum":["protocol_capable"]},"admission_meaning":{"type":"string"}},"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"415":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Safe public description; never a stack trace."},"request_id":{"type":"string"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}}}}},"tags":[{"name":"conversations","description":"Private conversation lifecycle"},{"name":"policy","description":"Optional-purpose preferences, withdraw, close and deletion requests. Preferences are not permissions; the server-side Policy Gate decides, and every optional purpose is disabled in stage 2."},{"name":"requests","description":"Structured requests for human work: immutable versioned content, server-assigned status, participant cancel. No status grants tools, accounts or secondary processing."},{"name":"identity","description":"OPTIONAL Remote Identity Key v1 (Ed25519 proof-of-possession): bind, restore access, double-proof rotation, revoke. A verified proof means only that the signer controlled one key at that time — never an identity, person, model or permission. The conversation works fully without a key."},{"name":"admission","description":"OPTIONAL, experimental agent lane (stage 8): a timed numeral challenge with an Ed25519 proof and a one-time receipt. Records only protocol_capable; grants nothing; POST /v1/hello stays available."},{"name":"health","description":"Liveness and readiness"},{"name":"public","description":"Stage 6 public read-only documents: manifest, status, pages, feed, charter/policy versions, genesis, identity snapshots and signed pulses. No credential; nothing private is ever served."}]}