Evidence API

Een Evidence-rij is één artefact dat tijdens een sessie is vastgelegd — een snapshot, een whiteboard, een videoclip, een opname of een geüpload document. Elke rij draagt een sha256 + byte_size + mime zodat de integriteitsverificatieketen kan bewijzen dat er niet met de bytes is geknoeid tussen vastlegging en audit.

Het Evidence-object

{
  "id": "ev-7f3a...",
  "session": "0c8f4d2e-1a3b-4c5d-9e7f-1234567890ab",
  "kind": "snapshot",
  "status": "ready",
  "mime": "image/jpeg",
  "byte_size": 184523,
  "sha256": "f9cc12fda76c30dcc9bee627baed6c9e8fe11b813313de70b1463f9f73e5e418",
  "captured_at": "2026-05-23T10:14:02.481Z",
  "created_at": "2026-05-23T10:14:02.917Z",
  "completed_at": "2026-05-23T10:14:03.211Z"
}

Soorten

Soort	Vastgelegd door	Opmerkingen
`snapshot`	Operator of veldkant	Enkel stilstaand frame (JPEG). De meest voorkomende soort.
`whiteboard`	Operator	Excalidraw-export — PNG + canonieke JSON. Zie Whiteboards.
`clip`	Operator	Korte MP4 geknipt uit de live sessie — gebruikt om beweging vast te leggen die de veldgebruiker demonstreert.
`recording`	Systeem	Volledige sessieopname. Na afloop van de sessie nabewerkt naar libx264 medium / crf20.
`document`	Operator	Bijlage uit de in-sessie-chat (PDF's, foto's, enz.). Basis voor PDF-voor-ondertekening.

Status

Status	Betekenis
`pending`	Rij aangemaakt; bytes nog niet in object storage.
`uploading`	Multipart-upload bezig.
`ready`	Bytes zijn opgeslagen; sha256 + byte_size zijn definitief. Alleen `ready` rijen zijn downloadbaar.
`failed`	Vastlegging of upload afgebroken. `completed_at` is null.

Sessiebewijs lijsten

GET /api/v1/public/sessions/{session_id}/evidence — scope evidence:read

curl "https://app.nexbasira.com/api/v1/public/sessions/0c8f.../evidence?kind=snapshot&limit=50" \
  -H "Authorization: Bearer nb_sec_..."

Query-params

Param	Type	Opmerkingen
`kind`	string	Filter — een van `snapshot`, `whiteboard`, `clip`, `recording`, `document`.
`limit`	int	Max 100. Standaard 25.
`cursor`	opaque	Uit de vorige response's `next_cursor`.

Een ondertekende download-URL ophalen

GET /api/v1/public/evidence/{evidence_id}/download — scope evidence:read

Retourneert een kortlevende presigned URL waarvan de klant de ruwe bytes ophaalt. De URL wijst rechtstreeks naar de object-storage-backend zodat downloads onze app-servers omzeilen — geen bandbreedte-egresskosten aan uw kant van de publieke API.

curl "https://app.nexbasira.com/api/v1/public/evidence/ev-7f3a.../download" \
  -H "Authorization: Bearer nb_sec_..."

{
  "url": "https://s3.eu-central-1.amazonaws.com/nb-prod-evidence/orgs/.../snapshot.jpg?X-Amz-Algorithm=...",
  "expires_in_seconds": 900,
  "sha256": "f9cc12fda76c30dcc9bee627baed6c9e8fe11b813313de70b1463f9f73e5e418",
  "byte_size": 184523,
  "mime": "image/jpeg",
  "kind": "snapshot"
}

Roep opnieuw aan wanneer de URL verloopt — geen rate-limit-straf voor herhaald genereren. Hash na het downloaden de bytes met SHA-256 en vergelijk met de geretourneerde sha256 om te verifiëren dat het bestand end-to-end intact is.

# integrity check — Python
import hashlib, requests
r = requests.get(presigned["url"]); r.raise_for_status()
assert hashlib.sha256(r.content).hexdigest() == presigned["sha256"]

Veelvoorkomende fouten

Status	Code	Wanneer
403	`permission_denied`	Credential mist `evidence:read`.
404	`not_found`	Evidence-rij bestaat niet in de org van de credential.
409	`evidence_not_ready`	Download aangevraagd op een rij waarvan `status` is niet `ready`.
410	`retention_expired`	Het retentiebeleid van de org heeft de leeftijdsgrens van de rij overschreden; bytes zijn uit object storage verwijderd.

Opmerkingen

Geen POST/PATCH/DELETE. Bewijs wordt client-side vastgelegd (operator + veld-SPA) tijdens de sessie. De publieke API is alleen-lezen op deze resource.
Retentie. Elke org configureert een retentievenster (standaard 7 jaar voor eIDAS-conforme deployments). Na het venster verwijderen object-storage-lifecycle-regels de bytes; de rij blijft zodat de audit chain niet breekt, maar /download retourneert 410.
Verankerd in de audit chain. Elke ready -rij draagt zijn sha256 bij aan de hashketen per sessie, die bij sessie-einde bij de TSA wordt verankerd. De ketenkop + het TSA-bewijs zijn bereikbaar via het audit-verify-endpoint aan de SPA-kant.