> ## 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, Medellín and Cali today: 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. Today it covers Medellín (about 120 acts from 2003, the Acuerdo 093 de 2023 statute among them) and Cali (about 40 acts from 2020, the Acuerdo 643 de 2026 statute among them); more cities follow. Search by free text over each act's label and the city's description, 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 matched against each act's label and the city's description, e.g. `calendario tributario` or `autorretenedores`. |
| `city` | enum | Optional: `medellin` or `cali`. |
| `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` (`medellin` or `cali`), `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); `source_document_url` is the document on the city's own site.

## One regulation

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

```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` (`medellin` or `cali`), `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); `source_document_url` is the document on the city's own site.

> [!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.