> ## 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. # Como funcionam as sanções da ONU > O que a Nomos ingere da Lista Consolidada do Conselho de Segurança, o que cada campo significa e o que a API garante — e o que não garante. A Nomos acompanha a **Lista Consolidada de Sanções do Conselho de Segurança da ONU**: as pessoas, organizações e embarcações designadas sob os regimes do Conselho, com o motivo de cada designação e o registro auditável de tudo que mudou desde que passamos a observar. A lista é reconciliada duas vezes por dia. Cada execução compara o retrato novo com o anterior e grava um evento por mudança real — nada é sobrescrito e nada é apagado. Este domínio não usa a gramática de `keywords` booleanas dos demais endpoints. São três rotas `GET` com filtros na query string. Se você já integra com `/search/*`, o contrato aqui é diferente de propósito — veja "Diferenças em relação aos buckets", mais abaixo. ## O que a API responde O produto existe para responder três perguntas, e cada rota responde uma: | Pergunta | Rota | | --------------------------------------------------------- | -------------------------------------------------- | | Quem está designado hoje, sob qual regime e por quê? | [`GET /watchlist`](/docs/busca-sancoes) | | O que exatamente consta sobre esta designação? | [`GET /watchlist/{ref}`](/docs/sancao-designacao) | | O que mudou, quando, e qual documento registra a mudança? | [`GET /watchlist/{ref}/events`](/docs/sancao-historico) | ## A unidade é a designação, não a pessoa Um resultado é uma **designação** — o ato que sancionou alguém —, identificada pelo `sourceRefNumber` (ex.: `QDi.436`). Essa é a chave de negócio da própria ONU: única em toda a lista, estável ao longo do tempo, e o valor que você deve guardar do lado de cá para casar registros entre consultas. Os IDs internos (`designationId`, `subjectId`) são UUIDs nossos e não têm significado na fonte. `subjectType` vale `individual` ou `entity`. **`entity` não quer dizer só organização**: embarcações designadas entram aí, com a bandeira em `extracted.flagState`. ## Datas: quais são da ONU e quais são nossas Esta é a distinção que mais gera erro de integração. | Campo | De quem é | | ------------------------------------- | ----------------------------------------------------------------------------------------- | | `listedOn` | **Da ONU.** A data oficial da designação. | | `lastReviewedOn`, `sourceLastUpdated` | **Da ONU.** | | `lastUpdatedOn` | Derivado: a mais recente entre as datas acima. É a chave da ordenação `recently_changed`. | | `delistedOn` | **Nossa.** O dia em que a reconciliação observou a ausência. | | `firstSeenAt`, `lastSeenAt` | **Nossas.** Quando vimos o registro, não quando a ONU agiu. | **A ONU não publica data de remoção.** `delistedOn` é o dia em que o registro sumiu da lista para nós — pode estar dias à frente da decisão real do Conselho. Nunca apresente esse valor ao usuário final como data oficial da ONU. ## O texto é da ONU, a tradução é nossa `narrative` é o motivo da designação **na redação oficial do Conselho, em inglês**. Reproduza com atribuição; não republique como afirmação da Nomos. Em `GET /watchlist/{ref}`, o parâmetro `lang` traz a tradução automática em `narrativeTranslated`. `narrative` continua intacto ao lado — a tradução é sempre um campo adicional, nunca uma substituição, para que a sua interface consiga rotulá-la como tradução de máquina e manter o original a um toque de distância. Uma tradução pode faltar. O texto traduzido passa por uma checagem que descarta a tradução inteira quando o modelo afirma algo que a fonte não sustenta — nesses casos `narrativeTranslated` vem `null` e o inglês é o que existe. Preferimos a lacuna à afirmação inventada. ## O bloco `extracted` é derivado, não publicado `extracted` reúne o que foi **lido automaticamente da narrativa**, e não o que a ONU publica como campo estruturado: medidas restritivas (`prohibitions`), documentos citados, última localização conhecida, afiliações, janela de validade e situação do indivíduo. Serve para buscar e filtrar. Não é asserção da Nomos, e `narrative` continua sendo a autoridade sobre qualquer ponto em que os dois divirjam. Dois campos merecem atenção: Vocabulário fechado, na redação da própria ONU: `asset freeze`, `travel ban`, `arms embargo` e as proibições específicas do regime de embarcações da Líbia. Fica em inglês de propósito — é chave de filtro (`?prohibition=travel%20ban`), e um valor que mudasse com o idioma do leitor não seria indexável. Array vazio é o caso comum: a maioria das narrativas descreve conduta, não consequência. Vale `deceased`, `in_custody` ou `null` (o caso comum). Registra o que a narrativa diz sobre o indivíduo. **Morte não delista.** `status` e `delistedOn` continuam sendo a única autoridade sobre a sanção estar em vigor. Use `?excludeDeceased=true` quando a sua tela for sobre o que ainda pode ser acionado — mas conte o total sem o filtro quando a pergunta for "quantos estão designados". ## O histórico `GET /watchlist/{ref}/events` devolve o log append-only da designação, do mais recente para o mais antigo. Em eventos `amended`, `changedFields`, `before` e `after` dizem exatamente quais campos mudaram e para quê — é diff por campo, não "algo mudou". Duas respostas parecidas que significam o oposto uma da outra: * **`404`** — não existe designação com essa referência. Provavelmente erro de digitação. * **`200` com `data: []`** — a designação existe e nada mudou desde a ingestão. Hoje é o caso da maioria: passamos a registrar alterações a partir da carga inicial. Eventos com `detail: "bootstrap"` são dessa carga inicial. Representam o retrato do que já estava na lista quando começamos a observar — **não** atividade recente do Conselho. Filtre-os para fora quando a pergunta for "o que mudou ultimamente". Quando conseguimos casar a mudança ao comunicado oficial que a anunciou, `pressReleaseUrl` e `pressReleaseSymbol` (ex.: `SC/16324`) levam direto à fonte primária. ## Diferenças em relação aos buckets Se você reaproveitar o cliente HTTP dos endpoints `/search/*`, três coisas vão quebrar. 1. **Método e entrada.** É `GET` com query string, não `POST` com corpo. `keywords` (`or`/`and`/`not`) é ignorado — a busca por nome é por substring, em `search`. 2. **Envelope.** A resposta é `{ data, total }`, não `{ results, pagination }`. 3. **Paginação.** Por `offset` e `limit` (máximo 100), não por `page`. A busca por nome cobre o nome principal **e todos os apelidos**, normalizando acento, caixa e pontuação dos dois lados — `qadi` encontra `QADI`, e `Muhammad` encontra `MUHAMMED` só se o apelido estiver grafado assim na fonte (a normalização não é fonética). O filtro `regime` é **comparação exata**, com a grafia da fonte: `Al-Qaida`, `Taliban`, `DPRK`, `Iran`, `Iraq`, `DRC`, `Sudan`, `Libya`, `Somalia`, `CAR`, `Haiti`, `Yemen`, `GB`, `SouthSudan`. `AL_QAIDA` ou `al-qaida` devolvem zero resultados sem erro. ## Casos de uso Consulte o nome antes de fechar contrato ou abrir conta: ```bash theme={"dark"} curl "https://api.nomos.pro/watchlist?search=swalleh&status=listed" \ -H "x-api-key: SUA_CHAVE_API" ``` Use `status=listed` para restringir ao que está em vigor, e trate `aliases[].quality` com cuidado: um apelido `low` **não é base segura** para afirmar identidade — é pista para revisão humana, não decisão automática. Ordene por `recently_changed` (padrão) e compare `lastUpdatedOn` com o da última execução: ```bash theme={"dark"} curl "https://api.nomos.pro/watchlist?sort=recently_changed&limit=100" \ -H "x-api-key: SUA_CHAVE_API" ``` Para cada designação que mexeu, `GET /watchlist/{ref}/events` diz o que mudou campo a campo. Quantos designados carregam congelamento de ativos no regime da Coreia do Norte: ```bash theme={"dark"} curl "https://api.nomos.pro/watchlist?regime=DPRK&prohibition=asset%20freeze&limit=1" \ -H "x-api-key: SUA_CHAVE_API" ``` `total` responde a contagem; `limit=1` evita trazer a página inteira só para contar. `GET /watchlist/{ref}?lang=pt-BR` traz o registro completo com a narrativa traduzida, e `GET /watchlist/{ref}/events` traz a linha do tempo com os links para os comunicados oficiais. ## Cobertura e limites * **Fonte:** apenas a Lista Consolidada do Conselho de Segurança da ONU (`source: "un_sc"`). OFAC, União Europeia e listas nacionais **não** estão cobertas. * **Atualização:** reconciliação duas vezes ao dia. * **Sem casamento de nomes.** A API entrega os dados; decidir se "João da Silva" do seu cadastro é o designado é responsabilidade de quem integra. Não fazemos *fuzzy matching* nem pontuação de similaridade. * **Nada é apagado.** Uma remoção da lista vira mudança de `status` mais um evento. O histórico é o produto. ## Nos assistentes de IA A mesma busca está disponível como ferramenta `buscar_watchlist` no [servidor MCP](/docs/servidor-mcp), para Claude, Cursor e Claude Code.