> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SAMAI Relatoría
> Search every ruling of the Consejo de Estado since December 2021 by its headnotes, full text, chamber, kind, ponente, parties or date, and read any ruling with its full text and its document.
The Consejo de Estado's relatoría titles every ruling it publishes on SAMAI: sentencias, autos, aclaraciones and salvamentos de voto and conceptos, each with its headnotes (thesaurus descriptors, the legal problem and its answer, the thesis, the formal sources and the relatoría's notes). Every ruling dated since December 2021 comes here with those headnotes, the full text, the document itself and a link to the case on the court's own site.
Search across all of them at once, by chamber, kind, year, case, ponente, parties or date, or with free text that reaches into the headnotes and the body of every ruling. Search first, then read one ruling in full.
The whole source, organized and ready to query: every endpoint on this page answers in milliseconds. Every response carries `as_of`: how current the data is. [How datasets work](/datasets).
## Search the rulings
`POST /co/samai-rulings/search/v1` Dataset
One search over the headnotes and full text of every ruling of the Consejo de Estado since December 2021, filtered by chamber, kind, year, case, ponente, parties or date.
| Field | Type | Notes |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | string | Optional words matched against the headnotes (descriptors, legal problem, thesis, sources, relatoría note), the case number, the parties and the full text. |
| `chamber` | string | Optional chamber, matched from the start of its name: `Sección Tercera` also matches its subsecciones, `Sala de Consulta`. Case and accents are ignored. |
| `type` | string | Optional kind of ruling, matched from the start of its name: `Sentencia`, `Auto` (every kind of auto), `Salvamento voto`, `Aclaración voto`. Case and accents are ignored. |
| `year` | integer | Optional year of the ruling date. 0 searches every year. Default `0`. |
| `registration_number` | string | Optional 23-digit case number (radicado). Spaces, dots and dashes are ignored. |
| `reporting_judge` | string | Optional consejero ponente, by full name as it appears in `reporting_judges`. Case and accents are ignored. |
| `plaintiff` | string | Optional plaintiff, matched from the start of the name as the court lists it. Case and accents are ignored. |
| `defendant` | string | Optional defendant, matched from the start of the name as the court lists it. Case and accents are ignored. |
| `from_date` | string | Optional: only rulings handed down on or after this date, `yyyy-mm-dd`. |
| `to_date` | string | Optional: only rulings handed down on or before this date, `yyyy-mm-dd`. |
| `page` | integer | 1-based page number. Default `1`. |
| `per_page` | integer | Results per page (1-50). Default `20`. |
```bash theme={"dark"}
curl https://api.croma.run/co/samai-rulings/search/v1 \
-H "Authorization: Bearer $CROMA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "query": "reparación directa", "chamber": "Sección Tercera" }'
```
Returns `as_of` (how current the data is), the applied filters, `total` (matches across every page), `page`, `per_page`, `total_pages`, `count` and `results[]`, most recent ruling first. Every result carries `id` (the 64-character certificate of the ruling's document), `registration_number` (the 23-digit radicado; one case groups several rulings), `internal_number`, `chamber` and `chamber_key`, `type` and `type_key`, `proceeding_class` (the medio de control), `action`, `ruling_date`, `filing_date` (when the case entered the Consejo de Estado), `year`, `reporting_judges[]` and `reporting_judge_keys[]`, `plaintiff` and `defendant` with their `*_key` twins, the relatoría's headnotes (`descriptors[]`, `legal_problem`, `legal_problem_answer`, `thesis`, `formal_sources[]`, `relatoria_note`, and `headnotes[]` with each headnote on its own), `text_status`, `document_format`, `document_url` (the ruling's document, PDF, or Word for some of the oldest rulings, always available) and `official_url` (the case's page on the Consejo de Estado's own site).
Search results leave out the ruling's text. `query` still matches against it, so a phrase from the body finds the ruling; read the text itself with the SAMAI Ruling endpoint.
## One ruling, in full
`POST /co/samai-rulings/ruling/v1` Dataset
| Field | Type | Notes |
| ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `ruling_id` | string | **Required.** The ruling's `id` from a search result: the 64-character hexadecimal certificate of its document. Case is ignored. |
| `offset` | integer | First character of the text to return. Pass the previous response's `next_offset` to read on. Default `0`. |
| `limit` | integer | How many characters of the text to return. Most rulings fit in one response. Default `200000`. |
```bash theme={"dark"}
curl https://api.croma.run/co/samai-rulings/ruling/v1 \
-H "Authorization: Bearer $CROMA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ruling_id": "8C5E75723C249F020E54B1D2B2BCB0735566D537789B23F23B1373B33F24F21F"
}'
```
Returns `as_of`, `found`, `ruling_id` and `ruling`, which carries everything the search returns plus `content`: a window onto the ruling's full text, with `text`, `offset`, `total_length`, `has_more` and `next_offset`. Every result carries `id` (the 64-character certificate of the ruling's document), `registration_number` (the 23-digit radicado; one case groups several rulings), `internal_number`, `chamber` and `chamber_key`, `type` and `type_key`, `proceeding_class` (the medio de control), `action`, `ruling_date`, `filing_date` (when the case entered the Consejo de Estado), `year`, `reporting_judges[]` and `reporting_judge_keys[]`, `plaintiff` and `defendant` with their `*_key` twins, the relatoría's headnotes (`descriptors[]`, `legal_problem`, `legal_problem_answer`, `thesis`, `formal_sources[]`, `relatoria_note`, and `headnotes[]` with each headnote on its own), `text_status`, `document_format`, `document_url` (the ruling's document, PDF, or Word for some of the oldest rulings, always available) and `official_url` (the case's page on the Consejo de Estado's own site).
Long rulings run to tens of thousands of characters, so the text is read a range at a time: send `offset` and `limit`, then pass the response's `next_offset` back as `offset` until `has_more` is false. `content` is null when `text_status` is not `extracted`; `document_url` still has the document.
An `id` that is not in the relatoría returns `found: false` with HTTP 200, not an error. The relatoría titles a ruling weeks or months after it is handed down, so a recent ruling can be `found: false` today and present later.
Schemas, all response fields, and an interactive playground.