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

# Conceitos de busca

> A gramática compartilhada por todos os endpoints de busca: palavras-chave, texto livre, modos, paginação, ordenação e intervalos de data.

Todos os endpoints de busca aceitam os mesmos parâmetros base e diferem apenas nos filtros
específicos do domínio. Aprender esta página uma vez basta para usar os onze.

A separação é simples: **parâmetros de consulta ficam na query string**, **palavras-chave e filtros
ficam no corpo JSON**.

## Palavras-chave

O objeto `keywords` combina três operadores booleanos. Todos são opcionais e podem ser usados
juntos.

```json theme={"dark"}
{
  "keywords": {
    "or":  ["reforma tributária", "IBS", "CBS"],
    "and": ["relatório"],
    "not": ["arquivada"]
  }
}
```

| Operador | Comportamento                                |
| -------- | -------------------------------------------- |
| `or`     | Pelo menos um dos termos deve estar presente |
| `and`    | Todos os termos devem estar presentes        |
| `not`    | Exclui o documento quando o termo aparece    |

## Texto livre e modos

O parâmetro de query `q` faz busca por texto livre e pode ser combinado com `keywords`.

O parâmetro `modes` altera como os termos são comparados. Aceita valores separados por vírgula:

| Modo        | Efeito                                              |
| ----------- | --------------------------------------------------- |
| `sensitive` | Diferencia maiúsculas, minúsculas e acentos         |
| `keyword`   | Exige correspondência exata do termo, sem variações |

```bash theme={"dark"}
curl -X POST "https://api.nomos.pro/search/dou?q=medida%20provisória&modes=sensitive,keyword" \
  -H "x-api-key: SUA_CHAVE_API"
```

## Paginação

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

<Warning>
  `limit` é limitado a **20 resultados por página**. Valores acima disso são rejeitados. Para
  percorrer conjuntos maiores, itere sobre `page`.
</Warning>

A resposta traz `pagination` com o total, o que permite calcular quantas páginas percorrer.

## Ordenação

| Valor              | Ordena por                                           |
| ------------------ | ---------------------------------------------------- |
| `newest`           | Mais recentes por data de publicação ou apresentação |
| `recently_updated` | Movimentados ou atualizados há menos tempo           |
| `older`            | Mais antigos primeiro                                |
| `relevance`        | Aderência às palavras-chave informadas               |

O padrão varia por domínio: `/search/propositions` usa `recently_updated`, porque o que importa numa
proposição costuma ser a última movimentação. Os demais domínios usam `newest`.

## Intervalos de data

Filtros de data são objetos com `from` e `to`, em `YYYY-MM-DD`.

```json theme={"dark"}
{ "date": { "from": "2026-01-01", "to": "2026-07-26" } }
```

<Warning>
  **Informe sempre os dois campos.** Se só `from` for enviado, `to` assume a data atual. Enviar
  apenas `to` retorna erro `400`.
</Warning>

Para uma data específica, repita o mesmo valor nos dois campos.

O nome do campo muda conforme o domínio: `date` na maioria, `created_at` e `updated_at` em
proposições, `speech_at` em discursos.

## Filtros por ID

Alguns filtros — `authors`, `rapporteurs`, `organs`, `themes`, `situations`, `stakeholders` —
esperam **IDs internos**, não nomes.

<Warning>
  IDs inventados **não geram erro**: a busca retorna zero resultados silenciosamente. Use apenas IDs
  extraídos de uma resposta anterior, por exemplo `authors.stakeholderId` ou
  `lastProceeding.openDataSituationId`.
</Warning>

Para descobrir IDs de parlamentares, use [`GET /stakeholders`](/docs/api-reference/stakeholders/liststakeholders).

## Valores de filtro em aberto

Filtros como `regimes`, `type`, `section` e `openDataResource` trazem exemplos na referência, mas
**não são listas fechadas**. Os conjuntos de valores crescem com o tempo — novas agências, novos
tipos de documento — e a API aceita e encaminha qualquer valor.

Um valor desconhecido não gera erro: ele simplesmente não corresponde a nada. Deixe o filtro vazio
para buscar em tudo, inclusive nas fontes adicionadas depois desta documentação.

## Formato da resposta

Toda busca devolve o mesmo envelope:

```json theme={"dark"}
{
  "results": [
    {
      "link_to_nomos_api": "https://nomos.pro/propositions/...",
      "...": "campos específicos do domínio"
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 342 }
}
```

O conteúdo de cada item em `results` é específico do domínio e evolui ao longo do tempo. Trate os
documentos como estruturas abertas: leia os campos que você precisa e ignore o resto, em vez de
validar contra um esquema fixo.

`link_to_nomos_api` está presente em todo documento e aponta para o registro no App da Nomos.