Referenz

API-Referenz

Eine lesende REST-API über die Datensätze und Versionen, für die Sie eine Lizenz halten. Sie liefert Metadaten und kurzlebige Download-URLs und streamt selbst kein Video.

Basis-URL und Authentifizierung

Alle Anfragen gehen an https://api.curatrix.de/v1 über TLS und tragen ein Bearer-Token. Anfragen ohne gültigen Schlüssel liefern 401. Anfragen zu Datensätzen außerhalb Ihres Lizenzumfangs liefern 404 statt 403, damit der Schlüsselumfang nicht aufzählbar ist.

Episoden auflisten

GET Episoden, gefiltert nach Ergebnis

GET /v1/datasets/electrical-assembly/versions/1.3.0/episodes
      ?outcome=failure&environment=workshop&limit=50
Host: api.curatrix.de
Authorization: Bearer $CURATRIX_API_KEY
Accept: application/json

Antwort 200

{
  "dataset_id": "electrical-assembly",
  "version": "1.3.0",
  "total": 184,
  "episodes": [
    {
      "episode_id": "ep_000123",
      "task": "terminal-block-wiring",
      "environment": "workshop",
      "duration_s": 142.6,
      "outcome": "failure",
      "has_recovery": true,
      "contributor": "c_7f21",
      "streams": ["head", "chest"]
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjUwfQ"
}

Endpunkte

GET /v1/datasets — Datensätze, die Ihr Schlüssel sehen darf.
GET /v1/datasets/{id}/versions — veröffentlichte Versionen und ihre Changelog-Einträge.
GET /v1/datasets/{id}/versions/{version}/manifest — das vollständige Manifest.
GET /v1/datasets/{id}/versions/{version}/episodes — Episodenmetadaten, paginiert.
GET /v1/episodes/{episode_id}/annotations — Teilaufgaben-Abschnitte einer Episode.
POST /v1/downloads — signierte Datei-URLs, 15 Minuten gültig.

Paginierung und Fehler

Listen-Endpunkte sind cursor-paginiert: Geben Sie next_cursor als ?cursor= zurück, bis der Wert null ist. Fehler sind JSON mit einem stabilen code-Feld, und 429-Antworten enthalten Retry-After.

Fehlerantwort

{
  "error": {
    "code": "version_not_licensed",
    "message": "Key is not licensed for version 2.0.0 of electrical-assembly.",
    "request_id": "req_01HB9Z2Q"
  }
}

Jede Auslieferung wird protokolliert

Download-Anfragen werden mit Empfänger, Datensatzversion, Umfang und Zeitpunkt in das Weitergabeprotokoll geschrieben. Dieses Protokoll macht eine Rechteprüfung im Nachhinein überhaupt beantwortbar.