> Also available in Spanish: https://cubaresearchproject.com/es/developers/ # Cuba Research Project API and Developer Documentation The Cuba Research Project archive is readable by machines as well as by people. Everything on this page is public, needs no key, and is served from ``. ## Quick reference | Resource | URL | | --- | --- | | API index | [/api](/api) | | OpenAPI 3.1 specification | [/api/openapi.json](/api/openapi.json) | | Interactive API documentation | [/api/docs](/api/docs) | | Agent guide (llms.txt) | [/llms.txt](/llms.txt) | | Full agent guide | [/llms-full.txt](/llms-full.txt) | | Sitemap | [/sitemap.xml](/sitemap.xml) | | API catalogue (RFC 9727) | [/.well-known/api-catalog](/.well-known/api-catalog) | ## Public REST endpoints All responses are JSON. `GET` only; no authentication. **`GET /api/health`**: liveness. Returns `{"status":"ok"}`. **`GET /api/meta`**: the archive's shape: every dataset with its record count, the record types in use, and the total number of indexed people. **`GET /api/collections`**: the full collection listing, one entry per dataset, each with the URL of its own page on this site. **`GET /api/search`**: the search that powers this site. Parameters: `q` (whole name), `given`, `surname`, `surname2`, `place`, `dataset` (id), `type` (record-type id), `yfrom` / `yto` (event year), `bfrom` / `bto` (birth year), `dfrom` / `dto` (death year), `sort`, `page`, and `source` (`records`, `trees`, or both). Returns `total`, `page`, `page_size`, `pages`, `rows`, and facet counts by record type and collection. Pages hold 24 rows. **`GET /api/suggest`**: typeahead over the name index. Takes the same name parameters as search and returns the most frequent matching names. **`GET /api/record/{record_id}`**: one record in full, including its dataset, record type, source, and the fields as transcribed. `404` when the record does not exist. **`GET /api/record/{record_id}/companions`**: the other people named on the same document. **`GET /api/person/{person_id}/main-record`**: the record a person belongs to. **`GET /api/stats/imports`**: a daily series of records added to the archive. **`GET /api/random`**: a random person, for discovery. ### Example Search for people whose paternal surname resembles *Valdés*, born between 1880 and 1900: ``` curl "/api/search?surname=Valdes&bfrom=1880&bto=1900" ``` Names are matched accent- and case-insensitively, so `Valdes` and `Valdés` return the same people. ## Markdown for agents Every content page on this site is also published as Markdown. Ask for it with content negotiation: ``` curl -H "Accept: text/markdown" /developers/ ``` The Markdown variant of a page also has a stable address of its own: append the page's path to `/md` and add `index.md`, as in `/md/developers/index.md`. Negotiated responses carry `Vary: Accept, Accept-Encoding`. A request that will accept only Markdown for a page that has no Markdown variant is answered with `406 Not Acceptable`. ## Errors Unknown paths return a real `404`, with a short Markdown body for clients that did not ask for HTML. Nothing on this site answers a missing page with a `200`. ## Terms The archive is offered for research and personal use. Please identify your client with a descriptive `User-Agent`, keep request rates civil, and credit Cuba Research Project when you publish anything built on it. Questions: [contact us](/contact).