Referência de Endpoints por Área

Integrar um sistema ao DATTA não deveria exigir engenharia reversa da interface. Esta página consolida, área por área, os endpoints citados nos guias da plataforma — com método, caminho e o que cada um faz — para que você monte sua integração consultando um único lugar. Autenticação, proteção CSRF e convenções gerais (formato JSON, campo error, permissões) estão na visão geral da API e valem para tudo o que segue.

Convenções desta página: segmentos variáveis aparecem como placeholders ({id}, {numero}, {taskId}); parâmetros de query relevantes são citados na descrição; endpoints marcados como servidor-a-servidor são pensados para integração entre sistemas, não para chamadas de navegador.

Busca, Chat & IA

Construa buscas semânticas, assistentes conversacionais e geração assistida por IA sobre o acervo do seu contexto.

As rotas de gravação no índice de busca — documentos, trechos, vetores, regras e texto integral — são servidor-a-servidor e exigem SEARCH_INDEX_WRITE (só do perfil ADMIN) ou a credencial de serviço da plataforma. A permissão de busca (SEARCH_EXECUTE), que todos os perfis têm, não grava nem apaga.

As leituras que expõem um índice inteiro — a varredura e a paginação do backfill (/api/search/backfill/scan e /api/search/backfill/page) e a exportação do texto dos documentos de um contexto (/api/search/chunks/document-texts) — também são servidor-a-servidor: exigem SEARCH_VIEW (só do perfil ADMIN) ou a credencial de serviço. A paginação só aceita o nome exato de um índice do escopo do backfill.

A exclusão por consulta (DELETE /api/search/query/{indexName}?field=&value=) exige SEARCH_INDEX_DELETE e, desde a issue #1912, só aceita o nome exato de um índice de contexto: padrão (datta_*), lista, exclusão e índice interno da plataforma respondem 400, mesmo para o ADMIN.

Disparar, verificar e cancelar a geração de embeddings (/api/embeddings/backfill, /api/embeddings/backfill-global e /api/embeddings/backfill/cancel) exige MODELS_MANAGE (só do perfil ADMIN) ou a credencial de serviço desde a issue #1912; a permissão de gerar embedding (EMBEDDING_GENERATE), que todos os perfis têm, pede vetor e lê o status da geração (/api/embeddings/backfill/status), mas não dispara nem cancela. Os disparos são POST desde 2026-09-28 (eram GET) e respondem o progresso em SSE; a geração segue no servidor mesmo que a conexão seja fechada. O mesmo vale para a migração Neo4j → OpenSearch (POST /api/search/admin/migrate/{domain} e /migrate-all, com OPENSEARCH_ADMIN) e para o download de modelo local (POST /api/local-llm/pull/{modelo}, com MODELS_MANAGE): nenhum GET da plataforma dispara trabalho.

Desde 2026-09-29 os dois também se cancelam, com a mesma permissão do disparo, e a exclusão vale para a plataforma inteira, não por réplica:

Só uma migração roda por vez: a segunda, em qualquer réplica, recebe um único evento error ("Já existe uma migração em andamento"). O download é um por modelo: pedir de novo o modelo que já está baixando acompanha o download em curso quando ele roda na mesma réplica, e responde 409 com a mensagem em português (um único evento cujo status é o texto) quando ele roda em outra réplica. Nenhum dos dois começa um segundo download ou uma segunda migração.

