digna REST API 2026.11¶

dignan REST API:n avulla omat työkalusi ja putkesi voivat käyttää dignaa HTTP:n ja JSONin kautta: lukea projekteja ja tarkastustuloksia, hallita tietolähteitä, datasettejä ja attribuutteja sekä käynnistää tarkastuksia esimerkiksi datan latauksen päätteeksi. Python SDK käyttää samaa API:a.

Tämä sivu kattaa sen, mikä on yhteistä kaikille pyynnöille. Resurssisivuilla on kuvattu jokainen päätepiste parametreineen, pyynnön runkoineen, vastauksineen ja skeemoineen:

Perus-URL¶

API on osa dignan backendia. Jokainen polku alkaa backendin osoitteen jälkeen merkkijonolla /v1:

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

Backendin osoite on sama, jota dashboard käyttää: baseUrl tiedoston dashboard/dashboard_config.toml osiossa [api]. Käytä HTTPS:ää aina, kun kutsuja ja digna eivät ole samalla koneella, koska jokainen pyyntö sisältää API-avaimen.

Todennus¶

Jokainen pyyntö lähettää digna-käyttäjän API-avaimen Authorization-otsakkeessa:

Authorization: Bearer <api key>

Luo avain avaamalla käyttäjäprofiilisi dashboardin vasemmasta alakulmasta, klikkaamalla API Keys ja sitten Add API Key ja kopioimalla avain. Se näytetään vain kerran. Samat avaimet toimivat myös digna MCP Serverille.

Pyyntö suoritetaan avaimen käyttäjän oikeuksilla. Luominen, muuttaminen ja poistaminen edellyttävät projektissa editorin roolia; muuten pyyntö hylätään koodilla 403 ja viestillä You don't have permission to edit this project.

Pyynnön tekeminen¶

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

Vastaukset ovat JSONia. Listat palautetaan JSON-taulukkona. Myös pyyntöjen rungot ovat JSONia, ja ne lähetetään otsakkeella Content-Type: application/json.

Rajat ja suodattimet¶

Listapäätepisteet palauttavat enintään limit kohdetta: oletuksena 200 ja enintään 5000. Tämän välin ulkopuolinen arvo hylätään koodilla 400. Offsetia tai sivutunnistetta ei ole, joten rajaa listaa sen sijaan sen suodattimilla, esimerkiksi project_id, data_source_id tai tarkastusten tiloissa start_date ja end_date.

Pyyntö, joka kestää yli 60 sekuntia, peruutetaan vastauksella 408 Request Timeout.

Virheet¶

Virhevastauksella on JSON-runko, jossa on koodi ja viesti:

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

401-vastauksen message kertoo, mikä avaimessa on vialla:

Tarkastuksen ajaminen¶

Tyypillinen integraatio käynnistää tarkastuksen, kun datan lataus on valmis, odottaa sen valmistumista ja lukee tuloksen:

1. Käynnistä tarkastus pyynnöllä POST /v1/inspection-requests. Vastaus sisältää pyynnön id:n.
2. Seuraa sen etenemistä pyynnöllä GET /v1/inspection-requests/{inspection_request_id}. Sen status etenee tilasta PENDING tilan RUNNING kautta tilaan COMPLETED tai päättyy tilaan FAILED, ABORTED tai CANCELLED. Kysy uudelleen muutaman sekunnin välein, kunnes se ei enää muutu.
3. Lue tulos pyynnöllä GET /v1/inspection-statuses/data-sources tarkastetuille päivämäärille. Jokaisella kohteella on kokonaistila status: 0 (OK), 1 (varoitus), 2 (kriittinen) tai -1 (ei tilaa), sekä moduulikohtainen tila, jossa on läpäistyjen, epävarmojen ja epäonnistuneiden tarkistusten määrä.

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-dokumentti¶

Jokainen digna-asennus kuvaa tämän API:n OpenAPI 3.1 -dokumentissa ja tarjoaa interaktiivisen Swagger UI:n, jossa voit kokeilla pyyntöjä sitä vasten:

Release 2026.11:n dokumentti on saatavilla myös täältä: openapi.json. Voit generoida sen avulla asiakasohjelman toisella ohjelmointikielellä.