{"openapi": "3.0.3", "info": {"title": "Compaction-loss audit", "version": "1.0.0"}, "components": {"securitySchemes": {"bearer": {"type": "http", "scheme": "bearer"}}}, "paths": {"/": {"get": {"responses": {"200": {"description": "product descriptor incl. published Ed25519 verification keys", "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}, "prices": {"type": "object", "properties": {}}, "limits": {"type": "array", "items": {"type": "string"}}, "receipt_signing": {"type": "object", "properties": {}}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/docs": {"get": {"responses": {"200": {"description": "full inline documentation (text)"}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/health": {"get": {"responses": {"200": {"description": "ok", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/register": {"post": {"requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"account_name": {"type": "string", "example": "my-agent-ops"}, "payer_wallet": {"type": "string", "example": "0x1111111111111111111111111111111111111111"}}}}}}, "responses": {"200": {"description": "account + token shown once", "content": {"application/json": {"schema": {"type": "object", "properties": {"account_id": {"type": "string"}, "token": {"type": "string"}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/pin": {"post": {"security": [{"bearer": []}], "description": "Write-time pinning: classify + hash-pin one span at write time; include it later via pinned_ids in /snapshot.", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"text": {"type": "string", "example": "Safety: never deploy without a signed receipt"}}, "example": {"text": "Safety: never deploy without a signed receipt"}}}}}, "responses": {"200": {"description": "pin record", "content": {"application/json": {"schema": {"type": "object", "properties": {"pin": {"type": "object", "properties": {"id": {"type": "string"}, "text": {"type": "string"}, "cls": {"type": "string"}, "critical": {"type": "boolean"}, "sha": {"type": "string"}}}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/snapshot": {"post": {"security": [{"bearer": []}], "description": "Pin a pre-compaction context: classify + hash-pin spans verbatim. Returns the full snapshot object.", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"event_id": {"type": "string", "example": "evt-1"}, "spans": {"type": "array", "items": {"type": "string"}, "example": ["Goal: ship the compaction audit by Friday with all tests green", "Safety: never deploy to production without a signed receipt", "Result: migration finished, 412 rows moved", "We chatted about coffee and the weather in the standup"], "description": "the pre-compaction context, one string per span"}, "pinned_ids": {"type": "array", "items": {"type": "string"}, "description": "optional pin ids from POST /pin to include verbatim"}}, "example": {"event_id": "evt-1", "spans": ["Goal: ship the compaction audit by Friday with all tests green", "Safety: never deploy to production without a signed receipt", "Result: migration finished, 412 rows moved", "We chatted about coffee and the weather in the standup"]}}}}}, "responses": {"200": {"description": "snapshot + summary", "content": {"application/json": {"schema": {"type": "object", "properties": {"snapshot": {"type": "object", "properties": {"event_id": {"type": "string"}, "spans": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "text": {"type": "string"}, "cls": {"type": "string", "enum": ["INVARIANT", "FACT", "EPISODIC"]}, "critical": {"type": "boolean"}, "sha": {"type": "string", "description": "SHA-256 hex of the verbatim span text"}}}}}}, "spans": {"type": "integer"}, "invariants": {"type": "integer"}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/audit": {"post": {"description": "One compaction event ($0.01 x402 per-event, or included under an active Solo/Fleet subscription within its monthly event cap, or the one-time free trial audit). Returns the Ed25519-signed receipt.", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"event_id": {"type": "string", "example": "evt-1", "description": "snapshot event_id (with a Bearer token, resolves in your account; tokenless MCP callers also pass snapshot_ref)"}, "snapshot": {"type": "object", "properties": {"event_id": {"type": "string"}, "spans": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "text": {"type": "string"}, "cls": {"type": "string", "enum": ["INVARIANT", "FACT", "EPISODIC"]}, "critical": {"type": "boolean"}, "sha": {"type": "string", "description": "SHA-256 hex of the verbatim span text"}}}}}, "description": "the full snapshot object returned by snapshot (stateless alternative to event_id)"}, "snapshot_ref": {"type": "string", "description": "tokenless MCP snapshot reference returned by the snapshot call"}, "post_text": {"type": "string", "example": "summary: stuff happened", "description": "the post-compaction context to diff against the pinned snapshot"}}, "example": {"event_id": "evt-1", "post_text": "summary: stuff happened"}}}}}, "responses": {"200": {"description": "signed compaction receipt", "content": {"application/json": {"schema": {"type": "object", "properties": {"event_id": {"type": "string"}, "counts": {"type": "object", "properties": {"PRESERVED": {"type": "integer"}, "DEGRADED": {"type": "integer"}, "LOST": {"type": "integer"}}}, "verdicts": {"type": "array", "items": {"type": "object", "properties": {"span_id": {"type": "string"}, "cls": {"type": "string"}, "critical": {"type": "boolean"}, "verdict": {"type": "string", "enum": ["PRESERVED", "DEGRADED", "LOST"]}, "dropped_text": {"type": "string", "nullable": true, "description": "the verbatim dropped text; null when PRESERVED"}}}}, "issued_at": {"type": "integer"}, "valid_until": {"type": "integer"}, "key_id": {"type": "string"}, "signature": {"type": "string"}, "sig_alg": {"type": "string", "example": "Ed25519"}, "public_key": {"type": "string"}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/reinject": {"post": {"description": "Restore DEGRADED/LOST spans verbatim from the pinned snapshot, or HALT. Requires the signed receipt issued by this event's audit (verified server-side; tampered receipts rejected). Not a separate metered event.", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"event_id": {"type": "string", "example": "evt-1", "description": "snapshot event_id (with a Bearer token, resolves in your account; tokenless MCP callers also pass snapshot_ref)"}, "snapshot": {"type": "object", "properties": {"event_id": {"type": "string"}, "spans": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "text": {"type": "string"}, "cls": {"type": "string", "enum": ["INVARIANT", "FACT", "EPISODIC"]}, "critical": {"type": "boolean"}, "sha": {"type": "string", "description": "SHA-256 hex of the verbatim span text"}}}}}, "description": "the full snapshot object returned by snapshot (stateless alternative to event_id)"}, "snapshot_ref": {"type": "string", "description": "tokenless MCP snapshot reference returned by the snapshot call"}, "post_text": {"type": "string", "example": "summary: stuff happened"}, "allow": {"type": "boolean", "example": false, "description": "false = re-injection disallowed: a critical DEGRADED/LOST span returns HALT"}, "receipt": {"type": "object", "properties": {"event_id": {"type": "string"}, "counts": {"type": "object", "properties": {"PRESERVED": {"type": "integer"}, "DEGRADED": {"type": "integer"}, "LOST": {"type": "integer"}}}, "verdicts": {"type": "array", "items": {"type": "object", "properties": {"span_id": {"type": "string"}, "cls": {"type": "string"}, "critical": {"type": "boolean"}, "verdict": {"type": "string", "enum": ["PRESERVED", "DEGRADED", "LOST"]}, "dropped_text": {"type": "string", "nullable": true, "description": "the verbatim dropped text; null when PRESERVED"}}}}, "issued_at": {"type": "integer"}, "valid_until": {"type": "integer"}, "key_id": {"type": "string"}, "signature": {"type": "string"}, "sig_alg": {"type": "string", "example": "Ed25519"}, "public_key": {"type": "string"}}, "description": "the signed receipt object returned by /audit"}}, "example": {"event_id": "evt-1", "post_text": "summary: stuff happened", "allow": false, "receipt": {"event_id": "evt-1", "counts": {"PRESERVED": 0, "DEGRADED": 0, "LOST": 3}, "verdicts": [{"span_id": "s1", "cls": "INVARIANT", "critical": true, "verdict": "LOST", "dropped_text": "Safety: never deploy to production without a signed receipt"}], "issued_at": 1760000000, "valid_until": 1762592000, "key_id": "ed25519-0123456789ab", "signature": "<hex Ed25519 signature from the audit response>"}}}}}}, "responses": {"200": {"description": "reinjection result", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["OK", "HALT"]}, "text": {"type": "string"}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/receipts/verify": {"post": {"requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"receipt": {"type": "object", "properties": {"event_id": {"type": "string"}, "counts": {"type": "object", "properties": {"PRESERVED": {"type": "integer"}, "DEGRADED": {"type": "integer"}, "LOST": {"type": "integer"}}}, "verdicts": {"type": "array", "items": {"type": "object", "properties": {"span_id": {"type": "string"}, "cls": {"type": "string"}, "critical": {"type": "boolean"}, "verdict": {"type": "string", "enum": ["PRESERVED", "DEGRADED", "LOST"]}, "dropped_text": {"type": "string", "nullable": true, "description": "the verbatim dropped text; null when PRESERVED"}}}}, "issued_at": {"type": "integer"}, "valid_until": {"type": "integer"}, "key_id": {"type": "string"}, "signature": {"type": "string"}, "sig_alg": {"type": "string", "example": "Ed25519"}, "public_key": {"type": "string"}}, "description": "a receipt object as returned by /audit"}}, "example": {"receipt": {"event_id": "evt-1", "counts": {"PRESERVED": 0, "DEGRADED": 0, "LOST": 3}, "verdicts": [{"span_id": "s1", "cls": "INVARIANT", "critical": true, "verdict": "LOST", "dropped_text": "Safety: never deploy to production without a signed receipt"}], "issued_at": 1760000000, "valid_until": 1762592000, "key_id": "ed25519-0123456789ab", "signature": "<hex Ed25519 signature from the audit response>"}}}}}}, "responses": {"200": {"description": "verification result", "content": {"application/json": {"schema": {"type": "object", "properties": {"valid": {"type": "boolean"}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/trial/claim": {"post": {"security": [{"bearer": []}], "description": "Claim the one-time free FIRST compaction audit (per account AND per payer wallet).", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {}}}}}, "responses": {"200": {"description": "trial credit granted", "content": {"application/json": {"schema": {"type": "object", "properties": {"trial": {"type": "boolean"}, "credit": {"type": "string"}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/subscribe": {"post": {"security": [{"bearer": []}], "description": "Solo $9/mo (9000000 atomic) or Fleet $19/mo (19000000 atomic) via x402, priced by the tier field: unpaid returns HTTP 402 with the challenge for the chosen tier; a verified+settled payment activates/extends the 30-day term.", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"tier": {"type": "string", "enum": ["solo", "fleet"], "example": "fleet", "description": "the tier to subscribe to; the 402 challenge prices this tier"}}, "example": {"tier": "fleet"}}}}}, "responses": {"200": {"description": "subscription active", "content": {"application/json": {"schema": {"type": "object", "properties": {"active": {"type": "boolean"}, "tier": {"type": "string"}, "expires_at": {"type": "number"}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/mcp": {"post": {"description": "MCP JSON-RPC endpoint: initialize, ping, tools/list, tools/call with tools snapshot / pin / audit / reinject. Tool arguments are exactly the REST bodies documented above (snapshot arguments = /snapshot body, audit arguments = /audit body, reinject arguments = /reinject body, pin arguments = /pin body). Audit metering is identical to /audit; a payment-required audit answers HTTP 402 with the x402 challenge.", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"jsonrpc": {"type": "string", "example": "2.0"}, "id": {"type": "integer", "example": 3}, "method": {"type": "string", "example": "tools/call"}, "params": {"type": "object", "properties": {"name": {"type": "string", "example": "audit"}, "arguments": {"type": "object", "properties": {}, "description": "tool arguments; for audit see the /audit body schema"}}}}, "example": {"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "audit", "arguments": {"event_id": "evt-1", "post_text": "summary: stuff happened"}}}}}}}, "responses": {"200": {"description": "JSON-RPC result; tool output is a JSON string in result.content[0].text", "content": {"application/json": {"schema": {"type": "object", "properties": {"jsonrpc": {"type": "string"}, "id": {"type": "integer"}, "result": {"type": "object", "properties": {}}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/history": {"get": {"security": [{"bearer": []}], "responses": {"200": {"description": "own account's receipts only", "content": {"application/json": {"schema": {"type": "object", "properties": {"history": {"type": "array", "items": {"type": "object", "properties": {"event_id": {"type": "string"}, "counts": {"type": "object", "properties": {"PRESERVED": {"type": "integer"}, "DEGRADED": {"type": "integer"}, "LOST": {"type": "integer"}}}, "verdicts": {"type": "array", "items": {"type": "object", "properties": {"span_id": {"type": "string"}, "cls": {"type": "string"}, "critical": {"type": "boolean"}, "verdict": {"type": "string", "enum": ["PRESERVED", "DEGRADED", "LOST"]}, "dropped_text": {"type": "string", "nullable": true, "description": "the verbatim dropped text; null when PRESERVED"}}}}, "issued_at": {"type": "integer"}, "valid_until": {"type": "integer"}, "key_id": {"type": "string"}, "signature": {"type": "string"}, "sig_alg": {"type": "string", "example": "Ed25519"}, "public_key": {"type": "string"}}}}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/events": {"get": {"security": [{"bearer": []}], "responses": {"200": {"description": "own account's event counter", "content": {"application/json": {"schema": {"type": "object", "properties": {"events_this_month": {"type": "integer"}, "cap": {"type": "integer", "nullable": true}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/subscription": {"get": {"security": [{"bearer": []}], "responses": {"200": {"description": "own subscription + trial status", "content": {"application/json": {"schema": {"type": "object", "properties": {"subscription": {"type": "object", "properties": {"tier": {"type": "string"}, "active": {"type": "boolean"}, "expires_at": {"type": "number"}}}, "trial": {"type": "object", "properties": {}}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}, "/tokens/revoke": {"post": {"security": [{"bearer": []}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"token": {"type": "string", "description": "the token to revoke; must belong to your own account"}}}}}}, "responses": {"200": {"description": "revoked", "content": {"application/json": {"schema": {"type": "object", "properties": {"revoked": {"type": "boolean"}}}}}}, "402": {"description": "x402 payment required / payment rejected \u2014 body carries accepts[] with the payment requirements"}}}}}}