Evidence-API

Eine Evidence-Zeile ist ein während einer Sitzung erfasstes Artefakt — ein Snapshot, ein Whiteboard, ein Videoclip, eine Aufzeichnung oder ein hochgeladenes Dokument. Jede Zeile trägt einen sha256 + byte_size + mime , sodass die Integritäts-Verifizierungskette beweisen kann, dass die Bytes zwischen Erfassung und Audit nicht manipuliert wurden.

Das Evidence-Objekt

{
  "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"
}

Kinds

Kind	Erfasst von	Anmerkungen
`snapshot`	Operator oder Feldseite	Einzelnes Standbild (JPEG). Die häufigste Art.
`whiteboard`	Operator	Excalidraw-Export — PNG + kanonisches JSON. Siehe Whiteboards.
`clip`	Operator	Kurzer MP4-Ausschnitt aus der Live-Sitzung — genutzt, um Bewegung zu erfassen, die der Feldbenutzer demonstriert.
`recording`	System	Vollständige Sitzungsaufzeichnung. Nach Sitzungsende zu libx264 medium / crf20 nachbearbeitet.
`document`	Operator	Dateianhang aus dem In-Session-Chat (PDFs, Fotos usw.). Grundlage für PDF-for-Signature.

Status

Status	Bedeutung
`pending`	Zeile erstellt; Bytes noch nicht im Objektspeicher.
`uploading`	Multipart-Upload läuft.
`ready`	Bytes sind persistiert; sha256 + byte_size sind finalisiert. Nur `ready` -Zeilen sind herunterladbar.
`failed`	Erfassung oder Upload abgebrochen. `completed_at` ist null.

Sitzungs-Evidence auflisten

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	Typ	Anmerkungen
`kind`	string	Filter — eines von `snapshot`, `whiteboard`, `clip`, `recording`, `document`.
`limit`	int	Max 100. Standardmäßig 25.
`cursor`	opaque	Aus dem `next_cursor`.

Eine signierte Download-URL erhalten

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

Gibt eine kurzlebige vorsignierte URL zurück, von der der Kunde die Roh-Bytes abruft. Die URL zeigt direkt auf das Objektspeicher-Backend, sodass Downloads unsere App-Server umgehen — keine Bandbreiten-Egress-Gebühren von Ihrer Seite der öffentlichen 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"
}

Rufen Sie erneut auf, wenn die URL abläuft — keine Rate-Limit-Strafe für wiederholtes Prägen. Hashen Sie nach dem Download die Bytes mit SHA-256 und vergleichen Sie mit dem zurückgegebenen sha256 , um zu verifizieren, dass die Datei end-to-end intakt ist.

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

Häufige Fehler

Status	Code	Wann
403	`permission_denied`	Dem Credential fehlt `evidence:read`.
404	`not_found`	Die Evidence-Zeile existiert nicht in der Org des Credentials.
409	`evidence_not_ready`	Download angefordert auf einer Zeile, deren `status` nicht `ready`.
410	`retention_expired`	Die Aufbewahrungsrichtlinie der Org hat die Altersgrenze der Zeile überschritten; die Bytes wurden aus dem Objektspeicher gelöscht.

Anmerkungen

Kein POST/PATCH/DELETE. Evidence wird clientseitig (Operator- + Feld-SPA) während der Sitzung erfasst. Die öffentliche API ist auf dieser Ressource schreibgeschützt.
Aufbewahrung. Jede Org konfiguriert ein Aufbewahrungsfenster (Standard 7 Jahre für eIDAS-konforme Deployments). Nach dem Fenster löschen Objektspeicher-Lifecycle-Regeln die Bytes; die Zeile bleibt, damit die Audit-Kette nicht bricht, aber /download gibt 410 zurück.
In der Audit-Kette verankert. Jede ready -Zeile trägt ihren sha256 zur sitzungsbezogenen Hash-Kette bei, die bei Sitzungsende an der TSA verankert wird. Der Kettenkopf + die TSA-Quittung sind über den SPA-seitigen Audit-Verify-Endpoint erreichbar.