API REST de digna 2026.11¶

La API REST de digna permite que sus propias herramientas y pipelines trabajen con digna mediante HTTP y JSON: leer proyectos y resultados de inspección, gestionar fuentes de datos, conjuntos de datos y atributos, e iniciar inspecciones, por ejemplo al final de una carga de datos. El Python SDK utiliza la misma API.

Esta página describe lo que tienen en común todas las solicitudes. Las páginas de recursos enumeran cada endpoint con sus parámetros, el cuerpo de la solicitud, las respuestas y los esquemas:

URL base¶

La API forma parte del backend de digna. Cada ruta empieza por /v1, después de la dirección del backend:

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

La dirección del backend es la misma que usa el dashboard: baseUrl en la sección [api] de dashboard/dashboard_config.toml. Use HTTPS siempre que el cliente que llama y digna no estén en la misma máquina, porque cada solicitud lleva una clave de API.

Autenticación¶

Cada solicitud envía la clave de API de un usuario de digna en la cabecera Authorization:

Authorization: Bearer <api key>

Para crear una clave, abra su perfil de usuario en la esquina inferior izquierda del dashboard, haga clic en API Keys y después en Add API Key, y copie la clave. Solo se muestra una vez. Las mismas claves sirven para el digna MCP Server.

Una solicitud se ejecuta con los permisos del usuario de la clave. Crear, modificar y eliminar requiere el rol de editor en el proyecto; de lo contrario, la solicitud se rechaza con 403 y el mensaje You don't have permission to edit this project.

Enviar una solicitud¶

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

Las respuestas son JSON. Las listas se devuelven como un array JSON. Los cuerpos de las solicitudes también son JSON y se envían con Content-Type: application/json.

Límites y filtros¶

Los endpoints de lista devuelven como máximo limit elementos: 200 de forma predeterminada y hasta 5000. Un valor fuera de ese rango se rechaza con 400. No hay offset ni token de página, así que acote una lista con sus filtros, por ejemplo project_id, data_source_id, o start_date y end_date en los estados de inspección.

Una solicitud que tarda más de 60 segundos se cancela con 408 Request Timeout.

Errores¶

Una respuesta de error tiene un cuerpo JSON con un código y un mensaje:

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

El message de una respuesta 401 indica qué falla en la clave:

Ejecutar una inspección¶

Una integración típica inicia una inspección cuando ha terminado una carga de datos, espera a que finalice y lee el resultado:

1. Inicie la inspección con POST /v1/inspection-requests. La respuesta contiene el id de la solicitud.
2. Siga su progreso con GET /v1/inspection-requests/{inspection_request_id}. Su status pasa de PENDING a RUNNING y luego a COMPLETED, o termina como FAILED, ABORTED o CANCELLED. Vuelva a consultarlo cada pocos segundos hasta que deje de cambiar.
3. Lea el resultado con GET /v1/inspection-statuses/data-sources para las fechas inspeccionadas. Cada elemento tiene un status general: 0 (OK), 1 (advertencia), 2 (crítico) o -1 (sin estado), y un estado por módulo con el número de comprobaciones superadas, inciertas y fallidas.

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¶

Cada instalación de digna describe esta API en un documento OpenAPI 3.1 y ofrece una Swagger UI interactiva para probar solicitudes contra ella:

El documento de Release 2026.11 también está disponible aquí: openapi.json. Úselo para generar un cliente en otro lenguaje.