{"openapi":"3.1.0","info":{"title":"Query Fanout Retrieval Control Plane","description":"Governed retrieval API for AI agents.\n\n**Start here:** `POST /policy/evaluate` — pass your query and pre-retrieved sources; get `allow_answer`, policy reasons, authority scores, and an `audit_id`. No new search. Default preset is `support` (customer-facing agents); use `legal` only for compliance workflows with authoritative sources.\n\n**Full retrieval:** `POST /evidence` — probe, fanout, policy gate, synthesis, and audit in one call.\n\nAuthenticate hosted requests with header `X-API-Key`. Request a design-partner key at [/contact](/contact).","version":"0.5.0"},"paths":{"/":{"get":{"summary":"Landing","operationId":"landing__get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/how-it-works":{"get":{"summary":"How It Works","operationId":"how_it_works_how_it_works_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/blog":{"get":{"summary":"Blog Index","operationId":"blog_index_blog_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/blog/retrieval-tax":{"get":{"summary":"Blog Retrieval Tax","operationId":"blog_retrieval_tax_blog_retrieval_tax_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/autopsy":{"get":{"summary":"Autopsy Guide","operationId":"autopsy_guide_autopsy_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/autopsy/preview":{"get":{"summary":"Autopsy Preview","operationId":"autopsy_preview_autopsy_preview_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/privacy":{"get":{"summary":"Privacy","operationId":"privacy_privacy_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/contact":{"get":{"summary":"Contact","operationId":"contact_contact_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/autopsy/sample":{"get":{"summary":"Autopsy Sample","operationId":"autopsy_sample_autopsy_sample_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Health Health Get"}}}}}}},"/dashboard":{"get":{"summary":"Dashboard","operationId":"dashboard_dashboard_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/metrics":{"get":{"tags":["ops"],"summary":"Metrics","operationId":"metrics_metrics_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Metrics Metrics Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/policies":{"get":{"tags":["ops"],"summary":"Policies","operationId":"policies_policies_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object","additionalProperties":true},"title":"Response Policies Policies Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/evidence":{"post":{"tags":["retrieval"],"summary":"Evidence","operationId":"evidence_evidence_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/EvidenceResponse"},{"$ref":"#/components/schemas/EvidenceDemoResponse"}],"title":"Response Evidence Evidence Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/policy/evaluate":{"post":{"tags":["policy"],"summary":"Gate pre-retrieved sources","description":"Evaluate caller-provided sources against a policy preset. Returns `allow_answer`, policy reasons, authority scores, and `audit_id`. Does not run new searches — use after your reranker, before synthesis.","operationId":"policy_evaluate_policy_evaluate_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyEvaluateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyEvaluateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/audit":{"get":{"tags":["audit"],"summary":"Audit List","operationId":"audit_list_audit_get","parameters":[{"name":"agent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id"}},{"name":"run_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"}},{"name":"workflow","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AuditSummaryOut"},"title":"Response Audit List Audit Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/audit/{audit_id}":{"get":{"tags":["audit"],"summary":"Audit Get","operationId":"audit_get_audit__audit_id__get","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string","title":"Audit Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Audit Get Audit  Audit Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/audit/run/{run_id}/export":{"get":{"tags":["audit"],"summary":"Audit Export Run","operationId":"audit_export_run_audit_run__run_id__export_get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","title":"Run Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Audit Export Run Audit Run  Run Id  Export Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/agents/{agent_id}/spend":{"get":{"tags":["audit"],"summary":"Agent Spend","operationId":"agent_spend_agents__agent_id__spend_get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Agent Spend Agents  Agent Id  Spend Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/autopsy/upload":{"post":{"tags":["autopsy"],"summary":"Autopsy Upload","operationId":"autopsy_upload_autopsy_upload_post","parameters":[{"name":"company","in":"query","required":false,"schema":{"type":"string","default":"Prospect","title":"Company"}},{"name":"period","in":"query","required":false,"schema":{"type":"string","default":"uploaded logs","title":"Period"}},{"name":"max_queries","in":"query","required":false,"schema":{"type":"integer","default":5,"title":"Max Queries"}},{"name":"governance_policy","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"legal","title":"Governance Policy"}},{"name":"governance_sample","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Governance Sample"}},{"name":"governance_preset","in":"query","required":false,"schema":{"type":"string","default":"mock","title":"Governance Preset"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_autopsy_upload_autopsy_upload_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutopsyUploadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}}},"components":{"schemas":{"AuditSummaryOut":{"properties":{"id":{"type":"string","title":"Id"},"timestamp":{"type":"string","title":"Timestamp"},"agent_id":{"type":"string","title":"Agent Id"},"run_id":{"type":"string","title":"Run Id"},"workflow":{"type":"string","title":"Workflow"},"query":{"type":"string","title":"Query"},"allow_answer":{"type":"boolean","title":"Allow Answer"},"policy_action":{"type":"string","title":"Policy Action"},"confidence":{"type":"number","title":"Confidence"},"sources":{"type":"integer","title":"Sources"}},"type":"object","required":["id","timestamp","agent_id","run_id","workflow","query","allow_answer","policy_action","confidence","sources"],"title":"AuditSummaryOut"},"AutopsyUploadResponse":{"properties":{"upload_id":{"type":"string","title":"Upload Id"},"filename":{"type":"string","title":"Filename"},"stored_path":{"type":"string","title":"Stored Path"},"validation":{"additionalProperties":true,"type":"object","title":"Validation"},"autopsy_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Autopsy Summary"},"report_markdown":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Markdown"}},"type":"object","required":["upload_id","filename","stored_path","validation"],"title":"AutopsyUploadResponse"},"Body_autopsy_upload_autopsy_upload_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_autopsy_upload_autopsy_upload_post"},"ConflictOut":{"properties":{"topic":{"type":"string","title":"Topic"},"summary":{"type":"string","title":"Summary"},"supporting_sources":{"items":{"type":"string"},"type":"array","title":"Supporting Sources"},"opposing_sources":{"items":{"type":"string"},"type":"array","title":"Opposing Sources"},"confidence":{"type":"number","title":"Confidence","default":0.0},"authority_gap":{"type":"number","title":"Authority Gap","default":0.0}},"type":"object","required":["topic","summary","supporting_sources","opposing_sources"],"title":"ConflictOut"},"CostOut":{"properties":{"budget":{"type":"number","title":"Budget"},"spent":{"type":"number","title":"Spent"},"saved_by_adaptive":{"type":"number","title":"Saved By Adaptive"},"queries_run":{"type":"integer","title":"Queries Run"},"queries_avoided":{"type":"integer","title":"Queries Avoided"},"per_backend":{"additionalProperties":{"type":"number"},"type":"object","title":"Per Backend"},"within_budget":{"type":"boolean","title":"Within Budget"}},"type":"object","required":["budget","spent","saved_by_adaptive","queries_run","queries_avoided","per_backend","within_budget"],"title":"CostOut"},"EvidenceDemoItemOut":{"properties":{"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"Url"},"confidence":{"type":"number","title":"Confidence"},"authority":{"type":"number","title":"Authority"},"consensus":{"type":"number","title":"Consensus"},"source":{"type":"string","title":"Source"}},"type":"object","required":["title","url","confidence","authority","consensus","source"],"title":"EvidenceDemoItemOut"},"EvidenceDemoResponse":{"properties":{"demo_mode":{"type":"boolean","title":"Demo Mode","default":true},"allow_answer":{"type":"boolean","title":"Allow Answer"},"audit_id":{"type":"string","title":"Audit Id"},"original_query":{"type":"string","title":"Original Query"},"mode":{"type":"string","enum":["adaptive","full","probe"],"title":"Mode"},"overall_confidence":{"type":"number","title":"Overall Confidence"},"probe_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Probe Confidence"},"policy":{"$ref":"#/components/schemas/PolicyOut"},"expanded_queries":{"items":{"type":"string"},"type":"array","title":"Expanded Queries"},"evidence":{"items":{"$ref":"#/components/schemas/EvidenceDemoItemOut"},"type":"array","title":"Evidence"},"cost":{"anyOf":[{"$ref":"#/components/schemas/CostOut"},{"type":"null"}]},"escalated":{"type":"boolean","title":"Escalated"},"errors":{"items":{"type":"string"},"type":"array","title":"Errors"},"cache_stats":{"additionalProperties":true,"type":"object","title":"Cache Stats"},"tenant_id":{"type":"string","title":"Tenant Id"}},"type":"object","required":["allow_answer","audit_id","original_query","mode","overall_confidence","probe_confidence","policy","expanded_queries","evidence","cost","escalated","errors","cache_stats","tenant_id"],"title":"EvidenceDemoResponse"},"EvidenceItemOut":{"properties":{"title":{"type":"string","title":"Title"},"snippet":{"type":"string","title":"Snippet"},"url":{"type":"string","title":"Url"},"confidence":{"type":"number","title":"Confidence"},"consensus":{"type":"number","title":"Consensus"},"authority":{"type":"number","title":"Authority"},"claims":{"items":{"type":"string"},"type":"array","title":"Claims"},"source":{"type":"string","title":"Source"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"}},"type":"object","required":["title","snippet","url","confidence","consensus","authority","claims","source","metadata"],"title":"EvidenceItemOut"},"EvidenceRequest":{"properties":{"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Query"},"mode":{"type":"string","enum":["adaptive","full","probe"],"title":"Mode","default":"adaptive"},"expand":{"type":"string","enum":["heuristic","llm"],"title":"Expand","default":"heuristic"},"max_queries":{"type":"integer","maximum":12.0,"minimum":1.0,"title":"Max Queries","default":5},"result_limit":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Result Limit","default":10},"budget":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Budget","default":0.25},"preset":{"anyOf":[{"type":"string","enum":["mock","wikipedia","tavily"]},{"type":"null"}],"title":"Preset","default":"wikipedia"},"backends_file":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backends File"},"policy":{"type":"string","enum":["default","legal","support","research","calibrated"],"title":"Policy","default":"default"},"agent_id":{"type":"string","title":"Agent Id","default":""},"run_id":{"type":"string","title":"Run Id","default":""},"audit":{"type":"boolean","title":"Audit","default":true},"use_cache":{"type":"boolean","title":"Use Cache","default":true},"agent_daily_budget":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Agent Daily Budget"},"policy_file":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Policy File"},"authority_overrides":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Authority Overrides"},"demo_mode":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Demo Mode"}},"type":"object","required":["query"],"title":"EvidenceRequest"},"EvidenceResponse":{"properties":{"original_query":{"type":"string","title":"Original Query"},"mode":{"type":"string","enum":["adaptive","full","probe"],"title":"Mode"},"expanded_queries":{"items":{"type":"string"},"type":"array","title":"Expanded Queries"},"synthesis":{"type":"string","title":"Synthesis"},"overall_confidence":{"type":"number","title":"Overall Confidence"},"probe_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Probe Confidence"},"evidence":{"items":{"$ref":"#/components/schemas/EvidenceItemOut"},"type":"array","title":"Evidence"},"conflicts":{"items":{"$ref":"#/components/schemas/ConflictOut"},"type":"array","title":"Conflicts"},"cost":{"anyOf":[{"$ref":"#/components/schemas/CostOut"},{"type":"null"}]},"errors":{"items":{"type":"string"},"type":"array","title":"Errors"},"policy":{"$ref":"#/components/schemas/PolicyOut"},"allow_answer":{"type":"boolean","title":"Allow Answer"},"audit_id":{"type":"string","title":"Audit Id"},"escalated":{"type":"boolean","title":"Escalated"},"cache_stats":{"additionalProperties":true,"type":"object","title":"Cache Stats"},"synthesis_contract":{"additionalProperties":true,"type":"object","title":"Synthesis Contract","default":{}},"tenant_id":{"type":"string","title":"Tenant Id"}},"type":"object","required":["original_query","mode","expanded_queries","synthesis","overall_confidence","probe_confidence","evidence","conflicts","cost","errors","policy","allow_answer","audit_id","escalated","cache_stats","tenant_id"],"title":"EvidenceResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PolicyEvaluateRequest":{"properties":{"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Query"},"sources":{"items":{"$ref":"#/components/schemas/PolicyEvaluateSourceIn"},"type":"array","maxItems":50,"minItems":1,"title":"Sources"},"policy":{"type":"string","enum":["default","legal","support","research","calibrated"],"title":"Policy","default":"support"},"agent_id":{"type":"string","title":"Agent Id","default":""},"run_id":{"type":"string","title":"Run Id","default":""},"audit":{"type":"boolean","title":"Audit","default":true},"authority_overrides":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Authority Overrides"},"demo_mode":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Demo Mode"}},"type":"object","required":["query","sources"],"title":"PolicyEvaluateRequest"},"PolicyEvaluateResponse":{"properties":{"allow_answer":{"type":"boolean","title":"Allow Answer"},"audit_id":{"type":"string","title":"Audit Id"},"original_query":{"type":"string","title":"Original Query"},"overall_confidence":{"type":"number","title":"Overall Confidence"},"policy":{"$ref":"#/components/schemas/PolicyOut"},"evidence":{"items":{"$ref":"#/components/schemas/PolicyEvaluateSourceOut"},"type":"array","title":"Evidence"},"conflicts":{"items":{"$ref":"#/components/schemas/ConflictOut"},"type":"array","title":"Conflicts"},"synthesis_contract":{"additionalProperties":true,"type":"object","title":"Synthesis Contract","default":{}},"tenant_id":{"type":"string","title":"Tenant Id"}},"type":"object","required":["allow_answer","audit_id","original_query","overall_confidence","policy","evidence","conflicts","tenant_id"],"title":"PolicyEvaluateResponse"},"PolicyEvaluateSourceIn":{"properties":{"title":{"type":"string","title":"Title","default":""},"snippet":{"type":"string","title":"Snippet","default":""},"url":{"type":"string","title":"Url","default":""},"score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Score","default":0.8},"source":{"type":"string","title":"Source","default":"provided"}},"type":"object","title":"PolicyEvaluateSourceIn"},"PolicyEvaluateSourceOut":{"properties":{"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"Url"},"confidence":{"type":"number","title":"Confidence"},"authority":{"type":"number","title":"Authority"},"consensus":{"type":"number","title":"Consensus"}},"type":"object","required":["title","url","confidence","authority","consensus"],"title":"PolicyEvaluateSourceOut"},"PolicyOut":{"properties":{"profile":{"type":"string","title":"Profile"},"passed":{"type":"boolean","title":"Passed"},"action":{"type":"string","title":"Action"},"reasons":{"items":{"type":"string"},"type":"array","title":"Reasons"},"metrics":{"additionalProperties":true,"type":"object","title":"Metrics"}},"type":"object","required":["profile","passed","action","reasons","metrics"],"title":"PolicyOut"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Design-partner API key. Request access at /contact."}}},"tags":[{"name":"policy","description":"Gate pre-retrieved sources after your reranker — no new search."},{"name":"retrieval","description":"Full governed retrieval when Query Fanout should run search backends."},{"name":"audit","description":"Tenant-scoped audit trail for every gated decision."},{"name":"autopsy","description":"Upload JSONL logs for design-partner retrieval autopsy."},{"name":"ops","description":"Health, metrics, and policy preset definitions."}]}