Corpus e ref_key

As rotas de leitura funcionam sem chave (30 req/min por IP). Todas estão detalhadas, com "Try it", na Referência da API → Corpus.

ref_key

Todo dispositivo tem um identificador canônico, o mesmo que o /resolver devolve:

SIGLA.artigo[.paragrafo][.inciso][.alinea][.item]

Só os níveis que existem entram na chave, sem segmentos vazios. Cada nível é reconhecido pela forma: parágrafo é número ou unico; inciso é romano maiúsculo; alínea é minúscula; item é número. Por isso CF.5.I é o inciso I e CF.5.i seria a alínea i. Exemplos:

Regras: artigo sem pontos de milhar e com sufixo maiúsculo (1003, 5-A); parágrafo é número ou unico; inciso em romano maiúsculo; alínea minúscula; item numérico. Súmulas comuns usam SUM, vinculantes SV. A chave é sensível a maiúsculas.

A chave vai na URL sem escape: /v1/dispositivos/CPC.1003.5.

Rotas

Artigo completo

GET /v1/diplomas/CPC/artigos/1003:

{
  "diploma": { "sigla": "CPC", "nome": "Código de Processo Civil" },
  "ref_key": "CPC.1003",
  "artigo": "1003",
  "hierarquia": "Parte Especial > Livro III – … > Título II – Dos Recursos > Capítulo I – Disposições Gerais",
  "revogado": false,
  "caput": "O prazo para interposição de recurso conta-se da data em que os advogados, …",
  "texto": "O prazo para interposição de recurso conta-se …\n§ 1º Os sujeitos previstos no caput …\n§ 2º …",
  "anotacoes": [],
  "alterado_por": null,
  "revogado_por": null,
  "dispositivos": [ { "ref_key": "CPC.1003.1", "paragrafo": "1", "texto": "…", "revogado": false, "anotacoes": [], "alterado_por": null, "revogado_por": null } ],
  "anterior": "1002",
  "proximo": "1004"
}

Na linha do artigo, caput é só o caput e texto é o artigo inteiro (caput + parágrafos, incisos, alíneas e itens rotulados, um por linha), ideal para injetar em um prompt. anotacoes, alterado_por e revogado_por aí são os do caput; os de cada filho estão em dispositivos.

Exportar um diploma inteiro

GET /v1/diplomas/CC/export devolve, em uma única resposta, os metadados do diploma, o sumario, a data snapshot_at (última ingestão que alterou o diploma) e todos os dispositivos em ordem de leitura, cada um no mesmo formato de GET /v1/dispositivos/{ref_key}. É a forma certa de montar um snapshot offline: um pedido por diploma (531 no total), em vez de um por artigo. A resposta vem comprimida quando o cliente envia Accept-Encoding: gzip e é cacheável por 24 h (Cache-Control: public, max-age=86400).

Para manter o snapshot atualizado depois, use o feed de alterações com desde=<snapshot_at> e busque só os artigos que mudaram.

Texto limpo e anotações

texto é só o texto legal. As marcações editoriais que o Planalto embute na página, como "(Incluído pela Emenda Constitucional nº 45, de 2004)", "(Vide ADIN 3392)", "(Revogado pela Lei nº …)", "Vigência" e "Regulamento", vêm separadas em anotacoes (lista de strings, sem os parênteses, na ordem em que aparecem). Delas saem dois campos estruturados:

• alterado_por: diploma da última anotação "Redação dada / Incluído / Renumerado pela …".
• revogado_por: diploma da anotação "Revogado pela …". Quando o Planalto escreve só "(revogado)" ao lado de "(Redação dada pela Lei X)", é a Lei X. null quando não há; caso típico: dispositivo incluído por medida provisória rejeitada.

Para exibir num app, use texto; para grounding de um LLM, texto + anotacoes dão o mesmo que a página do Planalto. No texto do artigo, um filho revogado sem redação aparece como § 1º (revogado) e um vetado como Parágrafo único. (vetado).

Hierarquia

hierarquia é o caminho do dispositivo na estrutura da lei, do nível mais alto ao mais baixo, separado por >: Título II – Dos Direitos e Garantias Fundamentais > Capítulo I – Dos Direitos e Deveres Individuais e Coletivos. Cada nível é Rótulo – Nome (Título II, Capítulo I, Seção III); rubricas de artigo (CP, CPP: "Homicídio simples") entram como último nível. Os nomes vêm do Planalto com a caixa normalizada (Title Case; a página original mistura caixa alta e mista). É texto de exibição; para navegar pela estrutura, use o sumario de GET /v1/diplomas/{sigla}.

Dispositivo revogado

revogado: true sempre. O que vai em texto depende de como o Planalto publica:

Regra: texto não vazio em dispositivo revogado é redação revogada, nunca vigente: exiba tachado ou com aviso, não como texto em vigor. Dispositivo vetado vem com revogado: false, texto: "" e "VETADO" em anotacoes.

Busca

GET /v1/busca?q=razoável duração do processo&siglas=CF,CPC&limit=5

• q (2–300 caracteres) aceita a sintaxe do websearch_to_tsquery: aspas para frase, - para excluir, or.
• siglas restringe a diplomas; tipo=dispositivo|sumula filtra o tipo.
• Cada resultado traz ref_key, trecho com <b>…</b> nos termos, rank, inativo (revogado ou cancelada) e alterador (comando que muda outro diploma).
• incluir_alteradores=false remove os dispositivos alteradores. O vetor de busca deles indexa só o comando (antes das aspas), então buscar "razoável duração do processo" acha o dispositivo da CF, não o artigo da emenda que o incluiu.

Feed de alterações

GET /v1/alteracoes?desde=2026-08-01&siglas=CF,CPC&tipos=dispositivo_alterado,dispositivo_revogado

Tipos: dispositivo_incluido, dispositivo_alterado, dispositivo_revogado, sumula_incluida, sumula_cancelada. Cada item aponta o ref_key, a sigla e detectado_em, e traz o estado atual do dispositivo (revogado, alterado_por, revogado_por; null em itens de súmula), o suficiente para um digest dizer "art. 5º da Lei de Improbidade revogado pela Lei nº 14.230, de 2021" sem chamada extra. Combine com /v1/dispositivos/{ref_key}/versoes para ver a redação anterior.

{
  "id": 8123,
  "tipo": "dispositivo_revogado",
  "ref_key": "LIMPROBIDADE.5",
  "sigla": "LIMPROBIDADE",
  "detectado_em": "2026-08-23T03:04:11.000Z",
  "ingest_run_id": 412,
  "revogado": true,
  "alterado_por": null,
  "revogado_por": "Lei nº 14.230, de 2021"
}

Atualização

A fonte da legislação é o texto consolidado do Planalto, não o Diário Oficial da União. Duas consequências:

• Atraso em relação ao DOU. Uma lei publicada hoje no DOU só entra na API quando o Planalto atualiza a página consolidada do diploma (o prazo varia de dias a semanas) e a ingestão seguinte roda. Nesse intervalo a API ainda devolve a redação anterior como vigente; para alterações muito recentes, confira o DOU.
• Cadência diária. A ingestão da legislação roda todos os dias, 03:00 UTC (00:00 em Brasília). Cada diploma traz ingested_at em GET /v1/diplomas; GET /v1/health mostra o status da última execução por diploma e por fonte de súmulas; é público e não conta nos limites.

Súmulas vêm dos portais do STF e do STJ, com ingestão semanal (domingos, 03:00 UTC).