{"openapi":"3.1.0","info":{"title":"Costa Rica Guide Chat API","version":"1.0.0","description":"Costa Rica-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 CR."},{"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-costa-rica","country":"CR","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 Costa Rica 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 Costa Rica?","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 Costa Rica is Montevideo.","language":"en","partial":false,"sources":[{"sourceId":"country:CR","country":"CR","title":"Costa Rica country profile","path":"/country-home/CR","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 Costa Rica is Montevideo.\"}\n\nevent: status\ndata: {\"phase\":\"verifying\"}\n\nevent: done\ndata: {\"status\":\"answered\",\"answer\":\"The capital of Costa Rica is Montevideo.\",\"language\":\"en\",\"partial\":false,\"sources\":[{\"sourceId\":\"country:CR\",\"country\":\"CR\",\"title\":\"Costa Rica country profile\",\"path\":\"/country-home/CR\",\"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 CR. 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":"CR","message":"What is the capital of Costa Rica?","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 Costa Rica is Montevideo.","language":"en","partial":false,"sources":[{"sourceId":"country:CR","country":"CR","title":"Costa Rica country profile","path":"/country-home/CR","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 Costa Rica 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-costa-rica"},"country":{"const":"CR"},"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":"CR"},"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":"CR"},"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":"CR"},"title":{"type":"string"},"path":{"type":"string","pattern":"^/country-home/CR(?:[/?#]|$)"},"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":"CR"},"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":"CR"},"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"}}}}}}