{"openapi":"3.1.0","info":{"title":"HYFL RAG Retrieval API","description":"Evidence retrieval API. The service returns citations and snippets; callers generate answers.","version":"0.1.0"},"paths":{"/rag/v1/keys/anonymous":{"post":{"summary":"Create Anonymous Key","description":"Mint a free-tier key. No auth required; lightly IP-limited to curb automated floods.","operationId":"create_anonymous_key_rag_v1_keys_anonymous_post","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/KeyCreateRequest"},{"type":"null"}],"title":"Payload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Create Anonymous Key Rag V1 Keys Anonymous Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/keys/anonymous":{"post":{"summary":"Create Anonymous Key","description":"Mint a free-tier key. No auth required; lightly IP-limited to curb automated floods.","operationId":"create_anonymous_key_v1_keys_anonymous_post","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/KeyCreateRequest"},{"type":"null"}],"title":"Payload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Create Anonymous Key V1 Keys Anonymous Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/health":{"get":{"summary":"Health","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health V1 Health Get"}}}}}}},"/v1/ready":{"get":{"summary":"Ready","operationId":"ready_v1_ready_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Ready V1 Ready Get"}}}}}}},"/v1/corpora":{"get":{"summary":"Corpora","operationId":"corpora_v1_corpora_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Corpora V1 Corpora Get"}}}}}}},"/v1/retrieve":{"post":{"summary":"Retrieve","operationId":"retrieve_v1_retrieve_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Retrieve V1 Retrieve Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/retrieve/stream":{"post":{"summary":"Retrieve Stream","operationId":"retrieve_stream_v1_retrieve_stream_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/chat":{"post":{"summary":"Chat Not Offered","operationId":"chat_not_offered_v1_chat_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Chat Not Offered V1 Chat Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/keys":{"post":{"summary":"Create Key","operationId":"create_key_v1_keys_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyCreateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Key V1 Keys Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/keys/{prefix_value}":{"delete":{"summary":"Revoke Key","operationId":"revoke_key_v1_keys__prefix_value__delete","parameters":[{"name":"prefix_value","in":"path","required":true,"schema":{"type":"string","title":"Prefix Value"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Revoke Key V1 Keys  Prefix Value  Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage":{"get":{"summary":"Usage","operationId":"usage_v1_usage_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Usage V1 Usage Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/content-requests":{"post":{"summary":"Create Content Request","operationId":"create_content_request_v1_content_requests_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRequestCreate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Content Request V1 Content Requests Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"List Content Requests","operationId":"list_content_requests_v1_content_requests_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Content Requests V1 Content Requests Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/content-requests/{request_id}":{"get":{"summary":"Get Content Request","operationId":"get_content_request_v1_content_requests__request_id__get","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"integer","title":"Request Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Content Request V1 Content Requests  Request Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"summary":"Update Content Request Status","operationId":"update_content_request_status_v1_content_requests__request_id__patch","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"integer","title":"Request Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRequestStatusUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Update Content Request Status V1 Content Requests  Request Id  Patch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rag/v1/health":{"get":{"summary":"Health","operationId":"health_rag_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Rag V1 Health Get"}}}}}}},"/rag/v1/ready":{"get":{"summary":"Ready","operationId":"ready_rag_v1_ready_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Ready Rag V1 Ready Get"}}}}}}},"/rag/v1/corpora":{"get":{"summary":"Corpora","operationId":"corpora_rag_v1_corpora_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Corpora Rag V1 Corpora Get"}}}}}}},"/rag/v1/retrieve":{"post":{"summary":"Retrieve","operationId":"retrieve_rag_v1_retrieve_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Retrieve Rag V1 Retrieve Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rag/v1/retrieve/stream":{"post":{"summary":"Retrieve Stream","operationId":"retrieve_stream_rag_v1_retrieve_stream_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rag/v1/chat":{"post":{"summary":"Chat Not Offered","operationId":"chat_not_offered_rag_v1_chat_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Chat Not Offered Rag V1 Chat Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rag/v1/keys":{"post":{"summary":"Create Key","operationId":"create_key_rag_v1_keys_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyCreateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Key Rag V1 Keys Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rag/v1/keys/{prefix_value}":{"delete":{"summary":"Revoke Key","operationId":"revoke_key_rag_v1_keys__prefix_value__delete","parameters":[{"name":"prefix_value","in":"path","required":true,"schema":{"type":"string","title":"Prefix Value"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Revoke Key Rag V1 Keys  Prefix Value  Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rag/v1/usage":{"get":{"summary":"Usage","operationId":"usage_rag_v1_usage_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Usage Rag V1 Usage Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rag/v1/content-requests":{"post":{"summary":"Create Content Request","operationId":"create_content_request_rag_v1_content_requests_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRequestCreate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Content Request Rag V1 Content Requests Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"List Content Requests","operationId":"list_content_requests_rag_v1_content_requests_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Content Requests Rag V1 Content Requests Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rag/v1/content-requests/{request_id}":{"get":{"summary":"Get Content Request","operationId":"get_content_request_rag_v1_content_requests__request_id__get","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"integer","title":"Request Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Content Request Rag V1 Content Requests  Request Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"summary":"Update Content Request Status","operationId":"update_content_request_status_rag_v1_content_requests__request_id__patch","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"integer","title":"Request Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRequestStatusUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Update Content Request Status Rag V1 Content Requests  Request Id  Patch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rag/mcp":{"post":{"summary":"Mcp Endpoint","operationId":"mcp_endpoint_rag_mcp_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"Mcp Health","operationId":"mcp_health_rag_mcp_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Mcp Health Rag Mcp Get"}}}}}}},"/mcp":{"post":{"summary":"Mcp Endpoint","operationId":"mcp_endpoint_mcp_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"Mcp Health","operationId":"mcp_health_mcp_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Mcp Health Mcp Get"}}}}}}}},"components":{"schemas":{"ContentRequestCreate":{"properties":{"request_type":{"type":"string","maxLength":80,"minLength":1,"title":"Request Type","default":"article_request"},"name":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Name"},"email":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"Email"},"title":{"type":"string","maxLength":240,"minLength":2,"title":"Title"},"url":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Url"},"details":{"type":"string","maxLength":4000,"minLength":5,"title":"Details"},"website":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"Website"}},"type":"object","required":["title","details"],"title":"ContentRequestCreate"},"ContentRequestStatusUpdate":{"properties":{"status":{"type":"string","maxLength":40,"minLength":1,"title":"Status"}},"type":"object","required":["status"],"title":"ContentRequestStatusUpdate"},"ConversationContext":{"properties":{"current_topic":{"anyOf":[{"type":"string","maxLength":240},{"type":"null"}],"title":"Current Topic"},"summary":{"anyOf":[{"type":"string","maxLength":1200},{"type":"null"}],"title":"Summary"},"salient_terms":{"items":{"type":"string"},"type":"array","title":"Salient Terms"}},"type":"object","title":"ConversationContext"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"KeyCreateRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":120,"minLength":1},{"type":"null"}],"title":"Name","default":"anonymous"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"budget":{"additionalProperties":true,"type":"object","title":"Budget"},"owner":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Owner"}},"type":"object","title":"KeyCreateRequest"},"Message":{"properties":{"role":{"type":"string","title":"Role"},"content":{"type":"string","title":"Content"}},"type":"object","required":["role","content"],"title":"Message"},"RetrieveRequest":{"properties":{"query":{"type":"string","maxLength":4000,"minLength":1,"title":"Query"},"messages":{"items":{"$ref":"#/components/schemas/Message"},"type":"array","title":"Messages"},"conversation":{"anyOf":[{"$ref":"#/components/schemas/ConversationContext"},{"type":"null"}]},"corpus":{"items":{"type":"string"},"type":"array","title":"Corpus"},"top_k":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Top K","default":8},"max_context_chars":{"type":"integer","maximum":100000.0,"minimum":500.0,"title":"Max Context Chars","default":6000},"include_trace":{"type":"boolean","title":"Include Trace","default":true}},"type":"object","required":["query"],"title":"RetrieveRequest"},"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"}}}}