Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ceibo.me/llms.txt

Use this file to discover all available pages before exploring further.

The Ceibo public API is a JSON-over-HTTPS REST interface. Every call goes through a single gateway in front of api.ceibo.me.

​
Base URL

https://api.ceibo.me/v1
All endpoints in this reference are relative to that base. URI versioning is in effect — when a new major version ships it will live at /v2 without breaking the /v1 contract. A liveness check is available at: 
curl https://api.ceibo.me/v1/health
It returns 200 OK with status, timestamp, and the deployed version when the API is healthy.

​
Authentication

Pass your API key in the x-api-key header on every request. See Authentication for the full key lifecycle and the JWT-based developer dashboard surface. 
x-api-key: ck_live_…

​
Pagination

Every list endpoint returns a paginated envelope. The shape is consistent regardless of resource: 
{
  "data": [
    { "id": 1, "name": "..." }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 195,
    "totalPages": 10
  }
}
Query paramDefaultMaxNotes
page1—1-based
limit20100Items per page
Some resources accept additional filters (name, iso2, continent, etc.) — check the endpoint reference for what each accepts.

​
Timestamps

All timestamps are ISO 8601 in UTC: 
2026-04-30T10:00:00.000Z
Both request and response bodies use this format. Date-only fields (e.g. expires_on on a passport) use YYYY-MM-DD.

​
Errors

The API returns a structured error envelope on any non-2xx response: 
{
  "statusCode": 404,
  "code": "NOT_FOUND",
  "message": "Country with id 9999 not found",
  "timestamp": "2026-04-30T10:00:00.000Z",
  "path": "/v1/countries/9999"
}
StatusCodeWhen
400VALIDATION_ERRORBody or query failed schema validation
401UNAUTHORIZEDMissing, revoked, or unknown API key
403FORBIDDENKey is valid but not allowed for this resource
404NOT_FOUNDResource does not exist
409CONFLICTUniqueness conflict (e.g. duplicate name)
422BUSINESS_RULE_VIOLATIONDomain rule rejected the request
429RATE_LIMIT_EXCEEDEDTier quota or burst limit hit
500INTERNAL_ERRORUnexpected server-side failure

​
CORS

The public API is consumable from browsers in production. Origins are allow-listed at the gateway — if you need a domain added, open an issue or contact support.

​
Conventions

  • Resource paths are plural (/countries, /cities).
  • IDs are integers, returned as numbers in JSON.
  • Field names are camelCase in responses; query parameters are also camelCase.
  • null is meaningful. A field returning null indicates the absence of data; the field is omitted only when explicitly noted.