---
title: "SAMAI Rulings Search"
method: POST
path: "/co/samai-rulings/search/v1"
tags: ["Colombia", "SAMAI / Consejo de Estado"]
---

# SAMAI Rulings Search

`POST /co/samai-rulings/search/v1`

## Request

- Base URL: `https://api.croma.run`
- URL: `https://api.croma.run/co/samai-rulings/search/v1`
- Auth: HTTP bearer

Search every ruling of the Consejo de Estado dated since December 2021 that its relatoría has titled: sentencias, autos, aclaraciones and salvamentos de voto and conceptos, each with the relatoría's headnotes (descriptors, legal problem and answer, thesis, formal sources, notes), its full text, its document (PDF, or Word for some of the oldest) and the case's page on the court's own site. Free text matches the headnotes, the case number, the parties and the full text. Filter by `chamber`, `type`, `year`, `registration_number` (the radicado), `reporting_judge` (the consejero ponente), `plaintiff`, `defendant` and the ruling date (`from_date`/`to_date`). Served by Croma (`as_of` says how current the data is).

**Dataset endpoint**: answers from the whole source in milliseconds and carries `as_of`.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `query` string: Optional search terms matched against the ruling's headnotes (descriptors, legal problem, thesis, sources, relatoría note), its case number, its parties and its full text.
  - `chamber` string: Optional chamber (sección or sala), matched from the start of its name: `Sección Tercera` also matches its subsecciones. 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.
  - `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, date: Optional date filter in yyyy-mm-dd format.
  - `to_date` string, date: Optional date filter in yyyy-mm-dd format.
  - `page` integer: 1-based page number for paginated results.
  - `per_page` integer: Results per page (1-50).

## Response `200`

Successful response

- SamaiRulingsSearchResponse
  - `data` SamaiRulingsSearchData, required
    - `as_of` string, nullable, required: How current the data in this response is.
    - `query` string, required
    - `chamber` string, nullable, required
    - `type` string, nullable, required
    - `year` number, nullable, required
    - `registration_number` string, nullable, required
    - `reporting_judge` string, nullable, required
    - `plaintiff` string, nullable, required
    - `defendant` string, nullable, required
    - `from_date` string, nullable, required
    - `to_date` string, nullable, required
    - `total` number, required: Matches, counted up to 1000.
    - `total_is_exact` boolean, required: False when more than 1000 match: `total` is then 1000, and the pages go on.
    - `page` number, required
    - `per_page` number, required
    - `total_pages` number, required: Pages over `total`; there are more when `total_is_exact` is false.
    - `count` number, required
    - `results` object[], required
      - `id` string, required: The ruling's identifier: the 64-character hexadecimal certificate of its document, as the court prints it. One case (`registration_number`) groups several rulings, each with its own `id`.
      - `registration_number` string, required: The 23-digit case number (radicado) the ruling belongs to.
      - `internal_number` string, nullable, required: The case's internal number at the Consejo de Estado. Null when it has none.
      - `chamber` string, nullable, required: The deciding chamber as the court names it, e.g. "Sección Tercera (Subsección B)", "Sala de Consulta y Servicio Civil".
      - `chamber_key` string, nullable, required: The chamber in canonical form (lowercased, unaccented, hyphenated: "seccion-tercera-subseccion-b"), which is what the `chamber` filter matches from the start.
      - `type` string, nullable, required: The kind of ruling as the court names it, e.g. "Sentencia", "Auto interlocutorio", "Salvamento voto", "Aclaración voto".
      - `type_key` string, nullable, required: The kind of ruling in canonical form ("auto-interlocutorio"), which is what the `type` filter matches from the start.
      - `proceeding_class` string, nullable, required: The class of proceeding (medio de control), as the court records it, e.g. "LEY 1437 NULIDAD Y RESTABLECIMIENTO DEL DERECHO".
      - `action` string, nullable, required: What the ruling does in the case, e.g. "Auto que admite demanda", "Sentencia".
      - `ruling_date` string, required: `yyyy-mm-dd` the court records for the ruling: the date a sentencia or auto is handed down, which its document opens with; for an aclaración or salvamento de voto, the date the court recorded the vote.
      - `filing_date` string, nullable, required: `yyyy-mm-dd` the case entered the Consejo de Estado. Null when the court records none.
      - `year` number, required: The year of `ruling_date`.
      - `reporting_judges` string[], required: The consejero or consejera ponente, as the court names them.
      - `reporting_judge_keys` string[], required: The same names in canonical form (lowercased, unaccented, hyphenated: "alberto-montana-plata"), which is what the `reporting_judge` filter matches.
      - `plaintiff` string, nullable, required: The plaintiff (actor) as the court lists it. Null when it lists none.
      - `plaintiff_key` string, nullable, required: The plaintiff in canonical form, cut to its first 200 characters, which is what the `plaintiff` filter matches from the start.
      - `defendant` string, nullable, required: The defendant (demandado) as the court lists it. Null when it lists none.
      - `defendant_key` string, nullable, required: The defendant in canonical form, cut to its first 200 characters, which is what the `defendant` filter matches from the start.
      - `descriptors` string[], required: Every thesaurus descriptor the relatoría recorded for the ruling, across its headnotes, without repeats.
      - `legal_problem` string, nullable, required: The legal problem the ruling resolves; with several headnotes, each one in order, separated by a blank line.
      - `legal_problem_answer` string, nullable, required: The answer to each legal problem, "Si" or "No", in the same order and separated the same way. `headnotes[]` pairs each problem with its answer.
      - `thesis` string, nullable, required: The relatoría's thesis or extract of the ruling; with several headnotes, each one in order, separated by a blank line.
      - `formal_sources` string[], required: Every norm the headnotes rest on, without repeats.
      - `relatoria_note` string, nullable, required: The relatoría's notes on related rulings and precedent; with several headnotes, each one in order, separated by a blank line.
      - `headnotes` object[], required: The relatoría's headnotes (titulación), one per legal problem, in order.
        - `descriptors` string[], required: The thesaurus descriptors of this headnote, in the order the relatoría chains them.
        - `legal_problem` string, nullable, required: The legal problem this headnote poses. Null when it poses none.
        - `legal_problem_answer` string, nullable, required: The relatoría's answer to the legal problem, as it prints it: "Si" or "No". Null when there is none.
        - `thesis` string, nullable, required: The thesis or extract of the ruling this headnote records.
        - `formal_sources` string[], required: The norms the headnote rests on, one per entry, e.g. "LEY 1437 DE 2011 - ARTÍCULO 188".
        - `challenged_norms` string, nullable, required: The challenged norms, as the relatoría records them, when the proceeding attacks one.
        - `relatoria_note` string, nullable, required: The relatoría's note: related rulings and precedent it points to.
      - `text_status` 'extracted' | 'no_text_layer' | 'unavailable', required: `extracted` when `text` holds the document's text, `no_text_layer` when the document is a scan without one, `unavailable` when the document could not be read yet.
      - `document_format` 'pdf' | 'docx' | 'doc', nullable, required: The format of the ruling's document: `pdf`, or `docx` or `doc` (Word) for some of the oldest rulings.
      - `document_url` string, nullable, required: The ruling's document (PDF, or Word for some of the oldest rulings), always available at this address. Null only while `text_status` is `unavailable`.
      - `official_url` string, required: The case's page on the Consejo de Estado's own site (SAMAI), where the court publishes its record and documents.

## Other responses

- `400`: Invalid request body
- `401`: Missing or invalid API key
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream source returned an error

---

[API](https://skmtc.dev/usecroma/apis/croma-marketplace-api.md) · [All operations](https://skmtc.dev/usecroma/apis/croma-marketplace-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usecroma/apis/croma-marketplace-api/revisions/df016cdb29d7?raw)