Senado Federal

Monitor and research Brazilian Senate legislative activity including bills, agendas, senators, votes, committees, speeches, and mandates via open data API.

Security Scan

The skill's code, instructions, and requirements are coherent with its stated purpose (a client for the Senado Federal open-data API); it requests no secrets and uses only the public Senate API.

Purpose & Capability

Name/description (monitor Brazilian Senate) matches the included code and SKILL.md: all code calls the public API at https://legis.senado.leg.br/dadosabertos and exposes endpoints for senators, bills, agendas, votes, committees, speeches, etc. No unrelated services, binaries, or credentials are requested.

Instruction Scope

SKILL.md lists concrete API endpoints and usage guidance only. The runtime instructions and included client code only perform HTTP GETs against the documented Senate endpoints; they do not instruct reading unrelated files, environment variables, or exfiltrating data to external domains.

Install Mechanism

This is declared as an instruction-only skill (no install spec). However, the package contains Python source files (an async httpx client, CLI script, and tests). While no external installers or download URLs are used, installing/running the included Python code will execute network requests. This is expected for the stated purpose but worth noting since code files exist despite 'instruction-only' install metadata.

Credentials

The skill requests no environment variables or credentials. The client operates against a public API that requires no auth; there are no hidden credential requests or access to unrelated secrets.

Persistence & Privilege

No 'always: true' or other elevated persistence is requested. The skill does not modify other skills or system-wide agent configs. Autonomous invocation is allowed by default (platform normal) but there are no additional privileged behaviors.

Assessment

This package appears to be a straightforward Python client for the Senado Federal open-data API and does not request credentials. Before installing, consider: (1) verify the author/source (some metadata/names differ between files: SKILL.md author, README author, and package version numbers are inconsistent), (2) run the code in an isolated environment (virtualenv/container) if you plan to execute scripts or tests, (3) the integration tests will call the real API if run, so run tests with network access disabled if you want to avoid remote calls, and (4) review the full code if you require stricter assurance (the client issues network requests to the public legis.senado.leg.br domain — expected, but any code execution should be audited in sensitive deployments).

Senado Federal — API de Dados Abertos

Base URL: https://legis.senado.leg.br/dadosabertos Swagger: https://legis.senado.leg.br/dadosabertos/api-docs/swagger-ui/index.html No authentication required. Format: append .json or .xml to endpoint paths.

---

Key Endpoints

Senators (Senadores)

GET /senador/lista/atual.json           # all senators currently in office
GET /senador/afastados.json             # senators on leave
GET /senador/lista/legislatura/{leg}.json  # by legislature number (e.g. 57)
GET /senador/partidos.json              # party list

GET /senador/{codigo}.json              # full senator profile
GET /senador/{codigo}/mandatos.json     # mandate history
GET /senador/{codigo}/filiacoes.json    # party affiliations
GET /senador/{codigo}/cargos.json       # positions held
GET /senador/{codigo}/comissoes.json    # committee memberships
GET /senador/{codigo}/liderancas.json   # leadership roles
GET /senador/{codigo}/discursos.json    # speeches
  ?dataInicio=YYYYMMDD&dataFim=YYYYMMDD&tipoPronunciamento=
GET /senador/{codigo}/apartes.json      # interjections
GET /senador/{codigo}/autorias.json     # authored bills
GET /senador/{codigo}/relatorias.json   # reports authored
GET /senador/{codigo}/votacoes.json     # voting history
GET /senador/{codigo}/profissao.json    # professional background
GET /senador/{codigo}/historicoAcademico.json
GET /senador/{codigo}/licencas.json     # leave periods

Bills / Matérias (API v2 — recommended)

GET /materia/pesquisa/lista.json
  ?sigla=PL          # type: PL, PEC, PLS, MSF, INC, etc.
  ?numero=123
  ?ano=2026
  ?autor=            # author name
  ?assunto=          # subject/keyword
  ?tramitando=S      # S=currently in progress
  ?codigoSituacao=

