{ "openapi": "3.1.0", "info": { "title": "Synproof's Syntropy — Deterministic Verification & Small Worlds API", "summary": "Language models guess. Syntropy proves. 5-Sieve Dialectical Verification Engine, Small Worlds Axiom Library & Axiomat Compiler.", "description": "Official Production Control Plane API for Synproof's Syntropy (https://synproof.ai). Install the Python SDK, CLI & MCP server from PyPI via `pip install syntropy-client` (https://pypi.org/project/syntropy-client/). Full Autonomous Agent Skill: https://synproof.ai/SKILL.md | LLM Documentation: https://synproof.ai/llms-full.txt", "version": "2.5.0", "contact": { "name": "Synproof Developer Support", "url": "https://synproof.ai/docs", "email": "developers@synproof.ai" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "paths": { "/v1/world": { "post": { "summary": "Upload World", "operationId": "upload_world_v1_world_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_world_v1_world_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/debate": { "post": { "summary": "Start Debate", "operationId": "start_debate_v1_debate_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "x-byok-typesafe", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Byok-Typesafe" } }, { "name": "X-LLM-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Llm-Api-Key" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/debate/{job_id}": { "get": { "summary": "Get Debate Status", "operationId": "get_debate_status_v1_debate__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/api-keys": { "post": { "tags": [ "API Keys" ], "summary": "Create Api Key", "description": "Vygeneruje nový SDK API klíč pro přihlášeného uživatele (Managed nebo BYOK).", "operationId": "create_api_key_v1_api_keys_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "API Keys" ], "summary": "List Api Keys", "description": "Vrátí seznam klíčů uživatele (ale jen jejich prefixy, nikdy ne celé klíče).", "operationId": "list_api_keys_v1_api_keys_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/api-keys/{key_id}": { "patch": { "tags": [ "API Keys" ], "summary": "Update Api Key", "description": "Deaktivuje nebo aktivuje API klíč, případně změní jeho název.", "operationId": "update_api_key_v1_api_keys__key_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "API Keys" ], "summary": "Delete Api Key", "description": "Trvale smaže / odvolá zadaný API klíč.", "operationId": "delete_api_key_v1_api_keys__key_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/billing/create-checkout-session": { "post": { "tags": [ "Billing & Stripe" ], "summary": "Create Checkout Session", "description": "Creates a Stripe Checkout Session for topping up Syntropy credits.", "operationId": "create_checkout_session_v1_billing_create_checkout_session_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/billing/webhook": { "post": { "tags": [ "Billing & Stripe" ], "summary": "Stripe Webhook", "description": "Stripe Webhook handler: Automatically credits user account upon checkout.session.completed.\nUsed in production when Stripe sends asynchronous webhook events.", "operationId": "stripe_webhook_v1_billing_webhook_post", "parameters": [ { "name": "Stripe-Signature", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stripe-Signature" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/billing/verify-session": { "post": { "tags": [ "Billing & Stripe" ], "summary": "Verify Checkout Session", "description": "Directly verifies a completed Stripe Checkout Session upon user redirect.\nEnsures instant credit fulfillment both in local dev (without Webhook tunnel)\nand on production (with strict idempotency to prevent double-crediting).", "operationId": "verify_checkout_session_v1_billing_verify_session_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifySessionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifySessionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/billing/transactions": { "get": { "tags": [ "Billing & Stripe" ], "summary": "Get Transaction History", "description": "Returns ledger transactions for the authenticated user.", "operationId": "get_transaction_history_v1_billing_transactions_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/billing/analytics": { "get": { "tags": [ "Billing & Stripe" ], "summary": "Get Billing Analytics", "description": "Returns spending analytics, daily timeline (last 30 days) and ledger metrics.", "operationId": "get_billing_analytics_v1_billing_analytics_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/worlds/domains": { "get": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Get Domains", "description": "Returns list of available and suggested domains/tags for the autocomplete whisperer.", "operationId": "get_domains_v1_worlds_domains_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/worlds/estimate": { "post": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Estimate Document", "description": "Computes token and cost estimation for given text before processing.", "operationId": "estimate_document_v1_worlds_estimate_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/axiomat/extract": { "post": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Process Axiomat", "description": "Core Axiomat Endpoint (Hardened):\n1. Validates & sanitizes inputs and price bounds (0.0 - 50.0 CRD).\n2. Acquires per-user concurrency lock to prevent TOCTOU credit race conditions.\n3. Extracts text from PDF / DOCX / TXT with anti-malware and anti-bomb guards.\n4. Runs 2-stage extraction & JEV Epistemic Reflection validation.\n5. Computes exact token usage and deducts credits from user ledger.\n6. Stores the world in `small_worlds` and axioms in `world_axioms`.", "operationId": "process_axiomat_v1_axiomat_extract_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_process_axiomat_v1_axiomat_extract_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/worlds/axiomat/process": { "post": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Process Axiomat", "description": "Core Axiomat Endpoint (Hardened):\n1. Validates & sanitizes inputs and price bounds (0.0 - 50.0 CRD).\n2. Acquires per-user concurrency lock to prevent TOCTOU credit race conditions.\n3. Extracts text from PDF / DOCX / TXT with anti-malware and anti-bomb guards.\n4. Runs 2-stage extraction & JEV Epistemic Reflection validation.\n5. Computes exact token usage and deducts credits from user ledger.\n6. Stores the world in `small_worlds` and axioms in `world_axioms`.", "operationId": "process_axiomat_v1_worlds_axiomat_process_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_process_axiomat_v1_worlds_axiomat_process_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/worlds/{world_id}/fork": { "post": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Fork World", "description": "Vytvoří soukromou upravitelnou kopii (Fork) libovolného veřejného nebo oficiálního\nverifikovaného Malého světa v účtu uživatele (`is_public = False`).\nVeřejný originál zůstává 100% nedotčený.", "operationId": "fork_world_v1_worlds__world_id__fork_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "world_id", "in": "path", "required": true, "schema": { "type": "string", "title": "World Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ForkWorldRequest" }, { "type": "null" } ], "title": "Req" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/worlds/{world_id}/ingest": { "post": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Ingest Into World Via Axiomat", "description": "Live Axiomat Ingest API (pro AI inženýry, databázové triggery, webhooky i UI Studio):\nPřijímá buď:\n1) `application/json`: `{\"text\": \"...\", \"payload\": {...}, \"source_reference\": \"DB:row#12\", \"on_conflict\": \"flag\" | \"replace\" | \"keep\"}`\n2) `multipart/form-data`: `file` (PDF/DOCX/TXT/MD) nebo `raw_text`, `source_reference`, `on_conflict`.\n\n- Pokud `world_id` odkazuje na veřejný/oficiální svět, který uživateli nepatří, automaticky vytvoří/použije\n jeho soukromý fork v jeho účtu (veřejný svět se nikdy nemění!).\n- Spustí 2-fázovou extrakci v Axiomatu + JEV 6-bodový epistemický audit.\n- Zrekonciliuje nové axiomy se stávajícími axiomy ve světě (automatická deduplikace + detekce kolizí s příznakem `flagged_for_review` nebo přepisem `replace`).", "operationId": "ingest_into_world_via_axiomat_v1_worlds__world_id__ingest_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "world_id", "in": "path", "required": true, "schema": { "type": "string", "title": "World Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/worlds/{world_id}/axiomat/ingest": { "post": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Ingest Into World Via Axiomat", "description": "Live Axiomat Ingest API (pro AI inženýry, databázové triggery, webhooky i UI Studio):\nPřijímá buď:\n1) `application/json`: `{\"text\": \"...\", \"payload\": {...}, \"source_reference\": \"DB:row#12\", \"on_conflict\": \"flag\" | \"replace\" | \"keep\"}`\n2) `multipart/form-data`: `file` (PDF/DOCX/TXT/MD) nebo `raw_text`, `source_reference`, `on_conflict`.\n\n- Pokud `world_id` odkazuje na veřejný/oficiální svět, který uživateli nepatří, automaticky vytvoří/použije\n jeho soukromý fork v jeho účtu (veřejný svět se nikdy nemění!).\n- Spustí 2-fázovou extrakci v Axiomatu + JEV 6-bodový epistemický audit.\n- Zrekonciliuje nové axiomy se stávajícími axiomy ve světě (automatická deduplikace + detekce kolizí s příznakem `flagged_for_review` nebo přepisem `replace`).", "operationId": "ingest_into_world_via_axiomat_v1_worlds__world_id__axiomat_ingest_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "world_id", "in": "path", "required": true, "schema": { "type": "string", "title": "World Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/worlds/{world_id}/axioms/push": { "post": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Push Axioms Batch", "description": "Direct Structured Axiom Push (0 LLM tokenů, okamžitá odezva):\nUmožňuje AI inženýrům posílat z databázových triggerů nebo agentních pipeline již zformulované věty\n(jednotlivě nebo v dávce `axioms: [...]`).\n- Automaticky provede deterministickou sanitizaci (DLP, XSS, délka, kanonická interpunkce).\n- Pokud cílí na cizí veřejný svět, automaticky vytvoří/použije privátní fork v účtu daného uživatele.\n- Odfiltruje duplicity a při kolizi nastaví příznak `flagged_for_review = True` (nebo přepíše starý axiom při `on_conflict=\"replace\"`).", "operationId": "push_axioms_batch_v1_worlds__world_id__axioms_push_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "world_id", "in": "path", "required": true, "schema": { "type": "string", "title": "World Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushAxiomsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/worlds/my": { "get": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Get My Worlds", "description": "Returns all Small Worlds created or forked by the authenticated user,\nplus revenue statistics.", "operationId": "get_my_worlds_v1_worlds_my_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/worlds": { "get": { "tags": [ "Small Worlds & Axiomat" ], "summary": "List Worlds", "description": "Lists public worlds in the Library Explorer with search, domain, and tag filtering.\nMerges custom database worlds with Syntropy Official Verified worlds.\nPrivate user worlds and private forks (`is_public = False`) are strictly excluded.", "operationId": "list_worlds_v1_worlds_get", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "domain", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain" } }, { "name": "tag", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tag" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/worlds/public": { "get": { "tags": [ "Small Worlds & Axiomat" ], "summary": "List Worlds", "description": "Lists public worlds in the Library Explorer with search, domain, and tag filtering.\nMerges custom database worlds with Syntropy Official Verified worlds.\nPrivate user worlds and private forks (`is_public = False`) are strictly excluded.", "operationId": "list_worlds_v1_worlds_public_get", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "domain", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain" } }, { "name": "tag", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tag" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/worlds/{world_id}/axioms": { "get": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Get World Axioms", "description": "Returns list of axioms for a given world including id and review flag.\nEnforces privacy: if world is private, only the authenticated author (via JWT or X-API-Key) can access it.", "operationId": "get_world_axioms_v1_worlds__world_id__axioms_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "world_id", "in": "path", "required": true, "schema": { "type": "string", "title": "World Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Add Axiom", "description": "Author (or API key holder) can add a new axiom to their world (or auto-fork a public world).\nIncludes sanitization, deduplication, and conflict detection.", "operationId": "add_axiom_v1_worlds__world_id__axioms_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "world_id", "in": "path", "required": true, "schema": { "type": "string", "title": "World Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAxiomRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/worlds/{world_id}/axioms/{axiom_id}": { "put": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Update Axiom", "description": "Author can update axiom text, source, or toggle 'flagged_for_review' (with DLP & XSS sanitization).", "operationId": "update_axiom_v1_worlds__world_id__axioms__axiom_id__put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "world_id", "in": "path", "required": true, "schema": { "type": "string", "title": "World Id" } }, { "name": "axiom_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Axiom Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAxiomRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Delete Axiom", "description": "Author can delete an axiom from the world.", "operationId": "delete_axiom_v1_worlds__world_id__axioms__axiom_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "world_id", "in": "path", "required": true, "schema": { "type": "string", "title": "World Id" } }, { "name": "axiom_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Axiom Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/worlds/{world_id}": { "patch": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Update World Metadata", "description": "Author can toggle visibility (Public vs Private) or update world metadata (title, description, domain, keywords, price).", "operationId": "update_world_metadata_v1_worlds__world_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "world_id", "in": "path", "required": true, "schema": { "type": "string", "title": "World Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorldRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/worlds/{world_id}/export": { "get": { "tags": [ "Small Worlds & Axiomat" ], "summary": "Export World Json", "description": "Exports clean JSON structure of a Small World with its axioms.\nEnforces privacy: private worlds can only be exported by their author (via JWT or X-API-Key).", "operationId": "export_world_json_v1_worlds__world_id__export_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "world_id", "in": "path", "required": true, "schema": { "type": "string", "title": "World Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/models": { "get": { "tags": [ "OpenAI & OpenRouter Bridge" ], "summary": "List Openai Compatible Models", "description": "Lists Syntropy JEV epistemic models and supported multi-model backends\nin standard OpenAI / OpenRouter `/v1/models` format.", "operationId": "list_openai_compatible_models_v1_models_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/chat/completions": { "post": { "tags": [ "OpenAI & OpenRouter Bridge" ], "summary": "Create Chat Completion", "description": "OpenAI & OpenRouter compatible `/v1/chat/completions` endpoint.\nAllows any OpenAI SDK client, LangChain/LlamaIndex agent, Cursor, or OpenRouter consumer\nto call Syntropy JEV as a drop-in model (`model=\"syntropy/jev-epistemic-verifier\"`).", "operationId": "create_chat_completion_v1_chat_completions_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-LLM-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Llm-Api-Key" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "X-Syntropy-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Syntropy-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/health": { "get": { "summary": "Health Check", "operationId": "health_check_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/skill.md": { "get": { "summary": "Serve Skill Md", "description": "Slouží SKILL.md přímo z API serveru pro autonomní AI agenty.", "operationId": "serve_skill_md_skill_md_get", "responses": { "200": { "description": "Successful Response", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/SKILL.md": { "get": { "summary": "Serve Skill Md", "description": "Slouží SKILL.md přímo z API serveru pro autonomní AI agenty.", "operationId": "serve_skill_md_SKILL_md_get", "responses": { "200": { "description": "Successful Response", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/llms.txt": { "get": { "summary": "Serve Llms Txt", "description": "Slouží llms.txt přímo z API serveru pro autonomní AI agenty.", "operationId": "serve_llms_txt_llms_txt_get", "responses": { "200": { "description": "Successful Response", "content": { "text/plain": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "AxiomModel": { "properties": { "statement": { "type": "string", "title": "Statement" }, "source_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Reference", "default": "Dokument" }, "logical_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logical Type", "default": "INVARIANT" } }, "type": "object", "required": [ "statement" ], "title": "AxiomModel" }, "Body_process_axiomat_v1_axiomat_extract_post": { "properties": { "file": { "anyOf": [ { "type": "string", "contentMediaType": "application/octet-stream" }, { "type": "null" } ], "title": "File" }, "raw_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Raw Text" }, "title": { "type": "string", "title": "Title" }, "description": { "type": "string", "title": "Description" }, "domain": { "type": "string", "title": "Domain" }, "keywords": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Keywords", "default": "" }, "price_per_use": { "type": "number", "title": "Price Per Use", "default": 0.05 }, "is_public": { "type": "boolean", "title": "Is Public", "default": true } }, "type": "object", "required": [ "title", "description", "domain" ], "title": "Body_process_axiomat_v1_axiomat_extract_post" }, "Body_process_axiomat_v1_worlds_axiomat_process_post": { "properties": { "file": { "anyOf": [ { "type": "string", "contentMediaType": "application/octet-stream" }, { "type": "null" } ], "title": "File" }, "raw_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Raw Text" }, "title": { "type": "string", "title": "Title" }, "description": { "type": "string", "title": "Description" }, "domain": { "type": "string", "title": "Domain" }, "keywords": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Keywords", "default": "" }, "price_per_use": { "type": "number", "title": "Price Per Use", "default": 0.05 }, "is_public": { "type": "boolean", "title": "Is Public", "default": true } }, "type": "object", "required": [ "title", "description", "domain" ], "title": "Body_process_axiomat_v1_worlds_axiomat_process_post" }, "Body_upload_world_v1_world_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_world_v1_world_post" }, "ChatCompletionRequest": { "properties": { "model": { "type": "string", "title": "Model", "default": "syntropy/epistemic-verifier" }, "messages": { "items": { "$ref": "#/components/schemas/ChatMessage" }, "type": "array", "title": "Messages" }, "stream": { "type": "boolean", "title": "Stream", "default": false }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Temperature", "default": 0.0 }, "max_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Tokens", "default": 2048 }, "world": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "World" }, "initial_axioms": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Initial Axioms" }, "max_failures": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Failures" }, "enable_research": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enable Research" }, "underlying_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Underlying Model" }, "allowed_source_types": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Source Types" } }, "additionalProperties": true, "type": "object", "required": [ "messages" ], "title": "ChatCompletionRequest" }, "ChatMessage": { "properties": { "role": { "type": "string", "title": "Role" }, "content": { "anyOf": [ { "type": "string" }, { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } ], "title": "Content" } }, "additionalProperties": true, "type": "object", "required": [ "role", "content" ], "title": "ChatMessage" }, "CreateApiKeyRequest": { "properties": { "name": { "type": "string", "title": "Name", "default": "Production Key" }, "key_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key Type", "default": "managed" } }, "type": "object", "title": "CreateApiKeyRequest" }, "CreateApiKeyResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "key_type": { "type": "string", "title": "Key Type" }, "raw_key": { "type": "string", "title": "Raw Key" }, "message": { "type": "string", "title": "Message", "default": "Tento klíč se zobrazí POUZE JEDNOU. Ihned si ho zkopírujte." } }, "type": "object", "required": [ "id", "name", "key_type", "raw_key" ], "title": "CreateApiKeyResponse" }, "CreateAxiomRequest": { "properties": { "statement": { "type": "string", "title": "Statement" }, "source_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Reference", "default": "Manuálně přidáno" }, "flagged_for_review": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Flagged For Review", "default": false }, "logical_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logical Type", "default": "INVARIANT" }, "on_conflict": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "On Conflict", "default": "flag" } }, "type": "object", "required": [ "statement" ], "title": "CreateAxiomRequest" }, "CreateCheckoutRequest": { "properties": { "amount_usd": { "type": "number", "maximum": 1000.0, "minimum": 5.0, "title": "Amount Usd", "description": "Amount in USD to recharge (min $5, max $1000)" }, "success_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Success Url" }, "cancel_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cancel Url" } }, "type": "object", "required": [ "amount_usd" ], "title": "CreateCheckoutRequest" }, "CreateCheckoutResponse": { "properties": { "checkout_url": { "type": "string", "title": "Checkout Url" }, "session_id": { "type": "string", "title": "Session Id" } }, "type": "object", "required": [ "checkout_url", "session_id" ], "title": "CreateCheckoutResponse" }, "DebateRequest": { "properties": { "thesis": { "type": "string", "title": "Thesis", "description": "The main thesis to debate" }, "initial_axioms": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Initial Axioms", "description": "List of axioms to use as a source of truth" }, "world": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "World", "description": "Identifier of the small world to fetch axioms from (e.g. '@law:sample_v1')" }, "max_failures": { "type": "integer", "title": "Max Failures", "description": "Max failed attempts before giving up", "default": 6 }, "enable_research": { "type": "boolean", "title": "Enable Research", "description": "Enable external research tools", "default": true }, "model_name": { "type": "string", "title": "Model Name", "description": "LLM model to use", "default": "gemini-2.5-flash" }, "llm_provider": { "type": "string", "title": "Llm Provider", "description": "LLM provider (gemini, openrouter)", "default": "gemini" }, "allowed_source_types": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Source Types", "description": "Allowed sources for research" } }, "type": "object", "required": [ "thesis" ], "title": "DebateRequest" }, "EstimateRequest": { "properties": { "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "text" ], "title": "EstimateRequest" }, "ForkWorldRequest": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "force_new": { "type": "boolean", "title": "Force New", "default": false } }, "type": "object", "title": "ForkWorldRequest" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "PushAxiomsRequest": { "properties": { "axioms": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AxiomModel" }, "type": "array" }, { "type": "null" } ], "title": "Axioms" }, "statement": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Statement" }, "source_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Reference", "default": "API Live Sync" }, "logical_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logical Type", "default": "INVARIANT" }, "on_conflict": { "type": "string", "title": "On Conflict", "default": "flag" } }, "type": "object", "title": "PushAxiomsRequest" }, "UpdateApiKeyRequest": { "properties": { "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "type": "object", "title": "UpdateApiKeyRequest" }, "UpdateAxiomRequest": { "properties": { "axiom_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Axiom Text" }, "source_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Ref" }, "flagged_for_review": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Flagged For Review" }, "logical_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logical Type" } }, "type": "object", "title": "UpdateAxiomRequest" }, "UpdateWorldRequest": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain" }, "keywords": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Keywords" }, "price_per_use": { "anyOf": [ { "type": "number", "maximum": 50.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Price Per Use" }, "is_public": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Public" } }, "type": "object", "title": "UpdateWorldRequest" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VerifySessionRequest": { "properties": { "session_id": { "type": "string", "title": "Session Id" } }, "type": "object", "required": [ "session_id" ], "title": "VerifySessionRequest" }, "VerifySessionResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "credited": { "type": "boolean", "title": "Credited" }, "amount_usd": { "type": "number", "title": "Amount Usd" }, "new_balance": { "type": "number", "title": "New Balance" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" } }, "type": "object", "required": [ "status", "credited", "amount_usd", "new_balance" ], "title": "VerifySessionResponse" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } }, "servers": [ { "url": "https://api.synproof.ai", "description": "Synproof's Syntropy Production API" }, { "url": "https://synproof.ai", "description": "Synproof's Syntropy Web & Static Discovery Host" } ] }