{ "openapi": "3.1.0", "info": { "title": "RHENIUS API", "version": "2.0", "summary": "Private, local-first Personal Relationship Management with Zero-Knowledge cryptography and an autonomous relationship-intelligence agent.", "description": "The RHENIUS HTTP API: contacts, graph data, journal, family tree, entities, the\nnatural-language AI agent and the homomorphic reciprocity ledger.\n\n**Authentication** — obtain a session token from `POST /api/auth/login` and present it as\n`Authorization: Bearer ` or `X-Session-Token: `. Identity and data scope derive\nexclusively from the validated session; there is no anonymous data access.\n\n**AI agent** — `POST /api/action` classifies natural language into deterministic, auditable,\nreversible mutations. Destructive proposals require `/api/action/confirm`; executed mutations\nundo via `/api/action/undo`.\n\nCanonical source: src/content/discovery.ts (v2.0). Prose documentation: /llms-full.txt." }, "servers": [ { "url": "https://rhenius.pages.dev", "description": "Current deployment origin" } ], "tags": [ { "name": "System" }, { "name": "Auth" }, { "name": "Contacts" }, { "name": "Data" }, { "name": "Family Tree" }, { "name": "Entities" }, { "name": "Journal" }, { "name": "AI Agent" }, { "name": "Intelligence" }, { "name": "Ledger" } ], "paths": { "/api/health": { "get": { "summary": "Liveness probe with the active database provider.", "tags": [ "System" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/login": { "post": { "summary": "Exchange email + password (Argon2id verification) for a session token.", "description": "Returns a session token to present as `Authorization: Bearer ` or `X-Session-Token: ` on every protected call. Tokens are stored server-side as SHA-256 hashes only; failed attempts are rate-limited with account lockout.", "tags": [ "Auth" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/auth/signup": { "post": { "summary": "Create an account and receive a session token.", "tags": [ "Auth" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/auth/logout": { "post": { "summary": "Revoke the presented session token.", "tags": [ "Auth" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/auth/me": { "get": { "summary": "Resolve the presented session token to its account.", "tags": [ "Auth" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/contacts": { "get": { "summary": "List the authenticated user’s contacts.", "tags": [ "Contacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ] }, "post": { "summary": "Create one contact.", "tags": [ "Contacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/contacts/batch": { "post": { "summary": "Upsert many contacts (vCard / bulk import).", "tags": [ "Contacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/contacts/batch-update": { "post": { "summary": "Apply one field change (tags, cadence, group) to many contacts.", "tags": [ "Contacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/contacts/batch-delete": { "post": { "summary": "Delete many contacts with undo snapshots.", "tags": [ "Contacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/data": { "get": { "summary": "Full app state: contacts, smart lists, entities and journal pages.", "tags": [ "Data" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ] } }, "/api/export": { "get": { "summary": "Complete portable export of the account.", "tags": [ "Data" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ] } }, "/api/family-tree": { "get": { "summary": "List genealogical family members and pedigree links.", "tags": [ "Family Tree" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ] }, "put": { "summary": "Replace the family tree (full snapshot write) and sync linked contacts.", "tags": [ "Family Tree" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/entities": { "get": { "summary": "List entities — companies, projects and pets with linked members.", "tags": [ "Entities" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ] }, "post": { "summary": "Create an entity.", "tags": [ "Entities" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/entities/{id}": { "put": { "summary": "Update an entity.", "tags": [ "Entities" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "summary": "Delete an entity.", "tags": [ "Entities" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ] } }, "/api/journal-pages": { "get": { "summary": "List daily journal pages with blocks and linked attendees.", "tags": [ "Journal" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ] }, "put": { "summary": "Upsert journal pages. A full list also deletes pages removed client-side.", "tags": [ "Journal" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/journal-pages/{id}": { "delete": { "summary": "Delete one journal page.", "tags": [ "Journal" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ] } }, "/api/action": { "post": { "summary": "Master natural-language relationship-intelligence agent.", "description": "Runs the deterministic fast path first (<5ms, no model call); unhandled prompts escalate to the configured LLM through the 9-stage pipeline (intent → entity resolution → grounding → planner → validator → confirmation policy). Destructive proposals pause at /api/action/confirm. Every action is audit-logged and reversible.", "tags": [ "AI Agent" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/action/confirm": { "post": { "summary": "Approve a DESTRUCTIVE proposal created by /api/action.", "description": "Proposals expire after 5 minutes.", "tags": [ "AI Agent" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/action/undo": { "post": { "summary": "Atomically reverse a previously executed mutation.", "description": "Returns HTTP 409 with code VERSION_MISMATCH when the record changed underneath the undo (optimistic locking).", "tags": [ "AI Agent" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Optimistic-locking conflict (VERSION_MISMATCH): the record changed since it was read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/query": { "post": { "summary": "Read-only natural-language question over the network.", "tags": [ "AI Agent" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/briefing": { "post": { "summary": "Generate a 1-page pre-meeting executive briefing sheet for a contact.", "tags": [ "Intelligence" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/nurture": { "post": { "summary": "Generate outreach, gift and follow-up suggestions for a contact.", "tags": [ "Intelligence" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/ingest-magic": { "post": { "summary": "Parse unstructured text (email signature, bio, notes) into contact fields.", "tags": [ "Intelligence" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/homomorphic/sum": { "post": { "summary": "Add two Paillier ciphertexts; plaintext values never reach the server.", "tags": [ "Ledger" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/homomorphic/network-sum": { "post": { "summary": "Homomorphically aggregate many Paillier ciphertexts across the network.", "tags": [ "Ledger" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required or session invalid (SESSION_REQUIRED | INVALID_SESSION | SESSION_REVOKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionToken": [] }, [ "BearerAuth" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "components": { "securitySchemes": { "SessionToken": { "type": "apiKey", "in": "header", "name": "X-Session-Token", "description": "Session token from POST /api/auth/login" }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer " } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code where applicable" }, "message": { "type": "string", "description": "Human-readable explanation" }, "code": { "type": "string", "description": "Machine-readable code (SESSION_REQUIRED, INVALID_SESSION, SESSION_REVOKED, VERSION_MISMATCH, …)" }, "retryable": { "type": "boolean" } } } } } }