GET /materia/{codigo}.json              # by internal code
GET /materia/{sigla}/{numero}/{ano}.json  # e.g. /materia/PL/1234/2026.json
GET /materia/situacaoatual/{codigo}.json  # current status
GET /materia/votacoes/{codigo}.json     # votes on this bill
GET /materia/textos/{codigo}.json       # bill texts
GET /materia/emendas/{codigo}.json      # amendments
GET /materia/relatorias/{codigo}.json   # rapporteurs
GET /materia/autoria/{codigo}.json      # authorship
GET /materia/movimentacoes/{codigo}.json # full tramitação history
GET /materia/tramitando.json            # all currently in progress
GET /materia/legislaturaatual.json      # current legislature bills
GET /materia/atualizadas.json           # recently updated
  ?numdias=7         # last N days

Plenary Agenda & Results (Plenário)

GET /plenario/agenda/dia/{data}.json     # e.g. /plenario/agenda/dia/20260304.json
GET /plenario/agenda/mes/{data}.json     # e.g. /plenario/agenda/mes/202603.json
GET /plenario/agenda/cn/{data}.json      # Congresso Nacional joint session agenda

GET /plenario/resultado/{data}.json      # plenary results for a date (YYYYMMDD)
GET /plenario/resultado/mes/{data}.json  # monthly results (YYYYMM)

GET /plenario/lista/votacao/{dataInicio}/{dataFim}.json  # votes in date range (YYYYMMDD)
GET /plenario/votacao/nominal/{ano}.json  # all nominal votes in a year

GET /plenario/lista/discursos/{dataInicio}/{dataFim}.json  # speeches
GET /plenario/lista/legislaturas.json
GET /plenario/legislatura/{data}.json

GET /plenario/encontro/{codigo}.json       # session detail
GET /plenario/encontro/{codigo}/pauta.json # session agenda
GET /plenario/encontro/{codigo}/resultado.json
GET /plenario/encontro/{codigo}/resumo.json

Committees (Comissões)

GET /comissao/lista/colegiados.json      # all standing committees
GET /comissao/lista/mistas.json          # joint CN/Congresso committees
GET /comissao/lista/{tipo}.json          # by type

GET /comissao/{codigo}.json              # committee detail
GET /comissao/agenda/{dataReferencia}.json   # YYYYMMDD
GET /comissao/agenda/{dataInicio}/{dataFim}.json
GET /comissao/agenda/mes/{mesReferencia}.json  # YYYYMM
GET /comissao/agenda/atual/iCal          # iCal feed

GET /comissao/reuniao/{codigoReuniao}.json
GET /comissao/reuniao/notas/{codigoReuniao}.json

GET /composicao/comissao/{codigo}.json   # membership
GET /composicao/comissao/resumida/mista/{codigo}/{dataInicio}/{dataFim}.json

Voting in Committees (VotaçãoComissão)

GET /votacaoComissao/comissao/{siglaComissao}.json
GET /votacaoComissao/materia/{sigla}/{numero}/{ano}.json
GET /votacaoComissao/parlamentar/{codigo}.json

Voting (Geral)

GET /votacao.json
  ?dataInicio=YYYYMMDD&dataFim=YYYYMMDD
  ?codigoSessao=

Leadership & Composition

GET /composicao/mesaSF.json           # Senate presiding board
GET /composicao/mesaCN.json           # CN presiding board
GET /composicao/lideranca.json        # leadership
GET /composicao/lista/liderancaSF.json
GET /composicao/lista/liderancaCN.json
GET /composicao/lista/partidos.json
GET /composicao/lista/blocos.json
GET /composicao/bloco/{codigo}.json

Authors / Autores

GET /autor/lista/atual.json
GET /autor/tiposAutor.json

Legislation / Normas

GET /legislacao/lista.json
  ?tipo=&ano=&numero=
GET /legislacao/{codigo}.json
GET /legislacao/urn.json?urn={urn}

Taquigrafia (Transcripts)

