{"openapi":"3.1.0","info":{"title":"Uruguay Guide Chat API","version":"1.0.0","description":"Uruguay-only retrieval augmented chat with published Laravel knowledge and cited evidence. Examples illustrate response shapes; answers and sources depend on the current index."},"servers":[{"url":"/","description":"This running installation"}],"tags":[{"name":"Health","description":"Service and local index checks. Readiness does not probe the AI provider."},{"name":"Browser chat","description":"Same-origin browser endpoints. The server fixes country to UY."},{"name":"Integration","description":"Authenticated server-to-server chat."},{"name":"Administration","description":"An administration key is required; integration keys cannot perform these operations."}],"paths":{"/health":{"get":{"operationId":"getHealth","tags":["Health"],"summary":"Check that the server is running","security":[],"responses":{"200":{"description":"Server is running; this does not test Gemini connectivity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"},"example":{"status":"ok","service":"guide-chat-uruguay","country":"UY","version":"1.0.0"}}}}}}},"/ready":{"get":{"operationId":"getReadiness","tags":["Health"],"summary":"Check whether the local index is ready","security":[],"description":"Requires indexed documents compatible with the current embedding settings. Provider configuration is reported as unprobed; a successful chat verifies provider connectivity.","responses":{"200":{"description":"Index is ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"},"example":{"status":"ready","documents":28,"provider":"configured_not_probed"}}}},"503":{"description":"Index is empty, incompatible, or unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"not_ready"}},"required":["status"]},"example":{"status":"not_ready"}}}}}}},"/api/project/status":{"get":{"operationId":"getProjectStatus","tags":["Health"],"summary":"Read the project launch page health checks","security":[],"description":"A public, credential-free summary of the server, knowledge files, and search index. AI provider network connectivity is not probed.","responses":{"200":{"description":"Local health check results.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"One or more local checks require attention.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/config":{"get":{"operationId":"getBrowserConfig","tags":["Browser chat"],"summary":"Read safe browser settings","security":[],"responses":{"200":{"description":"Allowlisted configuration only; credentials are never included.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrowserConfig"}}}}}}},"/api/chat":{"post":{"operationId":"chatInBrowser","tags":["Browser chat"],"summary":"Ask the Uruguay assistant","security":[],"description":"Send JSON to this same-origin endpoint. Country and source exclusions are server decisions: including either field is rejected. The browser limit defaults to 8 requests/minute and 150 requests/day. Request Accept: text/event-stream for streaming when enabled; otherwise the response is JSON.","parameters":[{"in":"header","name":"Accept","schema":{"type":"string","enum":["application/json","text/event-stream"],"default":"application/json"},"description":"Select JSON or server-sent events. Streaming can be disabled by the installation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrowserChatRequest"},"example":{"message":"What is the capital of Uruguay?","interfaceLanguage":"en","replyLanguage":"auto","history":[]}}}},"responses":{"200":{"description":"A verified answer, fixed scope refusal, greeting, unavailable response, or evidence-not-found response. Stream deltas are provisional until done.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"},"example":{"status":"answered","answer":"The capital of Uruguay is Montevideo.","language":"en","partial":false,"sources":[{"sourceId":"country:UY","country":"UY","title":"Uruguay country profile","path":"/country-home/UY","type":"country_profile","language":"en","modifiedAt":null,"labels":{},"excerpt":"Capital: Montevideo"}],"redirect":null,"followUps":[]}},"text/event-stream":{"schema":{"type":"string"},"example":"event: status\ndata: {\"phase\":\"planning\"}\n\nevent: delta\ndata: {\"text\":\"The capital of Uruguay is Montevideo.\"}\n\nevent: status\ndata: {\"phase\":\"verifying\"}\n\nevent: done\ndata: {\"status\":\"answered\",\"answer\":\"The capital of Uruguay is Montevideo.\",\"language\":\"en\",\"partial\":false,\"sources\":[{\"sourceId\":\"country:UY\",\"country\":\"UY\",\"title\":\"Uruguay country profile\",\"path\":\"/country-home/UY\",\"type\":\"country_profile\",\"language\":\"en\",\"modifiedAt\":null,\"labels\":{},\"excerpt\":\"Capital: Montevideo\"}],\"redirect\":null,\"followUps\":[]}\n\n"}}},"400":{"description":"Invalid JSON or request fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Supporting evidence changed during generation; retry the question.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds 128 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request budget exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The request could not be completed. Use the request ID when investigating.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"AI provider or response validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/chat":{"post":{"operationId":"chatFromIntegration","tags":["Integration"],"summary":"Ask from a trusted server integration","security":[{"ApiKey":[]}],"description":"Accepts an integration or administration key. country must be UY. This endpoint returns JSON; streaming is offered through /api/chat. History is supplied by the caller; the service does not persist conversations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationChatRequest"},"example":{"country":"UY","message":"What is the capital of Uruguay?","interfaceLanguage":"en","replyLanguage":"auto","history":[],"excludeSourceIds":[]}}}},"responses":{"200":{"description":"Final assistant result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"},"example":{"status":"answered","answer":"The capital of Uruguay is Montevideo.","language":"en","partial":false,"sources":[{"sourceId":"country:UY","country":"UY","title":"Uruguay country profile","path":"/country-home/UY","type":"country_profile","language":"en","modifiedAt":null,"labels":{},"excerpt":"Capital: Montevideo"}],"redirect":null,"followUps":[]}}}},"400":{"description":"Invalid JSON or request fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A valid X-API-Key header is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Supporting evidence changed; retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds 128 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request budget exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The request could not be completed. Use the request ID when investigating.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"AI provider request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/status":{"get":{"operationId":"getAdminStatus","tags":["Administration"],"summary":"Inspect the index and synchronization state","security":[{"ApiKey":[]}],"x-required-role":"admin","description":"Returns index compatibility, current document counts, per-country index totals, the most recent synchronization, and whether a synchronization is running.","responses":{"200":{"description":"Current administration status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminStatus"}}}},"401":{"description":"A valid X-API-Key header is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"An administration key is required for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request budget exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The request could not be completed. Use the request ID when investigating.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/knowledge":{"get":{"operationId":"getKnowledge","tags":["Administration"],"summary":"Inspect knowledge provenance and indexed documents","security":[{"ApiKey":[]}],"x-required-role":"admin","description":"Lists Uruguay document metadata. In bundled mode, the snapshot manifest is validated before it is returned. Website mode has no bundled manifest. No credentials or raw environment settings are returned.","parameters":[{"in":"query","name":"search","schema":{"type":"string","maxLength":200,"default":""},"description":"Search document metadata."},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Validated provenance and a page of indexed document metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeResponse"}}}},"400":{"description":"Invalid JSON or request fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A valid X-API-Key header is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"An administration key is required for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request budget exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The request could not be completed. Use the request ID when investigating.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Knowledge validation could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sync":{"post":{"operationId":"synchronizeKnowledge","tags":["Administration"],"summary":"Synchronize the configured knowledge source","security":[{"ApiKey":[]}],"x-required-role":"admin","description":"Incrementally embeds new or changed documents and removes withdrawn records. Bundled mode reads the existing knowledge files; it does not fetch a fresh Laravel export. Overlapping sync requests are coalesced. Provider usage can occur for changed content.","parameters":[{"in":"query","name":"wait","schema":{"type":"string","enum":["1","true"]},"description":"Wait for the result instead of returning 202 Accepted."}],"responses":{"200":{"description":"Completed synchronization summary (when wait=1 or wait=true).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncResult"}}}},"202":{"description":"Synchronization accepted. Poll /v1/status.","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"const":"accepted"}}},"example":{"status":"accepted"}}}},"401":{"description":"A valid X-API-Key header is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"An administration key is required for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request budget exceeded. Respect the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The request could not be completed. Use the request ID when investigating.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Website export or AI provider request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Use the integration key for /v1/chat. Use the separate administration key for status, knowledge, and synchronization. Never place keys in URLs or browser storage."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}},"Health":{"type":"object","required":["status","service","country","version"],"properties":{"status":{"const":"ok"},"service":{"const":"guide-chat-uruguay"},"country":{"const":"UY"},"version":{"type":"string"}}},"Readiness":{"type":"object","required":["status","documents","provider"],"properties":{"status":{"const":"ready"},"documents":{"type":"integer","minimum":1},"provider":{"const":"configured_not_probed"}}},"BrowserConfig":{"type":"object","properties":{"country":{"const":"UY"},"websiteUrl":{"type":"string","format":"uri"},"streamingEnabled":{"type":"boolean"},"maxMessageChars":{"type":"integer"},"maxHistoryMessages":{"type":"integer"},"requestTimeoutMs":{"type":"integer"}}},"HistoryMessage":{"type":"object","additionalProperties":false,"required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","minLength":1,"maxLength":4000}}},"BrowserChatRequest":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string","minLength":1,"maxLength":2000,"description":"Question text. Leading and trailing whitespace is removed."},"history":{"type":"array","maxItems":12,"default":[],"items":{"$ref":"#/components/schemas/HistoryMessage"},"description":"Previous user/assistant turns. System messages are not accepted."},"interfaceLanguage":{"type":"string","enum":["ar","en","es","pt"],"default":"ar","description":"Interface language and default answer language."},"replyLanguage":{"type":"string","enum":["auto","ar","en","es","pt"],"default":"auto","description":"An explicit answer-language preference."}}},"IntegrationChatRequest":{"type":"object","additionalProperties":false,"required":["country","message"],"properties":{"country":{"const":"UY"},"message":{"type":"string","minLength":1,"maxLength":2000,"description":"Question text. Leading and trailing whitespace is removed."},"history":{"type":"array","maxItems":12,"default":[],"items":{"$ref":"#/components/schemas/HistoryMessage"},"description":"Previous user/assistant turns. System messages are not accepted."},"interfaceLanguage":{"type":"string","enum":["ar","en","es","pt"],"default":"ar","description":"Interface language and default answer language."},"replyLanguage":{"type":"string","enum":["auto","ar","en","es","pt"],"default":"auto","description":"An explicit answer-language preference."},"excludeSourceIds":{"type":"array","maxItems":50,"default":[],"items":{"type":"string","minLength":3,"maxLength":280},"description":"Source identifiers withdrawn or excluded by the trusted caller."}}},"Source":{"type":"object","required":["sourceId","country","title","path","type","language","excerpt"],"properties":{"sourceId":{"type":"string"},"country":{"const":"UY"},"title":{"type":"string"},"path":{"type":"string","pattern":"^/country-home/UY(?:[/?#]|$)"},"type":{"type":"string"},"language":{"type":"string"},"modifiedAt":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":true},"excerpt":{"type":"string","maxLength":300},"members":{"type":"array","maxItems":1000,"items":{"type":"string"},"description":"Present for computed collection evidence."}}},"ChatResponse":{"type":"object","required":["status","answer","language","sources","redirect","followUps"],"properties":{"status":{"type":"string","enum":["answered","not_found","out_of_scope","greeting","unavailable"]},"answer":{"type":"string","maxLength":6000},"language":{"type":"string","enum":["ar","en","es","pt"]},"partial":{"type":"boolean","description":"Present for answered responses; true when the evidence answers only part of the question."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"redirect":{"type":"null"},"followUps":{"type":"array","maxItems":3,"items":{"type":"string","maxLength":200}}}},"IndexState":{"type":"object","properties":{"compatible":{"type":"boolean"},"documents":{"type":"integer"},"currentDocuments":{"type":"integer"}}},"CountryIndex":{"type":"object","properties":{"country":{"const":"UY"},"documents":{"type":"integer"},"sources":{"type":"integer"},"chunks":{"type":"integer"},"indexedAt":{"type":["string","null"],"format":"date-time"}}},"SyncResult":{"type":"object","properties":{"status":{"type":"string","enum":["succeeded","failed"]},"at":{"type":"string","format":"date-time"},"countries":{"type":"integer"},"documents":{"type":"integer"},"added":{"type":"integer"},"updated":{"type":"integer"},"deleted":{"type":"integer"},"deletedCountries":{"type":"array","items":{"type":"string"}},"unchanged":{"type":"integer"},"chunksEmbedded":{"type":"integer"},"failed":{"type":"integer"},"skipped":{"type":"object","additionalProperties":{"type":"integer"}},"ms":{"type":"integer"},"code":{"type":"string"}}},"AdminStatus":{"type":"object","properties":{"index":{"$ref":"#/components/schemas/IndexState"},"countries":{"type":"array","items":{"$ref":"#/components/schemas/CountryIndex"}},"lastSync":{"type":["object","null"],"additionalProperties":true,"description":"A current process sync summary or persisted sync-run record. Persisted records carry summary fields under stats."},"syncing":{"type":"boolean"}}},"KnowledgeManifest":{"type":"object","properties":{"status":{"const":"valid"},"version":{"const":1},"country":{"const":"UY"},"generatedAt":{"type":"string","format":"date-time"},"exportedAt":{"type":"string","format":"date-time"},"documentCount":{"type":"integer"},"sourceCount":{"type":"integer"},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"source":{"type":"string"}}},"KnowledgeDocument":{"type":"object","properties":{"id":{"type":"string"},"sourceId":{"type":"string"},"type":{"type":"string"},"language":{"type":"string"},"title":{"type":"string"},"path":{"type":"string"},"modifiedAt":{"type":["string","null"]},"characters":{"type":"integer"},"chunks":{"type":"integer"}}},"KnowledgeResponse":{"type":"object","properties":{"source":{"type":"string","enum":["bundled","website"]},"bundle":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeManifest"},{"type":"null"}]},"documents":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeDocument"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}