Pelo mesmo critério (issue #1935), as escritas em /api/embedding-models/** exigem MODELS_MANAGE no filtro e no handler — ativar e abrir a troca de modelo (/api/embedding-models/current, /api/embedding-models/migracao/preparar) e o passo do rerank aceitam também a credencial de serviço — e POST /api/rules/reindex-embeddings, que regera os vetores de todas as regras da plataforma, exige MODELS_MANAGE ou a credencial de serviço (antes, RULES_EDIT).

Nas rotas de busca que recebem índice no corpo (/api/search/query, /hybrid/multi, /suggest, /spellcheck…), um padrão com curinga (datta_*) ganha a exclusão de todos os índices de sistema da plataforma (histórico, prompts, telemetria, logs, glossário, catálogo, Captain), e pedir um deles pelo nome exato responde 400 (issue #1935).

curl -X PUT "$BASE/api/users/me/prompt" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Requested-With: XMLHttpRequest" \
  -H "Content-Type: application/json" \
  -d '{"customPrompt": "Responda sempre com referências normativas."}'

Documentos & Ingestão

Automatize a entrada de conteúdo — URLs de legislação, fontes de jurisprudência, atualizações de contexto — e a remoção controlada de processos.

Triagem & Regras

Dispare triagens em lote ou individuais, acompanhe o progresso em tempo real e gerencie o ciclo de vida completo das regras — inclusive geração por IA.

curl -X POST "$BASE/api/rules/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Requested-With: XMLHttpRequest" \
  -H "Content-Type: application/json" \
  -d '{"contexto": "CPC", "descricao": "prazos recursais", "quantidade": 5}'

Recursos & Peças

Gere peças recursais fundamentadas por IA e converta o resultado em documento editável.

curl -X POST "$BASE/api/chat/recurso" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Requested-With: XMLHttpRequest" \
  -H "Content-Type: application/json" \
  -d '{"processoNumero": "0001234-56.2024.8.26.0100", "tipoRecurso": "apelacao", "fundamentacao": "cerceamento de defesa"}'

Catálogo & Conhecimento

Publique e governe datasets no Knowledge Catalog, conduza a curadoria dos ativos de conhecimento e mantenha glossário e prompts de domínio.

curl -X POST "$BASE/api/knowledge/assets/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Requested-With: XMLHttpRequest" \
  -H "Content-Type: application/json" \
  -d '{"dominio": "CPC"}'

Conexões & Drivers

Cadastre fontes de dados externas de forma idempotente — toda conexão criada dispara catalogação automática — e administre os drivers que as suportam.

Painéis & DATTA BI

Monte workspaces, publique dashboards, renderize visuais com filtros e drill, e acione os copilots de BI — tudo o que o editor faz, via API.

As rotas /api/config/panel/{domain}/* consultam a fonte de dados com a identidade de quem abre o painel: o Authorization da chamada é encaminhado ao grafo, à busca, ao agente JDBC e ao Trino, e cada um aplica o próprio escopo de contexto e a própria permissão. Painel não é atalho: quem não alcança o contexto pela tela do grafo também não o alcança por um painel, e consultar um agente JDBC por um painel continua exigindo JDBC_EXECUTE. Chamada sem usuário (S2S por X-Internal-Token) recebe uma credencial de serviço restrita à descoberta de fontes.

curl -X POST "$BASE/api/dattabi/copilot/generate-dashboard" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Requested-With: XMLHttpRequest" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Painel de processos por classe e por mês", "persist": true}'

Pipelines & Execuções

Execute scripts DATTAX, assine streams em tempo real, controle o ciclo de vida de pipelines e acompanhe qualquer execução em segundo plano.

Processos BPM

Publique modelos de processo, crie instâncias e correlacione mensagens a eventos BPMN a partir dos seus sistemas.

Gerenciar modelos exige a permissão BPMN_DEPLOY (ou perfil administrador). Modelo publicado é imutável: para alterá-lo, abra uma nova versão.

curl -X POST "$BASE/api/bpmn/instancias" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Requested-With: XMLHttpRequest" \
  -H "Content-Type: application/json" \
  -d '{"modeloId": "triagem-processo", "chaveNegocio": "0001234-56.2024.8.26.0100", "titulo": "Triagem do processo", "variaveis": {}}'

Usuários, Permissões & Contextos

Provisione contas, atribua perfis e permissões, administre contextos de domínio e execute limpezas controladas.

MCP & Integrações Externas

Conecte agentes de IA externos às ferramentas do DATTA via protocolo MCP (JSON-RPC 2.0 + SSE), com observabilidade das invocações.

curl -X POST "$BASE/mcp/rpc" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Exportação de Conhecimento & Contas de Serviço

Leve o conhecimento curado do DATTA para sistemas externos — assistentes próprios, portais, buscadores — por um canal com identidade própria, separada das contas de pessoas.

Contas de serviço

Integrações não usam a conta de um usuário: você cria uma conta de serviço com escopo de contextos e troca as credenciais por um token de acesso. O segredo é exibido uma única vez, na criação — guarde-o no seu cofre.

Credencial inválida e conta revogada devolvem a mesma resposta de erro no pedido de token — a diferença não é revelada de propósito. Para saber se uma conta foi revogada, consulte a listagem.

Exportação por contexto

Base: /api/knowledge/export/{contexto}/.... Só conteúdo aprovado é exportado. Comece pelo manifesto: ele traz o inventário por coleção e uma versão de snapshot que serve de validador de cache — repetindo a chamada com esse validador, você recebe "sem novidades" em vez do conteúdo inteiro.

Para sincronização incremental, guarde o instante da última exportação e passe-o em since: as coleções devolvem apenas o que mudou desde então.

TOKEN=$(curl -s -X POST "$BASE/api/auth/service-accounts/token" \
  -H "Content-Type: application/json" \
  -d '{"clientId": "'"$CLIENT_ID"'", "clientSecret": "'"$CLIENT_SECRET"'"}' | jq -r .accessToken)

curl -s "$BASE/api/knowledge/export/MEC/manifest" \
  -H "Authorization: Bearer $TOKEN"

Configuração & Utilitários

Ajustes de plataforma consumíveis por API: modelos de IA, chaves de fontes externas, documentação restrita e navegação no armazenamento de objetos.

Os endpoints evoluem junto com a plataforma — novas rotas surgem e parâmetros são refinados a cada versão; em caso de divergência, o comportamento observado na versão instalada prevalece. Toda execução disparada via API (triagens, ingestões, gerações, sincronizações) aparece na área Execuções da interface, com a mesma trilha de auditoria das ações feitas pela tela.