GET /taquigrafia/notas/sessao/{idSessao}.json
GET /taquigrafia/notas/reuniao/{idReuniao}.json
GET /taquigrafia/videos/sessao/{idSessao}.json
GET /taquigrafia/videos/reuniao/{idReuniao}.json

Speeches / Discursos

GET /discurso/texto-integral/{codigoPronunciamento}.json
GET /discurso/texto-binario/{codigoPronunciamento}.json

---

Common Tasks

Today's plenary agenda

DATE=$(date +%Y%m%d)
curl "https://legis.senado.leg.br/dadosabertos/plenario/agenda/dia/$DATE.json"

Find a senator (search in lista/atual)

curl "https://legis.senado.leg.br/dadosabertos/senador/lista/atual.json" | \
  python3 -c "
import json,sys
data = json.load(sys.stdin)
senators = data['ListaParlamentarEmExercicio']['Parlamentares']['Parlamentar']
for s in senators:
    name = s['IdentificacaoParlamentar']['NomeParlamentar']
    if 'Pontes' in name:
        print(json.dumps(s, ensure_ascii=False, indent=2))
"

Search bills

curl "https://legis.senado.leg.br/dadosabertos/materia/pesquisa/lista.json?sigla=PL&ano=2026&tramitando=S&assunto=transporte"

Recent plenary votes

START=$(date -d '7 days ago' +%Y%m%d)
END=$(date +%Y%m%d)
curl "https://legis.senado.leg.br/dadosabertos/plenario/lista/votacao/$START/$END.json"

Committee agenda (current month)

MONTH=$(date +%Y%m)
curl "https://legis.senado.leg.br/dadosabertos/comissao/agenda/mes/$MONTH.json"

Bill tramitação

# By sigla/number/year:
curl "https://legis.senado.leg.br/dadosabertos/materia/movimentacoes/{codigo}.json"

---

Notes

• Date formats vary: plenary agenda uses YYYYMMDD; senator speeches use YYYYMMDD; materia pesquisa uses YYYY
• Current legislature: 57 (started Feb 2023)
• Senator codes (CodigoParlamentar) found in /senador/lista/atual.json
• Materia codes (codigo) found in /materia/pesquisa/lista.json results
• API v1 /materia/{sigla}/{numero}/{ano} is deprecated since 2025; prefer /processo or /materia/pesquisa/lista
• iCal feed available for committee agenda: /comissao/agenda/atual/iCal
• Full endpoint list: see references/api-endpoints.md

---

API Quirks & Tips

• Single-item responses: When an endpoint returns only 1 item, the Senado API may return a dict instead of a list. Always use the pattern: isinstance(x, list) else [x] if x else []
• Deeply nested JSON: Responses are typically 3-4 levels deep (e.g., data["ListaParlamentarEmExercicio"]["Parlamentares"]["Parlamentar"]). The Python client's _get_list() uses DFS to find the first list.
• Date format inconsistency: Plenário endpoints use YYYYMMDD; some senator endpoints also use YYYYMMDD; matéria pesquisa uses just YYYY for year filters.
• Processo vs Materia: /processo/{codigo}.json returns richer data (autuações, situações, tramitação completa) than /materia/{codigo}.json. Prefer processo for detailed status tracking.
• API v1 deprecation: /materia/{sigla}/{numero}/{ano} is deprecated since 2025. Use /materia/pesquisa/lista.json with params instead.
• Retry recommended: The API can be slow or return 500s. The Python client implements exponential backoff (2^attempt seconds).

---

Python Client (async)

You can use the async Python client for programmatic access:

import asyncio
from senado_client import get_senado_client

async def main():
    client = get_senado_client()
    
    # Listar senadores atuais
    senators = await client.lista_senadores_atuais()
    
    # Buscar por nome
    resultado = await client.buscar_senador_por_nome("Bolsonaro")
    
    # Pesquisar matérias
    materias = await client.pesquisar_materia(sigla="PL", ano=2026)
    
    # Votações da semana
    from datetime import date, timedelta
    votacoes = await client.get_votacoes_periodo(
        date.today() - timedelta(days=7),
        date.today()
    )
    
    await client.close()

