# Lowkey Media Server HTTP API - the source of truth for docs/server/api.html. # Edit this file, then run: node scripts/build-api-docs.js # media-server/openapi_coverage_test.go fails when a registered route is missing here. openapi: 3.1.0 info: title: Lowkey Media Server HTTP API version: 2.37.0 description: | Every endpoint served by Lowkey Media Server. Paths are relative to the server's address (port 10111 unless changed with `LOWKEY_PORT` or the `port` config key). license: name: MIT url: https://github.com/SteveCastle/loki/blob/master/LICENSE servers: - url: http://localhost:10111 description: Default local server components: securitySchemes: bearer: type: http scheme: bearer description: A JWT from `POST /auth/login` or an `lk_` API key. apiKey: type: apiKey in: header name: X-API-Key description: An `lk_` API key. cookie: type: apiKey in: cookie name: auth_token description: The session cookie set by `POST /auth/login`. schemas: Error: type: object description: >- Error body returned by handlers written for the web client. Older handlers return a plain-text message instead. properties: error: type: string description: Human-readable message. required: - error JobState: type: string enum: - pending - in_progress - paused - completed - cancelled - error description: >- `completed`, `cancelled` and `error` are terminal. `paused` holds progress and can be resumed. Job: type: object description: A job in the queue. properties: id: type: string description: Job id (UUID). command: type: string description: Task id. arguments: type: array items: type: string description: Option tokens passed to the task. input: type: string description: The job input after workflow substitution. original_input: type: string description: The input as submitted. host: type: string description: Concurrency bucket the job runs in. resources: type: array items: type: string description: Additional concurrency buckets the job occupies. dependencies: type: array items: type: string description: Ids of jobs that must complete first. state: $ref: '#/components/schemas/JobState' created_at: type: string format: date-time claimed_at: type: string format: date-time description: Zero time (`0001-01-01T00:00:00Z`) until claimed. completed_at: type: string format: date-time errored_at: type: string format: date-time output_files: type: array items: type: string description: Files the job registered for downstream workflow steps. source_files: type: array items: type: string description: Parallel to `output_files`; the source of each output. workflow_id: type: string description: Set when the job belongs to a workflow. progress_done: type: integer progress_total: type: integer interrupt_count: type: integer description: >- Times the job was found still in progress at server startup (its run died: crash, out of memory, unclean shutdown). After a capped number of auto-resumes the job is failed instead. required: - id - command - arguments - input - original_input - host - resources - dependencies - state - created_at - claimed_at - completed_at - errored_at - output_files - source_files - workflow_id - progress_done - progress_total - interrupt_count AuthUser: type: object description: A user account. required: - id - username - created_at properties: id: type: integer format: int64 username: type: string created_at: type: integer format: int64 description: Unix seconds. APIKey: type: object description: An API key's metadata. The secret is never returned after creation. required: - id - username - name - prefix - created_at - last_used_at properties: id: type: integer format: int64 username: type: string description: User the key acts as. name: type: string prefix: type: string description: First 11 characters of the key (`lk_` + 8 hex). created_at: type: integer format: int64 description: Unix seconds. last_used_at: type: integer format: int64 description: Unix seconds; `0` if never used. HealthStatus: type: object required: - status - version - timestamp - stream - jobs properties: status: type: string enum: - healthy description: Always `healthy` when the server answers. version: type: string description: Server version. timestamp: type: integer format: int64 description: Server time, Unix seconds. stream: type: object description: '`/stream` SSE statistics.' required: - active_connections - total_messages - max_connections - dropped_broadcasts - dropped_client_msgs - rejected_connections properties: active_connections: type: integer total_messages: type: integer max_connections: type: integer dropped_broadcasts: type: integer dropped_client_msgs: type: integer rejected_connections: type: integer jobs: type: object description: Job counts by state. Paused jobs are in `total` only. required: - total - pending - in_progress - completed - cancelled - error properties: total: type: integer pending: type: integer in_progress: type: integer completed: type: integer cancelled: type: integer error: type: integer SchedulerStatus: type: object description: Auto-scheduler status. Fields may be zero values before the first tick. required: - mode - forced - state - reason - done - total - ops - signals properties: mode: type: string enum: - 'off' - auto forced: type: boolean description: A one-shot forced run (`POST /api/scheduler/run`) is active. state: type: string enum: - disabled - waiting - running - yielding - complete reason: type: string description: Human-readable reason for the state, e.g. `the app is in use`, `session locked`. jobId: type: string description: The scheduled job's id, when there is one. Omitted otherwise. done: type: integer description: Items processed by the scheduled job. total: type: integer description: Items the scheduled job will process. ops: type: string description: >- Comma-separated per-item ops the job runs (default `hash,dimensions,describe,transcribe,autotag,embed,faces`). signals: type: object description: The idle signals behind the decision. required: - cpuPercent - sessionLocked - fullscreenBusy - onBattery - inputIdleSeconds - appQuietSeconds properties: cpuPercent: type: number description: Total system CPU percent; `-1` when unknown. sessionLocked: type: string enum: - 'yes' - 'no' - unknown fullscreenBusy: type: string enum: - 'yes' - 'no' - unknown onBattery: type: string enum: - 'yes' - 'no' - unknown inputIdleSeconds: type: number description: Seconds since the last keyboard/mouse input. appQuietSeconds: type: number description: Seconds since the last user-intent request to the server. example: mode: auto forced: false state: waiting reason: the app is in use done: 0 total: 0 ops: hash,dimensions,describe,transcribe,autotag,embed,faces signals: cpuPercent: 12.5 sessionLocked: 'no' fullscreenBusy: 'no' onBattery: 'no' inputIdleSeconds: 3 appQuietSeconds: 20 StorageRoot: type: object description: A storage root (local folder or S3-compatible bucket). required: - type - label properties: type: type: string enum: - local - s3 path: type: string description: Local filesystem path (`local`). label: type: string description: Display name. default: type: boolean description: Destination for uploads and downloads. endpoint: type: string region: type: string bucket: type: string prefix: type: string accessKey: type: string description: '`` on read when set.' secretKey: type: string description: '`` on read when set.' thumbnailPrefix: type: string ByoFaceModel: type: object description: A bring-your-own face recognizer (user-supplied ONNX file). required: - id - modelPath - dim properties: id: type: string description: Unique id; face vectors are keyed by it. name: type: string modelPath: type: string description: Absolute path to the ONNX file. dim: type: integer description: Embedding dimension. inputName: type: string description: Input tensor name (default `data`). outputName: type: string description: Output tensor name (default `fc1`). mean: type: array items: type: number description: Per-channel RGB mean on the 0..255 scale. std: type: array items: type: number description: Per-channel RGB std on the 0..255 scale. InferenceConcurrency: type: object description: Per-provider concurrency caps for vision inference. properties: ollama: type: integer runpod: type: integer lmstudio: type: integer llamacpp: type: integer strata: type: integer ServerConfig: type: object description: >- The server configuration as returned by `GET /api/config` (secrets redacted). Only commonly used keys are described; see the Config page for the meaning of each setting. properties: dbPath: type: string description: Active SQLite library database. port: type: integer description: HTTP port (default 10111). downloadPath: type: string extractorsPath: type: string inferenceProvider: type: string enum: - 'off' - ollama - runpod - lmstudio - llamacpp - strata ollamaBaseUrl: type: string ollamaModel: type: string describePrompt: type: string runpodEndpoint: type: string runpodApiKey: type: string lmstudioBaseUrl: type: string lmstudioModel: type: string lmstudioApiKey: type: string llamacppBaseUrl: type: string llamacppModel: type: string llamacppApiKey: type: string strataBaseUrl: type: string strataModel: type: string strataApiKey: type: string inferenceConcurrency: $ref: '#/components/schemas/InferenceConcurrency' autoProcessOps: type: string description: Comma-separated ops for the auto scheduler's job; empty = all. localComputeConcurrency: type: integer onnxTagger: type: object properties: modelPath: type: string labelsPath: type: string configPath: type: string ortSharedLibraryPath: type: string generalThreshold: type: number characterThreshold: type: number embeddingModel: type: string embeddingProvider: type: string enum: - cpu - directml embeddingPerformance: type: string enum: - low - balanced - max - custom embeddingWorkers: type: integer embeddingThreadsPerWorker: type: integer autotagModel: type: string autotagProvider: type: string autotagPerformance: type: string autotagWorkers: type: integer autotagThreadsPerWorker: type: integer faceModel: type: string faceProvider: type: string facePerformance: type: string faceWorkers: type: integer faceThreadsPerWorker: type: integer faceRouting: type: string enum: - auto - single faceClusterThresholdOffset: type: number faceClusterMinCluster: type: integer faceClusterMinQuality: type: number byoFaceModels: type: array items: $ref: '#/components/schemas/ByoFaceModel' onnxFileTimeoutSeconds: type: integer description: Per-file timeout for local ONNX tasks; `<= 0` disables. transcriptionProvider: type: string transcriptionModel: type: string transcriptionLanguage: type: string transcriptionVadFilter: type: boolean transcriptionInitialPrompt: type: string transcriptionHotwords: type: string transcriptionVocalExtract: type: boolean dreamModel: type: string reshootModels: type: array items: type: object properties: file: type: string label: type: string recipe: type: string enum: - fast - h3 fasterWhisperPath: type: string discordToken: type: string jwtSecret: type: string description: Always `` when set. setupComplete: type: boolean defaultStartPath: type: string allowPublicAccess: type: boolean swipeFeed: type: object additionalProperties: true description: Swipe For You feed tuning. engines: type: object description: GPU engine placement (see the GPU Engines section). properties: strategy: type: string enum: - local - pool - hybrid pools: type: - array - 'null' items: type: object additionalProperties: true routes: type: - object - 'null' additionalProperties: type: string fallback: type: boolean localOnly: type: boolean roots: type: array items: $ref: '#/components/schemas/StorageRoot' rootPaths: type: array items: type: string additionalProperties: true ConfigUpdateRequest: type: object description: >- Fields accepted by `POST /config`. Only `dbPath` is required; see the operation description for which fields are skipped when empty. required: - dbPath properties: dbPath: type: string description: Required, non-blank. A different value switches the library database. port: type: integer minimum: 1 maximum: 65535 description: Applied on restart. Out-of-range or 0 is ignored. downloadPath: type: string ollamaBaseUrl: type: string ollamaModel: type: string describePrompt: type: string inferenceProvider: type: string enum: - 'off' - ollama - runpod - lmstudio - llamacpp - strata description: Lower-cased. runpodEndpoint: type: string runpodApiKey: type: string description: '`` keeps the stored key.' lmstudioBaseUrl: type: string lmstudioModel: type: string lmstudioApiKey: type: string description: '`` keeps the stored key.' llamacppBaseUrl: type: string llamacppModel: type: string llamacppApiKey: type: string description: '`` keeps the stored key.' strataBaseUrl: type: string strataModel: type: string strataApiKey: type: string description: '`` keeps the stored key.' inferenceConcurrency: $ref: '#/components/schemas/InferenceConcurrency' localComputeConcurrency: type: integer onnxModelPath: type: string description: Always applied; omitting it clears it. onnxLabelsPath: type: string description: Always applied; omitting it clears it. onnxConfigPath: type: string description: Always applied; omitting it clears it. onnxOrtSharedLibPath: type: string description: Always applied; omitting it clears it. onnxGeneralThreshold: type: number onnxCharacterThreshold: type: number embeddingModel: type: string embeddingProvider: type: string embeddingPerformance: type: string embeddingWorkers: type: integer embeddingThreadsPerWorker: type: integer autotagModel: type: string autotagProvider: type: string autotagPerformance: type: string autotagWorkers: type: integer autotagThreadsPerWorker: type: integer onnxFileTimeoutSeconds: type: integer description: Non-zero values apply; negative disables the timeout. faceModel: type: string faceRouting: type: string enum: - auto - single description: Other values are ignored. faceProvider: type: string facePerformance: type: string faceWorkers: type: integer faceThreadsPerWorker: type: integer byoFaceModels: type: array items: $ref: '#/components/schemas/ByoFaceModel' description: Replaces the list when present; `[]` clears it. transcriptionProvider: type: string transcriptionModel: type: string transcriptionLanguage: type: string description: Applied when present; empty means auto-detect. transcriptionVadFilter: type: boolean transcriptionInitialPrompt: type: string transcriptionHotwords: type: string transcriptionVocalExtract: type: boolean allowPublicAccess: type: boolean defaultStartPath: type: string fasterWhisperPath: type: string discordToken: type: string description: '`` keeps the stored token.' roots: type: array items: $ref: '#/components/schemas/StorageRoot' description: Replaces the storage roots when present. CreateJobRequest: type: object properties: input: type: string description: >- Command string: ` [option tokens...] `, split on spaces with double-quote grouping (see the operation description). fields: type: object additionalProperties: type: string description: >- Extra options appended verbatim as `-- ` token pairs. Empty keys or values are skipped. required: - input JobSnapshot: type: object description: Response of `GET /api/job/{id}`. Every field is always present. properties: id: type: string description: Job id. command: type: string description: Task id. state: $ref: '#/components/schemas/JobState' progress_done: type: integer description: Items finished (including skips). progress_total: type: integer description: Total items; 0 until the input resolves. output_files: type: - array - 'null' items: type: string description: Files the job registered so far; `null` when none were ever registered. created_at: type: string format: date-time completed_at: type: string format: date-time description: Zero time (`0001-01-01T00:00:00Z`) until completed. log: type: array items: type: string description: The last `tail` log lines, oldest first. required: - id - command - state - progress_done - progress_total - output_files - created_at - completed_at - log JobForPathSummary: type: object properties: id: type: string description: Job id. command: type: string description: Task id. arguments: type: - array - 'null' items: type: string description: Option tokens. state: $ref: '#/components/schemas/JobState' progress_done: type: integer progress_total: type: integer created_at: type: string format: date-time required: - id - command - arguments - state - progress_done - progress_total - created_at TaskInfo: type: object properties: id: type: string description: Task id, used as a job's `command` and as the first token of `POST /create` input. name: type: string description: Display name. options: type: array items: $ref: '#/components/schemas/TaskOption' description: >- Option schema. Always present (possibly empty) on Windows; absent on macOS and Linux builds. required: - id - name TaskOption: type: object description: >- One option a task accepts. Passed to the job as `-- ` or `--=` in `arguments` (or as a `POST /create` `fields` entry). Unknown option tokens are ignored by the task. properties: name: type: string description: Option name (the flag without `--`). label: type: string description: Display label. type: type: string enum: - string - bool - enum - multi-enum - number description: > How the value is parsed: - `bool`: `--name` alone means true; `--name=true|1|yes` or a following `true`/`false`/`1`/`0`/`yes`/`no` token sets it explicitly. - `number`: parsed as a float; an unparsable value leaves the default. - `string`, `enum`, `multi-enum`: the following token (unless it starts with `--`) or the `=` value, as a string. choices: type: array items: type: string description: Allowed values for `enum` and `multi-enum`. Omitted when empty. default: description: >- Value used when the option is absent (string, boolean, number or array depending on the task). Omitted when the option has no default, in which case it defaults to `false`, `0` or an empty string by type. required: type: boolean description: Marked as required in the UI. Omitted when false. description: type: string description: Help text. Omitted when empty. required: - name - label - type WorkflowTask: type: object description: One DAG node; becomes one job. properties: id: type: string description: >- Node id, unique within the DAG and referenced by other nodes' `dependencies`. In saved workflows it is a template id replaced by a fresh UUID at run time; in `POST /workflow` it becomes the job id. command: type: string description: Task id (see `GET /tasks`). arguments: type: - array - 'null' items: type: string description: Option tokens, already split (for example `["--apply", "all"]`). input: type: string description: >- The node's own input. At claim time each dependency's output files are appended one per line. dependencies: type: - array - 'null' items: type: string description: Ids of nodes in the same DAG that must complete first. pos_x: type: number description: Editor canvas position. Omitted when 0. pos_y: type: number description: Editor canvas position. Omitted when 0. required: - id - command SavedWorkflowSummary: type: object properties: id: type: string description: Workflow id (UUID). name: type: string description: Unique workflow name. required: - id - name SavedWorkflow: type: object properties: id: type: string description: Workflow id (UUID). name: type: string description: Unique workflow name. dag: type: array items: $ref: '#/components/schemas/WorkflowTask' description: The DAG nodes. required: - id - name - dag SavedWorkflowInput: type: object description: Body of `POST /workflows/create` and `PUT /workflows/{id}`. properties: name: type: string description: Workflow name; must be unique. dag: type: array items: $ref: '#/components/schemas/WorkflowTask' description: >- Non-empty DAG. Every node needs a non-empty, unique `id` and a `command`; every dependency must name a node in this DAG. required: - dag WorkflowRunResponse: type: object properties: ids: type: - array - 'null' items: type: string description: >- The created job ids, in node order. `null` when the DAG was empty (`POST /workflow` only). required: - ids StreamConnectedEvent: type: object description: Data of the unnamed message sent once when a `/stream` connection opens. properties: type: type: string const: connected msg: type: string const: SSE connection established required: - type - msg JobListEvent: type: object description: Data of the `create`, `update` and `delete` events. properties: updateType: type: string enum: - create - update - delete description: Same as the event name. job: $ref: '#/components/schemas/Job' html: type: string description: The job rendered as a table row for the admin Jobs page. required: - updateType - job - html StdoutEvent: type: object description: Data of the `stdout-` event. properties: updateType: type: string const: stdout line: type: string description: One log line. required: - updateType - line ProgressEvent: type: object description: Data of the `progress` event. properties: updateType: type: string const: progress id: type: string description: Job id. done: type: integer description: Items finished. total: type: integer description: Total items. required: - updateType - id - done - total PeopleUpdatedEvent: type: object description: Data of the `people-updated` event. properties: models: type: - array - 'null' items: type: string description: Face model ids whose clustering ran; empty after a manual edit. required: - models DuplicatesUpdatedEvent: type: object description: Data of the `duplicates-updated` event. Counts are informational; clients refetch. properties: groups: type: integer description: Groups written so far by the scan (0 after a manual action). items: type: integer description: Items in those groups (0 after a manual action). required: - groups - items MediaPathsEvent: type: object description: Data of the `media-updated` and `media-created` events (never sent with an empty list). properties: paths: type: array items: type: string description: Affected file paths. required: - paths SchedulerEvent: type: object description: >- Data of the `scheduler` event; the auto scheduler's status. Sent only when `mode`, `state`, `reason` or `jobId` changes. properties: mode: type: string enum: - 'off' - auto forced: type: boolean description: A one-shot run-now override is active. state: type: string enum: - disabled - waiting - running - yielding - complete reason: type: string description: Human-readable explanation of the state. jobId: type: string description: The scheduler's current job. Omitted when none. done: type: integer total: type: integer ops: type: string description: Operations the scheduler runs. signals: type: object description: System signals the scheduler reads. properties: cpuPercent: type: number sessionLocked: type: string enum: - 'yes' - 'no' - unknown fullscreenBusy: type: string enum: - 'yes' - 'no' - unknown onBattery: type: string enum: - 'yes' - 'no' - unknown inputIdleSeconds: type: number appQuietSeconds: type: number required: - cpuPercent - sessionLocked - fullscreenBusy - onBattery - inputIdleSeconds - appQuietSeconds required: - mode - forced - state - reason - done - total - ops - signals StatsEvent: type: object description: >- Data of the `stats` event; the same object `GET /api/stats` returns (snapshot plus live progress deltas). Only the counters are listed here; see that endpoint for the full shape. additionalProperties: true properties: ready: type: boolean generatedAt: type: integer description: Unix seconds the snapshot was computed. totalMedia: type: integer totalVideos: type: integer totalAudio: type: integer totalImages: type: integer totalTranscribable: type: integer description: Videos plus audio. withDescription: type: integer withHash: type: integer withSize: type: integer withTags: type: integer withDimensions: type: integer withTranscript: type: integer withEmbedding: type: integer withFaceScan: type: integer autotagModel: type: object description: Active autotag model info. embedModel: type: object description: Active embedding model info. faceModel: type: object description: Active face model info. MediaQueryRequest: type: object description: >- Body of `POST /api/media/query`. There is no paging, limit or cursor; the full result is returned. properties: mode: type: string enum: - AND - OR default: AND description: >- Connector for predicates without their own `join`. Anything other than exactly `OR` means `AND`. predicates: type: array items: $ref: '#/components/schemas/MediaQueryPredicate' description: Evaluated left to right. Missing or empty returns the whole library. MediaQueryPredicate: type: object description: > One filter or ranking term. `value` semantics by `type`: - `tag`: exact tag label; the item has that tag. - `category`: exact category label; the item has any tag in that category. - `path`, `description`, `hash`: substring match (`LIKE '%value%'`, case-insensitive for ASCII; `%` and `_` in the value are wildcards). - `orientation`: `landscape`, `portrait` or `square` (case-insensitive), comparing stored width and height. Items without dimensions never match an include and are kept by an exclude. Other values match nothing. - `faces`: only `ungrouped`: items with at least one detected face and no face assigned to a person. Other values match nothing. - `dupe`: a duplicate group id (active, non-excluded members of that group), `pending` (members of pending groups) or `any`/`all` (every grouped item, dismissed groups included). Other values match nothing. - `similar` (visual): a library media path; ranks by image-embedding similarity to it, embedding the file on the fly if it has no vector. - `visual` (visual): free text; text-to-image search. - `clip` (visual): an image as a base64 data URL (`data:image/png;base64,...`) or bare base64; image-to-image search. - `face` (visual): a library media path or an image data URL; face-identity search, one hit per media item. Ignores `text` and `nodes`. For an exclude of a "matches nothing" value (unknown orientation, faces or dupe value, or a visual predicate with no hits), nothing is removed. required: - type - value properties: type: type: string enum: - tag - category - path - description - hash - orientation - faces - dupe - similar - visual - clip - face value: type: string description: Operand; meaning depends on `type`. An empty value removes the predicate from the query. exclude: type: boolean default: false description: Negate the predicate (`NOT EXISTS`, `NOT LIKE`, `NOT IN`). join: type: string enum: - AND - OR - '' description: >- Connector to the running result of the predicates before it. Missing, empty or any other value falls back to `mode`. Ignored on the first predicate. text: type: string description: >- Legacy blend, `similar` and `clip` only. Free text mixed into the image query as one combined vector. Without `nodes` it is a two-way image/text blend; with `nodes` it is folded in as one more text term weighted by `textWeight`. textWeight: type: number minimum: 0 maximum: 1 default: 0.5 description: >- Share of `text` in the blend, clamped to 0 to 1 (0 = pure image, 1 = pure text). Missing means 0.5. nodes: type: array items: $ref: '#/components/schemas/MediaQueryBlendNode' description: >- Composite similarity for `similar`, `clip` and `visual`. The predicate's own `value` is the base term with weight 1; each node adds a signed weighted term. Nodes with weight 0 are skipped. blendMode: type: string enum: - blend - shared - '' default: blend description: >- How a predicate with `nodes` is scored. `blend` (or empty, or any value other than `shared`) combines all terms into one centroid vector. `shared` scores candidates against every positive term at once (must match all), finding what the positive terms have in common. MediaQueryBlendNode: type: object required: - kind - value properties: kind: type: string enum: - image - clip - text description: >- `image` = a library media path, `clip` = an image data URL or base64, `text` = free text. Any other kind fails the query with `500`. value: type: string description: Path, data URL or text. Blank `text` nodes are skipped. weight: type: number minimum: 0 maximum: 1 description: Magnitude, clamped to 0 to 1. Missing means 1; 0 drops the node. negative: type: boolean default: false description: Subtract this term, steering results away from it. MediaListItem: type: object description: >- One item in a list result. Nullable database columns are omitted when NULL (a real zero is still sent). required: - path - mtimeMs properties: path: type: string description: Media path. mtimeMs: type: integer description: >- The driving tag assignment's `created_at` (milliseconds) when a tag predicate drives the row, otherwise `0`. Not the file's modification time. elo: type: number description: Battle Mode rating. battles: type: integer description: Battle Mode bout count. height: type: integer description: Pixel height. width: type: integer description: Pixel width. weight: type: number description: Weight of the driving tag assignment. tagLabel: type: string description: Label of the driving tag assignment. timeStamp: type: number description: Video timestamp (seconds) of the driving tag assignment. score: type: number description: >- Similarity score; present on every item, and only then, when the query had a visual predicate. SimilarHit: type: object required: - path - score properties: path: type: string description: Media path. score: type: number description: Cosine similarity in the active embedding model's space. ScoredMediaItem: type: object description: >- A ranked hit enriched with the item's row. Columns that are NULL, or the whole row when the path has no media row (an orphaned embedding), are omitted. required: - path - mtimeMs - score properties: path: type: string mtimeMs: type: integer description: Always `0`. elo: type: number battles: type: integer height: type: integer width: type: integer score: type: number description: Similarity score; items are sorted by it, highest first. FaceSearchItem: allOf: - $ref: '#/components/schemas/ScoredMediaItem' - type: object required: - faceId - face properties: faceId: type: integer description: Id of the best-matching face in this item. face: type: object description: That face's box, relative to the media (0 to 1). required: - x - 'y' - w - h - frameTs - personId properties: x: type: number 'y': type: number w: type: number h: type: number frameTs: type: number description: Video frame time the face was detected at; `0` for images. personId: type: integer description: Person the face is assigned to; `0` when ungrouped. MediaPathRequest: type: object required: - path properties: path: type: string description: Media path. MediaMetadata: type: object required: - fileMetadata - hash properties: fileMetadata: type: object required: - size - modified - width - height properties: size: type: string description: >- Human-readable size from the stored byte count, such as `2.41 MB`; `0 Bytes` when unknown. modified: type: string description: Always an empty string. width: type: integer description: Stored width; `0` when unknown. height: type: integer description: Stored height; `0` when unknown. hash: type: string description: Stored content hash; empty when unknown. description: type: string description: Present when the item has a description. transcript: type: string description: Present when the item has a transcript. textChunks: type: object additionalProperties: type: string description: >- Generator text embedded in a local file (for example PNG text chunks), keyed by chunk name. Omitted when there are none. MediaTagAssignment: type: object required: - tag_label - category_label - weight - time_stamp properties: tag_label: type: string category_label: type: string weight: type: number time_stamp: type: number description: Video timestamp in seconds; `0` for an untimed assignment. GifMetadata: type: object required: - frameCount - duration properties: frameCount: type: integer description: Frames counted by ffprobe; `0` when unreported. duration: type: number description: Duration in seconds; `0` when unreported. ThumbnailCache: type: string enum: - thumbnail_path_100 - thumbnail_path_600 - thumbnail_path_1200 default: thumbnail_path_600 description: Thumbnail size column (100, 600 or 1200 px). MediaEraseResult: type: object description: Rows removed per table by delete/forget. required: - path - media - tags - embeddings - faces - battles properties: path: type: string media: type: integer description: Media rows removed (0 or 1). tags: type: integer description: Tag assignment rows removed. embeddings: type: integer description: Embedding rows removed. faces: type: integer description: Face rows removed. battles: type: integer description: Battle-log rows removed. MediaMoveResult: type: object required: - from - to - prefix - dryRun - items - rows - total properties: from: type: string description: Normalised source (trimmed of whitespace and trailing separators). to: type: string description: Normalised destination. prefix: type: boolean dryRun: type: boolean items: type: integer description: Number of media rows whose path changed. rows: type: object additionalProperties: type: integer description: >- Rows updated per `table.column` key (for example `media.path`, `media_tag_by_category.media_path`), including zero entries. Tables missing from the library have no key. total: type: integer description: Sum of `rows`. paths: type: array items: type: object required: - from - to properties: from: type: string to: type: string description: Up to 100 sample rewrites, ordered by old path. Omitted when nothing matched. truncated: type: boolean description: True when more than 100 items moved; omitted otherwise. MediaMergeResult: type: object required: - target - sources - tags - embeddings - transcript - transcriptFile - deleted - failed - facesRemoved properties: target: type: string sources: type: array items: type: string tags: type: integer description: Tag rows the target gained. embeddings: type: integer description: Embedding rows the target gained. transcript: type: boolean description: True when the target's transcript was filled or a `.vtt` sidecar was moved next to it. transcriptFile: type: string description: Path of the moved sidecar; empty when none. deleted: type: - array - 'null' items: type: string description: Sources removed from disk and database. `null` when none. failed: type: - array - 'null' items: type: string description: Sources that kept their file and rows (`s3://`, or deletion failed). `null` when none. facesRemoved: type: integer description: Face rows erased with the sources. HlsStatus: type: object required: - status properties: status: type: string enum: - ready - processing - queued - idle - error description: '`queued` = waiting for the single ffmpeg slot; `idle` = nothing cached and `check=true`.' url: type: string description: Master playlist URL, when `ready`. progress: type: number minimum: 0 maximum: 1 description: Fraction done while processing; omitted when 0. duration: type: number description: Source duration in seconds; only on the response that starts generation. error: type: string description: Failure message, when `error`. LegacyMediaItem: type: object required: - path - description - size - hash - width - height - tags - exists - duplicateCount properties: path: type: string description: type: - string - 'null' size: type: - integer - 'null' description: Bytes. hash: type: - string - 'null' width: type: - integer - 'null' height: type: - integer - 'null' tags: type: array items: $ref: '#/components/schemas/LegacyMediaTag' exists: type: boolean description: Whether the file currently exists. duplicateCount: type: integer description: Declared but never populated by this endpoint; always `0`. LegacyMediaTag: type: object required: - label - category properties: label: type: string category: type: string EmptyObject: type: object description: An empty object, `{}`. additionalProperties: false LabelBody: type: object properties: label: type: string description: Tag label. RenameBody: type: object properties: label: type: string description: Current label. newLabel: type: string description: New label. WeightBody: type: object properties: label: type: string description: Tag label. weight: type: number description: Sort weight. TaxonomyCategory: type: object required: - label - weight - tagViewMode - tags properties: label: type: string weight: type: number description: Sort weight. tagViewMode: type: string description: How the viewer lists the tags (`card` when unset). tags: type: array items: type: object required: - label - category - weight properties: label: type: string category: type: string weight: type: number CategorySummary: type: object required: - label - weight - description - tagViewMode - tagGrouping properties: label: type: string weight: type: number description: Sort weight. description: type: string description: Empty string when unset. tagViewMode: type: string description: '`card` when unset.' tagGrouping: type: string enum: - 'on' - 'off' description: Whether the category's tags are listed under their groups. TaxonomyTag: type: object required: - label - category - weight properties: label: type: string category: type: string description: Empty string for a tag with no category. weight: type: number group: type: - string - 'null' description: 'Present only with `?category=`: the tag''s group, or `null` when ungrouped.' TagDetail: type: object required: - label - category - weight - description - thumbnail_path_600 - group properties: label: type: string category: type: string description: Empty string for a tag with no category. weight: type: number description: type: string description: Empty string when unset. thumbnail_path_600: type: - string - 'null' description: Stored preview thumbnail path. group: type: - string - 'null' description: The tag's group. TagWithCount: type: object required: - label - category - weight - media_count properties: label: type: string category: type: string description: Empty string for a tag with no category. weight: type: number media_count: type: integer description: Distinct media paths carrying the tag. CategoryImpact: type: object description: What deleting a category removes (or removed). required: - label - exists - tags - groups - assignments - media properties: label: type: string exists: type: boolean description: Whether the category exists. tags: type: integer description: Tags filed under the category. groups: type: integer description: Tag groups in the category. assignments: type: integer description: Assignment rows removed with them. media: type: integer description: Distinct media items those assignments are on. TagGroupRef: type: object required: - categoryLabel - label properties: categoryLabel: type: string description: The group's category. label: type: string description: Group label. TagGroup: type: object required: - label - weight - hidden - viewMode properties: label: type: string weight: type: number description: Sort weight. hidden: type: boolean description: Left out of the taxonomy panel unless hidden groups are shown. viewMode: type: - string - 'null' enum: - card - list - null description: Override of the category's tag view mode; `null` follows the category. IndexStatus: type: object required: - index - active_model - media_total - missing_active_model - orphaned - embeddings - total_count - total_bytes properties: index: type: object description: The in-memory search index. required: - installed - model - vectors properties: installed: type: boolean description: An index is loaded. model: type: string description: Model the index was built from; empty when none. vectors: type: integer description: Vectors in the index. active_model: type: string description: The configured embedding model. media_total: type: integer description: Rows in the media table. missing_active_model: type: integer description: Media items with no embedding for the active model. orphaned: type: integer description: Embedding rows whose media row is gone. embeddings: type: array description: Stored rows per model. items: type: object required: - model - count - dim - bytes properties: model: type: string count: type: integer dim: type: integer bytes: type: integer description: Stored vector bytes. total_count: type: integer description: Embedding rows across all models. total_bytes: type: integer description: Stored vector bytes across all models. EmbedModelInfo: type: object required: - id - display_name - dim - multimodal - active - indexed properties: id: type: string display_name: type: string dim: type: integer description: Vector dimension. multimodal: type: boolean description: Supports text queries in the same space. active: type: boolean description: The configured embedding model. indexed: type: boolean description: The model the in-memory index holds. StoredEmbeddingRow: type: object required: - model - dim - created_at properties: model: type: string dim: type: integer created_at: type: integer description: Stored creation time; the embed tasks currently write `0`. vector: type: array items: type: number description: Present only with `vector=true`. LibraryStats: type: object required: - ready - generatedAt - totalMedia - totalVideos - totalAudio - totalImages - totalTranscribable - withDescription - withHash - withSize - withTags - withDimensions - withTranscript - withEmbedding - withFaceScan - autotagModel - embedModel - faceModel properties: ready: type: boolean enum: - true generatedAt: type: integer description: Unix seconds when the snapshot was computed. totalMedia: type: integer totalVideos: type: integer description: 'By extension: .mp4 .mov .avi .mkv .wmv .webm.' totalAudio: type: integer description: 'By extension: .mp3 .wav .aac .ogg .m4a .wma .ape .flac .opus .aiff.' totalImages: type: integer description: Everything that is not video or audio. totalTranscribable: type: integer description: Videos plus audio; the transcript denominator. withDescription: type: integer withHash: type: integer withSize: type: integer withTags: type: integer withDimensions: type: integer withTranscript: type: integer description: Among videos and audio only. withEmbedding: type: integer description: For the active embedding model. withFaceScan: type: integer description: Scanned by any face model. autotagModel: $ref: '#/components/schemas/StatsModelInfo' embedModel: $ref: '#/components/schemas/StatsModelInfo' faceModel: $ref: '#/components/schemas/StatsModelInfo' StatsModelInfo: type: object required: - id - name properties: id: type: string name: type: string description: Display name. DBQueryResult: type: object required: - columns - rows - row_count - truncated - elapsed_ms properties: columns: type: array items: type: string rows: type: array description: 'One array per row, cells in column order. A BLOB cell is `{"blob_bytes": n}`.' items: type: array items: {} row_count: type: integer description: Rows returned. truncated: type: boolean description: More rows existed beyond `limit`. elapsed_ms: type: integer description: Query and read time in milliseconds. FSEntry: type: object required: - name - path - isDir - mtimeMs - size properties: name: type: string path: type: string isDir: type: boolean mtimeMs: type: number description: Modification time in milliseconds since the epoch (`0` for roots). size: type: integer description: Bytes; `0` for directories. type: type: string enum: - local - s3 description: Present only when listing the roots. UploadResult: type: object required: - success - files properties: success: type: boolean files: type: - array - 'null' items: type: string description: Stored paths; `null` on failure. message: type: string description: Present on success. error: type: string description: Present on failure. ImportResult: type: object required: - imported - skipped - files - dest_root properties: imported: type: integer description: New media items merged in. skipped: type: integer description: Items already present, skipped whole. files: type: integer description: File bytes copied into the destination root. dest_root: type: string description: Path of the destination storage root. warnings: type: array items: type: string description: Non-fatal problems; omitted when empty. TreemapNode: type: object required: - name - path - count - covered properties: name: type: string description: Folder name (empty at the library root). path: type: string description: Folder path exactly as stored; pass it back as `path` to drill down. count: type: integer description: Metric rows in the subtree. covered: type: integer description: Distinct items in the subtree that have rows. direct: type: integer description: Rows for files directly in this folder. Omitted when 0. itemCount: type: integer description: Items in this folder's subtree (non-`items` metrics only). Omitted when 0. children: type: array items: $ref: '#/components/schemas/TreemapNode' description: Largest first, up to `limit`. Omitted at the depth limit or when empty. otherCount: type: integer description: Rows in children beyond `limit`. Omitted when 0. otherDirs: type: integer description: Number of children beyond `limit`. Omitted when 0. Person: type: object description: >- A named (or auto-named `Unknown #N`) cluster of faces. Every person has a name so it can live in the taxonomy as a People-category tag. properties: id: type: integer format: int64 name: type: string description: >- Stored name. May end in `_cluster` when a tag in another category owns the plain name; UIs strip the suffix for display. coverFaceId: type: integer format: int64 description: >- Face used as the preview crop (`/media/facecrop?id=`): the chosen cover when it still belongs to the person, else the best face (confidence times bbox area). Omitted when the person has no faces. faceCount: type: integer description: Faces assigned to the person. mediaCount: type: integer description: Distinct media items containing the person. lockedCount: type: integer description: Faces that are user assignments (confirmed); these survive every recluster. createdAt: type: integer format: int64 description: Unix seconds. Omitted when unknown. models: type: string description: >- Comma-separated recognizer id(s) of the person's faces (normally one, e.g. `anime-ccip` for a drawn-character cluster). Omitted when the person has no faces. required: - id - name - faceCount - mediaCount - lockedCount Face: type: object description: >- One stored face detection. Bounding-box coordinates are relative (0-1 of the image size). Crops are served by `/media/facecrop?id=`. properties: id: type: integer format: int64 x: type: number description: Left edge (relative). 'y': type: number description: Top edge (relative). w: type: number description: Width (relative). h: type: number description: Height (relative). score: type: number description: Detection confidence. frameTs: type: number description: Video frame time in seconds (0 for images). personId: type: integer format: int64 description: Assigned person; 0 when unassigned. assignedBy: type: string enum: - auto - user - '' description: '`auto` (clustering), `user` (confirmed by hand), or empty when unassigned.' required: - id - x - 'y' - w - h - score - frameTs - personId - assignedBy PersonReviewFace: type: object description: One face in the person review payload. properties: id: type: integer format: int64 description: Face id. path: type: string description: Media path. frameTs: type: number description: Video frame time in seconds (0 for images). detScore: type: number description: Detection confidence. assignedBy: type: string enum: - auto - user description: '`auto` (clustering) or `user` (confirmed).' typicality: type: number description: >- Cosine similarity to the group center (see the operation). Low values are the outliers worth reviewing first; 0 when it cannot be computed (single face or mixed-dimension group). required: - id - path - frameTs - detScore - assignedBy - typicality UngroupedFace: type: object description: One face not yet assigned to any person. properties: id: type: integer format: int64 description: Face id. path: type: string description: Media path. frameTs: type: number description: Video frame time in seconds (0 for images). detScore: type: number description: Detection confidence. model: type: string description: Recognizer id. required: - id - path - frameTs - detScore - model FaceHitItem: type: object description: >- A `ScoredMediaItem` (one per media path) with the best matching face attached. `score` is that face's cosine similarity. allOf: - $ref: '#/components/schemas/ScoredMediaItem' - type: object properties: faceId: type: integer format: int64 description: The matching face. face: type: object description: The matching face's relative bounding box. properties: x: type: number 'y': type: number w: type: number h: type: number frameTs: type: number description: Video frame time in seconds. personId: type: integer format: int64 description: Assigned person; 0 when unassigned. required: - x - 'y' - w - h - frameTs - personId required: - faceId - face FaceTuning: type: object description: Face-grouping tuner (the People panel Tune sliders), stored in the server config. properties: thresholdOffset: type: number description: Added to the clustering similarity threshold, -0.2 to 0.3. Default 0. minCluster: type: integer description: Minimum faces for a new group, 1-50. Default 3. minQuality: type: number description: Minimum face quality, between 0 and 1 exclusive. Default 0.75. required: - thresholdOffset - minCluster - minQuality FaceStats: type: object properties: faces: type: array description: Per recognizer, ordered by model id. items: type: object properties: model: type: string description: Recognizer id. count: type: integer description: Stored faces. bytes: type: integer format: int64 description: Total vector blob bytes. required: - model - count - bytes total_faces: type: integer total_bytes: type: integer format: int64 scans: type: integer description: Face-scan markers (items scanned, including those with no faces). people: type: object properties: total: type: integer named: type: integer description: People with a non-empty name. unnamed: type: integer required: - total - named - unnamed index: type: object description: The in-memory face search index. properties: model: type: string description: Recognizer the index holds; empty when not built. vectors: type: integer description: Vectors in the index. required: - model - vectors required: - faces - total_faces - total_bytes - scans - people - index DuplicateGroup: type: object description: >- A cluster of media whose visual embeddings are at least `threshold` similar to the anchor item. properties: id: type: integer format: int64 model: type: string description: Embedding model the scan used. threshold: type: number description: Similarity floor the scan used, 0-1. anchorPath: type: string description: The item every member score is measured against. keeperPath: type: string description: >- Default merge target: the highest-resolution active member, then the largest file, then the anchor, then the shortest path. The anchor when no member is active. status: type: string enum: - pending - dismissed createdAt: type: integer format: int64 description: Unix seconds. updatedAt: type: integer format: int64 description: Unix seconds. memberCount: type: integer description: Every member row, excluded ones included. activeCount: type: integer description: Members not excluded. minScore: type: number description: Lowest active member similarity to the anchor (how tight the group is). members: type: array items: $ref: '#/components/schemas/DuplicateMember' description: Anchor first, then by similarity, excluded members last. required: - id - model - threshold - anchorPath - keeperPath - status - createdAt - updatedAt - memberCount - activeCount - minScore - members example: id: 311 model: siglip2 threshold: 0.97 anchorPath: D:/photos/IMG_0001.jpg keeperPath: D:/photos/IMG_0001.jpg status: pending createdAt: 1761900000 updatedAt: 1761900000 memberCount: 2 activeCount: 2 minScore: 0.985 members: - path: D:/photos/IMG_0001.jpg mtimeMs: 0 width: 4032 height: 3024 battles: 0 size: 3311221 score: 1 excluded: false anchor: true keeper: true - path: D:/photos/IMG_0001 (1).jpg mtimeMs: 0 width: 1600 height: 1200 size: 402113 score: 0.985 excluded: false anchor: false keeper: false DuplicateMember: type: object description: >- A group member in the flat renderer item shape plus review flags. `elo`, `battles`, `width`, `height` and `size` are omitted when unknown. properties: path: type: string mtimeMs: type: integer description: Always 0. elo: type: number battles: type: integer width: type: integer height: type: integer size: type: integer format: int64 description: File size in bytes; present only when known and non-zero. score: type: number description: Cosine similarity to the anchor (the anchor scores 1). excluded: type: boolean description: Pulled out of the group ("not a duplicate"). anchor: type: boolean description: This member is the anchor. keeper: type: boolean description: This member is the default merge target. required: - path - mtimeMs - score - excluded - anchor - keeper DuplicateStats: type: object properties: pending: type: integer description: Pending groups. dismissed: type: integer description: Dismissed groups. members: type: integer description: Member rows across all groups. pendingItems: type: integer description: 'Active members of pending groups: library items still awaiting a decision.' required: - pending - dismissed - members - pendingItems DuplicateMergeResult: type: object description: What a merge changed. The same shape as the `POST /api/media/merge-metadata` response. properties: target: type: string description: The kept path. sources: type: array items: type: string description: Paths merged in. tags: type: integer format: int64 description: Tag rows the target gained. embeddings: type: integer format: int64 description: Embedding rows the target gained. transcript: type: boolean description: >- The target's transcript was filled from a source, or a source's `.vtt` sidecar was moved next to it. transcriptFile: type: string description: The moved `.vtt` path; empty when none. deleted: type: - array - 'null' items: type: string description: Sources removed from disk and database. `null` when none. failed: type: - array - 'null' items: type: string description: >- Sources that could not be deleted (s3:// paths, delete errors); they keep their rows. `null` when none. facesRemoved: type: integer format: int64 description: Face rows erased with the sources. required: - target - sources - tags - embeddings - transcript - transcriptFile - deleted - failed - facesRemoved SwipeMediaTag: type: object properties: label: type: string category: type: string required: - label - category SwipeMediaItem: type: object description: A media row as the Swipe app receives it. properties: path: type: string description: type: - string - 'null' description: AI description; `null` when none. size: type: - integer - 'null' format: int64 description: File size in bytes. hash: type: - string - 'null' description: Content hash. width: type: - integer - 'null' height: type: - integer - 'null' tags: type: - array - 'null' items: $ref: '#/components/schemas/SwipeMediaTag' description: May be `null` when the item has no tags. exists: type: boolean description: Whether the file exists on disk. duplicateCount: type: integer format: int64 description: Other items with the same hash. required: - path - description - size - hash - width - height - tags - exists - duplicateCount SwipeResponse: type: object properties: items: type: - array - 'null' items: $ref: '#/components/schemas/SwipeMediaItem' description: The page. The shuffle mode returns `null` (not an empty array) when the pool is empty. has_more: type: boolean description: More items exist past this page. total_count: type: integer description: Not populated by this endpoint; always 0. required: - items - has_more - total_count SwipeManifest: type: object description: Web app manifest (fixed content). properties: name: type: string short_name: type: string description: type: string start_url: type: string display: type: string orientation: type: string background_color: type: string theme_color: type: string icons: type: array items: type: object properties: src: type: string sizes: type: string type: type: string purpose: type: string required: - src - sizes - type - purpose required: - name - short_name - description - start_url - display - orientation - background_color - theme_color - icons PromptReference: type: object description: One image, clip or audio file the model sees, with the token the prompt uses for it. properties: token: type: string description: For example `` (retouch) or ``, `