{"openapi":"3.0.0","info":{"title":"RAG Insurance Wording","version":"1.0.0","description":"HTTP API for document-grounded answers and related utilities. See `/docs` for interactive OpenAPI."},"components":{"schemas":{"AskRequest":{"type":"object","properties":{"user_id":{"type":"string","minLength":1,"description":"Account identifier issued to your integration.","example":"100"},"api_key":{"type":"string","minLength":1,"maxLength":128,"description":"Secret paired with `user_id` and your allowed caller networks.","example":"test1"},"query":{"type":"string","minLength":3,"description":"End-user question in natural language.","example":"What does Travel Allianz Voiaj cover?"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter market code for the document set (e.g. RO).","example":"RO"},"lang":{"type":"string","minLength":2,"maxLength":3,"description":"Desired language of the answer (ISO 639-1/639-2 style code).","example":"en"},"profile":{"type":"string","enum":["speed","expert"],"description":"Pipeline preset: `speed` favors lower latency; `expert` favors deeper retrieval.","example":"speed"},"memo":{"type":"string","description":"Optional client-supplied label echoed in logs or support (no effect on retrieval).","example":"agent 007"},"response_transport":{"type":"string","enum":["sync","stream"],"default":"sync","description":"`sync` returns one JSON payload. `stream` uses Server-Sent Events (SSE) with multiple event types before completion.","example":"sync"},"debug":{"type":"object","properties":{"intent":{"type":"boolean"},"context":{"type":"boolean"},"metadata":{"type":"boolean"}},"description":"Optional flags; when set, the response may include extra diagnostic sections."}},"required":["user_id","api_key","query","country","lang","profile"]},"AskRagBody":{"type":"object","properties":{"query":{"type":"string","minLength":3,"description":"End-user question in natural language.","example":"What does Travel Allianz Voiaj cover?"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter market code for the document set (e.g. RO).","example":"RO"},"lang":{"type":"string","minLength":2,"maxLength":3,"description":"Desired language of the answer (ISO 639-1/639-2 style code).","example":"en"},"profile":{"type":"string","enum":["speed","expert"],"description":"Pipeline preset: `speed` favors lower latency; `expert` favors deeper retrieval.","example":"speed"},"memo":{"type":"string","description":"Optional client-supplied label echoed in logs or support (no effect on retrieval).","example":"agent 007"},"response_transport":{"type":"string","enum":["sync","stream"],"default":"sync","description":"`sync` returns one JSON payload. `stream` uses Server-Sent Events (SSE) with multiple event types before completion.","example":"sync"},"debug":{"type":"object","properties":{"intent":{"type":"boolean"},"context":{"type":"boolean"},"metadata":{"type":"boolean"}},"description":"Optional flags; when set, the response may include extra diagnostic sections."}},"required":["query","country","lang","profile"]},"AskSwaggerBody":{"type":"object","properties":{"user_id":{"type":"string","minLength":1,"description":"Account identifier issued to your integration.","example":"100"},"api_key":{"type":"string","minLength":1,"maxLength":128,"description":"Secret paired with `user_id` and your allowed caller networks.","example":"test1"},"query":{"type":"string","minLength":3,"description":"End-user question in natural language.","example":"What does Travel Allianz Voiaj cover?"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter market code for the document set (e.g. RO).","example":"RO"},"lang":{"type":"string","minLength":2,"maxLength":3,"description":"Desired language of the answer (ISO 639-1/639-2 style code).","example":"en"},"profile":{"type":"string","enum":["speed","expert"],"description":"Pipeline preset: `speed` favors lower latency; `expert` favors deeper retrieval.","example":"speed"},"memo":{"type":"string","description":"Optional client-supplied label echoed in logs or support (no effect on retrieval).","example":"agent 007"},"response_transport":{"type":"string","enum":["sync","stream"],"default":"sync","description":"`sync` returns one JSON payload. `stream` uses Server-Sent Events (SSE) with multiple event types before completion.","example":"sync"},"debug":{"type":"object","properties":{"intent":{"type":"boolean"},"context":{"type":"boolean"},"metadata":{"type":"boolean"}},"description":"Optional flags; when set, the response may include extra diagnostic sections."}},"required":["user_id","api_key","query","country","lang","profile"]},"CompareExport":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["product_compare"]},"answer_id":{"type":"string"},"country":{"type":"string"},"lang":{"type":"string"},"columns":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["label","product"]},"product_code":{"type":"string"},"header":{"type":"string"},"insurer":{"type":"string"}},"required":["role","header"]}},"rows":{"type":"array","items":{"type":"object","properties":{"row_id":{"type":"string"},"label":{"type":"string"},"cells":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"string"},"coverage":{"type":"string","enum":["missing","stated","partial"]},"citation_indexes":{"type":"array","items":{"type":"integer","minimum":0}}},"required":["value"]}}},"required":["row_id","label","cells"]}},"notes":{"type":"array","items":{"type":"string"}}},"required":["version","kind","answer_id","country","lang","columns","rows"]},"AskResponse":{"type":"object","properties":{"answer":{"type":"string","description":"Natural-language answer grounded in the citations."},"citations":{"type":"array","items":{"type":"object","properties":{"document_id":{"type":"string","format":"uuid","description":"Stable id of the cited wording document.","example":"b6575ba1-fb72-4404-924f-b1a5b2e98ea6"},"file_name":{"type":"string","description":"Published file name for the cited source.","example":"AllianzVoiaj.pdf"},"insurer":{"type":"string","description":"Insurer name for the cited source.","example":"Allianz"},"product_code":{"type":"string","description":"Product code for the cited wording.","example":"TRAVEL_VOIAJ"},"valid_from":{"type":"string","description":"Version start date for the cited wording (ISO 8601 date).","example":"2026-01-01"},"page_from":{"type":"number","description":"First page referenced in the source (1-based).","example":3},"page_to":{"type":"number","description":"Last page referenced in the source (1-based).","example":5}},"required":["document_id","file_name","insurer","product_code","valid_from"]},"description":"Sources used to support statements in the answer."},"chunks_used":{"type":"number","description":"Number of text segments passed into the answer step."},"retrieved_count":{"type":"number","description":"Number of segments retrieved before ranking."},"reranked_count":{"type":"number","description":"Number of segments kept after ranking."},"answer_id":{"type":"string","description":"Opaque id for this answer (support and correlation)."},"compare_export":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["product_compare"]},"answer_id":{"type":"string"},"country":{"type":"string"},"lang":{"type":"string"},"columns":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["label","product"]},"product_code":{"type":"string"},"header":{"type":"string"},"insurer":{"type":"string"}},"required":["role","header"]}},"rows":{"type":"array","items":{"type":"object","properties":{"row_id":{"type":"string"},"label":{"type":"string"},"cells":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"string"},"coverage":{"type":"string","enum":["missing","stated","partial"]},"citation_indexes":{"type":"array","items":{"type":"integer","minimum":0}}},"required":["value"]}}},"required":["row_id","label","cells"]}},"notes":{"type":"array","items":{"type":"string"}}},"required":["version","kind","answer_id","country","lang","columns","rows"],"description":"Present only for multi-product compare (PRODUCT_MULTI): structured matrix for Excel export (second Gemini pass)."}},"required":["answer","citations","chunks_used","retrieved_count","reranked_count","answer_id"],"example":{"answer":"Travel Allianz Voiaj covers ..","citations":[{"document_id":"b6575ba1-fb72-4404-924f-b1a5b2e98ea6","file_name":"AllianzVoiaj.pdf","insurer":"Allianz","product_code":"TRAVEL_VOIAJ","valid_from":"2026-01-01","page_from":1,"page_to":3}],"chunks_used":8,"retrieved_count":8,"reranked_count":8,"answer_id":"ans_237587e56243"}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code.","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error description.","example":"country is required and must be a valid country code"},"action":{"type":"string","description":"Suggested corrective action for the client.","example":"Provide a valid country code (e.g. RO)."}},"required":["code","message"]}},"required":["error"]},"CountriesResponse":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":2,"maxLength":2,"description":"ISO-like country code (2 letters).","example":"RO"},"name":{"type":"string","description":"Human-readable country name.","example":"Romania"}},"required":["code","name"]},"description":"Countries currently enabled for questions and documents."}},"required":["countries"]},"CountriesAccessRequest":{"type":"object","properties":{"user_id":{"type":"string","minLength":1,"description":"Account identifier issued to your integration.","example":"100"},"api_key":{"type":"string","minLength":1,"maxLength":128,"description":"Secret paired with `user_id` and your allowed caller networks.","example":"test1"}},"required":["user_id","api_key"]}},"parameters":{}},"paths":{"/ask":{"post":{"summary":"RAG query","description":"Answer a question using the configured insurance wording catalog. Responses are grounded in published policy documents only.\n\nSend a JSON body as documented below. **Required fields:** `user_id`, `api_key`, `query`, `country`, `lang`, and `profile`. `response_transport` defaults to `sync`. Other fields are optional.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string","minLength":1,"description":"Account identifier issued to your integration.","example":"100"},"api_key":{"type":"string","minLength":1,"maxLength":128,"description":"Secret paired with `user_id` and your allowed caller networks.","example":"test1"},"query":{"type":"string","minLength":3,"description":"End-user question in natural language.","example":"What does Travel Allianz Voiaj cover?"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter market code for the document set (e.g. RO).","example":"RO"},"lang":{"type":"string","minLength":2,"maxLength":3,"description":"Desired language of the answer (ISO 639-1/639-2 style code).","example":"en"},"profile":{"type":"string","enum":["speed","expert"],"description":"Pipeline preset: `speed` favors lower latency; `expert` favors deeper retrieval.","example":"speed"},"memo":{"type":"string","description":"Optional client-supplied label echoed in logs or support (no effect on retrieval).","example":"agent 007"},"response_transport":{"type":"string","enum":["sync","stream"],"default":"sync","description":"`sync` returns one JSON payload. `stream` uses Server-Sent Events (SSE) with multiple event types before completion.","example":"sync"},"debug":{"type":"object","properties":{"intent":{"type":"boolean"},"context":{"type":"boolean"},"metadata":{"type":"boolean"}},"description":"Optional flags; when set, the response may include extra diagnostic sections."}},"required":["user_id","api_key","query","country","lang","profile"]}}}},"responses":{"200":{"description":"Successful answer with citations","content":{"application/json":{"schema":{"type":"object","properties":{"answer":{"type":"string","description":"Natural-language answer grounded in the citations."},"citations":{"type":"array","items":{"type":"object","properties":{"document_id":{"type":"string","format":"uuid","description":"Stable id of the cited wording document.","example":"b6575ba1-fb72-4404-924f-b1a5b2e98ea6"},"file_name":{"type":"string","description":"Published file name for the cited source.","example":"AllianzVoiaj.pdf"},"insurer":{"type":"string","description":"Insurer name for the cited source.","example":"Allianz"},"product_code":{"type":"string","description":"Product code for the cited wording.","example":"TRAVEL_VOIAJ"},"valid_from":{"type":"string","description":"Version start date for the cited wording (ISO 8601 date).","example":"2026-01-01"},"page_from":{"type":"number","description":"First page referenced in the source (1-based).","example":3},"page_to":{"type":"number","description":"Last page referenced in the source (1-based).","example":5}},"required":["document_id","file_name","insurer","product_code","valid_from"]},"description":"Sources used to support statements in the answer."},"chunks_used":{"type":"number","description":"Number of text segments passed into the answer step."},"retrieved_count":{"type":"number","description":"Number of segments retrieved before ranking."},"reranked_count":{"type":"number","description":"Number of segments kept after ranking."},"answer_id":{"type":"string","description":"Opaque id for this answer (support and correlation)."},"compare_export":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"kind":{"type":"string","enum":["product_compare"]},"answer_id":{"type":"string"},"country":{"type":"string"},"lang":{"type":"string"},"columns":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["label","product"]},"product_code":{"type":"string"},"header":{"type":"string"},"insurer":{"type":"string"}},"required":["role","header"]}},"rows":{"type":"array","items":{"type":"object","properties":{"row_id":{"type":"string"},"label":{"type":"string"},"cells":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"string"},"coverage":{"type":"string","enum":["missing","stated","partial"]},"citation_indexes":{"type":"array","items":{"type":"integer","minimum":0}}},"required":["value"]}}},"required":["row_id","label","cells"]}},"notes":{"type":"array","items":{"type":"string"}}},"required":["version","kind","answer_id","country","lang","columns","rows"],"description":"Present only for multi-product compare (PRODUCT_MULTI): structured matrix for Excel export (second Gemini pass)."}},"required":["answer","citations","chunks_used","retrieved_count","reranked_count","answer_id"],"example":{"answer":"Travel Allianz Voiaj covers ..","citations":[{"document_id":"b6575ba1-fb72-4404-924f-b1a5b2e98ea6","file_name":"AllianzVoiaj.pdf","insurer":"Allianz","product_code":"TRAVEL_VOIAJ","valid_from":"2026-01-01","page_from":1,"page_to":3}],"chunks_used":8,"retrieved_count":8,"reranked_count":8,"answer_id":"ans_237587e56243"}}}}},"400":{"description":"Invalid input or unsupported request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code.","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error description.","example":"country is required and must be a valid country code"},"action":{"type":"string","description":"Suggested corrective action for the client.","example":"Provide a valid country code (e.g. RO)."}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Access denied (invalid credentials or caller not allowed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code.","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error description.","example":"country is required and must be a valid country code"},"action":{"type":"string","description":"Suggested corrective action for the client.","example":"Provide a valid country code (e.g. RO)."}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code.","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error description.","example":"country is required and must be a valid country code"},"action":{"type":"string","description":"Suggested corrective action for the client.","example":"Provide a valid country code (e.g. RO)."}},"required":["code","message"]}},"required":["error"]}}}}}}},"/countries":{"get":{"summary":"List enabled countries","description":"Returns country codes and labels that are currently enabled for this API. Use these codes as `country` on POST /ask. Send credentials in the JSON request body below (`Content-Type: application/json`).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string","minLength":1,"description":"Account identifier issued to your integration.","example":"100"},"api_key":{"type":"string","minLength":1,"maxLength":128,"description":"Secret paired with `user_id` and your allowed caller networks.","example":"test1"}},"required":["user_id","api_key"]}}}},"responses":{"200":{"description":"List of enabled countries","content":{"application/json":{"schema":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":2,"maxLength":2,"description":"ISO-like country code (2 letters).","example":"RO"},"name":{"type":"string","description":"Human-readable country name.","example":"Romania"}},"required":["code","name"]},"description":"Countries currently enabled for questions and documents."}},"required":["countries"]}}}},"400":{"description":"Missing required parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code.","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error description.","example":"country is required and must be a valid country code"},"action":{"type":"string","description":"Suggested corrective action for the client.","example":"Provide a valid country code (e.g. RO)."}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Access denied (invalid credentials or caller not allowed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code.","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error description.","example":"country is required and must be a valid country code"},"action":{"type":"string","description":"Suggested corrective action for the client.","example":"Provide a valid country code (e.g. RO)."}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Failed to load country list","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code.","example":"INVALID_INPUT"},"message":{"type":"string","description":"Human-readable error description.","example":"country is required and must be a valid country code"},"action":{"type":"string","description":"Suggested corrective action for the client.","example":"Provide a valid country code (e.g. RO)."}},"required":["code","message"]}},"required":["error"]}}}}}}}}}