Reports & Verify-API

Fachlich: Diese Endpoints erzeugen die Unterlagen, die Prüfer sehen wollen - automatisierbar für wiederkehrende Audits (z. B. monatlicher Export ins GRC-System). Auth: App-Session (Browser-Download) oder API-Key.

GET /api/v1/reports/oversight#

Jede Aktion, die einen Menschen brauchte: was, wer, wann, Kanal, Begründung, Regel. Das PDF-Deckblatt enthält das Ergebnis der Hash-Chain-Verifikation - der Report ist damit als Audit-Anlage ohne Nachbearbeitung verwendbar.

Die Spalte approver_policy nennt den Kreis, der freigeben durfte - so, wie er beim Halten festgeschrieben wurde, nicht wie er heute lautet. Ohne sie belegte der Report zwar, wer entschieden hat, aber nicht, dass diese Person es durfte. Bei Holds aus der Zeit vor dieser Spalte bleibt sie leer.

reference,created_at,connection,tool,summary,agent,rule,status,verdict,channel,reason,decided_at,executed_at,approver_policy

Neue Spalten kommen hinten dazu - ein Import, der nach Spaltenposition liest, bleibt damit gültig.

GET /api/v1/reports/activity#

Alle Agentenaktivitäten inklusive auto_allowed: Top-Tools, Calls pro Tag und die Quote „hätte unter Enforce Freigabe gebraucht" - die Kennzahl für den Umstieg von Monitor auf Enforce.

Query-Parameter (beide Reports)#

Parameter	Default	Bedeutung
`from`, `to`	letzte 30 Tage	Zeitraum, ISO-Datum (`2026-06-01`). Beide Enden inklusive: ein reines Datum bei `to` deckt den ganzen Tag ab (UTC), nicht nur dessen Mitternacht. Ein vollständiger Zeitstempel (`2026-06-01T12:00:00Z`) gilt auf die Sekunde genau.
`format`	`csv`	`csv` oder `pdf`
`inline`	-	`1` = im Browser anzeigen statt Download

curl -H "Authorization: Bearer $TOKYN_TRAIL_API_KEY" \
  "https://trail.tokyn.studio/api/v1/reports/oversight?from=2026-06-01&to=2026-07-01&format=pdf" \
  -o oversight-juni.pdf

Beide Reports zählen auf den Rate-Limit-Topf v1-reports - getrennt von der Hold-API, damit ein monatlicher PDF-Export nicht das Kontingent Ihrer laufenden Aufrufe aufbraucht. Details unter Rate Limits.

GET /api/v1/audit/verify#

Verifiziert die komplette Hash-Chain des Arbeitsbereichs: hash = sha256(prev_hash + canonical_json(payload) + seq), verankert in sha256(org_id). Eine Manipulation oder Löschung bricht die Kette an exakt der betroffenen Sequenznummer.

{ "valid": true,  "checked": 1234 }
{ "valid": false, "checked": 41, "first_broken_seq": 42 }

Praxis-Tipp: Rufen Sie verify als Teil Ihres regelmäßigen Compliance-Checks auf und alarmieren Sie bei valid: false - das ist der eingebaute Integritätsnachweis Ihrer Evidenz.