openapi.json

{
  "components": {
    "schemas": {
      "BatchInferProgress": {
        "description": "Aggregate progress for a batched infer job across all language groups.",
        "properties": {
          "language_groups": {
            "additionalProperties": {
              "$ref": "#/components/schemas/LanguageGroupProgress"
            },
            "description": "Per-language-group progress, keyed by language code.\nUses BTreeMap for deterministic JSON serialization.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          }
        },
        "required": [
          "language_groups"
        ],
        "type": "object"
      },
      "ClientPath": {
        "description": "A path on the submitting client's filesystem.\n\nThe server MUST NOT do filesystem I/O on this directly — it's metadata\nonly.  The only way to convert it to a [`ServerPath`] for I/O is via\n[`assume_shared_filesystem`](Self::assume_shared_filesystem), which\nrequires the caller to verify that the server shares the client's\nfilesystem (paths_mode with a local daemon).\n\nDeliberately does NOT implement `AsRef<Path>` to prevent accidental\nfilesystem operations.",
        "type": "string"
      },
      "ContentType": {
        "description": "Engine category that supports backend overrides.\n\nCurrently only ASR and FA have multiple engine backends.\nOther inference tasks (morphosyntax, utseg, translate, coref)\nalways use their single built-in engine.\nMIME-like content discriminator for file results.",
        "enum": [
          "chat",
          "csv",
          "text"
        ],
        "type": "string"
      },
      "DisplayPath": {
        "description": "Display path for a file within a job: either a bare basename\n(`\"sample.cha\"`) for single-file input or a relative forward-slash path\n(`\"PWA/TYO_a1.cha\"`) for directory input with subdirectories.\n\nBackslashes are normalized to forward slashes on construction so the value\nis platform-independent regardless of whether the CLI ran on Windows.\n\nThis type replaces the former `FileName` which incorrectly rejected path\nseparators during deserialization even though the system routinely carries\nrelative paths.",
        "type": "string"
      },
      "DurationSeconds": {
        "description": "Duration measured in fractional seconds.",
        "format": "double",
        "type": "number"
      },
      "ErrorResponse": {
        "description": "Standard error response body, matching FastAPI's `HTTPException` format.\n\nAll non-2xx responses from the server use this shape so that clients\ncan parse errors uniformly. The one exception is\n[`ServerError::JobConflict`](crate::error::ServerError::JobConflict),\nwhich nests a `conflicts` array inside `detail`.",
        "properties": {
          "detail": {
            "description": "Human-readable description of what went wrong. For validation\nerrors this includes the specific field or constraint that failed.",
            "type": "string"
          }
        },
        "required": [
          "detail"
        ],
        "type": "object"
      },
      "ExecutionMode": {
        "description": "How a job reaches its execution host.",
        "enum": [
          "local",
          "staged_remote",
          "explicit_remote"
        ],
        "type": "string"
      },
      "ExecutionPlan": {
        "description": "Execution plan describing where and how a job is processed.\n\nAttached to `Job` and projected into `JobInfo` for API consumers.\nThe `stage` field tracks progress through the staged-remote lifecycle;\nfor local and explicit-remote jobs it is always [`ExecutionStage::Done`]\nonce the job finishes.",
        "properties": {
          "execution_host": {
            "description": "Hostname of the machine executing the job (e.g. `\"net\"`, `\"davida\"`).",
            "type": "string"
          },
          "mode": {
            "$ref": "#/components/schemas/ExecutionMode",
            "description": "How the job is being executed."
          },
          "remote_job_id": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/JobId",
                "description": "For staged-remote jobs: the job ID on the remote server.\n`None` until the remote job is submitted."
              }
            ]
          },
          "stage": {
            "$ref": "#/components/schemas/ExecutionStage",
            "description": "Current lifecycle stage of the execution plan."
          }
        },
        "required": [
          "mode",
          "execution_host",
          "stage"
        ],
        "type": "object"
      },
      "ExecutionStage": {
        "description": "Lifecycle stage of a staged-remote execution plan.\n\nFor [`ExecutionMode::Local`] and [`ExecutionMode::ExplicitRemote`] jobs,\nthe stage is always [`Done`](ExecutionStage::Done) on completion.",
        "enum": [
          "staging",
          "executing",
          "copying_back",
          "done",
          "failed"
        ],
        "type": "string"
      },
      "FailureCategory": {
        "description": "Broad classification for failures seen by the control plane.\n\nRetry behavior should be defined against these categories rather than raw\nerror strings.",
        "enum": [
          "validation",
          "parse_error",
          "input_missing",
          "worker_crash",
          "worker_timeout",
          "worker_protocol",
          "provider_transient",
          "provider_terminal",
          "memory_pressure",
          "cancelled",
          "system"
        ],
        "type": "string"
      },
      "FilePayload": {
        "description": "A single CHAT file submitted by the client.",
        "properties": {
          "content": {
            "description": "Full CHAT file text.",
            "type": "string"
          },
          "filename": {
            "$ref": "#/components/schemas/DisplayPath",
            "description": "Original filename (e.g. \"01DM_18.cha\")."
          }
        },
        "required": [
          "filename",
          "content"
        ],
        "type": "object"
      },
      "FileProgressStage": {
        "description": "Machine-readable sub-stage within a file's processing lifecycle.\n\nThis is more specific than [`FileStatusKind`]. For example, a file may be\nin the coarse `Processing` status while its current progress stage is\n`Aligning`, `BuildingChat`, or `RetryScheduled`.\n\nThe API exposes this enum so clients can branch on stable stage codes\nwithout parsing human-facing display labels.",
        "enum": [
          "processing",
          "reading",
          "resolving_audio",
          "recovering_utterance_timing",
          "recovering_timing_fallback",
          "aligning",
          "transcribing",
          "benchmarking",
          "checking_cache",
          "applying_results",
          "post_processing",
          "building_chat",
          "segmenting_utterances",
          "analyzing_morphosyntax",
          "finalizing",
          "writing",
          "parsing",
          "analyzing",
          "segmenting",
          "translating",
          "resolving_coreference",
          "comparing",
          "retry_scheduled"
        ],
        "type": "string"
      },
      "FileResult": {
        "description": "Result for a single processed file.",
        "properties": {
          "content": {
            "description": "Processed file content (CHAT text or CSV).  Empty string when\n`error` is `Some`.",
            "type": "string"
          },
          "content_type": {
            "$ref": "#/components/schemas/ContentType",
            "description": "MIME-like content discriminator: `\"chat\"` for CHAT files (default),\n`\"csv\"` for tabular output (e.g. opensmile features)."
          },
          "error": {
            "description": "Human-readable error message if this file failed processing.\n`None` for successfully processed files.",
            "type": [
              "string",
              "null"
            ]
          },
          "filename": {
            "$ref": "#/components/schemas/DisplayPath",
            "description": "Display path for this file: a bare basename (`\"sample.cha\"`) or a\nrelative forward-slash path (`\"PWA/TYO_a1.cha\"`) for directory input.\nBackslashes are normalized to forward slashes on construction."
          },
          "provenance": {
            "description": "Processing provenance extracted from the output CHAT file.\nEach entry records one batchalign3 command that was applied\n(command name, engine version, timestamp). Empty for non-CHAT\noutput or files that failed processing.",
            "items": {
              "$ref": "#/components/schemas/ProvenanceEntry"
            },
            "type": "array"
          }
        },
        "required": [
          "filename"
        ],
        "type": "object"
      },
      "FileStatusEntry": {
        "description": "Per-file status within a job.\n\nTracks processing state, timing, progress, and error details for a\nsingle file.  The server updates these entries as workers report\nresults, and they are included in `JobInfo.file_statuses`.",
        "properties": {
          "bug_report_id": {
            "description": "Opaque identifier linking to a persisted bug report (for post-mortem\nanalysis).  Generated by the server when a file fails unexpectedly.",
            "type": [
              "string",
              "null"
            ]
          },
          "error": {
            "description": "Human-readable error message.  Present only when `status` is `Error`.",
            "type": [
              "string",
              "null"
            ]
          },
          "error_category": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/FailureCategory",
                "description": "Broad classification of the failure. Helps the dashboard and retry\nlogic group failures without parsing free-form messages."
              }
            ]
          },
          "error_codes": {
            "description": "CHAT validation error codes (e.g. `[\"E362\", \"E704\"]`) when the failure\nwas a validation rejection.  Empty or absent for non-validation errors.",
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "error_line": {
            "description": "1-based line number in the CHAT file where the first error was\ndetected, if applicable.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "filename": {
            "$ref": "#/components/schemas/DisplayPath",
            "description": "Display path for this file: a bare basename (`\"sample.cha\"`) or a\nrelative forward-slash path (`\"PWA/TYO_a1.cha\"`) for directory input.\nBackslashes are normalized to forward slashes on construction."
          },
          "finished_at": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/UnixTimestamp",
                "description": "Unix timestamp (seconds since epoch) when processing finished\n(successfully or with error)."
              }
            ]
          },
          "next_eligible_at": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/UnixTimestamp",
                "description": "When the file is deferred for a retry, the earliest unix timestamp at\nwhich another attempt should start. `None` when no retry is pending."
              }
            ]
          },
          "progress_current": {
            "description": "Number of sub-steps completed so far (e.g. utterances processed).\nUsed with `progress_total` to drive progress bars.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "progress_label": {
            "description": "Human-readable label for the current processing stage\n(e.g. \"Morphosyntax\", \"Forced Alignment\").\n\nThis is derived from `progress_stage` by the server so operators can\nrender friendly text without hard-coding label mappings in every UI.",
            "type": [
              "string",
              "null"
            ]
          },
          "progress_stage": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/FileProgressStage",
                "description": "Machine-readable code for the current in-flight processing stage.\n\nThis is the stable field clients should use for branching or\nconditional UI. [`Self::progress_label`] is derived display text."
              }
            ]
          },
          "progress_total": {
            "description": "Total number of sub-steps expected for this file.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "started_at": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/UnixTimestamp",
                "description": "Unix timestamp (seconds since epoch) when the worker began processing\nthis file."
              }
            ]
          },
          "status": {
            "$ref": "#/components/schemas/FileStatusKind",
            "description": "Current lifecycle state of this file."
          }
        },
        "required": [
          "filename",
          "status"
        ],
        "type": "object"
      },
      "FileStatusKind": {
        "description": "Per-file lifecycle states within a job.\n\nEach file in a job tracks its own status independently.  On job restart,\nonly files in resumable states (`Queued`, `Processing`, `Interrupted`) are\nre-queued; `Done` and `Error` files are left as-is.",
        "enum": [
          "queued",
          "processing",
          "done",
          "error",
          "interrupted"
        ],
        "type": "string"
      },
      "HealthResponse": {
        "description": "`GET /health` response.\n\nProvides a snapshot of server liveness, capacity, and operational\nmetrics. The CLI uses this for daemon version checks (`build_hash`) and\ncapability probing.",
        "properties": {
          "active_jobs": {
            "description": "Number of jobs currently in `Queued` or `Running` state.",
            "format": "int64",
            "type": "integer"
          },
          "attempts_retried": {
            "description": "Cumulative count of attempts that were explicitly marked retryable.",
            "format": "int64",
            "type": "integer"
          },
          "attempts_started": {
            "description": "Cumulative count of work-unit attempts started since server start.",
            "format": "int64",
            "type": "integer"
          },
          "build_hash": {
            "description": "Build fingerprint — changes on every rebuild.  Used for stale-binary\ndetection during development.  Empty string from older servers.",
            "type": "string"
          },
          "cache_backend": {
            "description": "Utterance cache backend in use: `\"sqlite\"` (default).",
            "type": "string"
          },
          "capabilities": {
            "description": "Batchalign commands this server can process (e.g. `[\"morphotag\",\n\"align\", \"transcribe\"]`).  Determined by probing worker capabilities\nat startup.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "deferred_work_units": {
            "description": "Cumulative count of work units that were deferred for later execution.",
            "format": "int64",
            "type": "integer"
          },
          "forced_terminal_errors": {
            "description": "Cumulative count of files that were force-terminated (e.g. OOM-killed\nworkers, stuck processes) since server start.",
            "format": "int64",
            "type": "integer"
          },
          "free_threaded": {
            "description": "Whether the Python workers are running on free-threaded Python\n(3.14t+).  Affects memory budgets and concurrency strategy.",
            "type": "boolean"
          },
          "host_memory_active_leases": {
            "description": "Human-readable labels for active coordinator leases.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "host_memory_error": {
            "description": "Snapshot error surfaced when the host-memory ledger cannot be read.",
            "type": [
              "string",
              "null"
            ]
          },
          "host_memory_job_leases": {
            "description": "Number of active job-execution leases in the host coordinator.",
            "format": "int64",
            "type": "integer"
          },
          "host_memory_ml_test_locks": {
            "description": "Number of active machine-wide ML test locks in the host coordinator.",
            "format": "int64",
            "type": "integer"
          },
          "host_memory_pressure": {
            "$ref": "#/components/schemas/HostMemoryPressureLevel",
            "description": "Host-memory pressure classification derived from current OS memory plus\nactive cross-process reservations."
          },
          "host_memory_reserved_mb": {
            "$ref": "#/components/schemas/MemoryMb",
            "description": "Total memory currently reserved by the host-memory coordinator."
          },
          "host_memory_startup_leases": {
            "description": "Number of active worker/model startup leases in the host coordinator.",
            "format": "int64",
            "type": "integer"
          },
          "job_slots_available": {
            "description": "Number of additional jobs the server can accept right now, based on\nmemory and concurrency limits.",
            "format": "int64",
            "type": "integer"
          },
          "live_worker_keys": {
            "description": "Active worker keys (`target:lang`) currently loaded in the pool.\nInfer-task workers use labels such as `infer:asr:eng`.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "live_workers": {
            "description": "Number of currently live Python worker processes.",
            "format": "int64",
            "type": "integer"
          },
          "loaded_pipelines": {
            "description": "Pipelines currently loaded in memory (warm workers).  A subset of\n`capabilities` — only commands whose workers have been spawned.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "media_mapping_keys": {
            "description": "Named keys from `server.yaml` `media_mappings`, each mapping a\nlogical name (e.g. \"childes-data\") to a filesystem root.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "media_roots": {
            "description": "Filesystem directories the server searches for media files (audio/video).\nConfigured via `server.yaml` `media_roots`.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "memory_gate_aborts": {
            "description": "Backward-compat counter for job deferrals caused by host-memory\nadmission pressure.",
            "format": "int64",
            "type": "integer"
          },
          "memory_gate_threshold_mb": {
            "$ref": "#/components/schemas/MemoryMb",
            "description": "Host-memory reserve threshold in MB from server config.  0 means the\ncoordinator will not keep explicit free-memory headroom."
          },
          "node_id": {
            "$ref": "#/components/schemas/NodeId",
            "description": "Identifier of the current server node."
          },
          "status": {
            "$ref": "#/components/schemas/HealthStatus",
            "description": "Server health status.  Always `Ok` in the current implementation\n(the endpoint itself being reachable implies health), but future\nversions may report degraded states."
          },
          "system_memory_available_mb": {
            "$ref": "#/components/schemas/MemoryMb",
            "description": "Available memory in MB (free + reclaimable).  On macOS this is\n`free + purgeable` which can undercount; see `sysinfo` docs."
          },
          "system_memory_total_mb": {
            "$ref": "#/components/schemas/MemoryMb",
            "description": "Total physical memory in MB."
          },
          "system_memory_used_mb": {
            "$ref": "#/components/schemas/MemoryMb",
            "description": "Used memory in MB (`total - available`)."
          },
          "version": {
            "description": "Server software version (e.g. `\"0.6.0\"`).  Used by the CLI to\ndetect stale daemons and auto-restart them.",
            "type": "string"
          },
          "warmup_status": {
            "$ref": "#/components/schemas/WarmupStatus",
            "description": "Background warmup lifecycle state: `\"not_started\"`, `\"in_progress\"`,\nor `\"complete\"`.  Clients can poll this to know when the server is\nfully ready for low-latency jobs."
          },
          "worker_crashes": {
            "description": "Cumulative count of worker process crashes since server start.\nA high rate suggests resource exhaustion or buggy engine code.",
            "format": "int64",
            "type": "integer"
          },
          "workers_available": {
            "description": "Backward-compat alias for `job_slots_available`.  Older clients read\nthis field; newer clients prefer `job_slots_available`.",
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "HealthStatus": {
        "description": "Server health status.",
        "enum": [
          "ok"
        ],
        "type": "string"
      },
      "HostMemoryPressureLevel": {
        "description": "Host-wide memory pressure level derived from the current memory snapshot and\nreserved headroom.",
        "enum": [
          "healthy",
          "guarded",
          "constrained",
          "critical"
        ],
        "type": "string"
      },
      "JobControlPlaneBackendKind": {
        "description": "Control-plane backend that currently owns orchestration for a server job.",
        "enum": [
          "temporal",
          "test"
        ],
        "type": "string"
      },
      "JobControlPlaneInfo": {
        "description": "Backend-owned orchestration metadata for a job projection.",
        "properties": {
          "backend": {
            "$ref": "#/components/schemas/JobControlPlaneBackendKind",
            "description": "Control-plane backend that produced this projection."
          },
          "temporal": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/TemporalWorkflowExecutionInfo",
                "description": "Temporal workflow execution metadata when `backend == temporal`."
              }
            ]
          }
        },
        "required": [
          "backend"
        ],
        "type": "object"
      },
      "JobId": {
        "description": "Server-assigned identifier for a job (non-empty).",
        "type": "string"
      },
      "JobInfo": {
        "description": "`GET /jobs/{id}` response — job progress.\n\nContains full detail about a single job, including per-file statuses.\nPolled by the CLI to drive progress bars and by the dashboard for\nlive-updating tables.",
        "properties": {
          "active_lease": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/LeaseRecord",
                "description": "Active lease information when this job is currently claimed by a node."
              }
            ]
          },
          "batch_progress": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/BatchInferProgress",
                "description": "Per-language-group progress for batched text commands (morphotag,\nutseg, translate, coref).  Present only while a batch is in flight."
              }
            ]
          },
          "command": {
            "$ref": "#/components/schemas/ReleasedCommand",
            "description": "Batchalign command that was submitted (e.g. \"morphotag\", \"align\")."
          },
          "completed_at": {
            "description": "ISO 8601 timestamp of when the job reached a terminal state.",
            "type": [
              "string",
              "null"
            ]
          },
          "completed_files": {
            "description": "Number of files that have finished processing (status `Done`).\nInvariant: `0 <= completed_files <= total_files`.",
            "format": "int64",
            "type": "integer"
          },
          "control_plane": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/JobControlPlaneInfo",
                "description": "Server control-plane metadata for this job when returned by a server."
              }
            ]
          },
          "current_file": {
            "description": "Filename currently being processed.  `None` when the job is queued\nor has reached a terminal state.",
            "type": [
              "string",
              "null"
            ]
          },
          "duration_s": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/DurationSeconds",
                "description": "Wall-clock duration from first file dispatched to last file finished,\nin seconds.  `None` while the job is still active."
              }
            ]
          },
          "error": {
            "description": "Job-level error message (e.g. worker pool exhaustion, memory gate\ntimeout).  Distinct from per-file errors in `file_statuses`.",
            "type": [
              "string",
              "null"
            ]
          },
          "execution_plan": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ExecutionPlan",
                "description": "Execution plan describing where and how this job is processed.\nPresent for staged-remote jobs; `None` for local execution."
              }
            ]
          },
          "file_statuses": {
            "description": "Per-file processing status, one entry per submitted file.",
            "items": {
              "$ref": "#/components/schemas/FileStatusEntry"
            },
            "type": "array"
          },
          "job_id": {
            "$ref": "#/components/schemas/JobId",
            "description": "Server-assigned UUID (v4) for this job."
          },
          "lang": {
            "$ref": "#/components/schemas/LanguageSpec",
            "description": "Language specification: a resolved ISO 639-3 code or `\"auto\"`."
          },
          "next_eligible_at": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/UnixTimestamp",
                "description": "When the job is deferred before execution, the earliest unix timestamp\nat which it should be retried. `None` when the job is immediately\neligible to run."
              }
            ]
          },
          "num_workers": {
            "description": "Number of concurrent Python workers used for this job.  Determined\nby the pool at dispatch time.  `None` for queued jobs.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "options": {
            "description": "Typed submitted command options captured at job creation time.\n\nThe dashboard uses this to show the original argument/config payload for\ndebugging and operator review without reconstructing a lossy CLI string."
          },
          "source_dir": {
            "description": "Client's original input directory path, used for display in the\ndashboard and CLI output.  May be empty for content-mode submissions.",
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/JobStatus",
            "description": "Current lifecycle state of the job."
          },
          "submitted_at": {
            "description": "ISO 8601 timestamp of when the job was submitted (e.g.\n`\"2026-01-15T10:00:00Z\"`).",
            "type": [
              "string",
              "null"
            ]
          },
          "submitted_by": {
            "description": "IP address or Tailscale identifier of the submitting client.\nUsed for conflict detection (same `submitted_by` + filename =\nduplicate).",
            "type": [
              "string",
              "null"
            ]
          },
          "submitted_by_name": {
            "description": "Human-readable hostname of the submitting machine, resolved from\nTailscale or reverse DNS.  For dashboard display only.",
            "type": [
              "string",
              "null"
            ]
          },
          "total_files": {
            "description": "Total number of files in this job (immutable after submission).",
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "job_id",
          "status",
          "command",
          "options",
          "total_files",
          "completed_files"
        ],
        "type": "object"
      },
      "JobListItem": {
        "description": "Summary for job listing (`GET /jobs` response element).\n\nA lighter-weight projection of [`JobInfo`] without per-file statuses,\nsuitable for listing many jobs at once.",
        "properties": {
          "active_lease": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/LeaseRecord",
                "description": "Active lease information when this job is currently claimed by a node."
              }
            ]
          },
          "command": {
            "$ref": "#/components/schemas/ReleasedCommand",
            "description": "Batchalign command (e.g. \"morphotag\", \"align\")."
          },
          "completed_at": {
            "description": "ISO 8601 timestamp of when the job reached a terminal state.",
            "type": [
              "string",
              "null"
            ]
          },
          "completed_files": {
            "description": "Number of files that finished successfully (`Done`).",
            "format": "int64",
            "type": "integer"
          },
          "control_plane": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/JobControlPlaneInfo",
                "description": "Server control-plane metadata for this job when returned by a server."
              }
            ]
          },
          "duration_s": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/DurationSeconds",
                "description": "Wall-clock duration in seconds.  `None` while the job is active."
              }
            ]
          },
          "error_files": {
            "description": "Number of files that ended in `Error` status.",
            "format": "int64",
            "type": "integer"
          },
          "job_id": {
            "$ref": "#/components/schemas/JobId",
            "description": "Server-assigned UUID (v4) for this job."
          },
          "lang": {
            "$ref": "#/components/schemas/LanguageSpec",
            "description": "Language specification: a resolved ISO 639-3 code or `\"auto\"`."
          },
          "next_eligible_at": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/UnixTimestamp",
                "description": "When the job is deferred before execution, the earliest unix timestamp\nat which it should be retried. `None` when immediately eligible."
              }
            ]
          },
          "num_workers": {
            "description": "Number of concurrent Python workers used for this job.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "source_dir": {
            "description": "Client's original input directory path, for display.",
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/JobStatus",
            "description": "Current lifecycle state of the job."
          },
          "submitted_at": {
            "description": "ISO 8601 timestamp of submission.",
            "type": [
              "string",
              "null"
            ]
          },
          "submitted_by": {
            "description": "IP address or Tailscale identifier of the submitting client.",
            "type": [
              "string",
              "null"
            ]
          },
          "submitted_by_name": {
            "description": "Human-readable hostname of the submitting machine.",
            "type": [
              "string",
              "null"
            ]
          },
          "total_files": {
            "description": "Total number of files in this job.",
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "job_id",
          "status",
          "command",
          "total_files",
          "completed_files"
        ],
        "type": "object"
      },
      "JobResultResponse": {
        "description": "`GET /jobs/{id}/results` response — completed job results.",
        "properties": {
          "files": {
            "description": "Per-file results (empty until the job completes).",
            "items": {
              "$ref": "#/components/schemas/FileResult"
            },
            "type": "array"
          },
          "job_id": {
            "$ref": "#/components/schemas/JobId",
            "description": "Unique job identifier."
          },
          "status": {
            "$ref": "#/components/schemas/JobStatus",
            "description": "Terminal status of the job."
          }
        },
        "required": [
          "job_id",
          "status"
        ],
        "type": "object"
      },
      "JobStatus": {
        "description": "Lifecycle states for a job — mirrors `JobStatus` enum.\n\nJobs progress through a linear lifecycle: `Queued -> Running -> {terminal}`.\nTerminal states (`Completed`, `Failed`, `Cancelled`, `Interrupted`) are\npermanent and never transition further.  Only `Cancelled` and `Failed` jobs\ncan be restarted (which resets them to `Queued`).",
        "enum": [
          "queued",
          "running",
          "completed",
          "failed",
          "cancelled",
          "interrupted",
          "writeback_failed"
        ],
        "type": "string"
      },
      "JobSubmission": {
        "description": "`POST /jobs` request body.",
        "properties": {
          "before_paths": {
            "description": "Absolute paths to \"before\" files for incremental processing\n(paths_mode only). When non-empty, the diff engine compares each\nbefore file against its corresponding source_path and only\nreprocesses changed utterances.\n\nMust be the same length as `source_paths` when non-empty.",
            "items": {
              "$ref": "#/components/schemas/ClientPath"
            },
            "type": "array"
          },
          "command": {
            "$ref": "#/components/schemas/ReleasedCommand",
            "description": "Batchalign command (align, morphotag, etc.)."
          },
          "debug_traces": {
            "description": "When true, the server collects detailed algorithm traces for\nvisualization (DP alignment matrices, ASR pipeline stages, FA\ntimelines, retokenization mappings). Defaults to false — zero\noverhead when off.",
            "type": "boolean"
          },
          "display_names": {
            "description": "Human-readable filenames for display (paths_mode only, optional).",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "files": {
            "description": "CHAT files to process.",
            "items": {
              "$ref": "#/components/schemas/FilePayload"
            },
            "type": "array"
          },
          "lang": {
            "$ref": "#/components/schemas/LanguageSpec",
            "description": "Language specification: a 3-letter ISO code or `\"auto\"` for\nASR-driven detection."
          },
          "media_files": {
            "description": "Media filenames for the server to resolve from media_roots (transcribe only).",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "media_mapping": {
            "$ref": "#/components/schemas/MediaMappingKey",
            "description": "Key into server's media_mappings config (e.g. \"childes-data\")."
          },
          "media_subdir": {
            "$ref": "#/components/schemas/RepoRelativePath",
            "description": "Subdirectory under the mapped root (e.g. \"Eng-NA/MacWhinney/0young-ASR\")."
          },
          "num_speakers": {
            "$ref": "#/components/schemas/NumSpeakers",
            "description": "Number of speakers."
          },
          "options": {
            "description": "Typed command options (engine selections, processing flags, etc.)."
          },
          "output_paths": {
            "description": "Absolute paths to write output files to (paths_mode only).",
            "items": {
              "$ref": "#/components/schemas/ClientPath"
            },
            "type": "array"
          },
          "paths_mode": {
            "description": "When true, server reads/writes files directly via source_paths/output_paths.",
            "type": "boolean"
          },
          "source_dir": {
            "$ref": "#/components/schemas/ClientPath",
            "description": "Client's input directory path (for dashboard display)."
          },
          "source_paths": {
            "description": "Absolute paths to read input files from (paths_mode only).",
            "items": {
              "$ref": "#/components/schemas/ClientPath"
            },
            "type": "array"
          }
        },
        "required": [
          "command",
          "options"
        ],
        "type": "object"
      },
      "LanguageCode3": {
        "description": "3-letter ISO 639-3 language code (e.g. `\"eng\"`, `\"spa\"`).\n\nConstruction validates that the value is exactly 3 ASCII alphabetic\ncharacters, lowercased. Sentinel values like `\"auto\"` are rejected — use\n[`LanguageSpec`] at boundaries where auto-detection is meaningful.",
        "type": "string"
      },
      "LanguageGroupProgress": {
        "description": "Progress snapshot for one language group within a batched infer job.",
        "properties": {
          "completed_utterances": {
            "description": "Number of utterances completed so far.",
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "lang": {
            "description": "ISO 639-3 language code (e.g. \"fra\", \"eng\").",
            "type": "string"
          },
          "total_utterances": {
            "description": "Total utterances in this language group.",
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "lang",
          "completed_utterances",
          "total_utterances"
        ],
        "type": "object"
      },
      "LanguageSpec": {
        "description": "Language specification from the CLI or job submission.\n\n`Auto` means the ASR engine should detect the language. This variant must\nbe resolved to a concrete [`LanguageCode3`] before any CHAT construction\nor NLP dispatch that requires a known language.",
        "oneOf": [
          {
            "description": "Let the ASR engine auto-detect the language.",
            "enum": [
              "Auto"
            ],
            "type": "string"
          },
          {
            "description": "A concrete ISO 639-3 language code.",
            "properties": {
              "Resolved": {
                "$ref": "#/components/schemas/LanguageCode3",
                "description": "A concrete ISO 639-3 language code."
              }
            },
            "required": [
              "Resolved"
            ],
            "type": "object"
          }
        ]
      },
      "LeaseRecord": {
        "description": "Lease metadata for a claimed schedulable unit.\n\nIn single-node mode this is coarse-grained and attached at the job level:\nthe local dispatcher claims a queued job for a node, records the lease, and\nlater clears it when the runner exits. Fleet mode will extend the same shape\nwith real cross-node renewal and expiry handling.",
        "properties": {
          "expires_at": {
            "$ref": "#/components/schemas/UnixTimestamp",
            "description": "Unix timestamp when the lease should be considered expired if not renewed."
          },
          "heartbeat_at": {
            "$ref": "#/components/schemas/UnixTimestamp",
            "description": "Unix timestamp when the lease was created or most recently renewed."
          },
          "leased_by_node": {
            "$ref": "#/components/schemas/NodeId",
            "description": "Identifier of the node that currently owns the lease."
          }
        },
        "required": [
          "leased_by_node",
          "heartbeat_at",
          "expires_at"
        ],
        "type": "object"
      },
      "MediaMappingKey": {
        "description": "Key into `ServerConfig.media_mappings` (e.g. `\"slabank-data\"`).\n\nNot a filesystem path — it's a logical name that maps to a\n[`ServerPath`] via the server's configuration.",
        "type": "string"
      },
      "MemoryMb": {
        "description": "Physical memory quantity in megabytes.\n\nUsed for memory gate thresholds and health-response memory readings.",
        "format": "int64",
        "minimum": 0,
        "type": "integer"
      },
      "NodeId": {
        "description": "Identifier of a server/fleet node.\nEmpty when the node does not report an identity (older server versions).",
        "type": "string"
      },
      "NumSpeakers": {
        "description": "Number of speakers in a recording.",
        "format": "int32",
        "minimum": 0,
        "type": "integer"
      },
      "ProvenanceEntry": {
        "description": "One extracted provenance entry from a CHAT file.",
        "properties": {
          "command": {
            "description": "Command name (e.g., \"morphotag\", \"align\").",
            "type": "string"
          },
          "fields": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Key-value fields (engine, lang, etc.).",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "timestamp": {
            "description": "ISO 8601 timestamp string.",
            "type": "string"
          }
        },
        "required": [
          "command",
          "fields",
          "timestamp"
        ],
        "type": "object"
      },
      "ReleasedCommand": {
        "description": "Closed released command vocabulary used at all Rust seams.\n\nThis is the single canonical command type. Unknown command strings are\nrejected at deserialization boundaries (HTTP 422, DB recovery skip).",
        "enum": [
          "align",
          "transcribe",
          "transcribe_s",
          "translate",
          "morphotag",
          "coref",
          "utseg",
          "benchmark",
          "opensmile",
          "compare",
          "avqi"
        ],
        "type": "string"
      },
      "RepoRelativePath": {
        "description": "A path relative to a data repo root (e.g. `\"French/Newcastle/Photos/13\"`).\n\nValid on any machine that has the repo cloned, but must be combined\nwith a server root path to produce a [`ServerPath`] for I/O.",
        "type": "string"
      },
      "StatusMessageResponse": {
        "description": "Response body for mutating operations that return a status confirmation\n(e.g. cancel, delete, restart).\n\nReturned with HTTP 200 on success. Clients can branch on `status` for\nprogrammatic handling and display `message` to users.",
        "properties": {
          "message": {
            "description": "Human-readable sentence describing the action taken (e.g.\n`\"Job abc123 has been cancelled.\"`).",
            "type": "string"
          },
          "status": {
            "description": "Machine-readable outcome token (e.g. `\"cancelled\"`, `\"deleted\"`,\n`\"restarted\"`). Suitable for switch/match in client code.",
            "type": "string"
          }
        },
        "required": [
          "status",
          "message"
        ],
        "type": "object"
      },
      "TemporalWorkflowExecutionInfo": {
        "description": "Temporal workflow execution metadata attached to a server job projection.",
        "properties": {
          "describe_error": {
            "description": "Error surfaced when the server could not describe the workflow.",
            "type": [
              "string",
              "null"
            ]
          },
          "history_length": {
            "description": "Temporal history length when description succeeded.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "run_id": {
            "description": "Current Temporal run ID when one is known.",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "description": "Current Temporal workflow status, normalized for Batchalign clients.",
            "type": [
              "string",
              "null"
            ]
          },
          "task_queue": {
            "description": "Temporal task queue serving this workflow when known.",
            "type": [
              "string",
              "null"
            ]
          },
          "workflow_id": {
            "description": "Stable Temporal workflow ID used for this job.",
            "type": "string"
          }
        },
        "required": [
          "workflow_id"
        ],
        "type": "object"
      },
      "UnixTimestamp": {
        "description": "Unix timestamp as fractional seconds since epoch.",
        "format": "double",
        "type": "number"
      },
      "WarmupStatus": {
        "description": "Lifecycle state of background model warmup.\nBackground warmup lifecycle state for the worker pool.\n\nThe server pre-spawns workers at startup (\"warmup\") so the first job\ndoes not pay cold-start costs. This enum tracks that lifecycle for\nthe health endpoint.",
        "enum": [
          "not_started",
          "in_progress",
          "complete"
        ],
        "type": "string"
      }
    }
  },
  "info": {
    "description": "batchalign3 application: types, server, worker pool, cache",
    "license": {
      "identifier": "MIT",
      "name": "MIT"
    },
    "title": "batchalign-app",
    "version": "0.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/bug-reports": {
      "get": {
        "description": "Bug reports are JSON files written to disk by the validation layer when\nit detects semantic errors (e.g., alignment mismatches, monotonicity\nviolations). This endpoint scans the reports directory by mtime so the\ndashboard can surface recent failures without requiring database queries.",
        "operationId": "list_bug_reports",
        "parameters": [
          {
            "description": "Maximum number of reports to return",
            "in": "query",
            "name": "limit",
            "required": true,
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bug report documents (newest first)"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bug report storage could not be read"
          }
        },
        "summary": "Return the most recent bug reports, sorted newest-first.",
        "tags": [
          "bug-reports"
        ]
      }
    },
    "/bug-reports/{id}": {
      "get": {
        "description": "The ID corresponds to the JSON filename on disk without the `.json`\nextension. Returns the raw JSON document as-is so the dashboard can\nrender full diagnostic detail (stack traces, file paths, expected vs.\nactual values).",
        "operationId": "get_bug_report",
        "parameters": [
          {
            "description": "Bug report ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bug report JSON document"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bug report not found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bug report storage could not be read"
          }
        },
        "summary": "Return a single bug report by its ID (filename stem).",
        "tags": [
          "bug-reports"
        ]
      }
    },
    "/health": {
      "get": {
        "description": "The response includes worker availability, operational error counters\n(crashes, forced-terminal errors, memory-gate aborts), and the list of\nloaded pipelines so callers can decide whether this server is suitable\nfor a given command without probing individual workers.",
        "operationId": "health",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            },
            "description": "Server health snapshot"
          }
        },
        "summary": "Return a point-in-time health snapshot used by the CLI for server discovery\nand the dashboard for at-a-glance status.",
        "tags": [
          "health"
        ]
      }
    },
    "/jobs": {
      "get": {
        "description": "Used by the dashboard and CLI `jobs` command. The response is intentionally\ncompact -- per-file detail is omitted and available via `GET /jobs/{id}`.",
        "operationId": "list_jobs",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/JobListItem"
                  },
                  "type": "array"
                }
              }
            },
            "description": "List all jobs"
          }
        },
        "summary": "Return a summary of every job the server knows about (active, completed,\nfailed, or cancelled).",
        "tags": [
          "jobs"
        ]
      },
      "post": {
        "description": "Validates the command against built-in tasks and worker-advertised capabilities,\nstages input files (content mode) or records source paths (paths mode), detects\n`(submitted_by, filename)` conflicts with active jobs, and spawns a background\nrunner task that acquires workers and dispatches files. The response echoes the\njob back as `JobInfo` and includes the correlation ID in `X-Request-Id`.",
        "operationId": "submit_job",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JobSubmission"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobInfo"
                }
              }
            },
            "description": "Submitted job"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Validation error"
          }
        },
        "summary": "Accept a new processing job and begin execution.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/jobs/{job_id}": {
      "delete": {
        "description": "Returns 409 if the job is still running -- the caller must cancel it first.\nDeleting a job removes it from the in-memory store and SQLite, and broadcasts\na `JobDeleted` event to connected WebSocket/SSE clients.",
        "operationId": "delete_job",
        "parameters": [
          {
            "description": "Job identifier",
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusMessageResponse"
                }
              }
            },
            "description": "Job deleted"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Job not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Job still running"
          }
        },
        "summary": "Permanently remove a terminal job and its associated state.",
        "tags": [
          "jobs"
        ]
      },
      "get": {
        "description": "This is the primary polling endpoint for the CLI: the client calls it\nrepeatedly until `status` reaches a terminal value.",
        "operationId": "get_job",
        "parameters": [
          {
            "description": "Job identifier",
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobInfo"
                }
              }
            },
            "description": "Job detail"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Job not found"
          }
        },
        "summary": "Return full detail for a single job, including per-file statuses.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/jobs/{job_id}/cancel": {
      "post": {
        "description": "Fires the job's `CancellationToken`, which the runner checks between files.\nAlready-terminal jobs (completed, failed, cancelled) are no-ops. Interrupted\njobs can still be cancelled -- they are not considered terminal here because\nthey may be holding worker resources.",
        "operationId": "cancel_job",
        "parameters": [
          {
            "description": "Job identifier",
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusMessageResponse"
                }
              }
            },
            "description": "Cancel request accepted"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Job not found"
          }
        },
        "summary": "Request cancellation of a running or queued job.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/jobs/{job_id}/restart": {
      "post": {
        "description": "Only jobs in a terminal non-cancelled state can be restarted. The store\nresets per-file statuses and clears errors, then a fresh runner task is\nspawned. This is the primary recovery path after transient worker crashes\nor OOM kills.",
        "operationId": "restart_job",
        "parameters": [
          {
            "description": "Job identifier",
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobInfo"
                }
              }
            },
            "description": "Job restarted"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Job not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Job not restartable"
          }
        },
        "summary": "Reset a failed or interrupted job back to `Queued` and re-run it.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/jobs/{job_id}/results": {
      "get": {
        "description": "Blocks until the job has completed, failed, or been interrupted -- returns\n409 for jobs that are still running or queued. The response includes the\nfull staged content of each successful output file. Paths-mode jobs keep\nthe execution-host write, but also preserve a staged copy for download.\nCancelled jobs are intentionally excluded because they may have incomplete\nresults.",
        "operationId": "get_results",
        "parameters": [
          {
            "description": "Job identifier",
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobResultResponse"
                }
              }
            },
            "description": "Results for terminal jobs"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Job not found"
          }
        },
        "summary": "Retrieve all output files for a terminal job.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/jobs/{job_id}/results/{*filename}": {
      "get": {
        "description": "Waits for the individual file to reach a terminal status, not the whole job,\nso clients can fetch results incrementally as files finish. Supports\nstem-based matching (e.g., requesting `sample.wav` will find `sample.cha`)\nto handle the common case where the output extension differs from the input.",
        "operationId": "get_single_result",
        "parameters": [
          {
            "description": "Job identifier",
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Requested output filename",
            "in": "path",
            "name": "filename",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileResult"
                }
              }
            },
            "description": "One file result"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "File not found"
          }
        },
        "summary": "Retrieve the output for a single file within a job.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/jobs/{job_id}/stream": {
      "get": {
        "description": "Sends:\n- `snapshot` event with current file statuses on connect\n- `file_update` events as files are processed\n- `complete` event when the job reaches a terminal state, then closes",
        "operationId": "stream_job",
        "parameters": [
          {
            "description": "Job identifier",
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SSE event stream"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Job not found"
          }
        },
        "summary": "SSE stream for real-time per-file progress of a single job.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/media/list": {
      "get": {
        "description": "The CLI uses this to let users browse remote media before submitting a job\nthat references files by name (media_files field in `JobSubmission`). Results\ncome from the `MediaResolver` walk cache (60 s TTL) so repeated calls are\ncheap even over NFS mounts.",
        "operationId": "list_media",
        "parameters": [
          {
            "description": "Optional media bank key",
            "in": "query",
            "name": "bank",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Optional subdirectory under bank/root",
            "in": "query",
            "name": "subdir",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Media listing"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid bank/subdir"
          }
        },
        "summary": "List audio/video files available on this server's configured media volumes.",
        "tags": [
          "media"
        ]
      }
    }
  },
  "tags": [
    {
      "description": "Health and readiness endpoints",
      "name": "health"
    },
    {
      "description": "Job submission and lifecycle endpoints",
      "name": "jobs"
    },
    {
      "description": "Media bank and file discovery endpoints",
      "name": "media"
    },
    {
      "description": "Bug report retrieval endpoints",
      "name": "bug-reports"
    }
  ]
}