{ "openapi": "3.1.0", "info": { "title": "heng.lu Doctrine Service", "version": "0.1.0", "description": "Caller-funded analysis based on current public Notes. Records stay encrypted and private until explicit deletion. No expiry." }, "servers": [ { "url": "https://heng.lu/api/doctrine/v1" } ], "paths": { "/manifest": { "get": { "operationId": "manifest", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "corpus_version": { "type": "string" }, "providers": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "object" }, "retention": { "const": "until_user_deletion" }, "expires_at": { "type": "null" } } } } } }, "default": { "description": "Explicit error; sensitive upstream responses are never exposed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sources": { "get": { "operationId": "sources", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "corpus_version": { "type": "string" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceMetadata" } } } } } } }, "default": { "description": "Explicit error; sensitive upstream responses are never exposed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sources/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "example": "note-36-en" } } ], "get": { "operationId": "source", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } }, "default": { "description": "Explicit error; sensitive upstream responses are never exposed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analyses": { "post": { "security": [ { "AnalysisAccess": [], "ModelKey": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 128 } }, { "in": "header", "name": "Accept", "schema": { "enum": [ "application/json", "text/event-stream" ] } } ], "responses": { "200": { "description": "Completed or replayed turn. SSE events: identity, progress, result, error; heartbeat comments. Check the terminal event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "202": { "description": "Existing request remains running; no new inference started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" } } } }, "default": { "description": "Explicit error; sensitive upstream responses are never exposed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "createAnalysis", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "maxLength": 12000 }, "policy": { "$ref": "#/components/schemas/Policy" }, "language": { "type": "string", "default": "zh" }, "provider": { "enum": [ "openai", "anthropic" ] }, "model": { "type": "string", "maxLength": 160 } }, "required": [ "question", "provider", "model", "policy" ], "additionalProperties": false } } } } } }, "/analyses/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "readAnalysis", "security": [ { "AnalysisAccess": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Analysis" } } } }, "default": { "description": "Explicit error; sensitive upstream responses are never exposed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteAnalysis", "security": [ { "AnalysisAccess": [] } ], "responses": { "204": { "description": "Online content removed; access revoked. Historical backups retain their existing policy; restoration requires the latest deletion ledger." }, "default": { "description": "Explicit error; sensitive upstream responses are never exposed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Online content is deleted; QNAP deletion registration is pending. Repeat DELETE with the same capability until 204. No inference is started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "analysis_id": { "type": "string" }, "online_deleted": { "const": true }, "backup_deletion_pending": { "const": true }, "next_action": { "type": "string" } } } } } } } } }, "/analyses/{id}/turns": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "security": [ { "AnalysisAccess": [], "ModelKey": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 128 } }, { "in": "header", "name": "Accept", "schema": { "enum": [ "application/json", "text/event-stream" ] } } ], "responses": { "200": { "description": "Completed or replayed turn. SSE events: identity, progress, result, error; heartbeat comments. Check the terminal event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "202": { "description": "Existing request remains running; no new inference started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" } } } }, "default": { "description": "Explicit error; sensitive upstream responses are never exposed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "continueAnalysis", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Input" } } } } } } }, "components": { "securitySchemes": { "AnalysisAccess": { "type": "http", "scheme": "bearer", "description": "Client-generated 256-bit secret, unpadded base64url. Independent of provider key." }, "ModelKey": { "type": "apiKey", "in": "header", "name": "X-Model-API-Key", "description": "Injected by connector; never a tool argument or persisted record." } }, "schemas": { "Policy": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 1000 }, "text": { "type": "string", "maxLength": 60000 }, "source_url": { "type": "string", "format": "uri" }, "as_of": { "type": "string" } }, "required": [ "title", "text" ], "additionalProperties": false }, "Input": { "type": "object", "properties": { "question": { "type": "string", "maxLength": 12000 }, "policy": { "$ref": "#/components/schemas/Policy" }, "language": { "type": "string", "default": "zh" }, "provider": { "enum": [ "openai", "anthropic" ] }, "model": { "type": "string", "maxLength": 160 } }, "required": [ "question", "provider", "model" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "analysis_id": { "type": "string" }, "turn_id": { "type": "string" } }, "required": [ "error", "request_id" ] }, "SourceMetadata": { "type": "object", "properties": { "id": { "type": "string" }, "work_id": { "type": "string" }, "author": { "type": "string" }, "title": { "type": "string" }, "canonical_url": { "type": "string" }, "language": { "type": "string" }, "published_at": { "type": "string" }, "revised_at": { "type": "string" }, "digest": { "type": "string" } }, "required": [ "id", "work_id", "author", "title", "canonical_url", "language", "published_at", "revised_at", "digest" ] }, "Source": { "allOf": [ { "$ref": "#/components/schemas/SourceMetadata" }, { "type": "object", "properties": { "text": { "type": "string" }, "corpus_version": { "type": "string" }, "read_at": { "type": "string" } }, "required": [ "text" ] } ] }, "Citation": { "type": "object", "properties": { "source_id": { "type": "string" }, "quote": { "type": "string" }, "verified": { "type": "boolean" }, "canonical_url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "author": { "type": "string" }, "digest": { "type": "string" }, "language": { "type": "string" }, "work_id": { "type": "string" }, "read_at": { "type": "string" } }, "required": [ "source_id", "quote", "verified" ] }, "Attribution": { "type": "object", "properties": { "generated_by": { "const": "model" }, "author_reviewed": { "const": false }, "basis": { "type": "string" } } }, "Turn": { "type": "object", "properties": { "turn_id": { "type": "string" }, "status": { "enum": [ "running", "completed", "failed", "cancelled" ] }, "question": { "type": "string" }, "policy": { "$ref": "#/components/schemas/Policy" }, "language": { "type": "string" }, "provider": { "enum": [ "openai", "anthropic" ] }, "model": { "type": "string" }, "corpus_version": { "type": "string" }, "analysis_markdown": { "type": [ "string", "null" ] }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/Citation" } }, "source_observations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "source_id": { "type": "string" }, "previous_digest": { "type": "string" }, "current_digest": { "type": "string" } } } }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "usage": { "type": [ "object", "null" ], "properties": { "calls": { "type": "array", "items": { "type": "object", "properties": { "input_tokens": { "type": [ "integer", "null" ] }, "output_tokens": { "type": [ "integer", "null" ] } } } } } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "error": { "type": [ "string", "null" ] } }, "required": [ "turn_id", "status", "question", "provider", "model", "corpus_version", "analysis_markdown", "citations", "source_observations", "usage", "created_at", "updated_at" ] }, "Result": { "allOf": [ { "$ref": "#/components/schemas/Turn" }, { "type": "object", "properties": { "analysis_id": { "type": "string" }, "retention": { "const": "until_user_deletion" }, "expires_at": { "type": "null" }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "replay": { "type": "boolean" } }, "required": [ "analysis_id", "retention", "expires_at", "attribution" ] } ] }, "Analysis": { "type": "object", "properties": { "analysis_id": { "type": "string" }, "retention": { "const": "until_user_deletion" }, "expires_at": { "type": "null" }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "turns": { "type": "array", "items": { "$ref": "#/components/schemas/Turn" } } }, "required": [ "analysis_id", "retention", "expires_at", "attribution", "turns" ] } } } }