# Niadra > A memória compartilhada de todos os agentes de IA da sua empresa: contexto, histórico e governança. ## Guia ### Começar - [Introdução](https://docs.niadra.com/index.md): O que a Niadra guarda, o que cada agente recebe e as três chamadas que ligam tudo. - [Início rápido](https://docs.niadra.com/quickstart.md): Da chave de API ao primeiro contexto entregue, em Python, TypeScript ou cURL. ### Conceitos - [Espaços e chaves](https://docs.niadra.com/concepts/spaces-and-keys.md): Projeto, ambiente, fonte e chave: quem fala com a Niadra e o que cada chave pode fazer. - [Eventos e o lote](https://docs.niadra.com/concepts/events.md): Mensagens, eventos de sistema e ações, enviados em lote, idempotentes e com erro por item. - [Identidade e verificação](https://docs.niadra.com/concepts/identity.md): Handles, asserções, perfis que se unem e se separam, e os níveis V0 a V4. - [O contexto e as views](https://docs.niadra.com/concepts/context.md): O Context Pack: camadas, views de canal e de tarefa, ETag, live, delta e o que ficou retido. - [Navegação do histórico](https://docs.niadra.com/concepts/history.md): Busca, linha do tempo e abrir item: o agente consulta tudo o que já aconteceu com o cliente. - [Sistemas, objetos e ações](https://docs.niadra.com/concepts/systems.md): Eventos de CRM, ERP e help desk, objetos de negócio e as ações que fecham pendências. - [Contas e parceiros](https://docs.niadra.com/concepts/accounts.md): Organizações como sujeitos da memória, vínculos com papel e o contexto com about. - [Padrões](https://docs.niadra.com/concepts/patterns.md): Sinais que se repetem, cada um com a regra, as evidências e o prazo de validade. - [Aproveitamento do contexto](https://docs.niadra.com/concepts/context-use.md): A medição por agente e por fornecedor: uso, repetição, contradição e transferência sem leitura. - [Gatilhos e webhooks](https://docs.niadra.com/concepts/triggers-and-webhooks.md): Avisos assinados quando algo acontece na memória. A Niadra avisa; quem age é o seu sistema. - [Privacidade, apagamento e exportação](https://docs.niadra.com/concepts/privacy.md): Direitos do titular por API, apagamento por linhagem e exportação contínua para o seu bucket. - [Comprovantes e auditoria](https://docs.niadra.com/concepts/receipts.md): Cada leitura deixa um comprovante encadeado por SHA-256: quem leu o quê, sob qual política. ### Guias - [Agentes de voz](https://docs.niadra.com/guides/voice-agents.md): Contexto antes do alô dentro de 150 ms, atestado de rede, transcrição em duas levas e transbordo. - [Agentes de WhatsApp](https://docs.niadra.com/guides/whatsapp-agents.md): wa_id, BSUID e telefone, conversas que duram meses, OTP no mesmo canal e mídia por referência. - [Agentes internos](https://docs.niadra.com/guides/internal-agents.md): O agente de cobrança lê o contexto da fatura, lança o crédito no ERP e registra a ação. - [MCP com qualquer LLM](https://docs.niadra.com/guides/mcp.md): Sete ferramentas por Streamable HTTP, com o cliente amarrado por subject_token. - [Webhooks dos seus sistemas](https://docs.niadra.com/guides/system-webhooks.md): CRM, ERP e help desk entram pelo webhook genérico, com mapeamento versionado e autenticação. - [Ingestão por OpenTelemetry](https://docs.niadra.com/guides/opentelemetry.md): Envie os traces gen_ai.* que o seu agente já emite para o endpoint OTLP da Niadra. ### SDK - [SDK de Python](https://docs.niadra.com/sdk/python.md): Cada método da biblioteca niadra, com parâmetros, retorno e exemplo. - [SDK de TypeScript](https://docs.niadra.com/sdk/typescript.md): Cada método da biblioteca @niadra/sdk, com parâmetros, retorno e exemplo. ### Referência - [Erros](https://docs.niadra.com/errors.md): Respostas application/problem+json, o catálogo de códigos e o que fazer com cada um. - [Limites e convenções](https://docs.niadra.com/conventions.md): Versão, autenticação, idempotência, paginação, limites de taxa, ETag e dado pessoal fora da URL. ## Referência da API ### Visão geral - [A API da Niadra](https://docs.niadra.com/api.md): Endereço, autenticação e os grupos de rotas da API de dados e da API de controle. ### Escrita - [Enviar um lote](https://docs.niadra.com/api/batch.md): Mensagens, eventos de sistema, ações, identificação e verificação num lote só, com erro por item. - [Pedir upload de mídia](https://docs.niadra.com/api/media-uploads.md): URL pré-assinada e os cabeçalhos exatos do upload; o evento leva só a referência e o hash. - [Importar um arquivo](https://docs.niadra.com/api/ingest-files.md): CSV de identidades ou JSONL com um item de lote por linha, processado em segundo plano. - [Estado de uma importação](https://docs.niadra.com/api/ingest-file.md): Linhas aceitas, duplicadas e recusadas de uma importação de arquivo. - [Receber webhook de sistema](https://docs.niadra.com/api/ingest-webhook.md): A entrada genérica para CRM, ERP e help desk, com mapeamento versionado e autenticação da fonte. - [Responder ao desafio do webhook](https://docs.niadra.com/api/ingest-webhook-challenge.md): A verificação por GET que alguns sistemas fazem antes de mandar o primeiro evento. - [Receber traces OTLP](https://docs.niadra.com/api/otel-traces.md): Traces de OpenTelemetry com atributos gen_ai.*, convertidos em eventos. - [Corrigir a memória](https://docs.niadra.com/api/feedback.md): Retirar ou corrigir um fato, resolver uma pendência ou registrar o desfecho de uma conversa. ### Contexto - [Ler o contexto](https://docs.niadra.com/api/context.md): O Context Pack de um cliente ou objeto, para a view e o nível de verificação da conversa. - [Ler o contexto por perfil](https://docs.niadra.com/api/context-by-profile.md): O mesmo contexto, pelo id do perfil, com If-None-Match e resposta 304. - [Emitir subject_token](https://docs.niadra.com/api/subject-tokens.md): Um token de até 15 minutos que amarra uma conexão MCP a um cliente, e à conta dele quando houver. - [Servidor MCP](https://docs.niadra.com/api/mcp.md): As sete ferramentas por Streamable HTTP, com o cliente amarrado pelo subject_token. ### Histórico - [Buscar no histórico](https://docs.niadra.com/api/history-search.md): Busca por palavra e por significado no histórico de um cliente, com recorrência calculada. - [Linha do tempo](https://docs.niadra.com/api/history-timeline.md): Conversas, eventos de sistema e ações em ordem, uma linha cada, pelo handle do cliente no corpo. - [Linha do tempo por perfil](https://docs.niadra.com/api/history-timeline-by-profile.md): A mesma linha do tempo, pelo id do perfil na query. - [Abrir um item](https://docs.niadra.com/api/history-item.md): Uma conversa ou um objeto aberto: o que foi pedido, as promessas, o desfecho e o que nasceu dele. - [Definições das ferramentas](https://docs.niadra.com/api/history-tools.md): As ferramentas de navegação em JSON Schema de função, prontas para qualquer LLM. ### Objetos - [Ler um objeto](https://docs.niadra.com/api/object.md): Estado derivado de um pedido, ticket ou fatura, com as pendências abertas. - [Linha do tempo do objeto](https://docs.niadra.com/api/object-timeline.md): Os eventos e as ações de um objeto, em ordem. ### Identidade e perfis - [Listar asserções](https://docs.niadra.com/api/identity-assertions.md): O registro imutável que diz quais handles pertencem ao mesmo sujeito, e por quê. - [Criar asserção](https://docs.niadra.com/api/identity-assertions-create.md): Afirma que dois handles são do mesmo sujeito, com método e evidência. - [Retirar uma asserção](https://docs.niadra.com/api/identity-assertion-retract.md): Desfaz uma ligação errada; o perfil se separa e a memória segue a origem. - [Unir perfis](https://docs.niadra.com/api/identity-merge.md): União forçada de dois perfis, com ator e motivo registrados. - [Separar perfis](https://docs.niadra.com/api/identity-unmerge.md): Separa um handle do perfil atual, com ator e motivo registrados. - [Bloquear um handle](https://docs.niadra.com/api/identity-handles-block.md): Um valor que nunca deve ligar perfis, como o telefone de uma loja ou um e-mail de teste. - [Criar vínculo](https://docs.niadra.com/api/identity-links.md): Liga uma pessoa a uma conta ou parceiro, com papel e validade. - [Encerrar vínculo](https://docs.niadra.com/api/identity-link-end.md): Encerra o vínculo entre uma pessoa e uma organização. - [Listar sugestões de identidade](https://docs.niadra.com/api/identity-suggestions.md): Pares de perfis que parecem ser o mesmo sujeito, para revisão humana. - [Aceitar sugestão](https://docs.niadra.com/api/identity-suggestion-accept.md): A sugestão vira uma asserção accepted_suggestion e os perfis se unem. - [Descartar sugestão](https://docs.niadra.com/api/identity-suggestion-dismiss.md): Descarta a sugestão; o par não volta pela mesma evidência. - [Buscar perfis](https://docs.niadra.com/api/profiles-search.md): Encontra perfis por handle, com o valor no corpo e nunca registrado em log. - [Ler um perfil](https://docs.niadra.com/api/profile.md): Handles, tipo de sujeito e vínculos de um perfil, com a máscara do papel de quem lê. - [Memória de um perfil](https://docs.niadra.com/api/profile-memory.md): Fatos, episódios, pendências, ações e padrões, cada um com origem e evidência. - [Objetos de um perfil](https://docs.niadra.com/api/profile-objects.md): Os pedidos, tickets e faturas ligados a um perfil. ### Privacidade e auditoria - [Apagar](https://docs.niadra.com/api/forget.md): Apaga um perfil, handle ou conversa por linhagem e emite o comprovante de apagamento. - [Listar apagamentos](https://docs.niadra.com/api/forget-list.md): Os pedidos de apagamento do espaço, com o estado de cada um. - [Estado de um apagamento](https://docs.niadra.com/api/forget-status.md): Onde está um apagamento e o que ele já percorreu. - [Exportar](https://docs.niadra.com/api/export.md): Reúne os dados de um titular para acesso e portabilidade. - [Baixar exportação](https://docs.niadra.com/api/export-download.md): O arquivo de uma exportação pronta. - [Execuções de exportação](https://docs.niadra.com/api/export-runs.md): As execuções da exportação contínua e das exportações sob demanda. - [Credencial do destino de exportação](https://docs.niadra.com/api/export-destination-credential.md): Grava a credencial de escrita do seu bucket direto no cofre da célula. Só escrita. - [Listar comprovantes](https://docs.niadra.com/api/receipts.md): Leituras, buscas e ações administrativas, com o encadeamento por hash. - [Verificar a cadeia](https://docs.niadra.com/api/receipts-verify.md): Confere o encadeamento SHA-256 dos comprovantes de um dia. - [Linhagem de um comprovante](https://docs.niadra.com/api/lineage-receipt.md): Do comprovante aos itens entregues e aos eventos de origem: por que o agente disse aquilo. - [Quem viu um fato](https://docs.niadra.com/api/lineage-fact.md): Cada entrega em que um fato apareceu, com a fonte e a hora. - [Simular política](https://docs.niadra.com/api/policy-simulate.md): O que uma fonte veria de um perfil, item a item, antes de você liberar o acesso. - [Gravar segredo](https://docs.niadra.com/api/secrets.md): Segredo de assinatura de webhook ou credencial de modelo. Só escrita. ### Fontes - [Cobertura das fontes](https://docs.niadra.com/api/sources-coverage.md): Eventos por fonte e por dia, e as fontes que pararam de mandar. - [Cortar uma fonte na célula](https://docs.niadra.com/api/source-revoke.md): Todas as chaves da fonte param de autenticar nesta célula em segundos. ### Padrões, medição e uso - [Retirar um padrão](https://docs.niadra.com/api/trait-retract.md): Retira um padrão errado, com lápide, para ele não voltar pela mesma evidência. - [Testar regra de padrão](https://docs.niadra.com/api/traits-dry-run.md): Quantos perfis ganhariam o padrão nos últimos 90 dias, com amostra e evidências. - [Desligar padrões do titular](https://docs.niadra.com/api/traits-opt-out.md): Oposição ao perfilamento: a memória para de derivar padrões para esta pessoa. - [Aproveitamento do contexto](https://docs.niadra.com/api/context-use.md): Uso, repetição, contradição e transferência sem leitura, agrupados por fonte, fornecedor, canal ou view. - [Aproveitamento de uma conversa](https://docs.niadra.com/api/context-use-conversation.md): O detalhe de cada entrega de uma conversa, com os itens usados e o turno de cada sinal. - [Uso do espaço](https://docs.niadra.com/api/usage.md): Conversas, tarefas e eventos por período, e por fonte com group_by=source. ### Revisão e assistente - [Fila de revisão](https://docs.niadra.com/api/review-queue.md): As amostras que o seu time confere: fatos extraídos, sinais da medição e padrões. - [Registrar vereditos](https://docs.niadra.com/api/review-verdicts.md): Correto, errado ou faltou, por item de uma amostra. - [Concordância da revisão](https://docs.niadra.com/api/review-agreement.md): Quanto revisores e sistema concordam, por tipo de item. - [Pedir proposta ao assistente](https://docs.niadra.com/api/assist.md): O assistente de configuração propõe um mapeamento, esquema, política ou regra como diff para aprovação. - [Listar execuções do assistente](https://docs.niadra.com/api/assist-runs.md): As propostas pedidas ao assistente de configuração. - [Ler uma execução do assistente](https://docs.niadra.com/api/assist-run.md): O estado e o diff proposto de uma execução. ### Gatilhos e webhooks - [Testar regra de gatilho](https://docs.niadra.com/api/triggers-dry-run.md): Quantos disparos a regra teria nos últimos 30 dias, com amostra. - [Disparos de gatilho](https://docs.niadra.com/api/trigger-firings.md): Cada disparo, com a regra, a versão e os ponteiros de evidência. - [Entregas de webhook](https://docs.niadra.com/api/webhook-deliveries.md): Tentativas de entrega, status da resposta e a fila de mortos. - [Reenviar uma entrega](https://docs.niadra.com/api/webhook-redeliver.md): Reenvia uma entrega que falhou, com o mesmo webhook-id. ### Análise da base - [Esquema consultável](https://docs.niadra.com/api/insights-schema.md): As tabelas, métricas e dimensões que a análise da base aceita. - [Visão geral da base](https://docs.niadra.com/api/insights-overview.md): Os números principais da memória do espaço, sem dado pessoal. - [Agregar](https://docs.niadra.com/api/insights-aggregate.md): Contagens e taxas sobre todos os clientes, com pseudônimo por padrão. - [Encontrar perfis](https://docs.niadra.com/api/insights-profiles.md): Perfis que atendem a um critério, devolvidos por pseudônimo. - [Busca entre perfis](https://docs.niadra.com/api/insights-search.md): Busca por significado em episódios de toda a base, com trechos redigidos. - [Amostra de episódios](https://docs.niadra.com/api/insights-episodes-sample.md): Uma amostra redigida de episódios que atendem a um filtro. - [Contexto de um pseudônimo](https://docs.niadra.com/api/insights-context.md): O contexto de um cliente, pelo pseudônimo, para análise. - [Explicar a linhagem](https://docs.niadra.com/api/insights-lineage.md): De onde veio um número ou um item, até os eventos de origem. - [Pedir revelação](https://docs.niadra.com/api/insights-reveal.md): Troca um pseudônimo pelo handle, com motivo e comprovante. - [MCP de análise](https://docs.niadra.com/api/mcp-insights.md): As consultas da base inteira como ferramentas MCP, para outra LLM perguntar sobre todos os clientes. ### Controle: acesso - [Entrar](https://docs.niadra.com/api/control/login.md): Troca a credencial de uma pessoa pelo token que o Console e a API usam. - [Renovar token](https://docs.niadra.com/api/control/token.md): Emite um token novo antes do vencimento do atual. - [Chaves públicas (JWKS)](https://docs.niadra.com/api/control/jwks.md): As chaves que as células usam para verificar os tokens de pessoa sem consultar o controle. - [Quem sou eu](https://docs.niadra.com/api/control/me.md): A pessoa autenticada, os papéis dela e os espaços que ela alcança. - [Listar pessoas](https://docs.niadra.com/api/control/users.md): As pessoas do Console no tenant. - [Convidar pessoa](https://docs.niadra.com/api/control/users-create.md): Uma pessoa nova no Console. - [Definir papéis](https://docs.niadra.com/api/control/user-roles.md): Os papéis de uma pessoa: admin, security, integration, review, analysis ou vendor. - [Listar papéis](https://docs.niadra.com/api/control/roles.md): O que cada papel do Console pode fazer. ### Controle: tenant e projetos - [Criar tenant](https://docs.niadra.com/api/control/tenants-create.md): A empresa cliente, com contrato e região. - [Ler tenant](https://docs.niadra.com/api/control/tenant.md): Os dados de um tenant. - [Listar projetos](https://docs.niadra.com/api/control/projects.md): Os projetos do tenant, cada um com os espaços de sandbox e produção. - [Criar projeto](https://docs.niadra.com/api/control/projects-create.md): Um projeto novo, que nasce com os espaços de sandbox e produção. - [Ler espaço](https://docs.niadra.com/api/control/space.md): Um espaço: projeto, ambiente, região e endereço. ### Controle: fontes e chaves - [Listar fontes](https://docs.niadra.com/api/control/sources.md): Os agentes, fornecedores e sistemas que falam com um espaço. - [Criar fonte](https://docs.niadra.com/api/control/sources-create.md): Uma fonte nova, com canal, finalidade, audiência e teto de verificação. - [Listar chaves](https://docs.niadra.com/api/control/keys.md): As chaves de uma fonte, sem o segredo. - [Criar chave](https://docs.niadra.com/api/control/keys-create.md): Uma chave de fonte com escopos. O segredo aparece uma vez só. - [Girar chave](https://docs.niadra.com/api/control/keys-rotate.md): Uma chave nova no lugar da atual, com os mesmos escopos. - [Revogar chave](https://docs.niadra.com/api/control/keys-revoke.md): Corta o acesso de uma chave em todas as células. - [Revogar fonte](https://docs.niadra.com/api/control/source-revoke.md): Corta todas as chaves de uma fonte de uma vez, em todas as células. - [Listar referências de segredo](https://docs.niadra.com/api/control/secret-refs.md): Onde cada segredo mora, sem o valor. - [Criar referência de segredo](https://docs.niadra.com/api/control/secret-refs-create.md): Registra a referência de um segredo guardado no cofre da célula. ### Controle: configuração - [Tipos de configuração](https://docs.niadra.com/api/control/config-types.md): Políticas, esquemas, mapeamentos, views, regras e os demais tipos, com a versão vigente. - [Ler configuração](https://docs.niadra.com/api/control/config-document.md): O documento vigente de um tipo de configuração. - [Listar mudanças](https://docs.niadra.com/api/control/config-diffs-list.md): Os diffs propostos, aprovados, recusados e desfeitos. - [Propor mudança de configuração](https://docs.niadra.com/api/control/config-diffs.md): Política, view, mapeamento ou regra, sempre como diff versionado. - [Aprovar mudança](https://docs.niadra.com/api/control/config-diff-approve.md): Aprova um diff; a célula recebe a configuração nova pelo snapshot assinado. - [Recusar mudança](https://docs.niadra.com/api/control/config-diff-reject.md): Recusa um diff proposto. - [Desfazer mudança](https://docs.niadra.com/api/control/config-diff-rollback.md): Volta à versão anterior de uma configuração, como um diff novo. - [Histórico da configuração](https://docs.niadra.com/api/control/config-history.md): Cada versão de cada configuração, com quem aprovou. - [Receber proposta da célula](https://docs.niadra.com/api/control/config-proposals.md): Onde a célula entrega o diff proposto pelo assistente de configuração. ### Controle: uso - [Uso](https://docs.niadra.com/api/control/usage.md): Conversas e tarefas cobradas, por espaço e período. ### Controle: operação da plataforma - [Listar células](https://docs.niadra.com/api/control/cells.md): As células registradas. Rota da operação da Niadra. - [Registrar célula](https://docs.niadra.com/api/control/cells-create.md): Registra uma célula nova. Rota da operação da Niadra. - [Posição de um espaço](https://docs.niadra.com/api/control/placement.md): Em que célula um espaço mora e se está em mudança. - [Pedir mudança de célula](https://docs.niadra.com/api/control/placement-move.md): Começa a mudança de um espaço para outra célula. Rota da operação da Niadra. - [Concluir mudança de célula](https://docs.niadra.com/api/control/placement-complete.md): Troca o endereço do espaço para a célula nova. Rota da operação da Niadra. - [Definir cotas](https://docs.niadra.com/api/control/quotas.md): Limites de uso por tenant. Rota da operação da Niadra. - [Snapshot assinado](https://docs.niadra.com/api/control/snapshot.md): A configuração assinada que cada célula puxa do controle. - [Feed de revogações](https://docs.niadra.com/api/control/revocations.md): As chaves e fontes revogadas, que as células aplicam em segundos. - [Enviar uso da célula](https://docs.niadra.com/api/control/usage-push.md): As células mandam os agregados de uso para a cobrança. ## OpenAPI Specs - [cell](/openapi/pt/cell.json) - [control](/openapi/pt/control.json) > The links below point to documentation indexes. Follow each `/_llms/` index recursively until you reach documentation pages. ## Indexes - [English (141 pages)](https://docs.niadra.com/_llms/en.md): Documentation for English.