openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "pareto",
    "description": "Semantic search and debugging over LeRobot robot-episode datasets: register and index datasets, search episodes by natural language with frame-level evidence, inspect and annotate episodes, run episode-level analytics, export selections as new LeRobot datasets, and follow every operation live on the global event stream.",
    "license": {
      "name": "Apache-2.0",
      "identifier": "Apache-2.0"
    },
    "version": "0.0.0"
  },
  "paths": {
    "/api/access": {
      "get": {
        "tags": [
          "access"
        ],
        "summary": "Effective capabilities of the request's principal.",
        "operationId": "get_access",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "Optional bearer credential",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "X-Pareto-Organization-Id",
            "in": "header",
            "description": "Optional organization selector for the legacy CLI operator",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Effective request capabilities",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccessResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid supplied credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/analytics/consistency": {
      "get": {
        "tags": [
          "analytics"
        ],
        "summary": "Rate how consistent a dataset's episodes are (visual pooled-embedding spread\nplus per-episode action-metric spread) and surface the least-consistent\nepisodes with preview evidence.",
        "description": "The trajectory axis reads each episode's per-frame `action` (or\n`observation.state`) vectors from the dataset's data parquet; a dataset with\nneither feature reports `trajectory_available = false` and leans on the\nvisual axis alone.",
        "operationId": "dataset_consistency_route",
        "parameters": [
          {
            "name": "dataset",
            "in": "query",
            "description": "Dataset id from the catalog.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "outlier_limit",
            "in": "query",
            "description": "Least-consistent episodes returned, 1..=200 (default 20).",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0
            }
          },
          {
            "name": "iqr_k",
            "in": "query",
            "description": "IQR multiplier for the trajectory-metric fences (default 1.5); must be a\nfinite positive value.",
            "required": false,
            "schema": {
              "type": [
                "number",
                "null"
              ],
              "format": "float"
            }
          },
          {
            "name": "task_exact",
            "in": "query",
            "description": "Recompute consistency within episodes carrying this exact task.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Consistency report with ranked least-consistent episodes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsistencyReportDto"
                }
              }
            }
          },
          "400": {
            "description": "outlier_limit out of range, or a non-positive iqr_k",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset not indexed yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/analytics/contact-sheet": {
      "get": {
        "tags": [
          "analytics"
        ],
        "summary": "The endpoint contact sheet: every indexed episode's paired FIRST and LAST\nsampled frame, per camera, ranked by how unusual the episode's start/end\nframe looks for the dataset.",
        "description": "Frame ids come from a cheap frames-table scan (no vectors), so this is an\nindex-only read that works on a stateless pod. The endpoint-deviation rank\nreuses the precomputed `endpoint_deviations` from the consistency report\nsidecar (recomputed here only when that sidecar is absent or stale).",
        "operationId": "endpoint_contact_sheet_route",
        "parameters": [
          {
            "name": "dataset",
            "in": "query",
            "description": "Dataset id from the catalog.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "task_exact",
            "in": "query",
            "description": "Recompute endpoint deviations within episodes carrying this exact task.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Endpoint contact sheet ranked by endpoint deviation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactSheetResponse"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset not indexed yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/analytics/coverage": {
      "post": {
        "tags": [
          "analytics"
        ],
        "summary": "Measure how well natural-language probes are covered by the dataset.",
        "description": "POST because of the probe list. This endpoint EMBEDS every probe with the\nserver's embedding provider, so it costs provider calls (1 to 64 probes\nper call). An episode counts as covered when its best frame score reaches\n`relative_threshold * best episode score for that probe` (default 0.6);\nthe threshold is relative because absolute cosine magnitudes do not\ntransfer across models or probe phrasings.",
        "operationId": "probe_coverage_route",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CoverageRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "One coverage report per probe, in request order",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CoverageResponse"
                }
              }
            }
          },
          "400": {
            "description": "Empty/blank/too-many probes, or relative_threshold outside (0, 1]",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset not indexed, or provider model differs from the index (model_mismatch)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "502": {
            "description": "Embedding provider failure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/analytics/dupes": {
      "get": {
        "tags": [
          "analytics"
        ],
        "summary": "Find groups of near-duplicate episodes (transitive pairwise similarity).",
        "operationId": "duplicate_episodes_route",
        "parameters": [
          {
            "name": "dataset",
            "in": "query",
            "description": "Dataset id from the catalog.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "threshold",
            "in": "query",
            "description": "Pairwise cosine threshold in `(0, 1]` (default 0.97).",
            "required": false,
            "schema": {
              "type": [
                "number",
                "null"
              ],
              "format": "float"
            }
          },
          {
            "name": "task_exact",
            "in": "query",
            "description": "Restrict the pairwise scan to episodes carrying this exact task.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Duplicate groups, largest first",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DuplicateGroupsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Threshold outside (0, 1]",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset not indexed yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "413": {
            "description": "Too many episodes for the O(n^2) pairwise scan",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/analytics/similar": {
      "get": {
        "tags": [
          "analytics"
        ],
        "summary": "Find the episodes most similar to one episode (pooled-vector cosine).",
        "description": "Searching the episode's own dataset excludes the episode itself; with\n`against`, all target-dataset episodes are eligible.",
        "operationId": "similar_episodes_route",
        "parameters": [
          {
            "name": "dataset",
            "in": "query",
            "description": "Dataset id from the catalog.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "episode_index",
            "in": "query",
            "description": "The query episode.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            }
          },
          {
            "name": "camera",
            "in": "query",
            "description": "Compare within one camera's pooled vectors (original `LeRobot` key);\nomitted compares the all-cameras pooled vectors.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "against",
            "in": "query",
            "description": "Search another dataset's episodes instead of `dataset`'s own (must be\nbuilt with the same embedding model).",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum neighbors returned, 1..=200 (default 10).",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0
            }
          },
          {
            "name": "task_exact",
            "in": "query",
            "description": "Restrict eligible neighbors to episodes carrying this exact task.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Neighbors sorted by descending score",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimilarEpisodesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid limit or unknown camera for the episode",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id or episode index",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset not indexed, or embedding models differ (model_mismatch)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/annotations": {
      "get": {
        "tags": [
          "annotations"
        ],
        "summary": "List live annotations of a dataset, optionally filtered by episode and/or\nkey prefix.",
        "operationId": "list_annotations",
        "parameters": [
          {
            "name": "dataset",
            "in": "query",
            "description": "Dataset id from the catalog.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "episode_index",
            "in": "query",
            "description": "Restrict to one episode.",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int32",
              "minimum": 0
            }
          },
          {
            "name": "key_prefix",
            "in": "query",
            "description": "Plain string prefix filter on the key, e.g. `quality/` selects one\nnamespace.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Live annotations in chronological order",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnnotationsResponse"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset has no index directory yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "annotations"
        ],
        "summary": "Add one annotation to an episode.",
        "description": "The actor is taken from the `X-Pareto-Actor` header (default `api`).\nValues must be scalar JSON (string, number, or bool). Emits an\n`annotation_added` event. Mutating: in gated mode this requires the admin\nbearer token.",
        "operationId": "create_annotation",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for curation in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "X-Pareto-Actor",
            "in": "header",
            "description": "Acting agent/user recorded on the annotation and its event (default \"api\")",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAnnotationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Annotation added",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnnotationDto"
                }
              }
            }
          },
          "400": {
            "description": "Malformed key (must be namespace/key) or non-scalar value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset has no index directory yet (the store lives in the index directory; a rebuild in progress is fine)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/annotations/{dataset_id}/{annotation_id}": {
      "delete": {
        "tags": [
          "annotations"
        ],
        "summary": "Remove one annotation by id.",
        "description": "Removing an unknown (or already removed) id is a SUCCESS with\n`removed: false` — an outcome to branch on, not an error. Emits an\n`annotation_removed` event only when something was actually removed.\nMutating: in gated mode this requires the admin bearer token.",
        "operationId": "remove_annotation",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "description": "Dataset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "annotation_id",
            "in": "path",
            "description": "Annotation id from POST/GET /api/annotations",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for curation in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "X-Pareto-Actor",
            "in": "header",
            "description": "Acting agent/user recorded on the removal event (default \"api\")",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removal outcome (removed: false when the id was not found)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RemoveAnnotationResponse"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset has no index directory yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/backfills": {
      "post": {
        "tags": [
          "backfills"
        ],
        "summary": "Queue one backfill against the dataset's currently active complete index.",
        "description": "The request names one artifact. The server resolves request-level defaults\nand snapshots the active build before returning. Execution-host settings\nsuch as the RRD exporter command remain owned by the worker.",
        "operationId": "create_backfill",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for dataset management in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "X-Pareto-Actor",
            "in": "header",
            "description": "Acting agent/user recorded on the durable job (default \"api\")",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBackfillRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Backfill job queued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateBackfillResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid artifact settings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset has no complete active index, or a live backfill already covers overlapping episodes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/datasets": {
      "get": {
        "tags": [
          "datasets"
        ],
        "summary": "List registered datasets with their index status.",
        "operationId": "list_datasets",
        "parameters": [
          {
            "name": "tag",
            "in": "query",
            "description": "Restrict the listing to datasets carrying this exact normalized tag.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "All registered datasets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetsResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "datasets"
        ],
        "summary": "Register a dataset and start indexing it in the background.",
        "description": "Re-registering the same dataset path reuses its id; re-indexing an\nalready-indexed dataset requires `overwrite=true`. Progress can be\nobserved via `GET /api/datasets/{id}/progress`. Mutating: in gated mode\nthis requires the admin bearer token.",
        "operationId": "register_dataset",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for dataset management in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "X-Pareto-Actor",
            "in": "header",
            "description": "Acting agent/user recorded on the registration/indexing events (default \"api\")",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterDatasetRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Dataset registered; indexing started",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisterDatasetResponse"
                }
              }
            }
          },
          "400": {
            "description": "Not a readable LeRobot v3 dataset, or invalid options",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Already indexing, or already indexed without overwrite=true",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/datasets/attach": {
      "post": {
        "tags": [
          "datasets"
        ],
        "summary": "Attach an already-built index to the catalog WITHOUT starting a build.",
        "description": "This is the catalog-only foundation: it registers the dataset root (reusing\nits id when the root is already registered) and requires that a complete\nindex ALREADY exists for it — the opposite of [`register_dataset`], which\nstarts an ingest. Use it to adopt an index that was built elsewhere (e.g.\ncopied onto a fresh server's data root) without re-ingesting. Mutating: in\ngated mode this requires the admin bearer token.",
        "operationId": "attach_dataset",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for dataset management in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "X-Pareto-Actor",
            "in": "header",
            "description": "Acting agent/user recorded on the registration event (default \"api\")",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AttachDatasetRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Dataset attached; a complete index already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AttachDatasetResponse"
                }
              }
            }
          },
          "400": {
            "description": "Not a readable LeRobot v3 dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "No built index exists to attach",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/datasets/{id}": {
      "get": {
        "tags": [
          "datasets"
        ],
        "summary": "Dataset detail: summary, live progress or failure, and dataset metadata.",
        "operationId": "get_dataset_detail",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Dataset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetDetail"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "datasets"
        ],
        "summary": "Remove a dataset's catalog registration.",
        "description": "Deregisters the id ONLY: index builds, raw data, and converted artifacts\non storage are untouched, so a dataset with a surviving complete index can\nbe re-adopted later via `POST /api/datasets/attach`. Refused while an\ningest job is queued or running. Mutating: in gated mode this requires the\nadmin bearer token.",
        "operationId": "delete_dataset",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Dataset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for dataset management in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Dataset registration removed"
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "An ingest job is queued or running for this dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/datasets/{id}/progress": {
      "get": {
        "tags": [
          "datasets"
        ],
        "summary": "SSE stream of indexing progress for one dataset.",
        "description": "While indexing runs, the latest progress snapshot is replayed first and\nevery `IndexProgress` event follows verbatim as JSON, with the SSE event\nname set to the progress `type` (`started`, `episode_started`,\n`frames_embedded`, `episode_finished`, `finished`). The stream closes\nafter a terminal `finished` or `failed` event. When the dataset is not\nindexing, a single `status` event is sent and the stream closes.",
        "operationId": "dataset_progress",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Dataset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Server-sent events: `IndexProgress` JSON payloads named by their `type`, a terminal `failed` event on build failure, or one `status` event when not indexing",
            "content": {
              "text/event-stream": {}
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/datasets/{id}/reindex": {
      "post": {
        "tags": [
          "datasets"
        ],
        "summary": "Re-run the ingest/index build for an ALREADY-REGISTERED dataset by id.",
        "description": "The server resolves the source root from the catalog, so re-ingesting does\nnot require repeating the raw path. It reuses the exact build-start\nmachinery of [`register_dataset`]; an omitted `overwrite` defaults to `true`\nbecause rebuilding an indexed dataset is the intent. Progress is observable\nvia `GET /api/datasets/{id}/progress`. Mutating: in gated mode this requires\nthe admin bearer token.",
        "operationId": "reindex_dataset",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Dataset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for dataset management in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "X-Pareto-Actor",
            "in": "header",
            "description": "Acting agent/user recorded on the indexing events (default \"api\")",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReindexDatasetRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Re-index started",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisterDatasetResponse"
                }
              }
            }
          },
          "400": {
            "description": "The registered dataset root is no longer a readable LeRobot v3 dataset, or invalid options",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Already indexing, or already indexed with overwrite=false",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/datasets/{id}/tags": {
      "put": {
        "tags": [
          "datasets"
        ],
        "summary": "Replace a dataset's small curation-tag set. Tags are normalized to\nlowercase, de-duplicated, and sorted by the typed catalog representation.",
        "operationId": "update_dataset_tags",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Dataset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for curation in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDatasetTagsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Updated dataset summary",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetSummary"
                }
              }
            }
          },
          "400": {
            "description": "Too many or malformed tags",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/episodes": {
      "get": {
        "tags": [
          "episodes"
        ],
        "summary": "Browse indexed episode metadata without embedding a query. Each dataset is\nordered independently by the selected metadata strategy, then datasets are\nround-robin interleaved before applying a stable global offset/limit page.",
        "operationId": "browse_episodes",
        "parameters": [
          {
            "name": "dataset",
            "in": "query",
            "description": "Single dataset id from the catalog. Omit (or pass `*`) to browse every\nindexed dataset; use `datasets` for an explicit multi-dataset list.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "datasets",
            "in": "query",
            "description": "Comma-separated dataset ids, e.g. `alpha,beta`. Takes precedence over\n`dataset` and is de-duplicated in first-seen order.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of matching episodes to skip (default 0).",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum matching episodes returned (default 60, maximum 1000).",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0
            }
          },
          {
            "name": "task_contains",
            "in": "query",
            "description": "Case-insensitive substring filter over any task on the episode.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "task_exact",
            "in": "query",
            "description": "Exact, case-sensitive match against one complete episode task. Takes\nprecedence over `task_contains`.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "flagged_only",
            "in": "query",
            "description": "Restrict the page to episodes carrying any current curation flag.",
            "required": false,
            "schema": {
              "type": [
                "boolean",
                "null"
              ]
            }
          },
          {
            "name": "ordering",
            "in": "query",
            "description": "Metadata-only ordering strategy. `representativeness` reads the\nper-dataset ordering sidecar; absent or unknown values use\n`round_robin`.",
            "required": false,
            "schema": {
              "oneOf": [
                {
                  "type": "null"
                },
                {
                  "$ref": "#/components/schemas/EpisodeOrdering"
                }
              ]
            }
          },
          {
            "name": "cluster",
            "in": "query",
            "description": "HDBSCAN group: a non-negative cluster id or `noise`. Requires\n`ordering=representativeness`; multi-dataset scopes also require\n`cluster_dataset`.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "cluster_dataset",
            "in": "query",
            "description": "Dataset owning `cluster`. Optional for a single-dataset scope and\nrequired when drilling into a group from a multi-dataset scope.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "skip_unavailable",
            "in": "query",
            "description": "When true, an explicitly selected dataset that is unknown or lacks a\nCOMPLETE index (unindexed, failed, or still a mid-ingest checkpoint)\nis skipped instead of failing the request with 404/409. Exists so the\npublic UI can browse a pinned dataset allowlist without first\nreconciling it against the registry. Default false.",
            "required": false,
            "schema": {
              "type": [
                "boolean",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stable page of indexed episodes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EpisodeBrowseResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed or out-of-range parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown explicitly selected dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "An explicitly selected dataset is not indexed yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/episodes/clusters": {
      "get": {
        "tags": [
          "episodes"
        ],
        "summary": "The dataset scope's HDBSCAN cluster overview as a stable offset page:\ndatasets in ascending dataset-id order, each contributing its dense\nclusters in exploration order followed by its optional noise group.",
        "description": "The unfiltered per-dataset overview is computed once per opened index and\ncached, so repeat visits and scroll pages never rescan episode metadata;\ntask/flag filtered requests recompute their overview per request. `groups`\nis empty (with `total` 0) when any dataset in the scope lacks a complete\nHDBSCAN ordering.",
        "operationId": "list_episode_clusters",
        "parameters": [
          {
            "name": "dataset",
            "in": "query",
            "description": "Single dataset id from the catalog. Omit (or pass `*`) for every\nindexed dataset; use `datasets` for an explicit multi-dataset list.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "datasets",
            "in": "query",
            "description": "Comma-separated dataset ids, e.g. `alpha,beta`. Takes precedence over\n`dataset` and is de-duplicated in first-seen order.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of matching cluster groups to skip (default 0).",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum matching cluster groups returned (default 60, maximum 1000).",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0
            }
          },
          {
            "name": "task_contains",
            "in": "query",
            "description": "Case-insensitive substring filter over any task on an episode; group\nmembership and counts cover only matching episodes.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "task_exact",
            "in": "query",
            "description": "Exact, case-sensitive match against one complete episode task. Takes\nprecedence over `task_contains`.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "flagged_only",
            "in": "query",
            "description": "Restrict group membership to episodes carrying any curation flag.",
            "required": false,
            "schema": {
              "type": [
                "boolean",
                "null"
              ]
            }
          },
          {
            "name": "skip_unavailable",
            "in": "query",
            "description": "When true, an explicitly selected dataset that is unknown or lacks a\nCOMPLETE index (unindexed, failed, or still a mid-ingest checkpoint)\nis skipped instead of failing the request with 404/409. Exists so the\npublic UI can browse a pinned dataset allowlist without first\nreconciling it against the registry. Default false.",
            "required": false,
            "schema": {
              "type": [
                "boolean",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stable page of dataset-qualified HDBSCAN cluster groups",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EpisodeClusterOverviewResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed or out-of-range parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown explicitly selected dataset id (unless skip_unavailable)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "An explicitly selected dataset is not indexed yet (unless skip_unavailable)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/episodes/tasks": {
      "get": {
        "tags": [
          "episodes"
        ],
        "summary": "List exact natural-language tasks and their distinct episode counts using\nthe denormalized episode metadata sidecars only.",
        "operationId": "list_task_facets",
        "parameters": [
          {
            "name": "dataset",
            "in": "query",
            "description": "Single dataset id. Omit (or pass `*`) for every indexed dataset.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "datasets",
            "in": "query",
            "description": "Comma-separated explicit dataset ids. Takes precedence over `dataset`.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Exact task facets for the dataset scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskFacetsResponse"
                }
              }
            }
          },
          "404": {
            "description": "Unknown explicitly selected dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "An explicitly selected dataset is not indexed yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/episodes/{dataset_id}/preview-frames": {
      "get": {
        "tags": [
          "episodes"
        ],
        "summary": "Loads neutral, query-free card frames separately from browse metadata so\nbrowse and episode-detail responses remain compact.",
        "operationId": "get_episode_preview_frames",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "description": "Dataset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "episode_indices",
            "in": "query",
            "description": "Comma-separated episode indices. Duplicates are removed while\npreserving first-seen order; at most 100 distinct episodes are allowed.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Representative preview frames grouped by requested episode",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EpisodePreviewFramesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing, malformed, or oversized episode index list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id or episode index",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset not indexed yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/episodes/{dataset_id}/{episode_index}": {
      "get": {
        "tags": [
          "episodes"
        ],
        "summary": "Episode metadata (tasks, length, cameras with preview URLs) plus, when\n`q` is given, the ranked frame hits for this episode only.",
        "operationId": "get_episode_detail",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "description": "Dataset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "episode_index",
            "in": "path",
            "description": "Episode index within the dataset",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Optional query; when given, ranked frame hits for this episode are\nincluded in the response.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "frames",
            "in": "query",
            "description": "Maximum frame hits returned (default 60).",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Episode detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EpisodeDetailResponse"
                }
              }
            }
          },
          "400": {
            "description": "Empty query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id or episode index",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset not indexed yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "502": {
            "description": "Embedding provider failure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/episodes/{dataset_id}/{episode_index}/consistency": {
      "get": {
        "tags": [
          "episodes"
        ],
        "summary": "Per-episode consistency localization: which metrics are anomalous within this\nepisode and WHERE in time, so the viewer can highlight the flagged sections.",
        "description": "The trajectory anomalies are computed from the episode's own series\n(dataset-free), falling back to the raw dataset when the index has no series\nAND the raw files are hosted here. The `endpoint_flags` are supplied by the\ncaller (the dataset report determines them) and localized to the head/tail of\nthe timeline. Returns `404 series_unavailable` when neither series nor raw\ndata is available.",
        "operationId": "get_episode_consistency",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "description": "Dataset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "episode_index",
            "in": "path",
            "description": "Episode index within the dataset",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            }
          },
          {
            "name": "endpoint_flags",
            "in": "query",
            "description": "Comma-separated dataset-level endpoint flags for THIS episode (a subset\nof `start_pose`, `end_pose`, `visual_start`, `visual_end`), threaded from\nthe consistency tab's deep-link. Endpoint agreement is a CROSS-episode\ndetermination the dataset report makes, so the caller supplies it and the\nlocalizer places the corresponding start/end spans. Omitted for a plain\nviewer open.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Localized consistency detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EpisodeConsistencyDetailDto"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id, or no series/raw data for this episode (series_unavailable)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset not indexed yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/episodes/{dataset_id}/{episode_index}/flag": {
      "put": {
        "tags": [
          "annotations"
        ],
        "summary": "Set or replace one episode's mutually-exclusive curation flag.",
        "operationId": "set_episode_curation_flag",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "description": "Dataset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "episode_index",
            "in": "path",
            "description": "Episode index",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for curation in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "X-Pareto-Actor",
            "in": "header",
            "description": "Actor recorded on the underlying annotation events (default \"api\")",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetEpisodeCurationFlagRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Current episode curation flag",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EpisodeCurationFlagResponse"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset has no index directory yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "annotations"
        ],
        "summary": "Clear any curation flag from one episode. Unknown/already-clear is a\nsuccessful no-op represented by `removed: false`.",
        "operationId": "clear_episode_curation_flag",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "description": "Dataset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "episode_index",
            "in": "path",
            "description": "Episode index",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for curation in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "X-Pareto-Actor",
            "in": "header",
            "description": "Actor recorded on underlying annotation events (default \"api\")",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Clear outcome",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClearEpisodeCurationFlagResponse"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset has no index directory yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/episodes/{dataset_id}/{episode_index}/rerun.rrd": {
      "get": {
        "tags": [
          "episodes"
        ],
        "summary": "Serve the precomputed Rerun recording (`.rrd`) for one episode: every\ncamera's preview video plus the `observation.state` / `action` scalar\ntimeseries on a shared episode timeline, ready to open in the Rerun viewer.\nThe recording is generated after publication; datasets whose backfill has\nnot landed answer 404 `rrd_not_precomputed`.",
        "description": "A read endpoint — always available to principals with `ViewData`.",
        "operationId": "get_episode_rerun_recording",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "description": "Dataset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "episode_index",
            "in": "path",
            "description": "Episode index within the dataset",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rerun recording (.rrd) for the episode",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "format": "int32",
                    "minimum": 0
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id or episode index, or the RRD backfill is not complete (rrd_not_precomputed)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset not indexed yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "500": {
            "description": "Reading the recording sidecar failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/episodes/{dataset_id}/{episode_index}/series": {
      "get": {
        "tags": [
          "episodes"
        ],
        "summary": "The episode's downsampled state/action timeseries for the synced viewer.",
        "description": "Served straight from the index's `series/` sidecar (dataset-free); returns\n`404 series_unavailable` when the index has no series object for this episode\nwhile an incomplete publication has not produced that object yet.",
        "operationId": "get_episode_series",
        "parameters": [
          {
            "name": "dataset_id",
            "in": "path",
            "description": "Dataset id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "episode_index",
            "in": "path",
            "description": "Episode index within the dataset",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Downsampled state/action series",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EpisodeSeriesResponse"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id, or the index has no series for this episode (series_unavailable)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset not indexed yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/events": {
      "get": {
        "tags": [
          "events"
        ],
        "summary": "SSE stream of every server event (see the `EventEnvelope` schema).",
        "description": "Each SSE event is named by the payload's `type` tag (`dataset_registered`,\n`index_progress`, `search_executed`, `annotation_added`,\n`analytics_executed`, ...) and its data is the full `EventEnvelope` JSON.\n`seq` increases strictly in emission order. There is NO replay — subscribe\nBEFORE acting to observe the effects of your own requests. The stream\nnever closes on its own (keep-alive comments are sent while idle);\nsubscribers that lag more than the channel capacity behind skip ahead.",
        "operationId": "global_events_stream",
        "responses": {
          "200": {
            "description": "Server-sent events: one `EventEnvelope` JSON payload per event, the SSE event name equal to the envelope's `type` tag. No replay; the stream stays open until the client disconnects.",
            "content": {
              "text/event-stream": {}
            }
          }
        }
      }
    },
    "/api/exports": {
      "post": {
        "tags": [
          "exports"
        ],
        "summary": "Start exporting a selection of episodes as a new `LeRobot` dataset.",
        "description": "The export runs asynchronously; poll `GET /api/exports/{id}`. Its job record\nis persisted in the server's Postgres control plane. Execution is either\nlocal or delegated to a queued worker according to deployment configuration.\nEmits `export_created` now and `export_finished` / `export_failed` when the\njob terminates. Mutating: in gated mode this requires the admin bearer token.",
        "operationId": "create_export",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for exports in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "X-Pareto-Actor",
            "in": "header",
            "description": "Acting agent/user recorded on the export events (default \"api\")",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateExportRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Export job queued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateExportResponse"
                }
              }
            }
          },
          "400": {
            "description": "Empty selection, odd height, or an existing destination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "501": {
            "description": "This deployment hosts only the index, not the raw dataset files an export needs (raw_dataset_unavailable)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/exports/{id}": {
      "get": {
        "tags": [
          "exports"
        ],
        "summary": "Status of one export job.",
        "operationId": "get_export_status",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Export job id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for exports in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Export job status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportStatusResponse"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown export id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/jobs": {
      "get": {
        "tags": [
          "jobs"
        ],
        "summary": "List job records, newest first, optionally filtered by dataset and status.",
        "operationId": "list_jobs",
        "parameters": [
          {
            "name": "dataset",
            "in": "query",
            "description": "Only jobs for this dataset id.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Only jobs in this state: `queued`, `running`, `succeeded`, `failed`,\nor `cancelled`.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "kind",
            "in": "query",
            "description": "Only jobs of this kind: `acquisition`, `conversion`, `ingest`,\n`export`, or `backfill`.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for job management in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching job records, newest first",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Unknown status filter value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/jobs/acquisitions": {
      "post": {
        "tags": [
          "jobs"
        ],
        "summary": "Queue exact-file source acquisition into durable object storage.",
        "operationId": "create_acquisition_job",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for job management in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "X-Pareto-Actor",
            "in": "header",
            "description": "Acting agent/user recorded on the durable job (default \"api\")",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAcquisitionJobRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Acquisition job queued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateJobResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid acquisition specification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset already has a live acquisition",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/jobs/conversions": {
      "post": {
        "tags": [
          "jobs"
        ],
        "summary": "Queue typed conversion of a completed immutable acquisition.",
        "operationId": "create_conversion_job",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for job management in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "X-Pareto-Actor",
            "in": "header",
            "description": "Acting agent/user recorded on the durable job (default \"api\")",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateConversionJobRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Conversion job queued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateJobResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid conversion specification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset already has a live conversion",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/jobs/{id}": {
      "get": {
        "tags": [
          "jobs"
        ],
        "summary": "One job record by id.",
        "operationId": "get_job",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Job id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for job management in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The job record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobRecordDto"
                }
              }
            }
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown job id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/jobs/{id}/cancel": {
      "post": {
        "tags": [
          "jobs"
        ],
        "summary": "Request cancellation of a live job. Terminal jobs are an idempotent no-op.",
        "operationId": "cancel_job",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Job id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Bearer <legacy CLI operator credential>; required for job management in gated mode",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Cancellation requested"
          },
          "401": {
            "description": "Legacy CLI operator credential required or invalid (gated mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown job id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "tags": [
          "search"
        ],
        "summary": "Search indexed datasets; results are episode-ranked with evidence frames,\nthumbnails, and preview clip URLs. Every episode carries the id of the\ndataset it came from, so results spanning several datasets stay\nattributable. Emits a `search_executed` event on success.",
        "operationId": "search_frames",
        "parameters": [
          {
            "name": "dataset",
            "in": "query",
            "description": "Single dataset id from the catalog. Omit (or pass `*`) to search every\ncompatible dataset; use `datasets` for an explicit multi-dataset list.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "datasets",
            "in": "query",
            "description": "Comma-separated dataset ids, e.g. `alpha,beta`. Takes precedence over\n`dataset`; results are ranked across all listed datasets together.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Natural-language query text.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit_episodes",
            "in": "query",
            "description": "Maximum episodes returned (default 20).",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0
            }
          },
          {
            "name": "frames_per_episode",
            "in": "query",
            "description": "Maximum evidence frames per episode (default 5).",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0
            }
          },
          {
            "name": "candidate_frames",
            "in": "query",
            "description": "Nearest frames fetched before episode grouping (default 100).",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0
            }
          },
          {
            "name": "camera",
            "in": "query",
            "description": "Restrict hits to one camera key (original `LeRobot` key).",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "task_contains",
            "in": "query",
            "description": "Case-insensitive substring filter on the episode task.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "task_exact",
            "in": "query",
            "description": "Exact, case-sensitive match against one complete episode task. Takes\nprecedence over `task_contains`.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "flagged_only",
            "in": "query",
            "description": "Restrict results to episodes carrying any current curation flag.",
            "required": false,
            "schema": {
              "type": [
                "boolean",
                "null"
              ]
            }
          },
          {
            "name": "episodes",
            "in": "query",
            "description": "Comma-separated episode allowlist, e.g. `1,2,3`.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "min_score",
            "in": "query",
            "description": "Drop episodes whose match score is below this cosine threshold (e.g.\n`0.1`). Omit to return the top episodes regardless of absolute score.",
            "required": false,
            "schema": {
              "type": [
                "number",
                "null"
              ],
              "format": "float"
            }
          },
          {
            "name": "X-Pareto-Actor",
            "in": "header",
            "description": "Acting agent/user recorded on the search_executed event (default \"api\")",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Episode-ranked results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Empty query or malformed parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset not indexed yet, or embedding model mismatch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "502": {
            "description": "Embedding provider failure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/search/datasets": {
      "get": {
        "tags": [
          "search"
        ],
        "summary": "Rank indexed datasets by how well their best episodes match the query, so a\nuser with many datasets can find the relevant ones before drilling into one\ndataset's episodes. Each returned dataset carries a handful of evidence\nepisodes (with thumbnail / preview URLs). The dataset\nscore is a presence blend of its best episode scores, NOT a centroid\naverage. Emits a `dataset_search_executed` event on success.",
        "operationId": "search_datasets",
        "parameters": [
          {
            "name": "dataset",
            "in": "query",
            "description": "Single dataset id from the catalog. Omit (or pass `*`) to rank every\ncompatible dataset; use `datasets` for an explicit multi-dataset list.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "datasets",
            "in": "query",
            "description": "Comma-separated dataset ids, e.g. `alpha,beta`. Takes precedence over\n`dataset`; only the listed datasets are ranked.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Natural-language query text.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit_datasets",
            "in": "query",
            "description": "Maximum datasets returned (default 20).",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0
            }
          },
          {
            "name": "episodes_per_dataset",
            "in": "query",
            "description": "Evidence episodes kept per returned dataset (default 3).",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0
            }
          },
          {
            "name": "frames_per_episode",
            "in": "query",
            "description": "Maximum evidence frames per evidence episode (default 3).",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0
            }
          },
          {
            "name": "candidate_frames",
            "in": "query",
            "description": "Nearest frames fetched per dataset before episode grouping (default 100).",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0
            }
          },
          {
            "name": "camera",
            "in": "query",
            "description": "Restrict hits to one camera key (original `LeRobot` key).",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "task_contains",
            "in": "query",
            "description": "Case-insensitive substring filter on the episode task.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "task_exact",
            "in": "query",
            "description": "Exact, case-sensitive match against one complete episode task. Takes\nprecedence over `task_contains`.",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "min_score",
            "in": "query",
            "description": "Drop datasets whose match score is below this cosine threshold (e.g.\n`0.1`). Omit to return the top datasets regardless of absolute score.",
            "required": false,
            "schema": {
              "type": [
                "number",
                "null"
              ],
              "format": "float"
            }
          },
          {
            "name": "X-Pareto-Actor",
            "in": "header",
            "description": "Acting agent/user recorded on the dataset_search_executed event (default \"api\")",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset-ranked results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetSearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Empty query or malformed parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Dataset not indexed yet, or embedding model mismatch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          },
          "502": {
            "description": "Embedding provider failure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorBody"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AccessResponse": {
        "type": "object",
        "description": "Effective access granted to the principal represented by the request.",
        "required": [
          "scope",
          "capabilities",
          "writes_require_admin"
        ],
        "properties": {
          "capabilities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Capability"
            }
          },
          "scope": {
            "$ref": "#/components/schemas/DataScope"
          },
          "writes_require_admin": {
            "type": "boolean",
            "description": "`true` exactly when the server runs in gated mode (an admin token is\nconfigured): privileged endpoints require an authorization bearer token,\nwhile public reads stay open. `false` in open mode."
          }
        }
      },
      "ActionVarianceHeatmapDto": {
        "type": "object",
        "description": "The dataset's action-variance heatmap (mirror of\n`pareto_analytics::ActionVarianceHeatmap`).",
        "required": [
          "timestep_count",
          "groups"
        ],
        "properties": {
          "groups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaskGroupVarianceDto"
            },
            "description": "Per task group, ranked by episode count descending."
          },
          "timestep_count": {
            "type": "integer",
            "description": "Normalized-time columns per group row.",
            "minimum": 0
          }
        }
      },
      "AnalyticsVerb": {
        "type": "string",
        "description": "The analytics operation named by an `analytics_executed` event.",
        "enum": [
          "similar",
          "dupes",
          "coverage",
          "consistency",
          "contact_sheet"
        ]
      },
      "AnnotationDto": {
        "type": "object",
        "description": "One episode annotation (mirror of `pareto_index::Annotation`).\n\nAnnotations live in the index directory but survive index rebuilds, and\nmay reference episodes that are absent from the current index (e.g. after\nre-indexing a subset) — consumers must tolerate unknown episode indices.",
        "required": [
          "id",
          "created_unix_secs",
          "actor",
          "key",
          "value",
          "episode_index"
        ],
        "properties": {
          "actor": {
            "type": "string",
            "description": "Durable principal attribution, or the sanitized telemetry label for an\nanonymous action in open mode."
          },
          "created_unix_secs": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp (seconds) when the annotation was added.",
            "minimum": 0
          },
          "episode_index": {
            "type": "integer",
            "format": "int32",
            "description": "Episode the annotation is attached to.",
            "minimum": 0
          },
          "id": {
            "type": "string",
            "description": "Unique annotation id, the handle for `DELETE /api/annotations/...`."
          },
          "key": {
            "type": "string",
            "description": "Namespaced key of the shape `namespace/key`, both parts\n`[a-z0-9_.-]+`, e.g. `quality/gripper-occluded`."
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional free-form human note."
          },
          "value": {
            "type": "object",
            "description": "Scalar payload: JSON string, number, or bool."
          }
        }
      },
      "AnnotationsResponse": {
        "type": "object",
        "description": "Response of `GET /api/annotations`.",
        "required": [
          "annotations"
        ],
        "properties": {
          "annotations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AnnotationDto"
            },
            "description": "Live annotations in chronological (add) order."
          }
        }
      },
      "ApiErrorBody": {
        "type": "object",
        "description": "Error payload returned by every failing API route.",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Machine-readable error code, e.g. `dataset_not_found`."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message."
          }
        }
      },
      "AttachDatasetRequest": {
        "type": "object",
        "description": "Request body of `POST /api/datasets/attach`: register a dataset that\nALREADY has a built index, adding it to the catalog WITHOUT starting any\ningest/build. This is the catalog-only foundation that\n[`RegisterDatasetRequest`] (register + build) composes on top of.",
        "required": [
          "path"
        ],
        "properties": {
          "path": {
            "type": "string",
            "description": "Location of the `LeRobot` v3 dataset root whose index already exists: a\nlocal filesystem path or an object-store URI (`gs://bucket/prefix`)."
          }
        },
        "additionalProperties": false
      },
      "AttachDatasetResponse": {
        "type": "object",
        "description": "Response of `POST /api/datasets/attach` (201: catalog-only attach, no\nbuild). The dataset already had a complete index, so it reports `indexed`\nimmediately and carries no ingest `job_id`.",
        "required": [
          "id",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/DatasetStatus"
          }
        }
      },
      "BackfillRequest": {
        "oneOf": [
          {
            "type": "object",
            "description": "Encode missing downscaled preview renditions.",
            "required": [
              "artifact"
            ],
            "properties": {
              "artifact": {
                "type": "string",
                "enum": [
                  "previews"
                ]
              },
              "episode_index": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int32",
                "description": "Scope the backfill to ONE episode; omitted (with `episode_range`\nalso omitted) covers the whole dataset. Mutually exclusive with\n`episode_range`.",
                "minimum": 0
              },
              "episode_range": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/EpisodeIndexRange",
                    "description": "Scope the backfill to an INCLUSIVE episode-index range — the\nfan-out grain for large datasets (a bounded number of range jobs,\neach folding its episodes' metadata records into batched Lance\ncommits, instead of one commit-storming job per episode). Indices\nabsent from the index are skipped. Mutually exclusive with\n`episode_index`."
                  }
                ]
              },
              "preview_crf": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int32",
                "description": "h264 CRF; omitted uses the server default.",
                "minimum": 0
              },
              "preview_heights": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "integer",
                  "format": "int32",
                  "minimum": 0
                },
                "description": "Preview heights; omitted uses the server default."
              }
            }
          },
          {
            "type": "object",
            "description": "Generate per-episode Rerun recording sidecars.",
            "required": [
              "artifact"
            ],
            "properties": {
              "artifact": {
                "type": "string",
                "enum": [
                  "rrd"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "Recompute the episode-ordering (clustering) sidecar over the active\nbuild — repair/refresh after a cluster-service fix or tuning change.",
            "required": [
              "artifact"
            ],
            "properties": {
              "artifact": {
                "type": "string",
                "enum": [
                  "episode_ordering"
                ]
              }
            }
          }
        ],
        "description": "Artifact selected for a backfill run.\n\nThe tagged variants keep artifact-specific settings attached only to the\nartifact that understands them. Omitted preview settings use the same\nserver defaults as indexing (`[480, 720, 1080]`, CRF 20)."
      },
      "Capability": {
        "type": "string",
        "description": "Finite wire values returned by `GET /api/access`.",
        "enum": [
          "view_data",
          "curate_data",
          "export_data",
          "manage_datasets",
          "manage_jobs"
        ]
      },
      "ClearEpisodeCurationFlagResponse": {
        "type": "object",
        "description": "Response of clearing an episode curation flag.",
        "required": [
          "removed"
        ],
        "properties": {
          "removed": {
            "type": "boolean",
            "description": "True when at least one reserved annotation object was removed."
          }
        }
      },
      "ConsistencyReportDto": {
        "type": "object",
        "description": "Response of `GET /api/analytics/consistency` (mirror of\n`pareto_analytics::ConsistencyReport` plus the dataset id and per-outlier\npreview evidence). All consistency scores are in `[0, 1]`, higher = more\nconsistent.",
        "required": [
          "dataset",
          "episode_count",
          "visual_consistency",
          "trajectory_consistency",
          "endpoint_consistency",
          "overall_consistency",
          "trajectory_available",
          "endpoint_available",
          "least_consistent"
        ],
        "properties": {
          "dataset": {
            "type": "string"
          },
          "endpoint_available": {
            "type": "boolean",
            "description": "`false` when neither the joint-state nor the visual endpoint channel had\nenough episodes to score start/end agreement."
          },
          "endpoint_consistency": {
            "type": "number",
            "format": "float",
            "description": "`1 - (episodes whose start OR end pose / camera view disagrees with the\ndataset norm / episode_count)`; mirrors `visual_consistency` when the\nendpoint axis is unavailable."
          },
          "episode_count": {
            "type": "integer",
            "description": "Episodes considered (the index's pooled all-cameras rows).",
            "minimum": 0
          },
          "least_consistent": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EpisodeConsistencyDto"
            },
            "description": "Ranked most-inconsistent first, up to `outlier_limit` episodes."
          },
          "overall_consistency": {
            "type": "number",
            "format": "float",
            "description": "Mean of the two available axes; equals `visual_consistency` when\ntrajectory data is unavailable. The endpoint axis is reported on its own\n(`endpoint_consistency`), not folded in here."
          },
          "trajectory_available": {
            "type": "boolean",
            "description": "`false` when the dataset declares neither an `action` nor an\n`observation.state` feature."
          },
          "trajectory_consistency": {
            "type": "number",
            "format": "float",
            "description": "`1 - (episodes flagged on any trajectory metric / episode_count)`;\nmirrors `visual_consistency` when trajectory data is unavailable."
          },
          "variance_heatmap": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ActionVarianceHeatmapDto",
                "description": "Per-task-group action variance over normalized time (WHERE demonstrations\ndiverge). `None` when the report was computed without the raw dataset or\nthe dataset declares no action / state feature."
              }
            ]
          },
          "visual_consistency": {
            "type": "number",
            "format": "float",
            "description": "Mean cosine of each episode's pooled vector to the dataset centroid,\nclamped to `[0, 1]`."
          }
        }
      },
      "ConsistencySegmentDto": {
        "type": "object",
        "description": "One localized anomaly span within an episode (mirror of\n`pareto_analytics::ConsistencySegment`).",
        "required": [
          "metric",
          "start_sec",
          "end_sec",
          "detail"
        ],
        "properties": {
          "detail": {
            "type": "string",
            "description": "Short human-readable description of the anomaly."
          },
          "end_sec": {
            "type": "number",
            "format": "float",
            "description": "Episode-relative end of the span (seconds)."
          },
          "metric": {
            "type": "string",
            "description": "The metric this span localizes (`duration`, `jerk`, `peak_velocity`,\n`motionless_fraction`, `final_pose`, or an endpoint signal —\n`start_pose`, `end_pose`, `visual_start`, `visual_end`)."
          },
          "start_sec": {
            "type": "number",
            "format": "float",
            "description": "Episode-relative start of the span (seconds)."
          }
        }
      },
      "ContactSheetCameraDto": {
        "type": "object",
        "description": "One (episode, camera)'s endpoint thumbnails in the contact sheet.",
        "required": [
          "camera",
          "first_thumb_url",
          "last_thumb_url"
        ],
        "properties": {
          "camera": {
            "type": "string",
            "description": "The `LeRobot` video key (e.g. `observation.images.up`)."
          },
          "first_thumb_url": {
            "type": "string",
            "description": "Absolute URL of the episode's FIRST-frame thumbnail for this camera."
          },
          "last_thumb_url": {
            "type": "string",
            "description": "Absolute URL of the episode's LAST-frame thumbnail for this camera."
          }
        }
      },
      "ContactSheetEpisodeDto": {
        "type": "object",
        "description": "One episode's paired endpoint thumbnails plus its endpoint-deviation rank\nkey (mirror of `pareto_analytics::EpisodeEndpointFrames` plus asset URLs).",
        "required": [
          "episode_index",
          "endpoint_deviation",
          "visual_start_deviation",
          "visual_end_deviation",
          "cameras"
        ],
        "properties": {
          "cameras": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactSheetCameraDto"
            },
            "description": "Endpoint thumbnails per camera, sorted by camera key."
          },
          "endpoint_deviation": {
            "type": "number",
            "format": "float",
            "description": "The rank key: the larger of the start / end visual deviations (higher =\nmore unusual endpoint). `0` when no precomputed deviation exists."
          },
          "episode_index": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "visual_end_deviation": {
            "type": "number",
            "format": "float",
            "description": "`1 - cosine(last frame, dataset centroid-of-lasts)`."
          },
          "visual_start_deviation": {
            "type": "number",
            "format": "float",
            "description": "`1 - cosine(first frame, dataset centroid-of-firsts)`."
          }
        }
      },
      "ContactSheetResponse": {
        "type": "object",
        "description": "Response of `GET /api/analytics/contact-sheet`: every indexed episode's\nfirst/last frame per camera, ranked most-unusual-endpoint first.",
        "required": [
          "dataset",
          "asset_version",
          "cameras",
          "episodes"
        ],
        "properties": {
          "asset_version": {
            "type": "integer",
            "format": "int64",
            "description": "The cache-buster stamped onto every thumbnail URL (the index build\ntimestamp).",
            "minimum": 0
          },
          "cameras": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The union of cameras across the dataset's episodes, sorted, for the UI's\ncamera selector."
          },
          "dataset": {
            "type": "string"
          },
          "episodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactSheetEpisodeDto"
            },
            "description": "Episodes ranked by `endpoint_deviation` descending."
          }
        }
      },
      "CoverageRequest": {
        "type": "object",
        "description": "Request body of `POST /api/analytics/coverage`.",
        "required": [
          "dataset",
          "probes"
        ],
        "properties": {
          "dataset": {
            "type": "string",
            "description": "Dataset id from the catalog."
          },
          "probes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "1 to 64 natural-language probe texts."
          },
          "relative_threshold": {
            "type": [
              "number",
              "null"
            ],
            "format": "float",
            "description": "Coverage threshold RELATIVE to the best episode score per probe, in\n`(0, 1]` (default 0.6)."
          }
        },
        "additionalProperties": false
      },
      "CoverageResponse": {
        "type": "object",
        "description": "Response of `POST /api/analytics/coverage`.",
        "required": [
          "dataset",
          "relative_threshold",
          "probes"
        ],
        "properties": {
          "dataset": {
            "type": "string"
          },
          "probes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProbeCoverageDto"
            },
            "description": "One report per probe, in request order."
          },
          "relative_threshold": {
            "type": "number",
            "format": "float",
            "description": "The relative threshold that was applied."
          }
        }
      },
      "CreateAcquisitionJobRequest": {
        "type": "object",
        "description": "Request body of `POST /api/jobs/acquisitions`.",
        "required": [
          "dataset",
          "acquisition_id",
          "repo_id",
          "repo_type",
          "revision",
          "files",
          "destination"
        ],
        "properties": {
          "acquisition_id": {
            "type": "string",
            "description": "Stable acquisition checkpoint and manifest id."
          },
          "batch_size": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Exact files reconstructed per resumable batch; omitted defaults to 128.",
            "minimum": 0
          },
          "dataset": {
            "type": "string",
            "description": "Stable target dataset id used to group all pipeline stages."
          },
          "destination": {
            "type": "string",
            "description": "Durable GCS storage root for raw objects and the manifest."
          },
          "files": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Exact repository-relative source files; globs are unsupported."
          },
          "max_download_workers": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Concurrent downloads inside the official Hugging Face CLI.",
            "minimum": 0
          },
          "max_upload_workers": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Concurrent durable-storage uploads after each batch.",
            "minimum": 0
          },
          "repo_id": {
            "type": "string"
          },
          "repo_type": {
            "$ref": "#/components/schemas/HuggingFaceRepoTypeDto"
          },
          "revision": {
            "type": "string",
            "description": "Branch, tag, or immutable commit. Task plans normally provide a commit."
          },
          "xet_high_performance": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Enable hf-xet high-performance mode on the acquisition worker."
          }
        },
        "additionalProperties": false
      },
      "CreateAnnotationRequest": {
        "type": "object",
        "description": "Request body of `POST /api/annotations`.",
        "required": [
          "dataset",
          "episode_index",
          "key",
          "value"
        ],
        "properties": {
          "dataset": {
            "type": "string",
            "description": "Dataset id from the catalog."
          },
          "episode_index": {
            "type": "integer",
            "format": "int32",
            "description": "Episode the annotation is attached to.",
            "minimum": 0
          },
          "key": {
            "type": "string",
            "description": "Namespaced key of the shape `namespace/key` (`[a-z0-9_.-]+` parts)."
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional free-form human note."
          },
          "value": {
            "type": "object",
            "description": "Scalar payload: JSON string, number, or bool (arrays, objects, and\nnull are rejected with 400)."
          }
        },
        "additionalProperties": false
      },
      "CreateBackfillRequest": {
        "type": "object",
        "description": "Request body of `POST /api/backfills`.",
        "required": [
          "dataset",
          "operation"
        ],
        "properties": {
          "dataset": {
            "type": "string",
            "description": "Dataset id from the catalog."
          },
          "operation": {
            "$ref": "#/components/schemas/BackfillRequest",
            "description": "Artifact to materialize in the dataset's active index build."
          },
          "run_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional operator-chosen label that changes the durable job's identity\nand nothing else. Backfill job ids are deterministic over the resolved\nspec and a SUCCEEDED id is never re-executed, so re-running an\noperation whose identical spec already succeeded on the same build\n(e.g. previews after a transcode-pipeline fix) needs a fresh label to\nobtain a fresh id."
          }
        },
        "additionalProperties": false
      },
      "CreateBackfillResponse": {
        "type": "object",
        "description": "Response of `POST /api/backfills`.",
        "required": [
          "job_id"
        ],
        "properties": {
          "job_id": {
            "type": "string",
            "description": "Durable job id; inspect it through `GET /api/jobs/{id}`."
          }
        }
      },
      "CreateConversionJobRequest": {
        "type": "object",
        "description": "Request body of `POST /api/jobs/conversions`.",
        "required": [
          "dataset",
          "acquisition_id",
          "acquisition_source",
          "dataset_destination",
          "converter"
        ],
        "properties": {
          "acquisition_id": {
            "type": "string",
            "description": "Completed acquisition manifest to materialize."
          },
          "acquisition_source": {
            "type": "string",
            "description": "Durable storage root containing the acquisition."
          },
          "converter": {
            "$ref": "#/components/schemas/DatasetConverterRequest"
          },
          "dataset": {
            "type": "string",
            "description": "Stable target dataset id used to group all pipeline stages."
          },
          "dataset_destination": {
            "type": "string",
            "description": "Empty durable root where the converted `LeRobot` dataset is published."
          },
          "max_skipped_episodes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Accept up to this many SKIPPED episodes at finalize (unsupported\ncamera stations, unconformable timing) instead of the default\n1%/floor-8 budget that treats mass skipping as a systemic converter\nproblem. Does not change the conversion's content identity: a\nresubmission with a budget adopts every episode the default-budget\nrun already sealed.",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "CreateExportRequest": {
        "type": "object",
        "description": "Request body of `POST /api/exports`.",
        "required": [
          "dataset",
          "episode_indices",
          "dest_path"
        ],
        "properties": {
          "dataset": {
            "type": "string",
            "description": "Dataset id from the catalog."
          },
          "dest_path": {
            "type": "string",
            "description": "Destination directory; must not exist or must be empty."
          },
          "episode_indices": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            },
            "description": "Episodes to export, re-indexed `0..n` in this order."
          },
          "height": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Output video height in pixels; must be even (default 480).",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "CreateExportResponse": {
        "type": "object",
        "description": "Response of `POST /api/exports` (202: export job queued).",
        "required": [
          "export_id"
        ],
        "properties": {
          "export_id": {
            "type": "string",
            "description": "Id for polling `GET /api/exports/{id}` and inspecting its job record."
          }
        }
      },
      "CreateJobResponse": {
        "type": "object",
        "description": "Response of a first-class job submission endpoint.",
        "required": [
          "job_id"
        ],
        "properties": {
          "job_id": {
            "type": "string"
          }
        }
      },
      "DataScope": {
        "oneOf": [
          {
            "type": "object",
            "description": "Historical public-beta data. This remains the deserialization default\nfor durable records written before tenancy existed.",
            "required": [
              "kind"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "public"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "Data owned by one verified organization.",
            "required": [
              "organization_id",
              "kind"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "organization"
                ]
              },
              "organization_id": {
                "$ref": "#/components/schemas/OrganizationId"
              }
            }
          }
        ],
        "description": "The tenant boundary applied to every dataset, job, event, and storage key."
      },
      "DatasetConverterRequest": {
        "oneOf": [
          {
            "type": "object",
            "description": "External protobuf-MCAP to `LeRobot` v3 using mandatory GPU video media.",
            "required": [
              "converter"
            ],
            "properties": {
              "converter": {
                "type": "string",
                "enum": [
                  "media_converter"
                ]
              },
              "gpu_batch_size": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int32",
                "minimum": 0
              },
              "gpu_constant_quality": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int32",
                "minimum": 0
              },
              "gpu_count": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int32",
                "description": "Omitted selects every GPU exposed by the assigned worker sidecar.",
                "minimum": 0
              },
              "gpu_preset": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "image_height": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int32",
                "minimum": 0
              },
              "image_width": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int32",
                "minimum": 0
              },
              "lerobot_repo_id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Repository id recorded in `LeRobot` metadata."
              },
              "robot_type": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Robot type recorded in `LeRobot` metadata."
              },
              "worker_count": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int32",
                "minimum": 0
              }
            }
          },
          {
            "type": "object",
            "description": "Select and normalize a prepared packed `LeRobot` v3 source without\ndecoding or re-encoding its videos. GENERIC: the request carries the\nsource identity and selection knobs (no dataset-named policies).",
            "required": [
              "repository",
              "revision",
              "converter"
            ],
            "properties": {
              "cameras": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/PreparedCamerasRequest",
                    "description": "Camera views to keep; omitted keeps every RGB camera."
                  }
                ]
              },
              "converter": {
                "type": "string",
                "enum": [
                  "prepared_lerobot_subset"
                ]
              },
              "max_episodes_per_task": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int32",
                "description": "Keep at most N episodes per task family, in source order;\nomitted keeps every selected episode.",
                "minimum": 0
              },
              "max_materialization_files": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int32",
                "description": "Concurrent acquired files reconstructed on the CPU worker.",
                "minimum": 0
              },
              "max_publish_files": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int32",
                "description": "Concurrent normalized files published to durable storage.",
                "minimum": 0
              },
              "primary_camera": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Default display view; omitted uses the source's first RGB camera."
              },
              "repository": {
                "type": "string",
                "description": "Hugging Face repository id of the packed source."
              },
              "revision": {
                "type": "string",
                "description": "Immutable source revision (commit hash) the plan pins."
              },
              "tasks": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                },
                "description": "Keep only episodes of these tasks; omitted keeps every episode.\nMutually exclusive with `max_episodes_per_task`."
              }
            }
          }
        ],
        "description": "Converter selected for one dataset conversion job."
      },
      "DatasetDetail": {
        "type": "object",
        "description": "Response of `GET /api/datasets/{id}`: the summary fields plus live\nindexing progress, failure details, and dataset-metadata extras.",
        "required": [
          "id",
          "status",
          "tags"
        ],
        "properties": {
          "cameras_indexed": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "embedding_model_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "episode_count": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Episode count from the dataset metadata (`None` when the dataset root\ncannot be read).",
            "minimum": 0
          },
          "episode_indices": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            },
            "description": "Real episode indices from the dataset metadata, in dataset order —\npossibly NON-CONTIGUOUS (e.g. an exported subset), so consumers must\nnot assume `0..episode_count` (`None` when the dataset root cannot be\nread)."
          },
          "error": {
            "type": [
              "string",
              "null"
            ],
            "description": "Failure message when `status` is `failed`."
          },
          "id": {
            "type": "string"
          },
          "progress": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/IndexProgressDto",
                "description": "Latest progress event while `status` is `indexing`."
              }
            ]
          },
          "sample_fps": {
            "type": [
              "number",
              "null"
            ],
            "format": "double"
          },
          "status": {
            "$ref": "#/components/schemas/DatasetStatus"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Sorted, de-duplicated curation tags from the dataset catalog."
          },
          "target_total_episodes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Present exactly when the index is PARTIAL (see `DatasetSummary`).",
            "minimum": 0
          },
          "tasks": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Unique natural-language tasks from the dataset metadata (`None` when\nthe dataset root cannot be read)."
          },
          "total_episodes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "minimum": 0
          },
          "total_frames_indexed": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "minimum": 0
          }
        }
      },
      "DatasetEpisodeAveragesDto": {
        "type": "object",
        "description": "Whole-dataset episode averages returned with an episode drill-down.",
        "required": [
          "average_length_frames",
          "average_duration_secs"
        ],
        "properties": {
          "average_duration_secs": {
            "type": "number",
            "format": "double",
            "description": "The same mean episode length expressed in seconds at the dataset FPS."
          },
          "average_length_frames": {
            "type": "number",
            "format": "double",
            "description": "Mean native episode length across every episode in the raw dataset."
          }
        }
      },
      "DatasetHitDto": {
        "type": "object",
        "description": "One dataset ranked by how well its best episodes match the query, with a\nfew of those episodes as evidence.",
        "required": [
          "dataset",
          "score",
          "matching_episode_count",
          "episodes"
        ],
        "properties": {
          "dataset": {
            "type": "string",
            "description": "Id of the ranked dataset."
          },
          "episodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EpisodeHitDto"
            },
            "description": "Top evidence episodes, best first, each with its own asset URLs."
          },
          "matching_episode_count": {
            "type": "integer",
            "description": "Episodes with >= 1 frame hit after filters (before evidence\ntruncation) — how broadly the dataset matched.",
            "minimum": 0
          },
          "score": {
            "type": "number",
            "format": "float",
            "description": "Blended dataset score (`0.7 * max + 0.3 * mean(top 3)` episode scores)."
          }
        }
      },
      "DatasetSearchResponse": {
        "type": "object",
        "description": "Response of `GET /api/search/datasets`.",
        "required": [
          "query",
          "total_dataset_hits",
          "datasets"
        ],
        "properties": {
          "datasets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DatasetHitDto"
            },
            "description": "Ranked datasets, best first."
          },
          "query": {
            "type": "string",
            "description": "The query text as given."
          },
          "total_dataset_hits": {
            "type": "integer",
            "description": "Datasets with any matching episode, before the `min_score` and\n`limit_datasets` steps.",
            "minimum": 0
          }
        }
      },
      "DatasetStatus": {
        "type": "string",
        "description": "Index status of a registered dataset.",
        "enum": [
          "unindexed",
          "indexing",
          "indexed",
          "failed"
        ]
      },
      "DatasetSummary": {
        "type": "object",
        "description": "One dataset in the `GET /api/datasets` listing. The manifest-derived\nfields are present only when `status` is `indexed`.",
        "required": [
          "id",
          "status",
          "tags"
        ],
        "properties": {
          "cameras_indexed": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Original `LeRobot` camera keys that were indexed."
          },
          "embedding_model_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Embedding model the index is married to."
          },
          "id": {
            "type": "string",
            "description": "Catalog id used in every other route."
          },
          "sample_fps": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Frames sampled per second of episode video."
          },
          "status": {
            "$ref": "#/components/schemas/DatasetStatus"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Sorted, de-duplicated curation tags from the dataset catalog."
          },
          "target_total_episodes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Present exactly when the index is PARTIAL: the full selection size the\nrunning build is working toward (`total_episodes` of\n`target_total_episodes` done so far).",
            "minimum": 0
          },
          "total_episodes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Episodes in the index. For a PARTIALLY published index (a\ncheckpoint-publishing build still running) this is the browsable\ncount so far; see `target_total_episodes`.",
            "minimum": 0
          },
          "total_frames_indexed": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Frame rows in the index.",
            "minimum": 0
          }
        }
      },
      "DatasetsResponse": {
        "type": "object",
        "description": "Response of `GET /api/datasets`.",
        "required": [
          "datasets"
        ],
        "properties": {
          "datasets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DatasetSummary"
            }
          }
        }
      },
      "DuplicateGroupDto": {
        "type": "object",
        "description": "One group of near-duplicate episodes (mirror of\n`pareto_analytics::DuplicateGroup`).",
        "required": [
          "episode_indices",
          "mean_pairwise_similarity"
        ],
        "properties": {
          "episode_indices": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            },
            "description": "Members in ascending episode order; always at least two. Groups are\nTRANSITIVE closures of the pairwise threshold."
          },
          "mean_pairwise_similarity": {
            "type": "number",
            "format": "float",
            "description": "Mean cosine over ALL member pairs (including below-threshold pairs\npulled in transitively)."
          }
        }
      },
      "DuplicateGroupsResponse": {
        "type": "object",
        "description": "Response of `GET /api/analytics/dupes`.",
        "required": [
          "dataset",
          "threshold",
          "groups"
        ],
        "properties": {
          "dataset": {
            "type": "string"
          },
          "groups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DuplicateGroupDto"
            },
            "description": "Groups sorted by size descending (ties by smallest member episode)."
          },
          "threshold": {
            "type": "number",
            "format": "float",
            "description": "The similarity threshold that was applied."
          }
        }
      },
      "EpisodeBrowseItemDto": {
        "type": "object",
        "description": "One indexed episode returned by the dataset-scope browse endpoint.",
        "required": [
          "dataset_id",
          "episode_index",
          "tasks",
          "length_frames",
          "duration_secs",
          "cameras",
          "preview_urls"
        ],
        "properties": {
          "cameras": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Original `LeRobot` camera keys indexed for this episode."
          },
          "curation_flag": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EpisodeCurationFlagDto",
                "description": "Current typed curation flag; `None` means unflagged."
              }
            ]
          },
          "dataset_id": {
            "type": "string",
            "description": "Catalog id of the dataset containing this episode. Present on every\nitem so multi/all-scope pages remain attributable."
          },
          "duration_secs": {
            "type": "number",
            "format": "double",
            "description": "Episode duration derived from the index metadata sidecar fps."
          },
          "episode_index": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "length_frames": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "preview_urls": {
            "type": "object",
            "description": "Lowest-rung preview clip URL keyed by original camera name.",
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            }
          },
          "ranking": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EpisodeBrowseRankingDto",
                "description": "Dataset-local position and distance metric when representativeness\nordering was requested and this episode exists in the ordering sidecar."
              }
            ]
          },
          "tasks": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "EpisodeBrowseRankingDto": {
        "oneOf": [
          {
            "type": "object",
            "description": "Episode assigned to an HDBSCAN cluster, ranked by cluster size and\ndistance from that cluster's centroid.",
            "required": [
              "sequence_index",
              "cluster_id",
              "distance_from_cluster_centroid",
              "kind"
            ],
            "properties": {
              "cluster_id": {
                "type": "integer",
                "format": "int32",
                "description": "Non-negative HDBSCAN cluster label.",
                "minimum": 0
              },
              "distance_from_cluster_centroid": {
                "type": "number",
                "format": "float",
                "description": "Cosine distance from the assigned cluster centroid."
              },
              "kind": {
                "type": "string",
                "enum": [
                  "hdbscan_cluster"
                ]
              },
              "sequence_index": {
                "type": "integer",
                "format": "int32",
                "description": "Zero-based position in this dataset's exploration sequence.",
                "minimum": 0
              }
            }
          },
          {
            "type": "object",
            "description": "HDBSCAN noise episode, placed after detected clusters by distance from\nits nearest detected cluster centroid.",
            "required": [
              "sequence_index",
              "distance_from_nearest_cluster_centroid",
              "kind"
            ],
            "properties": {
              "distance_from_nearest_cluster_centroid": {
                "type": "number",
                "format": "float",
                "description": "Cosine distance from the nearest detected cluster centroid."
              },
              "kind": {
                "type": "string",
                "enum": [
                  "hdbscan_noise"
                ]
              },
              "sequence_index": {
                "type": "integer",
                "format": "int32",
                "description": "Zero-based position in this dataset's exploration sequence.",
                "minimum": 0
              }
            }
          }
        ],
        "description": "Dataset-local sequence position and the metric that produced it."
      },
      "EpisodeBrowseResponse": {
        "type": "object",
        "description": "Stable offset page returned by `GET /api/episodes`. The scope's HDBSCAN\ncluster overview is served separately by `GET /api/episodes/clusters`.\n\nCOORDINATE: the former `cluster_groups` field was removed in the release\nthat added `/api/episodes/clusters`, so either deploy order degrades to the\nflat episode grid across the serve/UI window instead of erroring — the old\nUI treats the missing field as \"no overview\", and the new UI treats the old\nrouter's bodyless 404 for the overview endpoint the same way\n(`EpisodeBrowseGrid`'s overview-failure fallback).",
        "required": [
          "total",
          "offset",
          "limit",
          "episodes"
        ],
        "properties": {
          "episodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EpisodeBrowseItemDto"
            },
            "description": "Episodes round-robin interleaved across datasets."
          },
          "limit": {
            "type": "integer",
            "minimum": 0
          },
          "offset": {
            "type": "integer",
            "minimum": 0
          },
          "total": {
            "type": "integer",
            "description": "Number of episodes matching the scope, optional task filter, and\noptional cluster filter before pagination.",
            "minimum": 0
          }
        }
      },
      "EpisodeCamera": {
        "type": "object",
        "description": "One camera of an episode with its preview-clip renditions.",
        "required": [
          "camera",
          "renditions"
        ],
        "properties": {
          "camera": {
            "type": "string",
            "description": "Original `LeRobot` camera key."
          },
          "renditions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PreviewRenditionDto"
            },
            "description": "Available preview renditions, ASCENDING by height. A rung may appear\nmore than once in different codecs; the client keeps the one its\nbrowser decodes and then picks a rung (\"Auto\" by connection estimate,\nor a manual override)."
          }
        }
      },
      "EpisodeClusterGroupDto": {
        "oneOf": [
          {
            "type": "object",
            "description": "Episodes assigned to one detected dense cluster.",
            "required": [
              "dataset_id",
              "cluster_id",
              "episode_count",
              "representative_episode_index",
              "kind"
            ],
            "properties": {
              "cluster_id": {
                "type": "integer",
                "format": "int32",
                "description": "Non-negative HDBSCAN cluster label.",
                "minimum": 0
              },
              "dataset_id": {
                "type": "string",
                "description": "Dataset whose local HDBSCAN ordering produced this group."
              },
              "episode_count": {
                "type": "integer",
                "description": "Matching episodes assigned to this cluster.",
                "minimum": 0
              },
              "kind": {
                "type": "string",
                "enum": [
                  "cluster"
                ]
              },
              "representative_episode_index": {
                "type": "integer",
                "format": "int32",
                "description": "Matching episode nearest the cluster centroid.",
                "minimum": 0
              },
              "task": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The task shared by every episode in this cluster (clustering is\ntask-scoped, so a cluster never spans tasks). Absent when episode\nmetadata carries no task labels."
              }
            }
          },
          {
            "type": "object",
            "description": "Episodes HDBSCAN classified as noise rather than a dense cluster.",
            "required": [
              "dataset_id",
              "episode_count",
              "representative_episode_index",
              "kind"
            ],
            "properties": {
              "dataset_id": {
                "type": "string",
                "description": "Dataset whose local HDBSCAN ordering produced this group."
              },
              "episode_count": {
                "type": "integer",
                "description": "Matching noise episodes.",
                "minimum": 0
              },
              "kind": {
                "type": "string",
                "enum": [
                  "noise"
                ]
              },
              "representative_episode_index": {
                "type": "integer",
                "format": "int32",
                "description": "Matching noise episode nearest any detected cluster centroid.",
                "minimum": 0
              }
            }
          }
        ],
        "description": "One dataset-qualified HDBSCAN browse group. Within each dataset, dense\nclusters are followed by the optional noise group in exploration order."
      },
      "EpisodeClusterOverviewResponse": {
        "type": "object",
        "description": "Stable offset page returned by `GET /api/episodes/clusters`: the dataset\nscope's HDBSCAN cluster overview.",
        "required": [
          "total",
          "offset",
          "limit",
          "groups"
        ],
        "properties": {
          "groups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EpisodeClusterGroupDto"
            },
            "description": "The `offset`/`limit` slice of the stable group ordering: datasets in\nascending dataset-id order; within each dataset, dense clusters in\nexploration order followed by the optional noise group."
          },
          "limit": {
            "type": "integer",
            "minimum": 0
          },
          "offset": {
            "type": "integer",
            "minimum": 0
          },
          "total": {
            "type": "integer",
            "description": "Number of cluster groups matching the scope and the optional task/flag\nfilters before pagination. 0 when any dataset in the scope lacks a\ncomplete HDBSCAN ordering — the overview is all-or-nothing across the\nscope, exactly like the browse overview it replaces.",
            "minimum": 0
          }
        }
      },
      "EpisodeConsistencyDetailDto": {
        "type": "object",
        "description": "Response of `GET /api/episodes/{dataset_id}/{episode_index}/consistency` —\nper-episode consistency localization (mirror of\n`pareto_analytics::EpisodeConsistencyDetail`). Computed from the episode's\nown series, so the viewer can highlight WHERE the flagged sections are.",
        "required": [
          "episode_index",
          "flags",
          "segments",
          "duration_secs"
        ],
        "properties": {
          "duration_secs": {
            "type": "number",
            "format": "float",
            "description": "The episode's total duration in seconds."
          },
          "episode_index": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "flags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The trajectory metrics anomalous within this episode, in first-seen\norder."
          },
          "segments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsistencySegmentDto"
            },
            "description": "Every localized anomaly span."
          }
        }
      },
      "EpisodeConsistencyDto": {
        "type": "object",
        "description": "One least-consistent (outlier) episode with per-camera preview evidence\n(mirror of `pareto_analytics::EpisodeConsistency` plus asset URLs).",
        "required": [
          "episode_index",
          "visual_deviation",
          "trajectory_flags",
          "endpoint_flags",
          "combined_outlier_score",
          "preview_urls"
        ],
        "properties": {
          "combined_outlier_score": {
            "type": "number",
            "format": "float",
            "description": "Blend used for ranking (higher = more inconsistent)."
          },
          "endpoint_flags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Which START/END agreement signals were outliers for this episode (subset\nof `start_pose`, `end_pose`, `visual_start`, `visual_end`) — its first or\nlast joint pose / camera view disagrees with the dataset norm. Empty when\nthe endpoint axis is unavailable or the episode agrees."
          },
          "episode_index": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "preview_urls": {
            "type": "object",
            "description": "Camera key -> absolute preview clip URL, evidence for eyeballing the\noutlier episode.",
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            }
          },
          "trajectory_flags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Which action metrics were IQR outliers for this episode (subset of\n`duration`, `jerk`, `peak_velocity`, `motionless_fraction`,\n`final_pose`); empty when trajectory data is unavailable."
          },
          "visual_deviation": {
            "type": "number",
            "format": "float",
            "description": "`1 - cosine(episode pooled vector, dataset centroid)`; higher = more\nvisually off from the dataset as a whole."
          }
        }
      },
      "EpisodeCurationFlagDto": {
        "type": "string",
        "description": "Mutually-exclusive human curation state for one episode. Absence means the\nepisode is unflagged.",
        "enum": [
          "good",
          "bad",
          "needs-review",
          "flagged-outlier"
        ]
      },
      "EpisodeCurationFlagResponse": {
        "type": "object",
        "description": "Response of setting an episode curation flag.",
        "required": [
          "flag"
        ],
        "properties": {
          "flag": {
            "$ref": "#/components/schemas/EpisodeCurationFlagDto"
          }
        }
      },
      "EpisodeDetailResponse": {
        "type": "object",
        "description": "Response of `GET /api/episodes/{dataset_id}/{episode_index}`.",
        "required": [
          "episode_index",
          "tasks",
          "length_frames",
          "duration_secs",
          "cameras"
        ],
        "properties": {
          "cameras": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EpisodeCamera"
            },
            "description": "Indexed cameras of this episode with preview URLs."
          },
          "curation_flag": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EpisodeCurationFlagDto",
                "description": "Current typed curation flag; `None` means unflagged."
              }
            ]
          },
          "dataset_episode_averages": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/DatasetEpisodeAveragesDto",
                "description": "Precomputed whole-dataset baseline. Absent only for legacy indexes\npublished before dataset episode averages were persisted."
              }
            ]
          },
          "dataset_from_index": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Inclusive global frame index of the episode's first frame. Present only\nwhen the raw dataset is available — a stateless index-only deployment\nserves detail from the metadata sidecar, which does not carry the global\nframe range, so this is omitted there.",
            "minimum": 0
          },
          "dataset_to_index": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Exclusive global frame index just past the episode's last frame. Omitted\nwhen the raw dataset is unavailable (see `dataset_from_index`).",
            "minimum": 0
          },
          "depth_cameras": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EpisodeCamera"
            },
            "description": "DEPTH views of this episode with viridis-colorized preview URLs.\nDepth is never embedded or searchable — these are extra viewer angles.\nA depth camera appears here only once the previews backfill has\nproduced its renditions; omitted entirely for RGB-only datasets."
          },
          "duration_secs": {
            "type": "number",
            "format": "double"
          },
          "episode_index": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "frames": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/FrameHitDto"
            },
            "description": "Ranked frame hits for this episode; present only when `q` was given."
          },
          "length_frames": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "tasks": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "EpisodeHitDto": {
        "type": "object",
        "description": "One ranked episode with its top evidence frames.",
        "required": [
          "dataset",
          "episode_index",
          "score",
          "tasks",
          "length_frames",
          "duration_secs",
          "cameras",
          "frames",
          "preview_urls"
        ],
        "properties": {
          "cameras": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Cameras indexed for this episode (original `LeRobot` keys)."
          },
          "curation_flag": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EpisodeCurationFlagDto",
                "description": "Current typed curation flag; `None` means unflagged."
              }
            ]
          },
          "dataset": {
            "type": "string",
            "description": "Id of the dataset this episode came from. Always present; with a\ncross-dataset search scope (`datasets=`, `dataset=*`, or none) it\ndisambiguates which dataset each ranked episode — and its asset URLs —\nbelongs to."
          },
          "duration_secs": {
            "type": "number",
            "format": "double"
          },
          "episode_index": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "frames": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FrameHitDto"
            },
            "description": "Top evidence frames, sorted by descending score."
          },
          "length_frames": {
            "type": "integer",
            "format": "int64",
            "description": "Episode length in dataset frames (at the dataset fps).",
            "minimum": 0
          },
          "preview_urls": {
            "type": "object",
            "description": "Camera key -> absolute preview clip URL.",
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            }
          },
          "score": {
            "type": "number",
            "format": "float",
            "description": "Blended episode score (`0.7 * max + 0.3 * mean(top 3)` frame scores)."
          },
          "tasks": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "EpisodeIndexRange": {
        "type": "object",
        "description": "An inclusive range of episode indices.",
        "required": [
          "start_episode_index",
          "end_episode_index"
        ],
        "properties": {
          "end_episode_index": {
            "type": "integer",
            "format": "int32",
            "description": "Last episode index of the range (inclusive); must not be below the\nstart.",
            "minimum": 0
          },
          "start_episode_index": {
            "type": "integer",
            "format": "int32",
            "description": "First episode index of the range (inclusive).",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "EpisodeNeighborDto": {
        "type": "object",
        "description": "One episode ranked by pooled-vector similarity (mirror of\n`pareto_analytics::EpisodeNeighbor`), enriched with everything the shared\nepisode card needs so clients do not need per-neighbor detail requests.",
        "required": [
          "episode_index",
          "camera",
          "score",
          "tasks",
          "length_frames",
          "duration_secs",
          "cameras",
          "preview_urls",
          "representative_preview_frames"
        ],
        "properties": {
          "camera": {
            "type": "string",
            "description": "Camera scope of the matched pooled row: the original `LeRobot` camera\nkey, or `*` for the all-cameras pooled row (returned when the query\ndid not filter by camera)."
          },
          "cameras": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Original `LeRobot` camera keys indexed for this episode."
          },
          "curation_flag": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EpisodeCurationFlagDto",
                "description": "Current typed curation flag; `None` means unflagged."
              }
            ]
          },
          "duration_secs": {
            "type": "number",
            "format": "double",
            "description": "Episode duration derived from the target index metadata sidecar fps."
          },
          "episode_index": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "length_frames": {
            "type": "integer",
            "format": "int64",
            "description": "Episode length in dataset frames (at the dataset fps).",
            "minimum": 0
          },
          "preview_urls": {
            "type": "object",
            "description": "Lowest-rung preview clip URL keyed by original camera name.",
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            }
          },
          "representative_preview_frames": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PreviewFrameDto"
            },
            "description": "Up to five chronological frames from the first indexed camera. These\nare neutral previews rather than similarity evidence."
          },
          "score": {
            "type": "number",
            "format": "float",
            "description": "Cosine similarity of the pooled episode vectors, in `[-1, 1]`."
          },
          "tasks": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "EpisodeOrdering": {
        "type": "string",
        "description": "Metadata-only ordering strategies supported by the episode browser.\n\nThe HTTP boundary deliberately accepts an arbitrary string and maps unknown\nvalues to [`Self::RoundRobin`], allowing newer clients to talk safely to an\nolder server. [`select_browse_episode_page`] remains the single injection\npoint between a strategy and stable pagination.",
        "enum": [
          "round_robin",
          "representativeness"
        ]
      },
      "EpisodePreviewFramesDto": {
        "type": "object",
        "description": "Representative preview frames for one requested episode.",
        "required": [
          "episode_index",
          "frames"
        ],
        "properties": {
          "episode_index": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "frames": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PreviewFrameDto"
            },
            "description": "Up to five chronological frames from the episode's first indexed\ncamera. These are neutral previews, not search evidence."
          }
        }
      },
      "EpisodePreviewFramesResponse": {
        "type": "object",
        "description": "Response of the batch episode preview-frame endpoint.",
        "required": [
          "dataset_id",
          "episodes"
        ],
        "properties": {
          "dataset_id": {
            "type": "string"
          },
          "episodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EpisodePreviewFramesDto"
            },
            "description": "One group per requested episode, preserving request order."
          }
        }
      },
      "EpisodeSampleStrategyDto": {
        "type": "string",
        "description": "How `max_episodes` chooses which episodes to sample when registering a\ndataset. Wire mirror of `pareto_index::EpisodeSampleStrategy` (kebab-case).\nThe `->` mapping onto the library enum lives with the consumer (the server),\nkeeping this crate a dependency-free leaf.",
        "enum": [
          "first",
          "uniform",
          "stratified-by-task",
          "stratified-by-task-and-length"
        ]
      },
      "EpisodeScoreDto": {
        "type": "object",
        "description": "One `(episode_index, score)` pair, used by analytics coverage lists and\nthe `search_executed` event's `top` digest.",
        "required": [
          "episode_index",
          "score"
        ],
        "properties": {
          "episode_index": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "score": {
            "type": "number",
            "format": "float",
            "description": "Cosine similarity in `[-1, 1]`."
          }
        }
      },
      "EpisodeSelectionManifestDto": {
        "type": "object",
        "description": "Browser-to-CLI handoff for an ordered episode selection.",
        "required": [
          "schema",
          "dataset_id",
          "episode_indices"
        ],
        "properties": {
          "dataset_id": {
            "type": "string"
          },
          "episode_indices": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            }
          },
          "schema": {
            "$ref": "#/components/schemas/EpisodeSelectionManifestSchema"
          }
        },
        "additionalProperties": false
      },
      "EpisodeSelectionManifestSchema": {
        "type": "string",
        "description": "Typed schema discriminator serialized as the manifest's string value.",
        "enum": [
          "pareto.episode-selection/v1"
        ]
      },
      "EpisodeSeriesResponse": {
        "type": "object",
        "description": "Response of `GET /api/episodes/{dataset_id}/{episode_index}/series` — the\ndownsampled per-episode state/action timeseries for the synced viewer\n(mirror of `pareto_index::EpisodeSeries`). All camera plots share this one\nplayhead: `timestamps_sec[k]` is the episode-relative time of sample `k`, and\n`state[k]` / `action[k]` are the joint vectors at that time.",
        "required": [
          "episode_index",
          "fps_series",
          "state_dims",
          "action_dims",
          "timestamps_sec",
          "state",
          "action"
        ],
        "properties": {
          "action": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "type": "number",
                "format": "float"
              }
            },
            "description": "One action vector per timestamp; empty when the dataset has no action\ncolumn."
          },
          "action_dims": {
            "type": "integer",
            "description": "Components per `action` vector; `0` when the dataset has no action\ncolumn.",
            "minimum": 0
          },
          "episode_index": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "fps_series": {
            "type": "number",
            "format": "float",
            "description": "The downsampled sample rate in Hz (`0.0` when the dataset fps is\ndegenerate)."
          },
          "state": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "type": "number",
                "format": "float"
              }
            },
            "description": "One state vector per timestamp; empty when the dataset has no state\ncolumn."
          },
          "state_dims": {
            "type": "integer",
            "description": "Components per `observation.state` vector; `0` when the dataset has no\nstate column.",
            "minimum": 0
          },
          "timestamps_sec": {
            "type": "array",
            "items": {
              "type": "number",
              "format": "float"
            },
            "description": "Episode-relative timestamp (seconds) of each sample."
          }
        }
      },
      "EventBody": {
        "oneOf": [
          {
            "type": "object",
            "description": "A dataset root was registered (idempotent: re-registering an existing\nroot emits this again with the same id).",
            "required": [
              "id",
              "type"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Dataset id."
              },
              "type": {
                "type": "string",
                "enum": [
                  "dataset_registered"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "An indexing build was accepted and is starting.",
            "required": [
              "id",
              "type"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Dataset id."
              },
              "type": {
                "type": "string",
                "enum": [
                  "dataset_index_started"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "One indexing progress step (mirrors the per-dataset progress SSE).",
            "required": [
              "id",
              "progress",
              "type"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Dataset id."
              },
              "progress": {
                "$ref": "#/components/schemas/IndexProgressDto"
              },
              "type": {
                "type": "string",
                "enum": [
                  "index_progress"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "An indexing build finished; the dataset is searchable.",
            "required": [
              "id",
              "frames_indexed",
              "type"
            ],
            "properties": {
              "frames_indexed": {
                "type": "integer",
                "format": "int64",
                "minimum": 0
              },
              "id": {
                "type": "string",
                "description": "Dataset id."
              },
              "type": {
                "type": "string",
                "enum": [
                  "dataset_indexed"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "An indexing build failed.",
            "required": [
              "id",
              "error",
              "type"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "id": {
                "type": "string",
                "description": "Dataset id."
              },
              "type": {
                "type": "string",
                "enum": [
                  "dataset_index_failed"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "A search completed successfully.",
            "required": [
              "dataset",
              "query",
              "flagged_only",
              "episode_count",
              "top",
              "type"
            ],
            "properties": {
              "camera": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "dataset": {
                "type": "string"
              },
              "episode_count": {
                "type": "integer",
                "description": "Episodes returned by the search.",
                "minimum": 0
              },
              "flagged_only": {
                "type": "boolean"
              },
              "query": {
                "type": "string"
              },
              "task_contains": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "task_exact": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "top": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/EpisodeScoreDto"
                },
                "description": "Up to five best episodes with their scores, best first."
              },
              "type": {
                "type": "string",
                "enum": [
                  "search_executed"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "A dataset-level search completed successfully.",
            "required": [
              "query",
              "dataset_count",
              "type"
            ],
            "properties": {
              "dataset_count": {
                "type": "integer",
                "description": "Datasets returned by the search.",
                "minimum": 0
              },
              "query": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "dataset_search_executed"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "An export job was created and queued.",
            "required": [
              "export_id",
              "dataset",
              "episode_count",
              "type"
            ],
            "properties": {
              "dataset": {
                "type": "string"
              },
              "episode_count": {
                "type": "integer",
                "minimum": 0
              },
              "export_id": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "export_created"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "An export job finished successfully.",
            "required": [
              "export_id",
              "type"
            ],
            "properties": {
              "export_id": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "export_finished"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "An export job failed.",
            "required": [
              "export_id",
              "error",
              "type"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "export_id": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "export_failed"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "An annotation was added to an episode.",
            "required": [
              "dataset",
              "annotation",
              "type"
            ],
            "properties": {
              "annotation": {
                "$ref": "#/components/schemas/AnnotationDto"
              },
              "dataset": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "annotation_added"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "An annotation was removed (only emitted for an actual removal, not\nfor a not-found no-op).",
            "required": [
              "dataset",
              "id",
              "type"
            ],
            "properties": {
              "dataset": {
                "type": "string"
              },
              "id": {
                "type": "string",
                "description": "Id of the removed annotation."
              },
              "type": {
                "type": "string",
                "enum": [
                  "annotation_removed"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "An analytics endpoint completed successfully.",
            "required": [
              "verb",
              "dataset",
              "summary",
              "type"
            ],
            "properties": {
              "dataset": {
                "type": "string"
              },
              "summary": {
                "description": "Small verb-specific result digest (counts / headline scores)."
              },
              "type": {
                "type": "string",
                "enum": [
                  "analytics_executed"
                ]
              },
              "verb": {
                "$ref": "#/components/schemas/AnalyticsVerb"
              }
            }
          }
        ],
        "description": "The typed payload of one [`EventEnvelope`], tagged by `type`."
      },
      "EventEnvelope": {
        "type": "object",
        "description": "One event on the global bus, as streamed by `GET /api/events` (the SSE\nevent name is the payload's `type` tag; the SSE data is this whole\nenvelope as JSON).",
        "required": [
          "schema_version",
          "seq",
          "unix_ms",
          "actor",
          "scope",
          "event"
        ],
        "properties": {
          "actor": {
            "type": "string",
            "description": "Sanitized `X-Pareto-Actor` header of the request that caused the\nevent (`\"api\"` when the header was absent or blank)."
          },
          "event": {
            "$ref": "#/components/schemas/EventBody",
            "description": "The event payload, discriminated by its `type` tag."
          },
          "schema_version": {
            "type": "integer",
            "format": "int32",
            "description": "Envelope wire-format version; currently always `2`.",
            "minimum": 0
          },
          "scope": {
            "$ref": "#/components/schemas/DataScope",
            "description": "Tenant scope in which the event occurred."
          },
          "seq": {
            "type": "integer",
            "format": "int64",
            "description": "Per-process sequence number, starting at 1 and strictly increasing in\nemission order. Resets when the server restarts.",
            "minimum": 0
          },
          "unix_ms": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp in milliseconds when the event was emitted.",
            "minimum": 0
          }
        }
      },
      "ExportJobStatus": {
        "type": "string",
        "description": "Lifecycle state of an export job.",
        "enum": [
          "queued",
          "running",
          "done",
          "failed"
        ]
      },
      "ExportReportDto": {
        "type": "object",
        "description": "Summary of a finished export. Deserialize is required because the report\nround-trips through the durable job record's progress field.",
        "required": [
          "episodes_written",
          "frames_written",
          "dest_path"
        ],
        "properties": {
          "dest_path": {
            "type": "string"
          },
          "episodes_written": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "frames_written": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          }
        }
      },
      "ExportStatusResponse": {
        "type": "object",
        "description": "Response of `GET /api/exports/{id}`.",
        "required": [
          "status"
        ],
        "properties": {
          "error": {
            "type": [
              "string",
              "null"
            ],
            "description": "Present when `status` is `failed`."
          },
          "report": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ExportReportDto",
                "description": "Present when `status` is `done`."
              }
            ]
          },
          "status": {
            "$ref": "#/components/schemas/ExportJobStatus"
          }
        }
      },
      "FrameHitDto": {
        "type": "object",
        "description": "One frame-level hit: the evidence backing an [`EpisodeHitDto`].",
        "required": [
          "frame_id",
          "episode_index",
          "camera",
          "t_sec",
          "frame_index",
          "score",
          "thumb_url"
        ],
        "properties": {
          "camera": {
            "type": "string",
            "description": "Original `LeRobot` camera key."
          },
          "episode_index": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "frame_id": {
            "type": "string",
            "description": "Unique frame id, also the thumbnail asset key."
          },
          "frame_index": {
            "type": "integer",
            "format": "int64",
            "description": "Frame number within the episode at the dataset fps."
          },
          "score": {
            "type": "number",
            "format": "float",
            "description": "Cosine similarity between the query and this frame, in `[-1, 1]`."
          },
          "t_sec": {
            "type": "number",
            "format": "float",
            "description": "Episode-relative timestamp in seconds (0 = episode start)."
          },
          "thumb_url": {
            "type": "string",
            "description": "Absolute thumbnail URL (`/assets/{dataset_id}/thumbs/...`)."
          }
        }
      },
      "HuggingFaceRepoTypeDto": {
        "type": "string",
        "description": "Hugging Face repository namespace for an acquisition job.",
        "enum": [
          "model",
          "dataset",
          "space"
        ]
      },
      "IndexProgressDto": {
        "oneOf": [
          {
            "type": "object",
            "description": "Emitted once before any work.",
            "required": [
              "total_episodes",
              "cameras",
              "type"
            ],
            "properties": {
              "cameras": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "total_episodes": {
                "type": "integer",
                "format": "int32",
                "minimum": 0
              },
              "type": {
                "type": "string",
                "enum": [
                  "started"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "An episode's sampling/embedding began.",
            "required": [
              "episode_index",
              "type"
            ],
            "properties": {
              "episode_index": {
                "type": "integer",
                "format": "int32",
                "minimum": 0
              },
              "type": {
                "type": "string",
                "enum": [
                  "episode_started"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "A frame was embedded. `frames_total_estimate` is an UPPER BOUND; the\nfinal `frames_done` can fall slightly short of it.",
            "required": [
              "frames_done",
              "frames_total_estimate",
              "type"
            ],
            "properties": {
              "frames_done": {
                "type": "integer",
                "format": "int64",
                "minimum": 0
              },
              "frames_total_estimate": {
                "type": "integer",
                "format": "int64",
                "minimum": 0
              },
              "type": {
                "type": "string",
                "enum": [
                  "frames_embedded"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "Every camera of an episode finished.",
            "required": [
              "episode_index",
              "frames",
              "type"
            ],
            "properties": {
              "episode_index": {
                "type": "integer",
                "format": "int32",
                "minimum": 0
              },
              "frames": {
                "type": "integer",
                "format": "int64",
                "minimum": 0
              },
              "type": {
                "type": "string",
                "enum": [
                  "episode_finished"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "The manifest was written; the index is complete.",
            "required": [
              "frames_indexed",
              "type"
            ],
            "properties": {
              "frames_indexed": {
                "type": "integer",
                "format": "int64",
                "minimum": 0
              },
              "type": {
                "type": "string",
                "enum": [
                  "finished"
                ]
              }
            }
          }
        ],
        "description": "Mirror of `pareto_index::IndexProgress`, serialized with the same\n`{\"type\": ...}` `snake_case` tag as the SSE progress events."
      },
      "JobKindDto": {
        "type": "string",
        "description": "What a job does (mirror of `pareto_jobs::JobKind`).",
        "enum": [
          "acquisition",
          "conversion",
          "ingest",
          "export",
          "backfill"
        ]
      },
      "JobRecordDto": {
        "type": "object",
        "description": "Public API projection of `pareto_jobs::JobView` (the latest run of a job\nid — resubmitting a dataset's singleton kinds reuses the id with a fresh\nrun).",
        "required": [
          "id",
          "kind",
          "dataset_id",
          "spec",
          "status",
          "attempts",
          "actor",
          "created_at_unix_secs",
          "updated_at_unix_secs"
        ],
        "properties": {
          "actor": {
            "type": "string",
            "description": "Durable principal attribution, or the sanitized telemetry label for an\nanonymous action in open mode."
          },
          "attempts": {
            "type": "integer",
            "format": "int32",
            "description": "Execution attempt within the current run (0 until first claim).",
            "minimum": 0
          },
          "build_dir": {
            "type": [
              "string",
              "null"
            ],
            "description": "Stable index build directory of this ingest run. Attempts within the\nrun reuse it; non-ingest jobs omit it."
          },
          "created_at_unix_secs": {
            "type": "integer",
            "format": "int64",
            "description": "Start time of the latest run (Unix seconds).",
            "minimum": 0
          },
          "dataset_id": {
            "type": "string",
            "description": "Dataset the job operates on."
          },
          "error": {
            "type": [
              "string",
              "null"
            ],
            "description": "Terminal failure reason when `status` is `failed`; while `running`,\nwhy the previous attempt died (absent unless the current attempt is a\nretry)."
          },
          "id": {
            "type": "string",
            "description": "Job id (deterministic per submission identity, e.g. `ingest-{dataset}`)."
          },
          "kind": {
            "$ref": "#/components/schemas/JobKindDto",
            "description": "What the job does."
          },
          "progress": {
            "type": [
              "object",
              "null"
            ],
            "description": "Latest progress snapshot while live (an `IndexProgress` payload for\ningests, pipeline progress for acquisitions/conversions); the recorded\nterminal result once succeeded (export report, backfill completion)."
          },
          "spec": {
            "type": "object",
            "description": "Opaque job parameters (the validated request that created it). Job\nrecord routes require admin access because specs may contain paths.\nBriefly `{}` right after start, before the control plane records it."
          },
          "status": {
            "$ref": "#/components/schemas/JobStatusDto",
            "description": "Current lifecycle state."
          },
          "updated_at_unix_secs": {
            "type": "integer",
            "format": "int64",
            "description": "Last observed change (Unix seconds).",
            "minimum": 0
          }
        }
      },
      "JobStatusDto": {
        "type": "string",
        "description": "Lifecycle state of a job (mirror of `pareto_jobs::JobStatus`).",
        "enum": [
          "queued",
          "running",
          "succeeded",
          "failed",
          "cancelled"
        ]
      },
      "JobsResponse": {
        "type": "object",
        "description": "Response of `GET /api/jobs`.",
        "required": [
          "jobs"
        ],
        "properties": {
          "jobs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JobRecordDto"
            },
            "description": "Matching job records, newest first."
          }
        }
      },
      "OrganizationId": {
        "type": "string",
        "description": "A verified WorkOS-compatible organization identifier.\n\nThe conservative URL-safe alphabet keeps the value safe in request\nheaders, object-storage prefixes, and durable workflow keys without\nadditional escaping."
      },
      "PreparedCamerasRequest": {
        "type": "string",
        "description": "Camera views a prepared conversion keeps.",
        "enum": [
          "all-rgb",
          "all-views"
        ]
      },
      "PreviewCodecDto": {
        "type": "string",
        "description": "The video codec of a preview rendition, so a client can pick one its\nbrowser decodes. Safari cannot play AV1; every browser plays h264.\n`unknown` means the index has not recorded it — try the rendition and fall\nback on error, which is what clients did before the codec was recorded.",
        "enum": [
          "unknown",
          "av1",
          "h264"
        ]
      },
      "PreviewFrameDto": {
        "type": "object",
        "description": "One neutral, query-free frame used to preview an episode card.",
        "required": [
          "frame_id",
          "camera",
          "t_sec",
          "frame_index",
          "thumb_url"
        ],
        "properties": {
          "camera": {
            "type": "string",
            "description": "Original `LeRobot` camera key."
          },
          "frame_id": {
            "type": "string",
            "description": "Unique frame id, also the thumbnail asset key."
          },
          "frame_index": {
            "type": "integer",
            "format": "int64",
            "description": "Frame number within the episode at the dataset fps."
          },
          "t_sec": {
            "type": "number",
            "format": "float",
            "description": "Episode-relative timestamp in seconds (0 = episode start)."
          },
          "thumb_url": {
            "type": "string",
            "description": "Absolute thumbnail URL (`/assets/{dataset_id}/thumbs/...`)."
          }
        }
      },
      "PreviewRenditionDto": {
        "type": "object",
        "description": "One preview-clip rendition of a camera. Identity is `(height, codec)`: the\nsame rung can be offered in more than one codec.",
        "required": [
          "height",
          "codec",
          "url"
        ],
        "properties": {
          "codec": {
            "$ref": "#/components/schemas/PreviewCodecDto",
            "description": "Codec of this rendition."
          },
          "height": {
            "type": "integer",
            "format": "int32",
            "description": "Rung height in pixels (even; never upscaled past the source).",
            "minimum": 0
          },
          "url": {
            "type": "string",
            "description": "Absolute preview clip URL (versioned with `?v=`)."
          }
        }
      },
      "ProbeCoverageDto": {
        "type": "object",
        "description": "Coverage of one probe (mirror of `pareto_analytics::ProbeCoverage`).",
        "required": [
          "probe",
          "episodes_covered",
          "coverage_ratio",
          "mean_top_score",
          "top_episodes",
          "thinnest_episodes"
        ],
        "properties": {
          "coverage_ratio": {
            "type": "number",
            "format": "float",
            "description": "`episodes_covered / total episodes in the index`."
          },
          "episodes_covered": {
            "type": "integer",
            "description": "Episodes whose score reached `relative_threshold * best episode\nscore`.",
            "minimum": 0
          },
          "mean_top_score": {
            "type": "number",
            "format": "float",
            "description": "Mean over episodes of the per-episode (max-frame) score."
          },
          "probe": {
            "type": "string",
            "description": "The probe text this report describes."
          },
          "thinnest_episodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EpisodeScoreDto"
            },
            "description": "Up to five WORST-scoring episodes, worst first — the gap signal when\nhunting missing coverage."
          },
          "top_episodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EpisodeScoreDto"
            },
            "description": "Up to five best-scoring episodes, best first."
          }
        }
      },
      "RegisterDatasetRequest": {
        "type": "object",
        "description": "Request body of `POST /api/datasets`.",
        "required": [
          "path"
        ],
        "properties": {
          "cameras": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Camera keys to index; omitted means every camera."
          },
          "embed_concurrency": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Maximum concurrent embedding batches in flight (`>= 1`); omitted means\nthe default 8. The self-hosted SigLIP provider is not client-side\nrate-limited, so this is the throughput control there.",
            "minimum": 0
          },
          "episodes": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            },
            "description": "Episode indices to index; omitted means every episode."
          },
          "frame_max_dim": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "`max(width, height)` cap for sampled frames (default 512).",
            "minimum": 0
          },
          "max_episodes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Cap indexing to a representative sample of at most this many episodes\n(`>= 1`), drawn from the selected episodes; omitted indexes them all.",
            "minimum": 0
          },
          "max_episodes_per_task": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Index at most N episodes PER task/instruction (length-strided within each\ntask), keeping every task — maximizes task diversity. Takes precedence\nover `max_episodes`/`sample` when set (`>= 1`).",
            "minimum": 0
          },
          "media_concurrency": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Maximum (episode, camera) pairs whose ffmpeg media stage runs at once\n(`>= 1`); omitted means the default (half the server's cores).",
            "minimum": 0
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Preferred dataset id (slugified before use). Omitted means the id is\nderived from the root's last path segment — a poor default when\nconversion destinations end in a generic segment such as `/lerobot`."
          },
          "overwrite": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Required (as `true`) to re-index a dataset that is already indexed."
          },
          "path": {
            "type": "string",
            "description": "Location of the `LeRobot` v3 dataset root: a local filesystem path or an\nobject-store URI (`gs://bucket/prefix`)."
          },
          "preview_crf": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "h264 CRF for preview clips (0..=51, lower = higher quality). Omitted means\nthe default 20.",
            "minimum": 0
          },
          "preview_heights": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            },
            "description": "Preview quality ladder: each rung an even height in `2..=2160`. A rung is\nemitted per DISTINCT height `<=` the source (never upscaling). Omitted\nmeans the default `[480, 720, 1080]`."
          },
          "sample": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EpisodeSampleStrategyDto",
                "description": "How `max_episodes` picks the sampled episodes; omitted defaults to\n`stratified-by-task`. Ignored when `max_episodes` is omitted."
              }
            ]
          },
          "sample_fps": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Frames sampled per second of episode video (default 1.0)."
          }
        }
      },
      "RegisterDatasetResponse": {
        "type": "object",
        "description": "Response of `POST /api/datasets` (202: indexing started).",
        "required": [
          "id",
          "job_id",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "job_id": {
            "type": "string",
            "description": "Id of the durable ingest job driving the build; observable via\n`GET /api/jobs/{id}`."
          },
          "status": {
            "$ref": "#/components/schemas/DatasetStatus"
          }
        }
      },
      "ReindexDatasetRequest": {
        "type": "object",
        "description": "Request body of `POST /api/datasets/{id}/reindex`: re-run the ingest/index\nbuild for an ALREADY-REGISTERED dataset, identified by its catalog id. The\nserver resolves the source root from the catalog, so the caller does not\nrepeat the raw path. Every field mirrors the indexing knobs of\n[`RegisterDatasetRequest`] (minus `path`); all are optional and omitted\nfields fall back to the server/library defaults.",
        "properties": {
          "cameras": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Camera keys to index; omitted means every camera."
          },
          "embed_concurrency": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Maximum concurrent embedding batches in flight (`>= 1`); omitted means\nthe default 8.",
            "minimum": 0
          },
          "episodes": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            },
            "description": "Episode indices to index; omitted means every episode."
          },
          "frame_max_dim": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "`max(width, height)` cap for sampled frames (default 512).",
            "minimum": 0
          },
          "max_episodes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Cap indexing to a representative sample of at most this many episodes\n(`>= 1`); omitted indexes them all.",
            "minimum": 0
          },
          "max_episodes_per_task": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Index at most N episodes PER task/instruction; takes precedence over\n`max_episodes`/`sample` when set (`>= 1`).",
            "minimum": 0
          },
          "media_concurrency": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Maximum (episode, camera) pairs in the ffmpeg media stage at once\n(`>= 1`); omitted means the server default.",
            "minimum": 0
          },
          "overwrite": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether to rebuild when a complete index already exists. Unlike\n[`RegisterDatasetRequest::overwrite`], an OMITTED value here defaults to\n`true`: rebuilding an indexed dataset is the whole point of reindex."
          },
          "preview_crf": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "h264 CRF for preview clips (0..=51); omitted means the default 20.",
            "minimum": 0
          },
          "preview_heights": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            },
            "description": "Preview quality ladder; omitted means the default `[480, 720, 1080]`."
          },
          "sample": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EpisodeSampleStrategyDto",
                "description": "How `max_episodes` picks the sampled episodes; omitted defaults to\n`stratified-by-task`. Ignored when `max_episodes` is omitted."
              }
            ]
          },
          "sample_fps": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Frames sampled per second of episode video (default 1.0)."
          }
        }
      },
      "RemoveAnnotationResponse": {
        "type": "object",
        "description": "Response of `DELETE /api/annotations/{dataset_id}/{annotation_id}`.\nRemoving an id that never existed (or was already removed) is a SUCCESS\nwith `removed: false`, not an error.",
        "required": [
          "removed"
        ],
        "properties": {
          "removed": {
            "type": "boolean",
            "description": "`true` when a live annotation was removed; `false` when no live\nannotation with that id existed."
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "description": "Response of `GET /api/search`.",
        "required": [
          "query",
          "total_frame_hits",
          "episodes"
        ],
        "properties": {
          "episodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EpisodeHitDto"
            },
            "description": "Ranked episodes, best first."
          },
          "query": {
            "type": "string",
            "description": "The query text as given."
          },
          "total_frame_hits": {
            "type": "integer",
            "description": "Candidate frame rows remaining after all filters.",
            "minimum": 0
          }
        }
      },
      "SetEpisodeCurationFlagRequest": {
        "type": "object",
        "description": "Request body of `PUT /api/episodes/{dataset_id}/{episode_index}/flag`.",
        "required": [
          "flag"
        ],
        "properties": {
          "flag": {
            "$ref": "#/components/schemas/EpisodeCurationFlagDto"
          }
        },
        "additionalProperties": false
      },
      "SimilarEpisodesResponse": {
        "type": "object",
        "description": "Response of `GET /api/analytics/similar`.",
        "required": [
          "dataset",
          "episode_index",
          "neighbors"
        ],
        "properties": {
          "against": {
            "type": [
              "string",
              "null"
            ],
            "description": "Dataset the neighbors were searched in; absent means the query's own\ndataset (in which case the query episode itself is excluded)."
          },
          "camera": {
            "type": [
              "string",
              "null"
            ],
            "description": "Camera scope of the comparison; absent means the all-cameras pooled\nvectors were compared."
          },
          "dataset": {
            "type": "string",
            "description": "Dataset the query episode lives in."
          },
          "episode_index": {
            "type": "integer",
            "format": "int32",
            "description": "The query episode.",
            "minimum": 0
          },
          "neighbors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EpisodeNeighborDto"
            },
            "description": "Neighbors sorted by descending score."
          }
        }
      },
      "TaskFacetDto": {
        "type": "object",
        "description": "One exact natural-language task available in the active dataset scope.",
        "required": [
          "task",
          "episode_count"
        ],
        "properties": {
          "episode_count": {
            "type": "integer",
            "description": "Distinct episodes carrying this exact task.",
            "minimum": 0
          },
          "task": {
            "type": "string"
          }
        }
      },
      "TaskFacetsResponse": {
        "type": "object",
        "description": "Response of `GET /api/episodes/tasks`.",
        "required": [
          "total_episodes",
          "tasks"
        ],
        "properties": {
          "tasks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaskFacetDto"
            },
            "description": "Exact task facets ordered by episode count descending, then task text."
          },
          "total_episodes": {
            "type": "integer",
            "description": "Indexed episodes scanned across the selected datasets.",
            "minimum": 0
          }
        }
      },
      "TaskGroupVarianceDto": {
        "type": "object",
        "description": "One task group's action variance over normalized time (mirror of\n`pareto_analytics::TaskGroupVariance`).",
        "required": [
          "task",
          "episode_count",
          "action_dims",
          "variance"
        ],
        "properties": {
          "action_dims": {
            "type": "integer",
            "description": "Action dimensions in `variance`.",
            "minimum": 0
          },
          "episode_count": {
            "type": "integer",
            "description": "Episodes pooled into this group's variance.",
            "minimum": 0
          },
          "task": {
            "type": "string",
            "description": "The task-group key: the episode's tasks joined with `'\\n'`."
          },
          "variance": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "type": "number",
                "format": "float"
              }
            },
            "description": "`variance[dim][timestep]`: the across-episode variance of action\ndimension `dim` at normalized time `timestep / (timestep_count - 1)`."
          }
        }
      },
      "UpdateDatasetTagsRequest": {
        "type": "object",
        "description": "Request body of `PUT /api/datasets/{id}/tags`. The full normalized set\nreplaces the prior tags atomically at the catalog boundary.",
        "required": [
          "tags"
        ],
        "properties": {
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": false
      }
    }
  }
}