> ## 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.

# Municipal tax regulations

> Search the tax regulations the tax authorities of Colombia's cities publish, Barranquilla, Medellín, Cali and Bucaramanga: acuerdos, decretos, resoluciones and circulares on predial, industria y comercio, retenciones and the calendario tributario, each with its original document; read any one.

Colombia's cities levy their own taxes (impuesto predial, industria y comercio and its retenciones, avisos y tableros, alumbrado público, delineación urbana, estampillas) under rules each city writes for itself: the acuerdos of its Concejo, which set and amend the city's tax statute, the decretos of its Alcalde, which regulate them, and the resoluciones and circulares of its Secretaría de Hacienda, which name the agentes de retención, set the calendario tributario and the autorretención rates, and open and close deadlines. Each city publishes its own list of these on its own site, and nowhere else.

This endpoint keeps those lists as one corpus, with a copy of every original document. It covers Barranquilla (about 170 acts and annexes from 2004, its yearly calendario tributario and valores absolutos among them), Medellín (about 120 acts from 2003, the Acuerdo 093 de 2023 statute among them) Cali (about 40 acts from 2020, the Acuerdo 643 de 2026 statute among them) and Bucaramanga (about 150 documents from 2001: its acts, the Decreto 040 de 2022 that compiles its tax regime and each year's calendario tributario among them, and the forms, guides and notices its page keeps beside them, as `otro`); more cities follow. Search by free text over the full text of each document, its label and the city's description, the best match first, or by city, kind, number, year or date, and read any one with the link to its document.

> [!NOTE]
>
> 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](https://docs.usecroma.com/datasets.md).

## Search the regulations

`POST /co/hacienda-municipal/regulations-search/v1` [Dataset](https://docs.usecroma.com/datasets.md)

One search over every act the covered cities list, filtered by city, kind, number, year or date.

| Field | Type | Notes |
| - | - | - |
| `query` | string | Optional words or a question, matched against the full text of each document, its label and the city's description, the best match first, e.g. `calendario tributario`, `autorretenedores` or `descuento por pronto pago del predial`. |
| `city` | enum | Optional: `barranquilla`, `medellin`, `cali` or `bucaramanga`. |
| `kind` | enum | Optional kind: `acuerdo` (of the Concejo), `decreto` (of the Alcalde), `resolucion` (of the city's tax authority), `circular` or `otro`. Default `any`. |
| `number` | string | Optional act number as the city prints it, e.g. `067`, `202550098566` or `SH18-007`. Leading zeros do not matter. |
| `year` | integer | Optional year of the act, 1990 or later. 0 searches every year. Default `0`. |
| `issued_from` | string | Optional: only acts dated on or after this day, `yyyy-mm-dd`. |
| `issued_to` | string | Optional: only acts dated on or before this day, `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/hacienda-municipal/regulations-search/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "calendario tributario", "city": "medellin" }'
```

Returns `as_of` (how current the data is), the applied filters, `total` and `total_is_exact`, `page`, `per_page`, `total_pages`, `count` and `results[]`, newest year first (best match first when `query` is set). Every result carries `id`, `city` (`barranquilla`, `medellin`, `cali` or `bucaramanga`), `city_name`, `entity` (the body that publishes it), `kind` (`acuerdo`, `decreto`, `resolucion`, `circular` or `otro`), `number`, `year`, `issued_at` (the date of the act, when the city's label gives a full one), `published_at` (when the city put the document on its page, when the page says so), `title` (as the city labels it), `summary` (the city's one-line description, when it gives one), `section` (the heading it sits under on the city's page), `official_url` (the city's listing page), `document_name`, `document_format`, `document_bytes`, `document_url` and `source_document_url`. `document_url` is Croma's copy of the document, byte for byte as the city published it, which stays available whatever happens to the city's link (null while the copy is still pending, and so are `document_name` and `document_format` for a city that names its files only in the document itself); `source_document_url` is the document on the city's own site. `viewer_url` opens the document in Croma Viewer, a page for signed-in Croma users that shows the PDF with the cited passages highlighted: add `&cite=<start>-<end>` once per passage, up to 12 (null when Croma holds no PDF of it). When `query` is set, each result also carries `matches[]`: up to 3 articles of the document that answer the search, best first, each with `article` (its heading as the document has it, e.g. `ARTÍCULO 5`, or null in a document without articles), `text` (the article exactly as it reads in the document), `start` and `end` (where it sits in the document's text), `scanned` and `viewer_url` (the document opened in Croma Viewer on that article, highlighted).

> [!NOTE]
>
> `scanned: true` means the city published that document as a scanned image and its text was recognized from it, which can introduce errors. Quote it, but check it against `document_url` before relying on the exact wording.

## One regulation, with its text

`POST /co/hacienda-municipal/regulation/v1` [Dataset](https://docs.usecroma.com/datasets.md)

| Field | Type | Notes |
| - | - | - |
| `regulation_id` | string | **Required.** The act's `id` from a search result, e.g. `medellin-b5327fbf73247a8c`, or its `source_document_url`. |
| `article` | string | Optional: return only this article, whole and verbatim, by its number or name as the document heads it, e.g. `1`, `118`, `primero` or `transitorio`. |
| `offset` | integer | First character of the text to return. Pass the previous response's `next_offset` to read on, or a search match's `start` to read from that passage. Default `0`. |
| `limit` | integer | How many characters of the text to return. Default `200000`. |

```bash theme={"dark"}
curl https://api.croma.run/co/hacienda-municipal/regulation/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "regulation_id": "medellin-b5327fbf73247a8c" }'
```

Returns `as_of`, `found`, `regulation_id` and `regulation`. Every result carries `id`, `city` (`barranquilla`, `medellin`, `cali` or `bucaramanga`), `city_name`, `entity` (the body that publishes it), `kind` (`acuerdo`, `decreto`, `resolucion`, `circular` or `otro`), `number`, `year`, `issued_at` (the date of the act, when the city's label gives a full one), `published_at` (when the city put the document on its page, when the page says so), `title` (as the city labels it), `summary` (the city's one-line description, when it gives one), `section` (the heading it sits under on the city's page), `official_url` (the city's listing page), `document_name`, `document_format`, `document_bytes`, `document_url` and `source_document_url`. `document_url` is Croma's copy of the document, byte for byte as the city published it, which stays available whatever happens to the city's link (null while the copy is still pending, and so are `document_name` and `document_format` for a city that names its files only in the document itself); `source_document_url` is the document on the city's own site. `viewer_url` opens the document in Croma Viewer, a page for signed-in Croma users that shows the PDF with the cited passages highlighted: add `&cite=<start>-<end>` once per passage, up to 12 (null when Croma holds no PDF of it).

The regulation also carries its document's text, so nothing has to be downloaded:

| Field | Notes |
| - | - |
| `content.text`, `content.offset` | The text asked for, verbatim, and the character it starts at: a range of the document, or the one article named by `article`. |
| `content.total_length` | The length of the document's whole text in characters. |
| `content.has_more`, `content.next_offset` | Whether the text asked for continues, and the `offset` to send to read on. |
| `article` | The article `content` holds, when `article` was sent and the document has it. |
| `articles[]` | The document's articles in order, each with `article`, `start` and `end`. |
| `text_url` | The whole text as one plain-text file, for a client that can download. |

> [!NOTE]
>
> `content` is null when the document has no text yet (a scan not read, a spreadsheet) or has no article of the name sent; `articles` lists the ones it has.

> [!NOTE]
>
> An `id` or link none of the cities' pages carries returns `found: false` with HTTP 200, not an error.

> [card] [Full reference](https://docs.usecroma.com/api-reference/overview.md)
>
> Schemas, all response fields, and an interactive playground.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.