{"openapi":"3.1.0","info":{"title":"Oxyo Developer & Verification API","version":"1.1.0","summary":"OpenAI-compatible verification API, persistent XY Informational DNA memory, and remote MCP server.","description":"Programmatic REST and Streamable HTTP MCP interface for Oxyo (`oxyo.si`). Provides OpenAI SDK drop-in completions (`/v1/chat/completions`), contradiction-free belief revision (`/api/v1/beliefs`), deterministic isolated Python execution (`/api/v1/verify-code`), formal constraint proving (`/api/v1/prove`), causal graph recording (`/api/v1/causal`), and 15 persistent Model Context Protocol tools (`/mcp`). Rate limits: 120 requests/minute per tenant API key; 60 requests/minute per IP on unauthenticated discovery.","contact":{"name":"Oxyo Developer Support (OMNIAMUS S.R.L.)","url":"https://oxyo.si/contact","email":"contact@oxyo.si"},"termsOfService":"https://oxyo.si/privacy"},"servers":[{"url":"https://oxyo.si","description":"Oxyo Production Server (HTTPS)"}],"tags":[{"name":"Discovery","description":"Public health, pricing, and model discovery endpoints."},{"name":"OpenAI-Compatible","description":"Drop-in OpenAI SDK `/v1/models` and `/v1/chat/completions` endpoints."},{"name":"Verification & Memory","description":"Deterministic Python sandbox, formal constraint prover, and XY Informational DNA vault."},{"name":"MCP","description":"Streamable HTTP Model Context Protocol (JSON-RPC 2.0) server."}],"paths":{"/api/health":{"get":{"operationId":"getServiceHealth","tags":["Discovery"],"summary":"Check Oxyo API health status","description":"Unauthenticated liveness probe returning operational status of `oxyo.si`.","responses":{"200":{"description":"Service is healthy and accepting requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/plans":{"get":{"operationId":"listSubscriptionPlans","tags":["Discovery"],"summary":"List Oxyo subscription tiers and supported BYOK providers","description":"Returns public plan specifications (Core, Pro, and Max — monthly & annual -20%) and supported upstream BYOK providers (Anthropic Claude, OpenAI, OpenRouter, Fireworks).","responses":{"200":{"description":"Catalog of available plans and BYOK provider descriptors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlansCatalogResponse"}}}}}}},"/v1/models":{"get":{"operationId":"listModels","tags":["OpenAI-Compatible"],"summary":"List available Oxyo verification and reasoning models","description":"OpenAI SDK-compatible model catalog (`oxyo-auto`, `oxyo-asi`, `oxyo-swarm`, `oxyo-verified`, `oxyo-deep`, `oxyo-fast`). Publicly readable without authentication; validates Bearer key if supplied.","responses":{"200":{"description":"OpenAI-compatible list of model descriptors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelListResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/v1/chat/completions":{"post":{"operationId":"createChatCompletion","tags":["OpenAI-Compatible"],"summary":"Create a verified chat completion grounded in persistent XY Informational DNA","description":"Drop-in OpenAI `/v1/chat/completions` endpoint supporting synchronous JSON and `stream: true` Server-Sent Events, multimodal `image_url` inputs, file `attachments`, and `oxyo` verification metadata. Rate limit: 120 req/min.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"Completed assistant message with token usage and Oxyo verification metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"429":{"$ref":"#/components/responses/RateLimitError"}}}},"/api/v1/interact":{"post":{"operationId":"interactWithOxyo","tags":["Verification & Memory"],"summary":"Send a native prompt to your persistent Oxyo tenant vault","description":"Executes a turn with automatic recall of contradiction-free beliefs, episodic context, causal rules, and optional deterministic sandbox verification.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InteractRequest"}}}},"responses":{"200":{"description":"Verified response, active thread list, and current budget status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InteractResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/api/v1/beliefs":{"post":{"operationId":"rememberBelief","tags":["Verification & Memory"],"summary":"Store a durable fact and automatically supersede contradicting older claims","description":"Persists an atomic rule, architectural invariant, or business parameter in the tenant's XY Informational DNA vault while automatically superseding stale contradictions within the same scope.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeliefRequest"}}}},"responses":{"200":{"description":"Stored belief identifier and list of superseded belief IDs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeliefResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/api/v1/causal":{"post":{"operationId":"recordCausalEdge","tags":["Verification & Memory"],"summary":"Record a directed cause-and-effect relationship in the tenant causal graph","description":"Persists an empirical `cause -> effect` engineering or operational link for multi-hop root-cause and intervention queries.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CausalEdgeRequest"}}}},"responses":{"200":{"description":"Recorded causal edge descriptor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CausalEdgeResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/api/v1/verify-code":{"post":{"operationId":"verifyPythonCode","tags":["Verification & Memory"],"summary":"Execute deterministic Python inside Oxyo's isolated verification sandbox","description":"Runs pure algorithmic, financial (`decimal.Decimal`), combinatorial, or audit code in a zero-network, AST-guarded sandbox and returns `RESULT` and `stdout`.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyCodeRequest"}}}},"responses":{"200":{"description":"Deterministic execution result and captured standard output.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyCodeResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/api/v1/prove":{"post":{"operationId":"proveOrSatisfyConstraints","tags":["Verification & Memory"],"summary":"Prove a universal mathematical/invariant claim or optimize discrete constraints","description":"Solves discrete constraint satisfaction/optimization (`action: satisfy`) or verifies universal implications (`action: prove`), returning an exact witness or counterexample.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProveConstraintsRequest"}}}},"responses":{"200":{"description":"Proof verdict, witness assignment, or counterexample.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProveConstraintsResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/api/v1/state":{"get":{"operationId":"getTenantVaultState","tags":["Verification & Memory"],"summary":"Inspect active beliefs, revision history, causal edges, and reusable skills","description":"Returns a sanitized snapshot of the authenticated tenant's active XY Informational DNA vault and 30-day token/MCP allowance.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Current tenant vault state and usage summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultStateResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/mcp":{"post":{"operationId":"invokeMcpJsonRpc","tags":["MCP"],"summary":"Streamable HTTP Model Context Protocol (JSON-RPC 2.0) endpoint","description":"Hosted MCP endpoint exposing 15 persistent memory, verification, causal, and goal-planning tools. Unauthenticated `initialize`, `ping`, and `tools/list` requests are permitted for IDE & registry discovery (60 req/min/IP). `tools/call` requires `Authorization: Bearer oxy_live_...` (120 req/min/tenant).","security":[{},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpJsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpJsonRpcResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"429":{"$ref":"#/components/responses/RateLimitError"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"oxy_live_<token>","description":"Generate an API key (`oxy_live_...`) at https://oxyo.si/app (Explorer includes 50 free MCP calls)."}},"responses":{"UnauthorizedError":{"description":"Missing, invalid, or revoked Oxyo API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimitError":{"description":"Sliding-window rate limit exceeded (retry after 60 seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","required":["detail"],"properties":{"detail":{"type":"string","description":"Human-readable error explanation."}}},"HealthResponse":{"type":"object","required":["ok","service","status"],"properties":{"ok":{"type":"boolean"},"service":{"type":"string","examples":["oxyo.si"]},"status":{"type":"string","examples":["operational"]}}},"PlansCatalogResponse":{"type":"object","required":["plans","byok_providers"],"properties":{"plans":{"type":"array","items":{"type":"object"}},"byok_providers":{"type":"array","items":{"type":"object"}}}},"ModelDescriptor":{"type":"object","required":["id","object","owned_by","description"],"properties":{"id":{"type":"string","examples":["oxyo-verified"]},"object":{"type":"string","examples":["model"]},"created":{"type":"integer"},"owned_by":{"type":"string","examples":["oxyo"]},"description":{"type":"string"}}},"ModelListResponse":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","examples":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ModelDescriptor"}}}},"ChatMessage":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","developer","user","assistant"]},"content":{"type":"string","description":"Message text content."}}},"ChatCompletionRequest":{"type":"object","required":["messages"],"properties":{"model":{"type":"string","default":"oxyo-auto","enum":["oxyo-auto","oxyo-asi","oxyo-swarm","oxyo-verified","oxyo-deep","oxyo-fast"],"description":"Reasoning and verification profile."},"messages":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ChatMessage"}},"stream":{"type":"boolean","default":false},"thread_id":{"type":["string","null"],"description":"Optional persistent thread ID."}}},"ChatCompletionResponse":{"type":"object","required":["id","object","created","model","choices","usage"],"properties":{"id":{"type":"string"},"object":{"type":"string","examples":["chat.completion"]},"created":{"type":"integer"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object"}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}},"oxyo":{"type":"object","description":"Deterministic verification status, result, and recall counters.","properties":{"mode":{"type":"string"},"verified":{"type":"boolean"},"verified_result":{},"recalled_count":{"type":"integer"},"beliefs_count":{"type":"integer"}}}}},"InteractRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":24000},"mode":{"type":"string","default":"auto","enum":["auto","fast","deep","verified","asi","swarm"]},"thread_id":{"type":["string","null"]}}},"InteractResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"text":{"type":"string"},"verified":{"type":"boolean"},"verified_result":{},"thread_id":{"type":"string"}}},"BeliefRequest":{"type":"object","required":["claim"],"properties":{"claim":{"type":"string","minLength":3,"maxLength":2000},"confidence":{"type":"number","minimum":0.05,"maximum":1.0,"default":0.92},"scope":{"type":"string","default":"global","maxLength":80}}},"BeliefResponse":{"type":"object","properties":{"belief_id":{"type":"string"},"claim":{"type":"string"},"superseded_ids":{"type":"array","items":{"type":"string"}}}},"CausalEdgeRequest":{"type":"object","required":["cause","effect"],"properties":{"cause":{"type":"string","minLength":1,"maxLength":160},"effect":{"type":"string","minLength":1,"maxLength":160},"action":{"type":"string","default":"intervene","maxLength":80},"polarity":{"type":"integer","enum":[-1,1],"default":1},"scope":{"type":"string","default":"global","maxLength":80}}},"CausalEdgeResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"edge":{"type":"object"}}},"VerifyCodeRequest":{"type":"object","required":["code"],"properties":{"code":{"type":"string","minLength":1,"maxLength":16000,"description":"Self-contained Python snippet assigning its final output to `RESULT`."},"timeout_s":{"type":"number","minimum":0.5,"maximum":8.0,"default":4.0}}},"VerifyCodeResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"result":{"description":"JSON-serialized value of `RESULT`."},"stdout":{"type":"string"},"error":{"type":["string","null"]}}},"ProveConstraintsRequest":{"type":"object","required":["variables"],"properties":{"action":{"type":"string","enum":["prove","satisfy"],"default":"prove"},"variables":{"type":"object","description":"Map of variable names to integer `[min, max]` bounds or discrete domain lists."},"claim":{"type":"string","default":""},"assumptions":{"type":"array","items":{"type":"string"}},"constraints":{"type":"array","items":{"type":"string"}},"objective":{"type":["string","null"]},"sense":{"type":"string","enum":["minimize","maximize"],"default":"minimize"}}},"ProveConstraintsResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":"string"},"witness":{"type":["object","null"]},"counterexample":{"type":["object","null"]},"objective_value":{"type":["number","null"]}}},"VaultStateResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"active_beliefs":{"type":"array","items":{"type":"object"}},"revisions":{"type":"array","items":{"type":"object"}},"causal_edges":{"type":"array","items":{"type":"object"}},"skills":{"type":"array","items":{"type":"object"}}}},"McpJsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":["string","integer","null"]},"method":{"type":"string","examples":["initialize","tools/list","tools/call","ping"]},"params":{"type":"object"}}},"McpJsonRpcResponse":{"type":"object","required":["jsonrpc","id"],"properties":{"jsonrpc":{"type":"string","examples":["2.0"]},"id":{"type":["string","integer","null"]},"result":{"type":"object"},"error":{"type":"object"}}}}}}