API-Referenz: Grundlagen

Die tokyn.trail-API besteht aus zwei Oberflächen: der Core-API (REST, Holds, Reports, Verify) und dem MCP-Proxy-Endpoint (streamable HTTP für MCP-Clients). Beide authentifizieren mit denselben API-Keys.

Base-URLs#

Oberfläche	URL	Lokal (Dev)
Core-API	`https://app.tokyn-trail.eu`	`http://localhost:3000`
MCP-Proxy	`https://mcp.tokyn-trail.eu`	`http://localhost:3001`

Authentifizierung#

Alle Requests tragen einen API-Key als Bearer-Token. Keys erstellen Sie unter Einstellungen → API-Keys; der Klartext wird genau einmal angezeigt, gespeichert wird nur ein SHA-256-Hash.

Authorization: Bearer tt_live_...   # Produktion
Authorization: Bearer tt_test_...   # Test/Entwicklung

Fachlich: Ein Key gehört zur Organisation, nicht zu einer Person — Entscheidungen über die API werden deshalb nie einem menschlichen Approver zugeschrieben. Menschen entscheiden über Inbox, E-Mail-Link, SMS, Slack oder Widget; die API legt Holds an und fragt sie ab.

Konventionen#

Alle Bodies sind JSON (Content-Type: application/json).
Zeitstempel sind UTC, ISO 8601 (2026-07-20T08:21:45.000Z).
Öffentliche Referenzen für Aktionen beginnen mit tt_pa_ — sie sind die IDs der Hold-API und der Statusseiten.
Idempotenz: POST /v1/holds verlangt einen idempotency_key; Wiederholungen liefern den ursprünglichen Hold statt Duplikate.
Versionierung: Alle Endpoints tragen den Pfad-Prefix /v1. Breaking Changes erscheinen nur unter einer neuen Version — /v1 bleibt stabil.

Rate Limits#

Die Core-API hat derzeit keine festen Request-Limits. Zwei Grenzen gibt es trotzdem: das monatliche Hold-Kontingent Ihres Plans (Hard-Stop nur im Free-Plan, 402) und Ihre eigenen Frequenz-Regeln (z. B. „mehr als 20 Calls/Stunde → halten"). Für die Statusabfrage empfehlen wir POST /holds/:id/wait (Long-Poll) oder Webhooks statt engem Polling.

Fehlerformat#

Fehler enthalten nie Payload-Inhalte — nur einen Code, bei Validierungsfehlern die betroffenen Felder und bei internen Fehlern eine referenceId für den Support:

{ "error": "invalid_json" }
{ "error": "validation_failed", "detail": "tool_name: String must contain at least 1 character(s)",
  "issues": [{ "field": "tool_name", "message": "String must contain at least 1 character(s)" }],
  "docs": "https://app.tokyn-trail.eu/docs/api/holds" }
{ "error": "internal", "referenceId": "b3f6…" }

Alle Statuscodes: Fehlercodes.

Endpoint-Übersicht#

Methode & Pfad	Zweck
`POST /api/v1/holds`	Aktion zur Freigabe einreichen (Regeln entscheiden: allowed / pending / denied)
`GET /api/v1/holds/:id`	Status einer Aktion abfragen (Polling)
`POST /api/v1/holds/:id/wait`	Long-Poll auf die Entscheidung (max. 60 s pro Runde)
`GET /api/v1/reports/oversight`	Oversight-Report als CSV/PDF
`GET /api/v1/reports/activity`	Activity-Report als CSV/PDF
`GET /api/v1/audit/verify`	Hash-Chain der Organisation verifizieren

Das ist die vollständige /v1-Oberfläche. Connections, Regeln, Approver und Webhook-Konfiguration verwalten Sie derzeit in der App — es gibt bewusst noch keine Management-API, keine Hold-Liste und kein programmatisches Storno. Wenn Ihnen davon etwas fehlt, sagen Sie es uns.

MCP-Proxy-Endpoint#

Pro Connection existiert ein MCP-Endpoint (streamable HTTP, kein stdio):

URL:    https://mcp.tokyn-trail.eu/v1/<connection-id>
Header: Authorization: Bearer tt_live_...
        X-TokynTrail-Agent: <agent-id>        # optional, erscheint in der Evidenz

tools/list wird durchgereicht und löst die Tool-Discovery aus; zusätzlich injiziert der Proxy das Tool tokyn_trail_check_status.
tools/call wird je nach Regel durchgereicht, gehalten (sofortige Antwort mit tt_pa_…-Referenz — die Verbindung blockiert nie) oder mit MCP-Error -32003 abgelehnt.
Nach einer Freigabe führt der Proxy den Upstream-Call selbst aus.