API reference

Base URL and authentication

All requests go to https://api.curatrix.de/v1 over TLS and carry a bearer token. Requests without a valid key return 401. Requests for a dataset outside your licence scope return 404 rather than 403, so key scope is not enumerable.

List episodes

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

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

Endpoints

• GET /v1/datasets — datasets your key can see.
• GET /v1/datasets/{id}/versions — released versions and their changelog entries.
• GET /v1/datasets/{id}/versions/{version}/manifest — the full manifest.
• GET /v1/datasets/{id}/versions/{version}/episodes — episode metadata, paginated.
• GET /v1/episodes/{episode_id}/annotations — subtask spans for one episode.
• POST /v1/downloads — signed file URLs, valid for 15 minutes.

Pagination and errors

List endpoints are cursor-paginated: pass next_cursor back as ?cursor= until it is null. Errors are JSON with a stable code field, and 429 responses carry Retry-After.

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

Every delivery is logged

Download requests are written to the disclosure log with recipient, dataset version, scope and time. That log is what makes a rights review answerable after the fact.