Skip to main content
As mesmas regras valem para toda rota da API da Niadra: a API de dados do seu espaço e a API de controle. Conhecer as regras uma vez evita reler em cada endpoint.

​
Endereço

Todo espaço tem um endereço estável, com a região dele no nome:
A chave carrega a região e o espaço, nunca a célula que os atende, e os SDKs montam o endereço a partir dela. Quando um espaço muda de célula, o endereço continua o mesmo; durante a mudança, a célula antiga responde 421 e os SDKs tentam de novo na hora, numa conexão nova. A topologia interna nunca faz parte do contrato. A API de controle, de tenants, projetos, fontes, chaves, pessoas, configuração e uso, fica em https://control.api.niadra.com.

​
Versões

A versão está no caminho: /v1. Campo novo ou rota nova não mudam a versão, então o seu código precisa ignorar campos que não conhece (os dois SDKs ignoram). Remover um campo ou mudar o sentido dele é /v2, com 12 meses em que as duas versões respondem, aviso por e-mail e o cabeçalho Deprecation em toda resposta da versão antiga.

​
Autenticação

Uma chave de fonte só autentica com o segredo; o key_id no prefixo é público. Os escopos são track, act, context, search, identify, admin e analytics. Veja Espaços e chaves. As rotas de governança (identidade, privacidade, auditoria, medição, revisão, gatilhos) aceitam uma pessoa com um dos papéis da rota ou uma chave de fonte com o escopo admin. Os papéis do Console são admin, security, integration, review, analysis e vendor; admin passa em toda checagem de papel, e uma pessoa vendor só enxerga as fontes nomeadas no vínculo do papel dela. Os vereditos de revisão são a exceção: só uma pessoa com o papel review registra.

​
Idempotência

As rotas que mudam identidade ou apagam dado recebem o cabeçalho Idempotency-Key, e nelas ele é obrigatório: toda escrita de identidade (criar ou retirar asserção, unir, separar, bloquear handle, criar ou encerrar vínculo, aceitar ou descartar sugestão), POST /v1/forget e o corte de uma fonte na célula. A Niadra guarda a chave por 24 horas, com um hash do corpo:
  • a mesma chave com o mesmo corpo devolve a primeira resposta de novo;
  • a mesma chave com outro corpo devolve 409 conflict.
O lote usa, no lugar do cabeçalho, a idempotency_key de cada item: o id da mensagem no provedor, ou um UUIDv7 criado pelo SDK. Uma chave repetida entra em duplicates e nunca é gravada duas vezes, mesmo quando um webhook é reenviado dias depois.

​
Erros

Os erros respondem application/problem+json (RFC 9457), com type, title, status, detail, code e request_id. O lote responde 200 quando todos os itens entraram, e 207 com um erro por item recusado quando não. O catálogo completo está em Erros.

​
Paginação

As listas são paginadas por um cursor opaco, em ordem estável. next_cursor vem null na última página. Nunca monte um cursor na mão: o conteúdo dele pode mudar sem aviso.

​
Limites de taxa

Passou do limite, a resposta é 429 rate_limited com Retry-After em segundos. Os limites valem por chave, e as escritas (/v1/batch, /v1/ingest, /v1/otel, /v1/media, /v1/feedback) são contadas à parte das leituras, então uma enxurrada de escritas nunca corta a leitura primeiro. Um 503 unavailable também traz Retry-After.

​
Cache e ETag

Toda leitura determinística tem ETag: o contexto, a navegação do histórico e os objetos de negócio. O mesmo pedido, com o mesmo estado, devolve os mesmos bytes. Os SDKs mandam o ETag que têm em toda atualização do contexto.

​
Dado pessoal fica fora da URL

Telefone, e-mail, documento, handle, consulta de busca e qualquer texto livre vão só no corpo da requisição, nunca no caminho nem na query. A URL acaba em log de balanceador, de firewall e em span de rastreio, fora da cifra e fora do alcance do forget. É por isso que context, search e timeline por handle são POST, e que a busca de perfis recebe a consulta no corpo. As formas GET do contexto e da linha do tempo recebem um id de perfil. Um teste no nosso CI, com um valor canário, garante que nada disso aparece em URL, log, span ou mensagem de erro. Ids que não são dado pessoal, como id de perfil, id de item, conversation_id ou id de objeto, podem ir no caminho.

​
Rastreio

Mande um cabeçalho traceparent do W3C, e a Niadra o devolve na resposta. Mande X-Request-Id para escolher o id da requisição, ou deixe a Niadra gerar um; toda resposta traz esse id no cabeçalho X-Request-Id e no request_id de um erro. Informe o id quando falar com o suporte.

​
Tamanhos

Um lote com corpo acima de 2,5 MB, ou com mais de 500 itens, responde 422 invalid_input. Um item acima de 1 MB é recusado sozinho, com o erro de item too_large, e o resto do lote entra.

​
Velocidade

Nenhum LLM roda no caminho do context() nem da navegação.

​
Tetos iniciais de um espaço

São valores de partida, definidos no seu contrato. Fale com a gente quando um caso de uso pedir mais.

​
Nomes no contrato

Todo nome na API, nos SDKs, nas ferramentas MCP, nos eventos e nos webhooks é em inglês, em ASCII. Os campos são snake_case (conversation_id, occurred_at); horários são ISO 8601 com fuso; os enums usam valores fixos em minúsculas, como message, system_event e action para kind, ou customer, ai_agent, human_agent e system para speaker. Os níveis de verificação são V0 a V4 e no_customer. Dentro da /v1, nenhum valor muda de sentido.

​
Próximos passos

Erros

cada código e o que fazer com ele.

Eventos e o lote

idempotência e erro por item na prática.

Espaços e chaves

escopos, fontes e o formato da chave.

A API da Niadra

todas as rotas, geradas do OpenAPI.