Portal da Transparência: federal spending data without an API key

TL;DR

• The skill queries the Brazilian federal transparency portal (CGU) for expenses, bids, contracts, agreements, corporate cards, civil-servant pay, invoices, travel, parliamentary amendments, social benefits and sanctions — without an API key.
• It documents 27 datasets and two modes: bulk open data as CSV, and the site's internal APIs for a single query.
• The three barriers it removes are concrete: the official REST API requires a gov.br silver or gold account, the site sits behind AWS WAF which answers curl with a 202 or 405 challenge, and the bulk open data is not documented in a usable way.
• The useful discovery: the open-data bucket is public and has no WAF, so the zips download directly — what was missing was a map of which file belongs to which dataset and period.

What it is and who it is for

Portal da Transparência is a skill for Claude Code, plus Python scripts that also run on their own, for querying the CGU portal at portaldatransparencia.gov.br.

It is for the analyst, the journalist and the agent that need federal spending numbers by code and keep hitting the same three walls: an API that wants a gov.br account, a WAF that answers a challenge to anything that is not a browser, and a bulk download whose file naming is undocumented.

Two modes, and why they are separate

Bulk mode downloads open data as CSV. The README's discovery is that dadosabertos-download.cgu.gov.br/PortalDaTransparencia/saida/ serves the zips directly, with no key, no cookie and no captcha, and no WAF. The missing piece was the map: which file corresponds to which dataset and period.

Query mode uses the site's internal APIs for a single query, which is what you want when the question is one contract rather than one year of contracts.

# how much each agency spent on its corporate card in May 2026
python3 scripts/pt.py baixar cpgf 202605 --dir dados
python3 scripts/pt.py agregar dados/202605_CPGF.csv --por "NOME ÓRGÃO" --valor "VALOR TRANSAÇÃO"

# federal contracts signed in Q1 2026
python3 scripts/site.py consulta contratos --p assinaturaDe=01/01/2026 \
    --p assinaturaAte=31/03/2026 --tam 500 --paginas 4 --csv --out contratos.csv

The first pair is the pattern worth reading twice: download the month as CSV, then aggregate locally by column. That is what makes a question answerable without paginating a web API.

What it covers

Twenty-seven datasets, including expenses, bids, contracts, agreements, corporate cards, civil-servant pay, invoices, travel, parliamentary amendments, social benefits and sanctions. The README says everything here was verified empirically against the source rather than deduced from documentation, which is the distinction worth trusting: a documented endpoint and a working endpoint are different things in this portal.

The official REST API still exists and is still optional. It requires a gov.br silver or gold account, which the README calls a real barrier for a quick script, an analysis notebook or an autonomous agent. Use it when you need what it offers and you have the account; use the other two modes when you do not.

The traps

The README has a section named "traps that will bite you", and it is the most useful part of the repository: the site answers a browser-shaped request with a challenge, the period in a file name changes from dataset to dataset, and the download naming is not announced anywhere. Reading that section before writing code saves the afternoon.

Install

The scripts are Python 3.9+ and need no API key. The skill is a directory you copy into your agent's skills folder, and the scripts run from a terminal.

When to use it, when not to

Use it when you need a reproducible answer about federal spending, when you want a month of transactions as CSV instead of a paginated page, or when you want the corporate card or the agreement data and the official API's account is the blocker.

Do not use it as the official portal or as a substitute for one, and do not use the internal APIs as a stable contract — the README verifies them empirically, which means they can change. And do not use it for data outside the 27 sets: the README documents the coverage it verified, not the coverage the portal has.

Sources

1. Portal da Transparência — repository — the three barriers, the two modes, the open-data discovery, the 27 datasets and the traps section quoted above.
2. README.md — usage examples, install, dataset list, license (MIT).

Project page: Portal da Transparência

For the São Paulo portal, see the Portal da Transparência SP skill, and for Paraná, the Portal da Transparência PR skill.

FAQ

Does it need an API key? No. The README states the open-data bucket serves the zips directly with no key, cookie or captcha, and the tested paths need none either.

Why does the official API want an account? Because it requires a gov.br silver or gold account, which the README calls a real barrier for a script, a notebook or an autonomous agent.

What is the open-data discovery? That the open-data bucket is public and free of WAF, so what was missing was a map of which file belongs to which dataset and period.

Which datasets are covered? Twenty-seven, including expenses, bids, contracts, agreements, corporate cards, pay, invoices, travel, amendments, benefits and sanctions.