Endpoint Reference by Area

Integrating a system with DATTA should not require reverse-engineering the user interface. This page consolidates, area by area, the endpoints referenced across the platform guides — with method, path and what each one does — so you can build your integration from a single place. Authentication, CSRF protection and general conventions (JSON format, error field, permissions) live in the API overview and apply to everything below.

Conventions on this page: variable segments appear as placeholders ({id}, {numero}, {taskId}); relevant query parameters are mentioned in the description; endpoints marked as server-to-server are meant for system-to-system integration, not browser calls.

Search, Chat & AI

Build semantic search, conversational assistants and AI-assisted generation on top of your context's collection.

The routes that write to the search index — documents, excerpts, vectors, rules and full text — are server-to-server and require SEARCH_INDEX_WRITE (ADMIN profile only) or the platform's service credential. The search permission (SEARCH_EXECUTE), which every profile has, neither writes nor deletes.

The reads that expose a whole index — the backfill scan and paging (/api/search/backfill/scan and /api/search/backfill/page) and the export of a context's document text (/api/search/chunks/document-texts) — are server-to-server too: they require SEARCH_VIEW (ADMIN profile only) or the platform's service credential. Paging only accepts the exact name of an index in the backfill scope.

Deleting by query (DELETE /api/search/query/{indexName}?field=&value=) requires SEARCH_INDEX_DELETE and, since issue #1912, accepts only the exact name of a context index: a pattern (datta_*), a list, an exclusion or a platform-internal index answers 400, even for ADMIN.

Triggering, verifying and cancelling embedding generation (/api/embeddings/backfill, /api/embeddings/backfill-global and /api/embeddings/backfill/cancel) requires MODELS_MANAGE (ADMIN profile only) or the service credential since issue #1912; the embedding permission (EMBEDDING_GENERATE), which every profile has, requests vectors and reads the generation status (/api/embeddings/backfill/status), but neither triggers nor cancels. The triggers are POST since 2026-09-28 (they were GET) and answer the progress as SSE; generation keeps running on the server even if the connection is closed. The same holds for the Neo4j → OpenSearch migration (POST /api/search/admin/migrate/{domain} and /migrate-all, with OPENSEARCH_ADMIN) and for the local model download (POST /api/local-llm/pull/{model}, with MODELS_MANAGE): no platform GET starts a job.

Since 2026-09-29 both can also be cancelled, with the same permission as the trigger, and the exclusion holds for the whole platform, not per replica:

Only one migration runs at a time: the second one, on any replica, gets a single error event ("Já existe uma migração em andamento"). Downloads are one per model: asking again for a model that is already downloading follows the running download when it runs on the same replica, and answers 409 with the Portuguese message (a single event whose status is the text) when it runs on another replica. Neither starts a second download or a second migration.

By the same criterion (issue #1935), writes under /api/embedding-models/** require MODELS_MANAGE in the filter and in the handler — activating and opening a model switch (/api/embedding-models/current, /api/embedding-models/migracao/preparar) and the reranker step also accept the service credential — and POST /api/rules/reindex-embeddings, which regenerates the vectors of every rule on the platform, requires MODELS_MANAGE or the service credential (previously RULES_EDIT).

On the search routes that take an index in the body (/api/search/query, /hybrid/multi, /suggest, /spellcheck…), a wildcard pattern (datta_*) gets the exclusion of every platform system index (history, prompts, telemetry, logs, glossary, catalog, Captain), and asking for one of them by its exact name answers 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."}'

Documents & Ingestion

Automate content intake — legislation URLs, case-law sources, context updates — and the controlled removal of court cases.

Screening & Rules

Trigger batch or single-case screenings, follow progress in real time and manage the full rule lifecycle — including AI generation.

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}'

Appeals & Legal Drafts

Generate AI-grounded appeal drafts and convert the result into an editable document.

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"}'

Catalog & Knowledge

Publish and govern datasets in the Knowledge Catalog, run the knowledge-asset curation cycle and maintain glossary and domain prompts.

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"}'

Connections & Drivers

Register external data sources idempotently — every created connection triggers automatic cataloging — and manage the drivers behind them.

Panels & DATTA BI

Assemble workspaces, publish dashboards, render visuals with filters and drill, and drive the BI copilots — everything the editor does, via API.

The /api/config/panel/{domain}/* routes query the data source with the identity of whoever opens the panel: the request's Authorization is forwarded to the graph, the search, the JDBC agent and Trino, and each one applies its own context scope and its own permission. A panel is not a shortcut: whoever cannot reach a context from the graph screen cannot reach it through a panel either, and querying a JDBC agent from a panel still requires JDBC_EXECUTE. A call with no user (S2S via X-Internal-Token) gets a service credential restricted to source discovery.

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 & Executions

Run DATTAX scripts, subscribe to real-time streams, control pipeline lifecycles and track any background execution.

BPM Processes

Publish process models, create instances and correlate messages to BPMN events from your own systems.

Managing models requires the BPMN_DEPLOY permission (or an administrator profile). A published model is immutable: to change it, open a new version.

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": {}}'

Users, Permissions & Contexts

Provision accounts, assign roles and permissions, manage domain contexts and run controlled cleanups.

MCP & External Integrations

Connect external AI agents to DATTA's tools via the MCP protocol (JSON-RPC 2.0 + SSE), with observability over invocations.

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

Knowledge Export & Service Accounts

Take DATTA's curated knowledge to external systems — your own assistants, portals or search engines — through a channel with its own identity, separate from people's accounts.

Service accounts

Integrations do not use a person's account: you create a service account scoped to contexts and exchange its credentials for an access token. The secret is shown only once, at creation — store it in your vault.

An invalid credential and a revoked account return the same error on the token request — the difference is withheld on purpose. To find out whether an account was revoked, check the listing.

Export by context

Base: /api/knowledge/export/{context}/.... Only approved content is exported. Start with the manifest: it carries the per-collection inventory and a snapshot version that works as a cache validator — repeating the call with that validator returns "nothing new" instead of the whole content.

For incremental synchronization, keep the timestamp of your last export and pass it in since: the collections return only what changed since then.

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"

Configuration & Utilities

Platform settings consumable via API: AI models, external-source keys, restricted documentation and object-storage browsing.

Endpoints evolve with the platform — new routes appear and parameters are refined in every release; when in doubt, the behavior observed in your installed version prevails. Every execution triggered via API (screenings, ingestions, generations, syncs) shows up in the Executions area of the interface, with the same audit trail as actions performed on screen.