digna REST-API 2026.11¶

Mit der digna REST-API arbeiten Ihre eigenen Tools und Pipelines über HTTP und JSON mit digna: Sie lesen Projekte und Inspektionsergebnisse, verwalten Datenquellen, Datensätze und Attribute und starten Inspektionen, zum Beispiel am Ende eines Datenladevorgangs. Das Python SDK verwendet dieselbe API.

Diese Seite beschreibt, was alle Anfragen gemeinsam haben. Die Ressourcenseiten führen jeden Endpunkt mit seinen Parametern, seinem Request-Body, seinen Antworten und Schemas auf:

Basis-URL¶

Die API ist Teil des digna-Backends. Jeder Pfad beginnt nach der Adresse des Backends mit /v1:

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

Die Adresse des Backends ist dieselbe, die das Dashboard verwendet: baseUrl im Abschnitt [api] von dashboard/dashboard_config.toml. Verwenden Sie HTTPS, sobald der Aufrufer und digna nicht auf demselben Rechner laufen, denn jede Anfrage enthält einen API-Schlüssel.

Authentifizierung¶

Jede Anfrage sendet den API-Schlüssel eines digna-Benutzers im Header Authorization:

Authorization: Bearer <api key>

Um einen Schlüssel zu erstellen, öffnen Sie Ihr Benutzerprofil unten links im Dashboard, klicken auf API-Schlüssel und dann auf API-Schlüssel hinzufügen und kopieren den Schlüssel. Er wird nur einmal angezeigt. Dieselben Schlüssel funktionieren auch für den digna MCP Server.

Eine Anfrage läuft mit den Berechtigungen des Benutzers, dem der Schlüssel gehört. Zum Erstellen, Ändern und Löschen ist die Editorrolle im Projekt nötig; andernfalls wird die Anfrage mit 403 und der Meldung You don't have permission to edit this project abgelehnt.

Eine Anfrage senden¶

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

Antworten sind JSON. Listen werden als JSON-Array zurückgegeben. Auch Request-Bodys sind JSON und werden mit Content-Type: application/json gesendet.

Limits und Filter¶

Listen-Endpunkte geben höchstens limit Einträge zurück: standardmäßig 200, maximal 5000. Ein Wert außerhalb dieses Bereichs wird mit 400 abgelehnt. Es gibt weder Offset noch Seiten-Token. Grenzen Sie eine Liste deshalb mit ihren Filtern ein, zum Beispiel project_id, data_source_id oder start_date und end_date bei den Inspektionsstatus.

Eine Anfrage, die länger als 60 Sekunden dauert, wird mit 408 Request Timeout abgebrochen.

Fehler¶

Eine Fehlerantwort hat einen JSON-Body mit einem Code und einer Meldung:

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

Die message einer 401-Antwort sagt, was mit dem Schlüssel nicht stimmt:

Eine Inspektion ausführen¶

Eine typische Integration startet eine Inspektion, wenn ein Datenladevorgang abgeschlossen ist, wartet auf ihr Ende und liest das Ergebnis:

1. Starten Sie die Inspektion mit POST /v1/inspection-requests. Die Antwort enthält die id der Anfrage.
2. Verfolgen Sie ihren Fortschritt mit GET /v1/inspection-requests/{inspection_request_id}. Ihr status wechselt von PENDING über RUNNING zu COMPLETED oder endet als FAILED, ABORTED oder CANCELLED. Fragen Sie alle paar Sekunden erneut ab, bis er sich nicht mehr ändert.
3. Lesen Sie das Ergebnis mit GET /v1/inspection-statuses/data-sources für die inspizierten Tage. Jeder Eintrag hat einen Gesamt-status: 0 (OK), 1 (Warnung), 2 (kritisch) oder -1 (kein Status), und einen Status pro Modul mit der Anzahl der bestandenen, unsicheren und fehlgeschlagenen Checks.

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

OpenAPI-Dokument¶

Jede digna-Installation beschreibt diese API in einem OpenAPI-3.1-Dokument und bietet eine interaktive Swagger UI, in der Sie Anfragen dagegen ausprobieren können:

Das Dokument von Release 2026.11 finden Sie auch hier: openapi.json. Damit können Sie einen Client in einer anderen Sprache generieren.