> ## Documentation Index > Fetch the complete documentation index at: https://docs.niadra.com/llms.txt > Use this file to discover all available pages before exploring further. # A API da Niadra > Endereço, autenticação e os grupos de rotas da API de dados e da API de controle. A Niadra tem duas APIs HTTP. A **API de dados** é de cada espaço: é nela que os seus agentes e sistemas gravam eventos, leem o contexto e navegam no histórico, e que o seu time de governança apaga, exporta, audita e mede. A **API de controle** cuida de tenants, projetos, fontes, chaves, pessoas e configuração versionada, e nunca guarda conteúdo de cliente. Os SDKs cobrem o lado do agente na API de dados; cada rota das duas APIs tem página própria nesta referência. ## Endereço Cada espaço tem um endereço estável, que leva a região e nunca expõe a infraestrutura por trás: ```text theme={null} https://..api.niadra.com ``` O SDK tira esse endereço da chave (`nia_sk_____`). Enquanto um espaço muda de célula, a célula antiga responde `421 wrong_cell` e o SDK tenta de novo numa conexão nova. A API de controle fica em `https://control.api.niadra.com`. ## Autenticação Toda rota recebe `Authorization: Bearer `. Qual credencial serve depende da rota: | Tipo de rota | Credencial | Exemplo | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | Rotas de agentes e sistemas | Uma chave de fonte com o escopo da rota: `track`, `act`, `context`, `search`, `identify` | [`POST /v1/context`](/api/context) pede `context` | | Rotas de governança | O token de uma pessoa do Console com um dos papéis da rota, ou uma chave de fonte com o escopo `admin` | [`POST /v1/forget`](/api/forget) pede `security` | | Análise da base | Uma chave com o escopo `analytics` (só fontes de analista) ou uma pessoa com `analysis`; a revelação pede também `admin` na chave, ou `security` na pessoa | [`POST /v1/insights/aggregate`](/api/insights-aggregate) | | Entrada de webhook | O método declarado no mapeamento da fonte: bearer, assinatura HMAC, token na URL ou mTLS | [`POST /v1/ingest/webhook/{source_id}`](/api/ingest-webhook) | | API de controle | O token de uma pessoa, emitido por [`POST /v1/auth/login`](/api/control/login) e válido por 15 minutos | [`GET /v1/users/me`](/api/control/me) | Os papéis do Console são `admin`, `security`, `integration`, `review`, `analysis` e `vendor`. `admin` passa em toda checagem de papel. Uma pessoa `vendor` só enxerga as fontes nomeadas no vínculo do papel dela. Uma chave sem o escopo da rota recebe `403 scope_missing`; uma pessoa sem o papel, `403 forbidden`. Cada página da referência diz o que a rota aceita. ## Grupos de rotas | Grupo | O que cobre | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Escrita | [lote](/api/batch), [upload de mídia](/api/media-uploads), [importação de arquivo](/api/ingest-files) e [o estado dela](/api/ingest-file), [webhook de sistema](/api/ingest-webhook) e [o desafio dele](/api/ingest-webhook-challenge), [traces OTLP](/api/otel-traces), [correção](/api/feedback) | | Contexto | [por handle](/api/context), [por id de perfil](/api/context-by-profile), [subject tokens](/api/subject-tokens), [servidor MCP](/api/mcp) | | Histórico | [busca](/api/history-search), [linha do tempo por handle](/api/history-timeline), [linha do tempo por perfil](/api/history-timeline-by-profile), [abrir item](/api/history-item), [definições das ferramentas](/api/history-tools) | | Objetos | [estado](/api/object) e [linha do tempo](/api/object-timeline) de um pedido, ticket ou fatura | | Identidade e perfis | [asserções](/api/identity-assertions), [criar](/api/identity-assertions-create), [retirar](/api/identity-assertion-retract), [unir](/api/identity-merge), [separar](/api/identity-unmerge), [bloquear handle](/api/identity-handles-block), [vínculos](/api/identity-links), [sugestões](/api/identity-suggestions), [busca de perfis](/api/profiles-search), [perfil](/api/profile), [memória](/api/profile-memory), [objetos](/api/profile-objects) | | Privacidade e auditoria | [apagar](/api/forget), [lista de apagamentos](/api/forget-list), [exportar](/api/export), [execuções de exportação](/api/export-runs), [comprovantes](/api/receipts), [verificação da cadeia](/api/receipts-verify), [linhagem](/api/lineage-receipt), [simulação de política](/api/policy-simulate), [segredos](/api/secrets) | | Fontes | [cobertura](/api/sources-coverage), [cortar uma fonte na célula](/api/source-revoke) | | Padrões, medição e uso | [retirar padrão](/api/trait-retract), [testar regra](/api/traits-dry-run), [oposição](/api/traits-opt-out), [aproveitamento do contexto](/api/context-use), [uso](/api/usage) | | Revisão e assistente | [fila de revisão](/api/review-queue), [vereditos](/api/review-verdicts), [concordância](/api/review-agreement), [assistente de configuração](/api/assist) | | Gatilhos e webhooks | [testar gatilho](/api/triggers-dry-run), [disparos](/api/trigger-firings), [entregas](/api/webhook-deliveries), [reenvio](/api/webhook-redeliver) | | Análise da base | [esquema](/api/insights-schema), [visão geral](/api/insights-overview), [agregar](/api/insights-aggregate), [encontrar perfis](/api/insights-profiles), [busca](/api/insights-search), [revelação](/api/insights-reveal), [MCP de análise](/api/mcp-insights) | | API de controle | [acesso](/api/control/login), [pessoas e papéis](/api/control/me), [projetos](/api/control/projects), [fontes e chaves](/api/control/sources), [configuração](/api/control/config-types), [uso](/api/control/usage), [operação da plataforma](/api/control/cells) | ## Convenções numa tabela | Assunto | Regra | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Versão | No caminho (`/v1`). Campo novo e rota nova não mudam a versão; remover um campo ou mudar o sentido dele é `/v2`, com 12 meses de convivência e o cabeçalho `Deprecation` | | Dado pessoal | Telefone, e-mail, documento e texto livre vão no corpo, nunca na URL. Por isso contexto, busca e linha do tempo por handle são `POST`; as formas `GET` recebem um id de perfil | | Idempotência | Eventos levam `idempotency_key`; escritas de identidade, `POST /v1/forget` e o corte de fonte exigem o cabeçalho `Idempotency-Key` | | Erros | `application/problem+json` com um `code` estável; o lote responde `200`, ou `207` quando algum item foi recusado | | Paginação | `cursor` opaco e `limit` (até 200 nas listas, 100 nas linhas do tempo) | | Cache | ETag nas leituras determinísticas; no contexto por handle, mande `known_etag` no corpo; por perfil, `If-None-Match` devolve `304` | | Rastreio | `traceparent` é aceito e devolvido; toda resposta traz `request_id` | Os detalhes estão em [Limites e convenções](/conventions) e em [Erros](/errors). ## Contrato A referência sai do contrato OpenAPI 3.1 que o servidor exporta do próprio código, o mesmo arquivo contra o qual os SDKs e o Console são testados. Valores de enum e nomes de campo são em inglês ASCII e nunca mudam de sentido dentro da `/v1`. As descrições aparecem em português; os nomes do contrato ficam como são. ## Próximos passos A chamada que todo agente faz antes de agir. Mensagens, eventos de sistema e ações. O catálogo de códigos e o que fazer com cada um. Tamanhos, taxas, idempotência e cache.