> ## Documentation Index
> Fetch the complete documentation index at: https://nomos.pro/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> A API Nomos tem base em https://api.nomos.pro e autentica pelo header `x-api-key`.
> Todos os endpoints de busca são POST. Parâmetros de consulta (page, limit, sort, q, modes) vão na query string; palavras-chave e filtros vão no corpo JSON.
> `limit` é limitado a 20 resultados por página. Para conjuntos maiores, itere sobre `page`.
> Filtros de data exigem `from` e `to` juntos. Enviar apenas `to` retorna erro 400.
> Filtros por ID (authors, rapporteurs, organs, themes, situations, stakeholders) exigem IDs internos reais devolvidos por uma busca anterior. IDs inventados não geram erro: retornam zero resultados silenciosamente.
> Filtros de valor aberto (type, regimes, section, openDataResource) não são listas fechadas. Deixe-os vazios para buscar em todas as fontes.
> Para uso conversacional ou por agentes, prefira o servidor MCP hospedado da Nomos em vez de chamar a API diretamente.

# Limites e paginação

> Limites verificados da API Nomos: tamanho de página, percurso de resultados e boas práticas de volume.

## Paginação

| Parâmetro | Padrão | Limite |
| --------- | ------ | ------ |
| `page`    | `1`    | —      |
| `limit`   | `10`   | **20** |

<Warning>
  **`limit` máximo é 20**, não 100. Valores acima são rejeitados pela validação. Para conjuntos
  maiores, itere sobre `page` usando o `total` devolvido em `pagination`.
</Warning>

```python theme={"dark"}
import os
import requests

def percorrer_tudo(endpoint, payload, limit=20):
    page = 1
    while True:
        r = requests.post(
            f"https://api.nomos.pro/search/{endpoint}",
            params={"page": page, "limit": limit},
            headers={"x-api-key": os.environ["NOMOS_API_KEY"]},
            json=payload,
        )
        r.raise_for_status()
        data = r.json()
        results = data.get("results", [])
        if not results:
            return
        yield from results
        total = data.get("pagination", {}).get("total")
        if total is not None and page * limit >= total:
            return
        page += 1
```

## Volume de requisições

Os limites de volume dependem do plano contratado. Se o seu caso de uso envolve ingestão em massa
ou sincronização periódica de grandes janelas, fale com a equipe da Nomos antes de construir —
existe caminho melhor que paginar milhares de páginas.

<Note>
  A API não retorna headers `X-RateLimit-*`. Não construa sua lógica de retry em torno deles: use o
  código de status `429` e backoff exponencial, como descrito em [Tratamento de erros](/docs/erros).
</Note>

## Boas práticas

<Steps>
  <Step title="Filtre por data em vez de paginar tudo">
    Para sincronização incremental, guarde a data da última execução e busque só a janela nova. É
    mais rápido e muito mais barato que percorrer o histórico inteiro.
  </Step>

  <Step title="Use `limit=20` quando for percorrer">
    O padrão é 10. Ao paginar conjuntos grandes, 20 corta o número de requisições pela metade.
  </Step>

  <Step title="Faça cache do que não muda">
    Documentos já publicados — atos do DOU, discursos, publicações de diários — não são reescritos.
    Proposições mudam; use `sort=recently_updated` para pegar só o que se moveu.
  </Step>

  <Step title="Distribua a carga">
    Prefira um fluxo constante a rajadas. Rajadas são o que dispara `429`.
  </Step>

  <Step title="Implemente backoff exponencial">
    Com jitter, para evitar que várias instâncias retentem em sincronia.
  </Step>
</Steps>