{"openapi":"3.1.0","info":{"title":"Metabase docs++ API","version":"1.0.0","summary":"Search, read and ask the Metabase documentation.","description":"Anonymous, with rate limits for each client (search, docs, related, feedback and MCP: 120 requests a minute; ask: 10). CORS allows any origin without credentials. Search results are passages of the docs, never generated text; answers are generated from those passages only and cite each claim.","license":{"name":"Metabase docs content: see www.metabase.com"}},"servers":[{"url":"https://docs.metabase.fyi"}],"paths":{"/v1/health":{"get":{"operationId":"health","summary":"Health check","responses":{"200":{"description":"The Worker is up.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true}}}}}}}}},"/v1/search":{"get":{"operationId":"search","summary":"Hybrid search over the docs (no LLM)","description":"Exact identifiers, keywords and meaning, fused and reranked. Returns ranked passages and the same passages grouped by page. A `Server-Timing` header gives each stage's duration.","parameters":[{"name":"q","in":"query","required":true,"description":"The question or search terms.","schema":{"type":"string","minLength":1,"maxLength":1000}},{"name":"version","in":"query","required":false,"description":"Metabase version: \"v0.65\", \"0.64\", \"v58\", \"latest\". Default: the newest version.","schema":{"type":"string","maxLength":20}},{"name":"section","in":"query","required":false,"description":"Top-level docs folder, like \"permissions\".","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Number of passages.","schema":{"type":"integer","minimum":1,"maximum":30,"default":8}},{"name":"debug","in":"query","required":false,"description":"1: add stage scores and timing.","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Ranked results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Missing or invalid parameter, or unknown version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests from this client. Wait for `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/ask":{"post":{"operationId":"ask","summary":"A cited answer from the docs","description":"Streams server-sent events by default: `retrieval` (the sources, first), `token` (answer text), then `done` (the result); `error` if the stream fails after it started. Send `Accept: application/json` for one JSON object instead.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"}}}},"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskJsonResponse"}},"text/event-stream":{"schema":{"type":"string"},"description":"Events `retrieval` (data: RetrievalEvent), `token` (data: {text}), `done` (data: AskResult), `error` (data: Error)."}}},"400":{"description":"Invalid body or unknown version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is larger than 32 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests from this client. Wait for `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/docs":{"get":{"operationId":"getDoc","summary":"One docs page as normalized Markdown, by URL","description":"Send `Accept: text/markdown` for the Markdown only.","parameters":[{"name":"url","in":"query","required":true,"description":"A docs URL; the anchor is ignored, and /docs/latest/ means the newest version.","schema":{"type":"string"}}],"responses":{"200":{"description":"The page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocPage"}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Missing or invalid url.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that URL in the index.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests from this client. Wait for `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/docs/{version}/{path}":{"get":{"operationId":"getDocByPath","summary":"One docs page as normalized Markdown, by version and path","description":"`path` can contain slashes, like `configuring-metabase/environment-variables`.","parameters":[{"name":"version","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocPage"}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Missing version or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that URL in the index.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests from this client. Wait for `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/related":{"get":{"operationId":"related","summary":"Pages related to a docs page","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Related pages, most related first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelatedResponse"}}}},"400":{"description":"Missing url.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No page with that URL in the index.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests from this client. Wait for `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/feedback":{"post":{"operationId":"feedback","summary":"Thumbs up or down on an answer","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackRequest"}}}},"responses":{"201":{"description":"Saved.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true}}}}}},"400":{"description":"Invalid body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No answer with that answer_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests from this client. Wait for `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/openapi.json":{"get":{"operationId":"openapi","summary":"This document","responses":{"200":{"description":"OpenAPI 3.1.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/mcp":{"post":{"operationId":"mcp","summary":"MCP server (Streamable HTTP, stateless)","description":"JSON-RPC 2.0 messages of the Model Context Protocol. Tools: search_docs, read_doc, ask_docs. GET is not offered (405).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":["object","array"]}}}},"responses":{"200":{"description":"JSON-RPC response.","content":{"application/json":{"schema":{"type":["object","array"]}}}},"202":{"description":"Accepted (a notification)."},"429":{"description":"Too many requests from this client. Wait for `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable code, like \"rate_limited\"."},"message":{"type":"string"},"retryAfter":{"type":"integer"},"versions":{"type":"array","items":{"type":"string"}}}},"Passage":{"type":"object","required":["id","url","anchor","title","heading","headingPath","snippet","highlights","text","version","plan","source","kind","score","relevance","exact"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri","description":"Page URL without the anchor."},"anchor":{"type":["string","null"],"description":"Heading id on the page."},"title":{"type":"string"},"heading":{"type":"string"},"headingPath":{"type":"array","items":{"type":"string"}},"snippet":{"type":"string"},"highlights":{"type":"array","description":"Character ranges of query terms in `snippet`.","items":{"type":"array","prefixItems":[{"type":"integer"},{"type":"integer"}],"minItems":2,"maxItems":2}},"text":{"type":"string","description":"The passage as Markdown."},"version":{"type":"string","description":"Docs version, like \"v0.65\", or \"cloud\" / \"shared\"."},"plan":{"type":["string","null"],"description":"The plan the feature needs (\"pro\", \"enterprise\"), or null."},"source":{"type":"string"},"kind":{"type":"string"},"score":{"type":"number","description":"Rank score, comparable within one response."},"relevance":{"type":"number","minimum":0,"maximum":1,"description":"Reranker relevance, comparable across queries."},"exact":{"type":"boolean","description":"An exact identifier match."},"debug":{"type":"object"}}},"PageGroup":{"type":"object","required":["url","title","version","passages"],"properties":{"url":{"type":"string"},"title":{"type":"string"},"version":{"type":"string","description":"Docs version, like \"v0.65\", or \"cloud\" / \"shared\"."},"passages":{"type":"array","items":{"$ref":"#/components/schemas/Passage"}}}},"VersionFallback":{"type":["object","null"],"required":["from","to","note"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"note":{"type":"string"}}},"SearchResponse":{"type":"object","required":["query","version","fallback","results","pages"],"properties":{"query":{"type":"string"},"version":{"type":"string","description":"Docs version, like \"v0.65\", or \"cloud\" / \"shared\"."},"fallback":{"$ref":"#/components/schemas/VersionFallback"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Passage"}},"pages":{"type":"array","items":{"$ref":"#/components/schemas/PageGroup"}},"timing":{"type":"object","additionalProperties":{"type":"number"}},"degraded":{"type":"array","items":{"type":"string"},"description":"Stages that failed upstream."}}},"AskContext":{"type":"object","description":"Facts about the asker's setup. Never instance data.","properties":{"version":{"type":"string"},"edition":{"type":"string","examples":["oss","ee"]},"plan":{"type":"string"},"deployment":{"type":"string","examples":["cloud","self-hosted"]},"surface":{"type":"string","examples":["admin/settings/email","query-builder"]},"error":{"type":"string","description":"An error message the user sees."}}},"AskRequest":{"type":"object","required":["question"],"properties":{"question":{"type":"string","minLength":1,"maxLength":1000},"history":{"type":"array","maxItems":10,"items":{"type":"object","required":["role","content"],"properties":{"role":{"enum":["user","assistant"]},"content":{"type":"string","maxLength":4000}}}},"version":{"type":"string"},"context":{"$ref":"#/components/schemas/AskContext"},"debug":{"type":"boolean","description":"Add each source's full text and the token usage."}}},"Citation":{"type":"object","required":["n","title","heading","url","snippet","version","plan"],"properties":{"n":{"type":"integer","minimum":1,"description":"The number used in the answer as [n]."},"title":{"type":"string"},"heading":{"type":"string"},"url":{"type":"string","description":"Docs URL with the section anchor."},"snippet":{"type":"string"},"version":{"type":"string","description":"Docs version, like \"v0.65\", or \"cloud\" / \"shared\"."},"plan":{"type":["string","null"],"description":"The plan the feature needs (\"pro\", \"enterprise\"), or null."},"text":{"type":"string","description":"Only with debug."}}},"Usage":{"type":"object","required":["model","inputTokens","outputTokens"],"properties":{"model":{"type":"string"},"inputTokens":{"type":"integer"},"outputTokens":{"type":"integer"}}},"RetrievalEvent":{"type":"object","required":["answer_id","version","standalone","queries","notes","fallback","sources"],"properties":{"answer_id":{"type":"string"},"version":{"type":"string","description":"Docs version, like \"v0.65\", or \"cloud\" / \"shared\"."},"standalone":{"type":"string","description":"The question, rewritten to stand alone."},"queries":{"type":"array","items":{"type":"string"}},"notes":{"type":"array","items":{"type":"string"}},"fallback":{"$ref":"#/components/schemas/VersionFallback"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Citation"}},"degraded":{"type":"array","items":{"type":"string"}}}},"AskResult":{"type":"object","required":["answer_id","answer","citations","version","grounded","followups","mode","model"],"properties":{"answer_id":{"type":"string","pattern":"^ans_"},"answer":{"type":"string","description":"Markdown with [n] citations."},"citations":{"type":"array","items":{"$ref":"#/components/schemas/Citation"},"description":"The cited sources."},"version":{"type":"string","description":"Docs version, like \"v0.65\", or \"cloud\" / \"shared\"."},"grounded":{"type":"boolean","description":"The answer cites the docs (not an \"I couldn't find this\" answer)."},"followups":{"type":"array","items":{"type":"string"}},"mode":{"enum":["answer","no_sources","search_only"],"description":"search_only: answers are paused (spend or rate limit); the answer lists matching pages."},"model":{"type":["string","null"]},"removed_citations":{"type":"array","items":{"type":"integer"}},"truncated":{"type":"boolean"},"usage":{"type":"array","items":{"$ref":"#/components/schemas/Usage"}},"cached":{"enum":["exact","semantic"]}}},"AskJsonResponse":{"allOf":[{"$ref":"#/components/schemas/AskResult"},{"type":"object","required":["sources","notes","fallback"],"properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/Citation"}},"notes":{"type":"array","items":{"type":"string"}},"fallback":{"$ref":"#/components/schemas/VersionFallback"}}}]},"DocPage":{"type":"object","required":["url","version","title","summary","section","plan","deployment","aliases","sections","markdown"],"properties":{"url":{"type":"string"},"version":{"type":"string","description":"Docs version, like \"v0.65\", or \"cloud\" / \"shared\"."},"title":{"type":"string"},"summary":{"type":["string","null"]},"section":{"type":["string","null"]},"plan":{"type":["string","null"],"description":"The plan the feature needs (\"pro\", \"enterprise\"), or null."},"deployment":{"type":["string","null"]},"aliases":{"type":"array","items":{"type":"string"},"description":"Old paths of this page."},"sections":{"type":"array","items":{"type":"object","required":["level","heading","anchor","url"],"properties":{"level":{"type":"integer"},"heading":{"type":"string"},"anchor":{"type":"string"},"url":{"type":"string"}}}},"markdown":{"type":"string"}}},"RelatedResponse":{"type":"object","required":["url","title","version","related"],"properties":{"url":{"type":"string"},"title":{"type":"string"},"version":{"type":"string","description":"Docs version, like \"v0.65\", or \"cloud\" / \"shared\"."},"related":{"type":"array","items":{"type":"object","required":["url","title","score"],"properties":{"url":{"type":"string"},"title":{"type":"string"},"score":{"type":"number"}}}}}},"FeedbackRequest":{"type":"object","required":["answer_id","rating"],"properties":{"answer_id":{"type":"string","pattern":"^ans_[A-Za-z0-9_-]{6,64}$"},"rating":{"enum":["up","down"]},"reason":{"enum":["wrong","outdated","incomplete","didnt_answer","other",null]},"comment":{"type":["string","null"],"maxLength":2000}}}}}}