{"openapi":"3.1.0","info":{"title":"NeuralRing API","version":"0.13.0","description":"Sovereign EU inference gateway — OpenAI-compatible, with a signed sovereignty attestation per request. Every sovereignty signal states its substantiated assurance level; unmeasured numbers are absent, never invented."},"servers":[{"url":"https://neuralring.eu","description":"Production (canonical apex — openrouter.ai/api/v1 parity)"},{"url":"https://api.neuralring.eu","description":"Production (DEPRECATED alias — kept indefinitely; new integrations should use the apex)"},{"url":"http://localhost:4000","description":"Local dev — control plane (gateway on :4001)"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"SovereigntyPolicy":{"type":"object","properties":{"jurisdiction":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Hard pin: only endpoints with a data center in these ISO-3166 alpha-2 jurisdictions are eligible. Applied FIRST; never loosened by any preference or variant."},"min_tier":{"type":"integer","minimum":0,"maximum":3},"min_assurance":{"type":"string","enum":["self_attested","verified","certified"]},"exclude_parent_jurisdictions":{"type":"array","items":{"type":"string"}}}},"ChatMessage":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant","tool"]},"content":{},"name":{"type":"string"},"tool_call_id":{"type":"string"}},"required":["role"]},"ChatCompletionRequest":{"type":"object","properties":{"model":{"type":"string","example":"mistralai/mistral-small-2501"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}},"stream":{"type":"boolean"},"temperature":{"type":"number"},"top_p":{"type":"number"},"max_tokens":{"type":"integer"},"stop":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"seed":{"type":"integer"},"tools":{"type":"array","items":{}},"tool_choice":{},"response_format":{},"models":{"type":"array","items":{"type":"string"},"description":"Ordered fallback list (OpenRouter parity)."},"provider":{"type":"object","properties":{"order":{"type":"array","items":{"type":"string"}},"only":{"type":"array","items":{"type":"string"}},"ignore":{"type":"array","items":{"type":"string"}},"allow_fallbacks":{"type":"boolean"},"sort":{"type":"string","enum":["price","throughput","latency"]}}},"sovereignty":{"$ref":"#/components/schemas/SovereigntyPolicy"},"locale":{"type":"string"},"quorum":{"type":"object","properties":{"max_turns":{"type":"integer","minimum":3,"maximum":12}},"description":"Phase 14: options for model 'neuralring/quorum' (Thinker→Worker→Verifier over the pinned-eligible pool; non-streaming; server turn ceiling 6). Response carries x-neuralring-quorum-* headers and the full trajectory; budget_exhausted is flagged honestly."}},"required":["model","messages"]},"EmbeddingsRequest":{"type":"object","properties":{"model":{"type":"string","example":"dev/embed-de"},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"integer"}},{"type":"array","items":{"type":"array","items":{"type":"integer"}}}],"description":"string | string[] | token array | token arrays (OpenAI parity). Batch inputs meter as the sum of their tokens."},"dimensions":{"type":"integer","exclusiveMinimum":0},"encoding_format":{"type":"string","enum":["float","base64"]},"models":{"type":"array","items":{"type":"string"},"description":"Ordered fallback list."},"provider":{"type":"object","properties":{"order":{"type":"array","items":{"type":"string"}},"only":{"type":"array","items":{"type":"string"}},"ignore":{"type":"array","items":{"type":"string"}},"allow_fallbacks":{"type":"boolean"},"sort":{"type":"string","enum":["price","throughput","latency"]}}},"sovereignty":{"$ref":"#/components/schemas/SovereigntyPolicy"},"locale":{"type":"string"}},"required":["model","input"]},"ErrorEnvelope":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","description":"Normalized code: auth | rate_limit | context_length | content_filter | upstream_timeout | no_eligible_endpoint | invalid_request | insufficient_credits | spend_cap_exceeded | key_revoked | byok_invalid | forbidden | not_implemented | internal"},"code":{"type":"string"}},"required":["message","type","code"]}},"required":["error"]},"SignUp":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8},"name":{"type":"string"},"orgName":{"type":"string"},"defaultJurisdiction":{"type":"array","items":{"type":"string"}}},"required":["email","password"]},"CreateApiKey":{"type":"object","properties":{"name":{"type":"string"},"spendCapCredits":{"type":"number"},"modelFilter":{"type":"array","items":{"type":"string"}},"jurisdictionFilter":{"type":"array","items":{"type":"string"},"description":"May only NARROW the org default, never widen it."}},"required":["name"]}},"parameters":{}},"paths":{"/api/v1/chat/completions":{"post":{"summary":"OpenAI-compatible chat completion (streams with stream:true). Response carries x-neuralring-* attestation headers.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"Completion (OpenAI shape) + `neuralring` routing summary"},"4XX":{"description":"Normalized error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/messages":{"post":{"summary":"Anthropic Messages-compatible surface (fallbacks ≤3, model-only entries).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Anthropic-shaped completion"},"4XX":{"description":"Normalized error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/embeddings":{"post":{"summary":"OpenAI-compatible embeddings — the sovereignty pin applies FIRST (no non-sovereign fallback, ever); every request emits a signed content-free attestation and meters input tokens.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingsRequest"}}}},"responses":{"200":{"description":"OpenAI embeddings list + `neuralring` routing summary; x-neuralring-* attestation headers"},"4XX":{"description":"Normalized error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/models":{"get":{"summary":"Catalog with honest sovereignty blocks; filters: jurisdiction, min_tier, min_assurance, min_seal, capability, language, backed_by.","responses":{"200":{"description":"Model catalog"}}}},"/api/v1/models/{slug}/endpoints":{"get":{"summary":"Every endpoint serving a model, with per-endpoint sovereignty + MEASURED stats (or 'not yet measured').","responses":{"200":{"description":"Endpoint list"},"4XX":{"description":"Normalized error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/providers":{"get":{"summary":"Sovereign provider directory with live health.","responses":{"200":{"description":"Providers"}}}},"/api/v1/attestations/{requestId}":{"get":{"summary":"One signed, hash-chained attestation (public — the requestId is the capability).","responses":{"200":{"description":"Attestation record"},"4XX":{"description":"Normalized error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/attestations/export":{"get":{"summary":"Signed export bundle for a date range (?from=&to=) — verify offline with scripts/verify-attestations.mjs.","responses":{"200":{"description":"Bundle"}}}},"/api/v1/attestations/public-key":{"get":{"summary":"Ed25519 public key for attestation verification.","responses":{"200":{"description":"PEM public key"}}}},"/api/v1/badge/{requestId}.svg":{"get":{"summary":"README badge for one attested request; copy tracks the REAL assurance level.","responses":{"200":{"description":"SVG"}}}},"/api/v1/auth/signup":{"post":{"summary":"Create an account + org (50-credit free tier granted automatically; verification email sent).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignUp"}}}},"responses":{"200":{"description":"sessionToken + user + org"},"4XX":{"description":"Normalized error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/auth/signin":{"post":{"summary":"Sign in.","responses":{"200":{"description":"sessionToken"},"4XX":{"description":"Normalized error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/keys":{"post":{"summary":"Create an API key (rawKey shown once).","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKey"}}}},"responses":{"200":{"description":"rawKey + key metadata"},"4XX":{"description":"Normalized error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"summary":"List keys (hashed; never the secret).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Keys"}}}},"/api/v1/activity":{"get":{"summary":"Recent requests (metadata only; each row links to its attestation).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Activity"}}}},"/api/v1/usage":{"get":{"summary":"Usage rollups by day.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Rollups"}}}},"/api/v1/credits/topup":{"post":{"summary":"Request a manual top-up (operator credits + invoice; no card, no automatic charge — money movement is human-gated).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice + balance"},"4XX":{"description":"Normalized error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/offers":{"get":{"summary":"Every way to get a model, as ranked comparable offers (flat-price capacity / pay-as-you-go / hire-the-provider / BYOK). Filters: model, jurisdiction, min_tier, min_assurance. Each offer states honestly whether its guarantee is a pool's contractual policy or your per-request pin.","responses":{"200":{"description":"Ranked offers, easiest first"}}}},"/api/v1/purchases":{"post":{"summary":"Accept an offer in ONE call — subscribes/contracts as needed and returns the exact model slug plus working curl/python/typescript snippets. Never bypasses a human gate (first-contract and above-limit contracts hold for approval).","security":[{"bearerAuth":[]}],"responses":{"201":{"description":"status + requestAs + snippets"},"4XX":{"description":"Normalized error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/capacity/pools":{"get":{"summary":"Flat-price capacity pools: published price, guaranteed sovereignty policy, member COUNT and assurance floor — never member pricing. Upcoming price versions expose the reprice-notice window.","responses":{"200":{"description":"Pools"}}}},"/api/v1/capacity/subscriptions":{"post":{"summary":"Subscribe the org to a capacity pool (then request model `capacity/<pool-slug>`).","security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Subscription"},"4XX":{"description":"Normalized error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/contracts":{"post":{"summary":"Hire a provider through NeuralRing (Mode B): pass-through pricing, one invoice, spend cap, evidence-backed provisioning. Sovereignty is checked at CONTRACT time and downgrades auto-suspend.","security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Contract (may await human approval)"},"4XX":{"description":"Normalized error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"summary":"The org's provider contracts with full actor-stamped status history.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Contracts"}}}},"/api/v1/billing/statement":{"get":{"summary":"ONE statement across all purchase modes (?from&to; &format=pdf): one fee line per mode, capacity margin disclosed per pool, quorum coordination fee named separately.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Statement (JSON or PDF)"}}}}},"webhooks":{}}