asyncio.run(main())

Requires: pip install httpx

Available Methods

Senadores:

• lista_senadores_atuais() — Senadores em exercício
• buscar_senador_por_nome(nome) — Busca por nome
• get_senador_detalhe(codigo) — Detalhes completos
• get_autorias_senador(codigo) — Matérias de autoria
• get_discursos_senador(codigo, data_inicio?, data_fim?) — Discursos
• get_senador_votacoes(codigo) — Histórico de votações
• get_senador_comissoes(codigo) — Comissões
• get_senador_mandatos(codigo) — Mandatos
• get_senador_filiacoes(codigo) — Filiações partidárias
• get_senador_cargos(codigo) — Cargos exercidos
• get_senador_liderancas(codigo) — Lideranças
• get_senador_apartes(codigo) — Apartes/intervenções
• get_senador_relatorias(codigo) — Relatorias
• get_senador_profissao(codigo) — Profissão
• get_senador_historico_academico(codigo) — Histórico acadêmico
• get_senador_licencas(codigo) — Licenças

Matérias/Proposições:

• pesquisar_materia(sigla?, numero?, ano?, tramitando?) — Pesquisa
• pesquisar_materia_por_assunto(assunto, tramitando?) — Por assunto
• get_materia_detalhe(codigo) — Detalhes
• get_materia_movimentacoes(codigo) — Movimentações
• get_materia_tramitacao(codigo) — Tramitação
• get_materia_por_sigla(sigla, numero, ano) — Por sigla completa
• get_materia_situacao_atual(codigo) — Situação atual
• get_materia_textos(codigo) — Textos
• get_materia_emendas(codigo) — Emendas
• get_materia_relatorias(codigo) — Relatorias
• get_materia_autoria(codigo) — Autoria
• get_materias_tramitando() — Em tramitação
• get_materias_atualizadas(dias?) — Atualizadas recentemente

Plenário:

• get_agenda_plenario_dia(data?) — Agenda diária
• get_agenda_plenario_mes(ano, mes) — Agenda mensal
• get_votacoes_periodo(data_inicio, data_fim) — Votações em período
• get_resultado_plenario_dia(data) — Resultado do dia
• get_resultado_plenario_mes(ano, mes) — Resultado do mês
• get_votacoes_nominais_ano(ano) — Votações nominais
• get_discursos_plenario(data_inicio, data_fim) — Discursos
• get_encontro_plenario(codigo) — Detalhes de sessão
• get_encontro_pauta(codigo) — Pauta de sessão

Comissões:

• get_lista_comissoes() — Lista de comissões
• get_agenda_comissao_dia(data?) — Agenda do dia
• get_agenda_comissao_periodo(data_inicio, data_fim) — Agenda de período
• get_comissao_detalhe(codigo) — Detalhes
• get_comissao_reuniao(codigo_reuniao) — Reunião
• get_composicao_comissao(codigo) — Membros
• get_lista_comissoes_mistas() — Comissões mistas

Votação em Comissões:

• get_votacao_comissao(sigla_comissao) — Votações
• get_votacao_comissao_materia(sigla, numero, ano) — Por matéria
• get_votacao_comissao_parlamentar(codigo) — Por parlamentar

Composição e Lideranças:

• get_mesa_senado() — Mesa diretora do Senado
• get_mesa_congresso() — Mesa do CN
• get_liderancas() — Lideranças partidárias
• get_blocos_parlamentares() — Blocos parlamentares

Processo:

• get_processo(codigo) — Processo legislativo completo

Autores, Legislação, Discurso:

• get_autores_atuais() — Autores atuais
• pesquisar_legislacao(tipo?, ano?, numero?) — Pesquisa legislação
• get_discurso_texto_integral(codigo_pronunciamento) — Texto integral

Utilitários:

• get_materias_recentes(dias?) — Matérias recentes
• get_votacoes_semana() — Votações da semana
• get_agenda_semana() — Agenda da semana