API REST do digna 2026.11¶

A API REST do digna permite que suas próprias ferramentas e pipelines trabalhem com o digna por HTTP e JSON: ler projetos e resultados de inspeção, gerenciar fontes de dados, conjuntos de dados e atributos e iniciar inspeções, por exemplo ao final de uma carga de dados. O Python SDK usa a mesma API.

Esta página descreve o que todas as solicitações têm em comum. As páginas de recursos listam cada endpoint com seus parâmetros, corpo da solicitação, respostas e esquemas:

URL Base¶

A API faz parte do backend do digna. Todo caminho começa com /v1, depois do endereço do backend:

https://digna.example.com/v1/projects

O endereço do backend é o mesmo que o dashboard usa: baseUrl na seção [api] de dashboard/dashboard_config.toml. Use HTTPS sempre que o chamador e o digna não estiverem na mesma máquina, porque toda solicitação carrega uma chave de API.

Autenticação¶

Toda solicitação envia a chave de API de um usuário do digna no cabeçalho Authorization:

Authorization: Bearer <api key>

Para criar uma chave, abra seu perfil de usuário no canto inferior esquerdo do dashboard, clique em API Keys e depois em Add API Key, e copie a chave. Ela é exibida apenas uma vez. As mesmas chaves funcionam para o digna MCP Server.

Uma solicitação é executada com as permissões do usuário da chave. Criar, alterar e excluir exige a função de editor no projeto; caso contrário, a solicitação é recusada com 403 e a mensagem You don't have permission to edit this project.

Fazendo uma Solicitação¶

export DIGNA_API_KEY='<api key>'
curl https://digna.example.com/v1/projects -H "Authorization: Bearer $DIGNA_API_KEY"

As respostas são em JSON. Listas são retornadas como um array JSON. Os corpos das solicitações também são em JSON, enviados com Content-Type: application/json.

Limites e Filtros¶

Endpoints de listagem retornam no máximo limit itens: 200 por padrão e até 5000. Um valor fora desse intervalo é rejeitado com 400. Não há offset nem token de página, então restrinja uma lista com os filtros dela, por exemplo project_id, data_source_id, ou start_date e end_date nos status de inspeção.

Uma solicitação que demora mais de 60 segundos é cancelada com 408 Request Timeout.

Erros¶

Uma resposta de erro tem um corpo JSON com um código e uma mensagem:

{
  "code": "NOT_FOUND",
  "message": "Data set not found"
}

A message de uma resposta 401 informa o que há de errado com a chave:

Executando uma Inspeção¶

Uma integração típica inicia uma inspeção quando uma carga de dados termina, aguarda sua conclusão e lê o resultado:

1. Inicie a inspeção com POST /v1/inspection-requests. A resposta contém o id da solicitação.
2. Acompanhe o progresso com GET /v1/inspection-requests/{inspection_request_id}. O status passa de PENDING por RUNNING até COMPLETED, ou termina como FAILED, ABORTED ou CANCELLED. Consulte novamente a cada poucos segundos até que ele não mude mais.
3. Leia o resultado com GET /v1/inspection-statuses/data-sources para as datas inspecionadas. Cada item tem um status geral: 0 (OK), 1 (aviso), 2 (crítico) ou -1 (sem status), e um status por módulo com o número de verificações aprovadas, incertas e com falha.

curl -X POST https://digna.example.com/v1/inspection-requests \
  -H "Authorization: Bearer $DIGNA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "project_id": 1,
    "include_all_data_sources": true,
    "data_source_ids": [],
    "start_date": "2026-11-06",
    "end_date": "2026-11-06",
    "mode": "DAILY",
    "weekly_mode_weekdays": [],
    "monthly_mode_days": [],
    "use_notification": true
  }'

Documento OpenAPI¶

Toda instalação do digna descreve esta API em um documento OpenAPI 3.1 e oferece uma Swagger UI interativa para testar solicitações com ela:

O documento do Release 2026.11 também está disponível aqui: openapi.json. Use-o para gerar um cliente em outra linguagem.