{"openapi":"3.1.0","info":{"title":"TokenZero Gateway","version":"0.2.2","description":"BYOK LLM gateway with prompt-cache formatting, edge cache, opt-in cascade routing and signed savings receipts.","contact":{"email":"support@tokenzero.sh"}},"servers":[{"url":"https://tokenzero.sh"}],"paths":{"/v1/chat/completions":{"post":{"summary":"OpenAI Chat Completions (OpenAI, Gemini, OpenRouter, Anthropic-compat)","description":"Pass-through to the provider with TokenZero engines applied. Body and response are exactly the provider's (OpenAI Chat Completions schema). Streaming supported.","parameters":[{"in":"header","name":"X-TokenZero-Key","required":false,"schema":{"type":"string"},"description":"Workspace key from POST /v1/workspaces. Optional."},{"in":"header","name":"X-TokenZero-Provider","required":false,"schema":{"type":"string"},"description":"openai | anthropic | gemini | openrouter"},{"in":"header","name":"X-TokenZero-Cache","required":false,"schema":{"type":"string"},"description":"auto | off | always"},{"in":"header","name":"X-TokenZero-Semantic-Cache","required":false,"schema":{"type":"string"},"description":"true to enable near-duplicate cache"},{"in":"header","name":"X-TokenZero-Cascade","required":false,"schema":{"type":"string"},"description":"off | advise | auto"},{"in":"header","name":"X-TokenZero-Cache-Strategy","required":false,"schema":{"type":"string"},"description":"static | conversation | off"},{"in":"header","name":"X-TokenZero-Prompt-Cache-TTL","required":false,"schema":{"type":"string"},"description":"5m | 1h"},{"in":"header","name":"X-TokenZero-Upstream","required":false,"schema":{"type":"string"},"description":"custom https upstream base"},{"in":"header","name":"X-TokenZero-Bypass","required":false,"schema":{"type":"string"},"description":"true for pure pass-through"},{"in":"header","name":"X-TokenZero-Fallback","required":false,"schema":{"type":"string"},"description":"off | auto: retry 429/5xx/529 with jitter, then re-issue once to X-TokenZero-Fallback-Model / X-TokenZero-Fallback-Key"},{"in":"header","name":"X-TokenZero-Fallback-Model","required":false,"schema":{"type":"string"},"description":"model to re-issue to when the primary keeps failing (fallback=auto)"},{"in":"header","name":"X-TokenZero-Fallback-Key","required":false,"schema":{"type":"string"},"description":"provider key for the fallback model"},{"in":"header","name":"X-TokenZero-ZDR","required":false,"schema":{"type":"string"},"description":"true: zero data retention (no cache, no shadow eval, metadata-only ledger)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Provider response plus X-TokenZero-* headers"}}}},"/v1/responses":{"post":{"summary":"OpenAI Responses API","description":"Pass-through to the provider with TokenZero engines applied. Body and response are exactly the provider's (OpenAI Responses schema). Streaming supported.","parameters":[{"in":"header","name":"X-TokenZero-Key","required":false,"schema":{"type":"string"},"description":"Workspace key from POST /v1/workspaces. Optional."},{"in":"header","name":"X-TokenZero-Provider","required":false,"schema":{"type":"string"},"description":"openai | anthropic | gemini | openrouter"},{"in":"header","name":"X-TokenZero-Cache","required":false,"schema":{"type":"string"},"description":"auto | off | always"},{"in":"header","name":"X-TokenZero-Semantic-Cache","required":false,"schema":{"type":"string"},"description":"true to enable near-duplicate cache"},{"in":"header","name":"X-TokenZero-Cascade","required":false,"schema":{"type":"string"},"description":"off | advise | auto"},{"in":"header","name":"X-TokenZero-Cache-Strategy","required":false,"schema":{"type":"string"},"description":"static | conversation | off"},{"in":"header","name":"X-TokenZero-Prompt-Cache-TTL","required":false,"schema":{"type":"string"},"description":"5m | 1h"},{"in":"header","name":"X-TokenZero-Upstream","required":false,"schema":{"type":"string"},"description":"custom https upstream base"},{"in":"header","name":"X-TokenZero-Bypass","required":false,"schema":{"type":"string"},"description":"true for pure pass-through"},{"in":"header","name":"X-TokenZero-Fallback","required":false,"schema":{"type":"string"},"description":"off | auto: retry 429/5xx/529 with jitter, then re-issue once to X-TokenZero-Fallback-Model / X-TokenZero-Fallback-Key"},{"in":"header","name":"X-TokenZero-Fallback-Model","required":false,"schema":{"type":"string"},"description":"model to re-issue to when the primary keeps failing (fallback=auto)"},{"in":"header","name":"X-TokenZero-Fallback-Key","required":false,"schema":{"type":"string"},"description":"provider key for the fallback model"},{"in":"header","name":"X-TokenZero-ZDR","required":false,"schema":{"type":"string"},"description":"true: zero data retention (no cache, no shadow eval, metadata-only ledger)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Provider response plus X-TokenZero-* headers"}}}},"/v1/messages":{"post":{"summary":"Anthropic Messages API","description":"Pass-through to the provider with TokenZero engines applied. Body and response are exactly the provider's (Anthropic Messages schema). Streaming supported.","parameters":[{"in":"header","name":"X-TokenZero-Key","required":false,"schema":{"type":"string"},"description":"Workspace key from POST /v1/workspaces. Optional."},{"in":"header","name":"X-TokenZero-Provider","required":false,"schema":{"type":"string"},"description":"openai | anthropic | gemini | openrouter"},{"in":"header","name":"X-TokenZero-Cache","required":false,"schema":{"type":"string"},"description":"auto | off | always"},{"in":"header","name":"X-TokenZero-Semantic-Cache","required":false,"schema":{"type":"string"},"description":"true to enable near-duplicate cache"},{"in":"header","name":"X-TokenZero-Cascade","required":false,"schema":{"type":"string"},"description":"off | advise | auto"},{"in":"header","name":"X-TokenZero-Cache-Strategy","required":false,"schema":{"type":"string"},"description":"static | conversation | off"},{"in":"header","name":"X-TokenZero-Prompt-Cache-TTL","required":false,"schema":{"type":"string"},"description":"5m | 1h"},{"in":"header","name":"X-TokenZero-Upstream","required":false,"schema":{"type":"string"},"description":"custom https upstream base"},{"in":"header","name":"X-TokenZero-Bypass","required":false,"schema":{"type":"string"},"description":"true for pure pass-through"},{"in":"header","name":"X-TokenZero-Fallback","required":false,"schema":{"type":"string"},"description":"off | auto: retry 429/5xx/529 with jitter, then re-issue once to X-TokenZero-Fallback-Model / X-TokenZero-Fallback-Key"},{"in":"header","name":"X-TokenZero-Fallback-Model","required":false,"schema":{"type":"string"},"description":"model to re-issue to when the primary keeps failing (fallback=auto)"},{"in":"header","name":"X-TokenZero-Fallback-Key","required":false,"schema":{"type":"string"},"description":"provider key for the fallback model"},{"in":"header","name":"X-TokenZero-ZDR","required":false,"schema":{"type":"string"},"description":"true: zero data retention (no cache, no shadow eval, metadata-only ledger)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Provider response plus X-TokenZero-* headers"}}}},"/v1beta/models/{model}:generateContent":{"post":{"summary":"Gemini API generateContent (native; model in the path, x-goog-api-key or ?key=)","description":"Pass-through to the provider with TokenZero engines applied. Body and response are exactly the provider's (Gemini GenerateContentRequest). Streaming supported.","parameters":[{"in":"header","name":"X-TokenZero-Key","required":false,"schema":{"type":"string"},"description":"Workspace key from POST /v1/workspaces. Optional."},{"in":"header","name":"X-TokenZero-Provider","required":false,"schema":{"type":"string"},"description":"openai | anthropic | gemini | openrouter"},{"in":"header","name":"X-TokenZero-Cache","required":false,"schema":{"type":"string"},"description":"auto | off | always"},{"in":"header","name":"X-TokenZero-Semantic-Cache","required":false,"schema":{"type":"string"},"description":"true to enable near-duplicate cache"},{"in":"header","name":"X-TokenZero-Cascade","required":false,"schema":{"type":"string"},"description":"off | advise | auto"},{"in":"header","name":"X-TokenZero-Cache-Strategy","required":false,"schema":{"type":"string"},"description":"static | conversation | off"},{"in":"header","name":"X-TokenZero-Prompt-Cache-TTL","required":false,"schema":{"type":"string"},"description":"5m | 1h"},{"in":"header","name":"X-TokenZero-Upstream","required":false,"schema":{"type":"string"},"description":"custom https upstream base"},{"in":"header","name":"X-TokenZero-Bypass","required":false,"schema":{"type":"string"},"description":"true for pure pass-through"},{"in":"header","name":"X-TokenZero-Fallback","required":false,"schema":{"type":"string"},"description":"off | auto: retry 429/5xx/529 with jitter, then re-issue once to X-TokenZero-Fallback-Model / X-TokenZero-Fallback-Key"},{"in":"header","name":"X-TokenZero-Fallback-Model","required":false,"schema":{"type":"string"},"description":"model to re-issue to when the primary keeps failing (fallback=auto)"},{"in":"header","name":"X-TokenZero-Fallback-Key","required":false,"schema":{"type":"string"},"description":"provider key for the fallback model"},{"in":"header","name":"X-TokenZero-ZDR","required":false,"schema":{"type":"string"},"description":"true: zero data retention (no cache, no shadow eval, metadata-only ledger)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Provider response plus X-TokenZero-* headers"}}}},"/v1beta/models/{model}:streamGenerateContent":{"post":{"summary":"Gemini API streaming (SSE with ?alt=sse)","description":"Pass-through to the provider with TokenZero engines applied. Body and response are exactly the provider's (Gemini GenerateContentRequest). Streaming supported.","parameters":[{"in":"header","name":"X-TokenZero-Key","required":false,"schema":{"type":"string"},"description":"Workspace key from POST /v1/workspaces. Optional."},{"in":"header","name":"X-TokenZero-Provider","required":false,"schema":{"type":"string"},"description":"openai | anthropic | gemini | openrouter"},{"in":"header","name":"X-TokenZero-Cache","required":false,"schema":{"type":"string"},"description":"auto | off | always"},{"in":"header","name":"X-TokenZero-Semantic-Cache","required":false,"schema":{"type":"string"},"description":"true to enable near-duplicate cache"},{"in":"header","name":"X-TokenZero-Cascade","required":false,"schema":{"type":"string"},"description":"off | advise | auto"},{"in":"header","name":"X-TokenZero-Cache-Strategy","required":false,"schema":{"type":"string"},"description":"static | conversation | off"},{"in":"header","name":"X-TokenZero-Prompt-Cache-TTL","required":false,"schema":{"type":"string"},"description":"5m | 1h"},{"in":"header","name":"X-TokenZero-Upstream","required":false,"schema":{"type":"string"},"description":"custom https upstream base"},{"in":"header","name":"X-TokenZero-Bypass","required":false,"schema":{"type":"string"},"description":"true for pure pass-through"},{"in":"header","name":"X-TokenZero-Fallback","required":false,"schema":{"type":"string"},"description":"off | auto: retry 429/5xx/529 with jitter, then re-issue once to X-TokenZero-Fallback-Model / X-TokenZero-Fallback-Key"},{"in":"header","name":"X-TokenZero-Fallback-Model","required":false,"schema":{"type":"string"},"description":"model to re-issue to when the primary keeps failing (fallback=auto)"},{"in":"header","name":"X-TokenZero-Fallback-Key","required":false,"schema":{"type":"string"},"description":"provider key for the fallback model"},{"in":"header","name":"X-TokenZero-ZDR","required":false,"schema":{"type":"string"},"description":"true: zero data retention (no cache, no shadow eval, metadata-only ledger)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Provider response plus X-TokenZero-* headers"}}}},"/v1/workspaces":{"post":{"summary":"Create a workspace key","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"settings":{"type":"object"}}}}}},"responses":{"201":{"description":"{workspace, key} — key shown once"}}}},"/v1/workspaces/me":{"get":{"summary":"Current workspace (X-TokenZero-Key)","responses":{"200":{"description":"workspace"}}},"patch":{"summary":"Update settings","responses":{"200":{"description":"workspace"}}}},"/v1/ledger/stats":{"get":{"summary":"Savings stats for a workspace","parameters":[{"in":"query","name":"workspace","schema":{"type":"string"}},{"in":"query","name":"days","schema":{"type":"integer","default":30}}],"responses":{"200":{"description":"stats"}}}},"/v1/ledger/receipt/{id}":{"get":{"summary":"Signed receipt for a request","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{receipt, signature, public_key}"}}}},"/v1/ledger/verify":{"post":{"summary":"Verify a receipt signature, or a chain segment ({items:[{receipt, signature}]})","responses":{"200":{"description":"{valid} or {valid, checked, break_at}"}}}},"/v1/ledger/chain":{"get":{"summary":"Walk the hash-chained receipts of a workspace (X-TokenZero-Key)","parameters":[{"in":"query","name":"limit","schema":{"type":"integer"}},{"in":"query","name":"before","schema":{"type":"integer"}}],"responses":{"200":{"description":"{items, head}"}}}},"/v1/status":{"get":{"summary":"Public system status: gateway, signer self-test, pricing, providers","responses":{"200":{"description":"status document"}}}},"/v1/doctor":{"get":{"summary":"Connection and receipt doctor (optional X-TokenZero-Key)","responses":{"200":{"description":"{ok, checks[], snippets}"}}},"post":{"summary":"Same as GET; the key may be passed as JSON {key}","responses":{"200":{"description":"{ok, checks[], snippets}"}}}},"/v1/support":{"post":{"summary":"Open a support ticket {subject, message, email?, workspace_id?, category?, receipt_id?}","responses":{"201":{"description":"{ok, ticket}"}}}},"/v1/workspaces/rotate-key":{"post":{"summary":"Rotate the workspace key (X-TokenZero-Key); returns the new key and a one-click dashboard URL","responses":{"200":{"description":"{workspace, key, dashboard_url}"}}}},"/v1/workspaces/settings":{"post":{"summary":"Update workspace settings (alias of PATCH /v1/workspaces/me; friendly alias keys accepted)","responses":{"200":{"description":"workspace"}}}},"/v1/workspaces/me/metrics":{"get":{"summary":"Customer value scorecard (X-TokenZero-Key; ?window=24h|7d|30d|all; ?demo=1 for a sample without a key)","parameters":[{"in":"query","name":"window","schema":{"type":"string","enum":["24h","7d","30d","all"]}},{"in":"query","name":"demo","schema":{"type":"string"}}],"responses":{"200":{"description":"{cost_and_roi, by_engine, speed_and_latency, quality_and_safety, reliability_and_privacy, by_provider, by_model, daily_series, actionable_recommendations, system_improvements}"}}}},"/v1/signup":{"post":{"summary":"One-call workspace provisioning for agents (no account)","responses":{"201":{"description":"{workspace_id, api_key, dashboard_url, openai_base_url, anthropic_base_url}"}}}},"/v1/billing/status":{"get":{"summary":"Plan and Stripe subscription status (X-TokenZero-Key)","responses":{"200":{"description":"status"}}}},"/v1/billing/checkout":{"post":{"summary":"Start a Stripe Checkout session for a paid plan {plan, interval}","responses":{"200":{"description":"{url}"}}}},"/v1/billing/portal":{"post":{"summary":"Open the Stripe customer portal","responses":{"200":{"description":"{url}"}}}},"/v1/ledger/leaderboard":{"get":{"summary":"Top workspaces by verified savings","responses":{"200":{"description":"rows"}}}},"/v1/ledger/global":{"get":{"summary":"Global totals","responses":{"200":{"description":"totals"}}}},"/v1/badge/{workspace_id}.svg":{"get":{"summary":"Live savings badge","responses":{"200":{"description":"image/svg+xml"}}}},"/v1/simulate":{"post":{"summary":"Project savings for a request shape","responses":{"200":{"description":"projection"}}}},"/v1/audit":{"post":{"summary":"Static token-waste audit of a public repo or files","responses":{"200":{"description":"report"}}}},"/v1/github/pr-audit":{"post":{"summary":"Audit a PR diff and produce a review comment","responses":{"200":{"description":"{report, comment_markdown}"}}}},"/v1/pricing":{"get":{"summary":"Versioned list-price table","responses":{"200":{"description":"table"}}}},"/mcp":{"post":{"summary":"MCP server (Streamable HTTP, JSON-RPC 2.0)","responses":{"200":{"description":"JSON-RPC response"}}}}}}