{"openapi":"3.1.0","info":{"title":"ColdState API","version":"0.1.0","summary":"Deterministic Knowledge Infrastructure for AI agents","description":"Deterministic, verifiable knowledge retrieval. Global knowledge base (48M entries, 35 domains) with fetch / cite / verify primitives, plus zero-knowledge custom indexes. Identical query + kb_snapshot ⇒ identical results. Also exposed as an MCP server at /mcp (Streamable HTTP, stateless).","termsOfService":"https://services.coldstate.ai/terms","contact":{"name":"ColdState","url":"https://services.coldstate.ai","email":"daniel@coldstate.ai"}},"externalDocs":{"description":"Human-readable API reference","url":"https://services.coldstate.ai/docs"},"servers":[{"url":"https://cold-api.coldstate.ai"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Knowledge","description":"Global knowledge base: search, fetch, cite, verify, related, resolve"},{"name":"Indexes","description":"Zero-knowledge custom indexes"},{"name":"Search","description":"Search custom indexes"},{"name":"Auth","description":"Accounts, sessions, API keys"},{"name":"Usage","description":"Metering"},{"name":"Billing","description":"Stripe subscription management"},{"name":"MCP","description":"Model Context Protocol endpoint"},{"name":"Meta","description":"Health and discovery"}],"paths":{"/health":{"get":{"tags":["Meta"],"security":[],"summary":"Liveness","responses":{"200":{"description":"OK"}}}},"/ready":{"get":{"tags":["Meta"],"security":[],"summary":"Readiness (db, redis, tokenizer)","responses":{"200":{"description":"OK"}}}},"/openapi.json":{"get":{"tags":["Meta"],"security":[],"summary":"This document","responses":{"200":{"description":"OK"}}}},"/llms.txt":{"get":{"tags":["Meta"],"security":[],"summary":"llms.txt index","responses":{"200":{"description":"text/markdown"}}}},"/.well-known/mcp/server.json":{"get":{"tags":["Meta"],"security":[],"summary":"MCP registry server.json","responses":{"200":{"description":"OK"}}}},"/mcp":{"post":{"tags":["MCP"],"summary":"MCP Streamable HTTP endpoint (JSON-RPC 2.0)","description":"Stateless Model Context Protocol server. Send `Accept: application/json, text/event-stream`. `initialize` and `tools/list` need no key; `tools/call` forwards your bearer key to the corresponding /v1 route so auth, limits and metering are per customer.","responses":{"200":{"description":"JSON-RPC response (JSON or SSE)"},"401":{"description":"Tool call without a valid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/search/global":{"post":{"tags":["Knowledge"],"summary":"Search the global knowledge base","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalSearchRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalSearchResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/search/domains":{"get":{"tags":["Knowledge"],"summary":"List knowledge domains with counts","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainsResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/knowledge/fetch":{"get":{"tags":["Knowledge"],"summary":"Fetch an entry verbatim by stable id","parameters":[{"name":"id","in":"query","required":true,"description":"Stable entry id, e.g. eng_000229f438f7cebd","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entry"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/knowledge/cite":{"get":{"tags":["Knowledge"],"summary":"Canonical citation for an entry","parameters":[{"name":"id","in":"query","required":true,"description":"Stable entry id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Citation"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/knowledge/verify":{"post":{"tags":["Knowledge"],"summary":"Verify a cited fact is unchanged","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/knowledge/snapshot":{"get":{"tags":["Knowledge"],"summary":"Current knowledge-base snapshot","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Snapshot"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/knowledge/related":{"get":{"tags":["Knowledge"],"summary":"Related entries via the concept-cluster graph","parameters":[{"name":"id","in":"query","required":true,"description":"Stable entry id","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1–50, default 10","schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelatedResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/knowledge/resolve":{"get":{"tags":["Knowledge"],"summary":"Resolve a name/alias to a canonical entry","parameters":[{"name":"query","in":"query","required":true,"description":"Surface form to resolve (≤500 chars)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max alternatives, 1–5","schema":{"type":"integer","minimum":1,"maximum":5}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/knowledge/batch":{"post":{"tags":["Knowledge"],"summary":"Several queries against one snapshot","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/knowledge/stats":{"get":{"tags":["Knowledge"],"summary":"Query coverage stats, or global KB stats","parameters":[{"name":"query","in":"query","required":false,"description":"Optional query","schema":{"type":"string"}},{"name":"domain","in":"query","required":false,"description":"Optional domain filter","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/knowledge/capabilities":{"get":{"tags":["Knowledge"],"summary":"Machine-readable service manifest","responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/knowledge/isomorph":{"get":{"tags":["Knowledge"],"summary":"Cross-domain structural analog of an entry","parameters":[{"name":"id","in":"query","required":true,"description":"Stable entry id","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1–35, default 8","schema":{"type":"integer","minimum":1,"maximum":35}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown id or no analog available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/indexes":{"get":{"tags":["Indexes"],"summary":"List your indexes","responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Indexes"],"summary":"Create an index (async build)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIndexRequest"}}}},"responses":{"202":{"description":"Queued; poll GET /v1/indexes/{index_id}"},"400":{"description":"Validation error or plan limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/indexes/{index_id}":{"get":{"tags":["Indexes"],"summary":"Index detail and status","parameters":[{"name":"index_id","in":"path","required":true,"description":"idx_…","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not your index","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Indexes"],"summary":"Delete an index","parameters":[{"name":"index_id","in":"path","required":true,"description":"idx_…","schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not your index","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/indexes/{index_id}/documents":{"get":{"tags":["Indexes"],"summary":"Browse documents (ref ids + metrics only)","parameters":[{"name":"index_id","in":"path","required":true,"description":"idx_…","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1–100","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"≥0","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Index not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/indexes/{index_id}/download":{"get":{"tags":["Indexes"],"summary":"Download an IaaS index file (single use, 24h TTL)","parameters":[{"name":"index_id","in":"path","required":true,"description":"idx_…","schema":{"type":"string"}}],"responses":{"200":{"description":"application/x-sqlite3"},"400":{"description":"Not an IaaS index / expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/indexes/{index_id}/search":{"post":{"tags":["Search"],"summary":"Search a custom index","parameters":[{"name":"index_id","in":"path","required":true,"description":"idx_…","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexSearchRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexSearchResponse"}}}},"400":{"description":"Validation error or index not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not your index","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/indexes/{index_id}/explain":{"post":{"tags":["Search"],"summary":"Explain why a document ranked for a query","parameters":[{"name":"index_id","in":"path","required":true,"description":"idx_…","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplainRequest"}}}},"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/search":{"post":{"tags":["Search"],"summary":"Search a custom index by collection name","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionSearchRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexSearchResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No index for collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/index":{"post":{"tags":["Indexes"],"summary":"Convenience: create-or-append documents to a collection","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvenienceIndexRequest"}}}},"responses":{"202":{"description":"Queued"},"400":{"description":"Validation error or plan limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/register":{"post":{"tags":["Auth"],"security":[],"summary":"Create an account (returns first API key)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"Validation error / email taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/login":{"post":{"tags":["Auth"],"security":[],"summary":"Log in (returns a dashboard session token)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}},"responses":{"200":{"description":"OK"},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Locked or rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/forgot-password":{"post":{"tags":["Auth"],"security":[],"summary":"Request a password reset email","responses":{"200":{"description":"Always the same message"},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/reset-password":{"post":{"tags":["Auth"],"security":[],"summary":"Consume a reset token","responses":{"200":{"description":"OK"},"400":{"description":"Invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/keys":{"get":{"tags":["Auth"],"summary":"List API keys (prefixes only)","responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/keys/create":{"post":{"tags":["Auth"],"summary":"Create an additional API key","responses":{"201":{"description":"OK"},"400":{"description":"Key limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/keys/rotate":{"post":{"tags":["Auth"],"summary":"Deactivate all keys and issue a new one","responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/keys/{keyId}":{"delete":{"tags":["Auth"],"summary":"Delete a key","parameters":[{"name":"keyId","in":"path","required":true,"description":"key_…","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/keys/{keyId}/deactivate":{"post":{"tags":["Auth"],"summary":"Deactivate a key","parameters":[{"name":"keyId","in":"path","required":true,"description":"key_…","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/logout":{"post":{"tags":["Auth"],"summary":"Revoke the current session","responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"tags":["Usage"],"summary":"Current/last month and all-time usage with plan limits","responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage/history":{"get":{"tags":["Usage"],"summary":"Monthly usage history (12 months)","responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/subscription":{"get":{"tags":["Billing"],"summary":"Current subscription","responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/portal":{"post":{"tags":["Billing"],"summary":"Open the Stripe billing portal","responses":{"200":{"description":"{ url }"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/cancel":{"post":{"tags":["Billing"],"summary":"Cancel at period end","responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/resume":{"post":{"tags":["Billing"],"summary":"Resume a cancelling subscription","responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key `cs_live_…` (or dashboard session `cs_sess_…`)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","message","statusCode"]},"State":{"type":"string","enum":["CRYSTALLINE","FLUID","REACTIVE","DECOHERENT"],"description":"Result confidence state derived from the Ψ score"},"Score":{"type":"object","properties":{"Ψ":{"type":"number","minimum":0,"maximum":1}},"required":["Ψ"]},"StateDistribution":{"type":"object","properties":{"CRYSTALLINE":{"type":"integer"},"FLUID":{"type":"integer"},"REACTIVE":{"type":"integer"},"DECOHERENT":{"type":"integer"}}},"Pagination":{"type":"object","properties":{"offset":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}},"KnowledgeResult":{"type":"object","properties":{"id":{"type":"string","description":"Stable entry id"},"title":{"type":"string"},"snippet":{"type":"string"},"metadata":{"type":"object","properties":{"domain":{"type":"string"},"source":{"type":"string"}}},"score":{"$ref":"#/components/schemas/Score"},"state":{"$ref":"#/components/schemas/State"}}},"GlobalSearchRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","maxLength":2000},"domain":{"type":"string","description":"Optional domain filter, e.g. MEDICINE (case-insensitive)"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":10},"offset":{"type":"integer","minimum":0,"default":0}}},"GlobalSearchResponse":{"type":"object","properties":{"source":{"type":"string","const":"global"},"domain":{"type":["string","null"]},"query":{"type":"string"},"kb_snapshot":{"type":["string","null"],"description":"Pin this to reproduce results later"},"results":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeResult"}},"diagnostics":{"type":"object","properties":{"execution_time_ms":{"type":"number"},"results_count":{"type":"integer"},"state_distribution":{"$ref":"#/components/schemas/StateDistribution"}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"DomainsResponse":{"type":"object","properties":{"domains":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"count":{"type":"integer"}}}}}},"Entry":{"allOf":[{"$ref":"#/components/schemas/KnowledgeResult"},{"type":"object","properties":{"content":{"type":"string"},"content_hash":{"type":"string","description":"sha256 of content"},"kb_snapshot":{"type":["string","null"]},"created_at":{"type":"string"}}}]},"Citation":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"metadata":{"type":"object","properties":{"domain":{"type":"string"},"source":{"type":"string"}}},"content_hash":{"type":"string"},"kb_snapshot":{"type":["string","null"]},"built_at":{"type":["string","null"]},"created_at":{"type":"string"}}},"VerifyRequest":{"type":"object","required":["id","content_hash"],"properties":{"id":{"type":"string"},"content_hash":{"type":"string"}}},"VerifyResponse":{"type":"object","properties":{"id":{"type":"string"},"found":{"type":"boolean"},"matches":{"type":"boolean"},"current_hash":{"type":["string","null"]},"kb_snapshot":{"type":["string","null"]}}},"Snapshot":{"type":"object","properties":{"kb_snapshot":{"type":"string"},"version":{"type":"string"},"built_at":{"type":"string"},"entry_count":{"type":"integer"}}},"RelatedResponse":{"type":"object","properties":{"id":{"type":"string"},"kb_snapshot":{"type":["string","null"]},"related":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/KnowledgeResult"},{"type":"object","properties":{"relation":{"type":"string","enum":["same-cluster","neighbor-cluster"]},"cross_domain":{"type":"boolean"}}}]}}}},"ResolveResponse":{"type":"object","properties":{"query":{"type":"string"},"resolved":{"oneOf":[{"$ref":"#/components/schemas/KnowledgeResult"},{"type":"null"}]},"match_type":{"type":"string","enum":["exact","best","none"]},"alternatives":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeResult"}},"kb_snapshot":{"type":["string","null"]}}},"BatchRequest":{"type":"object","required":["queries"],"properties":{"queries":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","maxLength":2000}},"domain":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":20,"default":5}}},"BatchResponse":{"type":"object","properties":{"kb_snapshot":{"type":["string","null"]},"count":{"type":"integer"},"searches":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"total":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeResult"}}}}}}},"Document":{"type":"object","required":["content"],"properties":{"content":{"type":"string"},"ref_id":{"type":"string","description":"Your reference id; the only identifier stored"},"metadata":{"type":"object"}}},"CreateIndexRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":1000},"collection_name":{"type":"string","maxLength":100},"domain_preset":{"type":"string","enum":["general","medical","biomedical","scientific","technical","legal","financial","ecommerce"]},"mode":{"type":"string","enum":["hosted","iaas"],"default":"hosted"},"webhook_url":{"type":"string","format":"uri"},"settings":{"type":"object"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/Document"}}}},"ConvenienceIndexRequest":{"type":"object","required":["collection"],"properties":{"collection":{"type":"string"},"name":{"type":"string"},"domain_preset":{"type":"string"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/Document"}}}},"IndexSearchRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","maxLength":2000},"limit":{"type":"integer","minimum":1,"maximum":100,"default":10},"offset":{"type":"integer","minimum":0,"default":0}}},"CollectionSearchRequest":{"type":"object","required":["collection","query"],"properties":{"collection":{"type":"string"},"query":{"type":"string","maxLength":2000},"limit":{"type":"integer","minimum":1,"maximum":100,"default":10}}},"IndexSearchResponse":{"type":"object","properties":{"index_id":{"type":"string"},"collection":{"type":"string"},"query":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"ref_id":{"type":"string"},"metadata":{"type":"object"},"score":{"$ref":"#/components/schemas/Score"},"state":{"$ref":"#/components/schemas/State"}}}},"diagnostics":{"type":"object"},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"ExplainRequest":{"type":"object","required":["query","doc_id"],"properties":{"query":{"type":"string"},"doc_id":{"type":"string","description":"\"doc_42\" or \"42\""}}},"RegisterRequest":{"type":"object","required":["email","password","company_name"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8,"maxLength":128},"company_name":{"type":"string","maxLength":200}}},"LoginRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}}},"AuthResponse":{"type":"object","properties":{"customer_id":{"type":"string"},"api_key":{"type":"string"},"session_token":{"type":"string"},"tier":{"type":"string"},"message":{"type":"string"}}}}}}