HTTP API Reference

On success the JWT is returned in the body and also set as the auth_token cookie (HttpOnly, SameSite=Lax, Path=/, expiring after 365 days, the same lifetime as the token). CORS on this route echoes a chrome-extension:// or moz-extension:// origin, otherwise allows http://localhost:1212, with credentials. OPTIONS answers 200 with no body.

Expires the auth_token cookie. It does not revoke the JWT itself: a copy of the token held elsewhere stays valid until it expires. Any method other than POST and OPTIONS (for example a browser GET /auth/logout) clears the cookie and answers 302 to /login.

Never fails: an invalid credential reports loggedIn: false. Header credentials are checked first. When the credential is the auth_token cookie, the response also carries the session's JWT in token, so the embedded web viewer can use it as a Bearer token. The handler does not check the method; every method except OPTIONS behaves like GET.

The route skips the auth middleware so the first account can be created before any credential exists (see POST); the handler itself requires a valid credential (header or cookie) to list users.

Open without a credential only while setup is required (the temporary admin account is the only account). After that the caller must present a valid credential (header or cookie). Creating a user also deletes the temporary admin account if it still exists. The username admin is reserved.

Requires a valid credential (header or cookie). The last remaining user cannot be deleted. Deleting a username that does not exist still answers 200.

Step 1 of the RFC 8252 loopback flow with PKCE used by lokictl login and the viewer's "Sign in with browser". The client listens on 127.0.0.1:<port>, generates a PKCE verifier and opens this page. Only the auth_token cookie session counts here (header credentials are ignored). With no session the browser is redirected to /login?redirect=<this URL>. The page shows the key name and user, and posts the same parameters back to this URL with action=approve or action=deny.

Submitted by the approval page. The redirect target is always built server-side as http://127.0.0.1:<port>/callback. On approve, a one-time authorization code bound to the session user, the PKCE challenge and the key name is minted (single use, expires after 2 minutes) and the browser is sent to ...callback?code=<code>&state=<state>. On deny (any action other than approve), it is sent to ...callback?error=access_denied&state=<state>. If the browser sends an Origin header, its host must equal the request Host.

Step 2 of the loopback flow. The code is consumed on the first attempt whether or not the verifier matches. On success a new lk_ API key is minted for the approving user, named after the name given to the authorize page.

Registered without the auth middleware, so it needs no credential even though it reports job counts. Sets fully permissive CORS headers (Access-Control-Allow-Origin: *); OPTIONS answers 200. Paused jobs are counted in jobs.total but in no per-state bucket.

Reloads the config file and returns it. Every non-empty secret is replaced by the literal <redacted>: jwtSecret, discordToken, runpodApiKey, lmstudioApiKey, llamacppApiKey, strataApiKey, storage-root accessKey/secretKey, and engine pool API keys and node tokens. Empty secrets stay empty (and storage-root credentials, being omitempty, are then absent). POST /config treats <redacted> as "keep the stored value", so a read-modify-write round trip is safe.

Runs on the machine the server runs on. Only useful when the server is on the same desktop as the user.

Not a full replacement: the server starts from its in-memory configuration and overwrites only the fields below, mostly only when they are present and non-empty (strings) or positive (numbers), so partial posts are safe. Exceptions:

• dbPath is required on every call.
• onnxModelPath, onnxLabelsPath, onnxConfigPath and onnxOrtSharedLibPath are assigned unconditionally, so omitting them clears them.
• Pointer-style fields (transcriptionLanguage, transcriptionVadFilter, transcriptionInitialPrompt, transcriptionHotwords, transcriptionVocalExtract, allowPublicAccess, defaultStartPath) and the arrays byoFaceModels and roots apply whenever present, including empty values; omitted means unchanged.
• Secret fields equal to <redacted> keep the stored value; storage roots posted with <redacted> credentials recover them from the stored root with the same bucket+endpoint+prefix, else the same label.

Keys not accepted here (for example engines, swipeFeed, reshootModels, dreamModel, autoProcessOps, setupComplete, jwtSecret) are ignored. After saving, the server switches databases if dbPath changed (clearing the auth_token cookie, since users and keys live in the library database), rebuilds the embedding or face index in the background when the active model changed, rebuilds storage backends, and re-applies concurrency caps. A port change takes effect on restart.

Queues a one-task workflow. The struct has no JSON tags, so the canonical keys are Command and Arguments; Go's case-insensitive decoding also accepts command and arguments. The last element of Arguments is the task input; the rest are the task's option tokens. Prefer POST /create.

Serves the latest snapshot with live task progress applied, and starts a background recount when the snapshot is stale. Until the first snapshot after startup (or after a database switch) exists, the response is just {"ready": false}; poll until ready is true.

Coverage counts ignore rows whose media item no longer exists. Transcript coverage is counted against videos and audio only, embedding coverage against the active embedding model, and face-scan coverage against items scanned by any face model. Between recounts, live progress can make a count drift slightly; it never exceeds its denominator.

Queues one job. The input string is split into tokens by these rules:

• Tokens are separated by the space character only (tabs and newlines are not separators and stay inside tokens).
• A double quote (") toggles quoting; spaces inside quotes are kept. The quote characters themselves are removed. There is no escape syntax, so a token cannot contain a literal double quote. Quoting can start mid-token (a"b c"d is one token ab cd).
• Empty tokens are discarded.

The first token is the task id. If there is more than one token, the last token is the job input and the tokens in between become arguments. A single-token string creates a job with no arguments and an empty input.

Each non-empty key/value pair of fields is then appended to arguments as two tokens, --<key> and <value>, verbatim (no splitting or unquoting), so values can contain spaces, quotes or newlines. Pairs with an empty key or empty value are skipped. Map order is not preserved, and any key is accepted. Task options are parsed with the last occurrence winning, so a fields entry overrides the same option given in input.

The task id is not validated here: an unknown task is accepted and the job fails when it runs. The job is assigned to a fresh single-node workflow (its workflow_id is set).

Returns all jobs held in memory (every job not yet removed or cleared), newest first. There is no paging or filtering. Job log lines are not included; use GET /api/job/{id} or the stdout-<jobId> stream event.

Server-rendered admin page for one job, with its log and live output over /stream. This is a page for browsers, not a JSON API; use GET /api/job/{id} for machine-readable job state. The handler does not check the method, so any method renders the page.

Cancels a pending, in_progress or paused job: its context is cancelled and its state becomes cancelled immediately. A running task keeps its concurrency slots until it actually returns. Dependents of the job are not cancelled.

The handler ignores the queue's result, so it answers 200 even when the id does not exist or the job is already in a terminal state (nothing changes in those cases).

A pending job becomes paused at once. For an in_progress job a pause is requested: the task finishes the item it is working on, then the job parks in paused with its progress kept. Tasks that do not poll for pause requests run to completion.

Returns a paused job to pending so it is claimed again. The task re-resolves its input and skips items it already processed.

Creates a new pending job with a fresh id and the same command, arguments, original input, dependencies, host, resources and workflow id. Progress, outputs, log and timestamps are reset.

Removes the job from the queue and the database in any state, and broadcasts a delete event. It does not cancel a running task (the task keeps running unobserved); cancel first.

Removes every job in a terminal state (completed, cancelled, error) and broadcasts a delete event for each. pending, in_progress and paused jobs are kept.

A compact JSON snapshot for pollers (for example Lowkey Studio following a splat job cross-origin with an API key). Sent with Cache-Control: no-store.

Answers from the queue's in-memory path index. Only active jobs (pending, in_progress, paused) are returned. Jobs whose input is a path list appear as soon as they are created; jobs whose input is a query appear once they resolve it when claimed.

Lists every task id that can be used as a job command, sorted by id. On Windows each task also carries its options (an empty array when it has none). The macOS and Linux builds return only id and name, with no options field.

Queues one job per node, in array order, all sharing a new workflow id. Unlike saved workflows, the DAG is not validated and node ids are used as the job ids verbatim (a node with an empty id gets a generated UUID, but then nothing can depend on it). Node ids must therefore be globally unique across the queue; a clash fails the request part way, leaving earlier nodes queued. A dependency on an id that never becomes a completed job leaves the dependent pending forever.

Ids and names only, ordered by name. Empty library returns [].

Validates the DAG (non-empty; every node has a non-empty id and command; node ids unique; every dependency names a node in the DAG) and stores it under a new UUID. Cycles are not detected. Names must be unique; name is not otherwise checked and may be empty.

Both name and dag are replaced (an omitted name becomes empty). The DAG is validated as for create.

Jobs already started from the workflow are not affected.

Loads the template, gives every node a fresh UUID (dependencies are remapped to match), and queues one job per node in DAG order under a new workflow id. When input is non-empty it is injected into every root node (a node with no dependencies): appended after a space to the node's own input, or used as-is when the node's input is empty. Node pos_x / pos_y are dropped.

Opens a text/event-stream (Cache-Control: no-cache, Access-Control-Allow-Origin: *, never compressed). The route is registered without the auth middleware, so it is open to anyone who can reach the port regardless of the Allow Public Access setting; it carries job metadata and job output lines.

On connect the server first sends one unnamed message (a plain message event) whose data is StreamConnectedEvent. A comment line : keep-alive follows every 30 seconds. Then, for each broadcast, event: <name> plus data: <JSON>:

• create, update, delete: a job was added (including copies), changed state, or was removed or cleared. Data: JobListEvent. For delete only job.id is meaningful; every other field is a zero value.
• stdout-<jobId>: one log line from that job. Data: StdoutEvent.
• progress: item progress of a job (throttled to about 4 per second per job; the first and final updates always go out). Data: ProgressEvent.
• people-updated: person groupings changed (face clustering finished a model, or a manual People edit). Data: PeopleUpdatedEvent; models is empty for manual edits. Refetch people.
• duplicates-updated: duplicate-candidate groups changed (the find-duplicates task, or a manual review action). Data: DuplicatesUpdatedEvent; counts are 0 for manual actions. Refetch duplicates.
• media-updated: the save task overwrote these files in place; bust caches. Data: MediaPathsEvent.
• media-created: the save task wrote these new files. Data: MediaPathsEvent.
• scheduler: the auto scheduler changed mode, state, reason or job. Data: SchedulerEvent.
• stats: library statistics changed (coalesced; at most one per second). Data: StatsEvent, the same object as GET /api/stats.

At most 5000 concurrent connections are accepted. Connections that see no traffic for about two minutes are reaped (keep-alives count as traffic).

The main library query. Predicates are combined left to right: the first predicate with a non-empty value is the base, and each later one is connected to the running result by its own join, or by mode when join is missing or not AND/OR. The expression is parenthesised left-associatively, so a OR b AND c means (a OR b) AND c. Predicates with an empty value are ignored. With no usable predicates the whole library is returned.

The four visual types (similar, visual, clip, face) are resolved through the embedding index into a candidate set of at most 1000 paths, which then takes part in the boolean expression like any other predicate. When every connector is AND and the query mixes visual and non-visual predicates, evaluation is filter-first: the non-visual predicates run first and similarity is scored only inside that set, so the result is the top 1000 most similar items within the filter. If that filter matches nothing, the model is not called at all.

Ordering: - Without a visual predicate the server emits no ORDER BY; the order is whatever SQLite returns (the viewer sorts client side). Every item omits score. - With a visual predicate every item carries score and items are sorted by it, highest first. When several visual predicates match the same item the highest score is kept; items that matched only a non-visual branch of an OR get score 0.

An unknown predicate type produces invalid SQL and a 500.

The handler does not check the method; clients send POST.

With an empty or missing tags array, returns every item in the library ordered by path (tag fields are empty strings and 0).

With tags, mode (case-insensitive, default EXCLUSIVE) chooses the semantics: - EXCLUSIVE: items that carry every listed tag, one row per item, ordered by path. The tag fields come from one of the item's matching assignments. - Any other value: one row per matching tag assignment, ordered by path. An item carrying two of the tags, or one tag at several video timestamps, appears more than once.

Only POST is handled. Any other method gets an empty 200 response with no body.

Returns every item whose description contains the given text (SQL LIKE '%text%', case-insensitive for ASCII; % and _ in the text act as wildcards). Ordered by path. An empty description matches every item that has a non-NULL description.

tags and filteringMode are accepted in the body but ignored.

The handler does not check the method; clients send POST.

Ranks the library by cosine similarity to the item's embedding in the active embedding model. When the item has no stored vector it is embedded on the fly (and the vector is saved). The item itself is usually the top hit.

The handler does not check the method.

Embeds the text with the active embedding model's text encoder and ranks the library by cross-modal similarity.

The handler does not check the method.

The request body is the raw bytes of an image in any common format (no multipart, no JSON). Returns the 50 most similar items; the count is fixed.

The handler does not check the method.

The request body is the raw bytes of an image. Faces are detected in it and matched against stored face embeddings. limit counts faces searched; hits are then collapsed to one item per media path (best face wins), so the result can hold fewer items than limit.

Reads the item's row (width, height, size, description, transcript, hash). A path with no row still answers 200 with the defaults. For local files the handler also extracts generator text chunks (for example a ComfyUI workflow or WebUI parameters) into textChunks.

The handler does not check the method; clients send POST.

Every row of the item's tag assignments, one per tag and video timestamp. An unknown path returns an empty list.

The handler does not check the method; clients send POST.

Runs ffprobe -count_frames on the first video stream. When ffprobe fails or reports no stream the response is JSON null with status 200.

The handler does not check the method; clients send POST.

Returns the thumbnail's location as a JSON string: a local filesystem path on the server, or an s3:// URL for media in a bucket. To fetch the image bytes use GET /media/thumbnail instead.

Lookup order: the path recorded in the item's thumbnail column (if the file or object still exists), then for local media the deterministic cache path on disk, then generation (throttled). Results are written back to the item's row.

cache that is not a string, or an empty string, returns null without doing anything. A string that is not one of the three column names is treated as thumbnail_path_600. Without a configured database path, local media returns null.

The handler does not check the method; clients send POST.

Writes description to the item's row. An empty string stores an empty description. A path with no row changes nothing and still returns 200.

The handler does not check the method; clients send POST.

Only fields present in the body are written; a body with just path reads. The response always reflects the row after the update.

The Elo math runs server side in one transaction, and the vote is appended to the battle log. Ratings start at 1500. The K-factor depends on how many battles the item has fought: 48 under 10, 24 under 30, 12 after that. A win adds 1 to the winner's wins and the loser's losses; a draw changes neither. battles is reset from the battle-log count. A path with no library row gets one created.

Erases every database reference to the path: the media row, tag assignments, embeddings, faces and their curation assertions (vetoes, cannot-links), person cover pointers, face-scan markers and battle-log rows, and evicts the path from the in-memory vector and face indexes. The file on disk is never deleted. Identical to /api/media/forget.

The handler does not check the method; clients send POST.

Same implementation and response as /api/media/delete; meant for media the viewer can no longer load (file gone or unreachable).

The handler does not check the method; clients send POST.

The bookkeeping half of a move: the filesystem is never touched, the caller has already moved the file(s). All references are rewritten in one transaction: media.path, media_tag_by_category.media_path, media_embedding.media_path, face.media_path, face_scan.media_path, battle.winner_path, battle.loser_path, duplicate_member.media_path and duplicate_group.anchor_path. Tables that do not exist in the library are skipped (their key is absent from rows).

from and to are trimmed of whitespace and trailing / or \. With prefix, both are folders and every item under from moves under to keeping its sub-path. Matching is segment-aligned (/a/foo never drags /a/foobar) and case-sensitive.

With dryRun the whole move runs and is rolled back, so the counts are exactly what a real run would change.

If any destination path already belongs to another library item that is not itself moving, nothing changes and the answer is 409. This check also applies to dry runs.

After a real move the vector and face indexes are re-keyed for the paths listed in paths. When truncated is true only the first 100 were re-keyed; rebuild the index to refresh the rest.

The handler does not check the method; clients send POST.

The first non-blank path is the target; every other distinct path is a source. The merge is additive: tag rows and per-model embedding rows the target lacks are copied in (the target's own rows win), an empty transcript is filled from the first source that has one, and that source's .vtt sidecar is moved next to the target. The sources are then deleted from disk (plus leftover sidecars) and every database reference to them is erased. s3:// sources and files that fail to delete keep their file and rows and are listed in failed.

The handler does not check the method; clients send POST.

Assigns one face of the item: when the item has several faces, the one most similar to the person's existing faces wins; for a person with no faces yet (always the case with newPerson) the largest face wins. The item is face-scanned on the fly when it has no stored faces yet.

With newPerson: true a new person is created (named name, or the next automatic "Unknown" name) only after a face has been found, so a face-less item never leaves an empty group behind; setCover is then implied. The assignment is recorded as a user action.

The inverse of assign-person: each of the person's faces on the item gets a permanent veto plus cannot-links and is unassigned, so the group actually loses those faces. Used by the Electron viewer when a person tag is removed from an item. The person is identified by personId, or by display name when personId is missing or not positive.

Looks at the item's thumbnail_path_600 and thumbnail_path_1200 columns and reports each one that is set, with whether the file exists on local disk and its size. The 100 px cache is not reported. s3:// thumbnails always report exists: false.

The handler does not check the method; clients send POST.

Removes the cached file at the deterministic cache path, generates a new one, stores it in the item's column and returns its path. Only local media is supported (there is no S3 branch). An unrecognised cache is treated as thumbnail_path_600.

The handler does not check the method; clients send POST.

• Local files stream through http.ServeFile with Range support, no size limit, Content-Type from the extension (unknown extensions are application/octet-stream), Content-Length, Cache-Control: public, max-age=3600 and an ETag of the form "<name>-<size>-<mtime>". A matching If-None-Match answers 304.
• HEIC/HEIF files, which browsers cannot decode, are served as a cached JPEG rendering instead.
• s3:// paths answer 302 to a presigned URL.
• http(s):// paths (admins only) are proxied through an SSRF-safe client: only the remote Content-Type, Content-Length, Cache-Control and ETag are copied (default Cache-Control: public, max-age=1800), and bodies are cut at 100 MB.

Lookup order: a thumbnail recorded in the item's cache column (an existing s3:// object is answered with a 302 to a presigned URL), then for s3:// media generation into the bucket followed by a 302, then for local media the recorded file, the deterministic cache path, and finally generation (throttled). Generated paths are stored on the item's row.

Local thumbnails are sent with Cache-Control: public, max-age=86400, immutable and an ETag of "<file name>-<size>"; a matching If-None-Match answers 304, and Range is supported. Video thumbnails are short .mp4 clips (video/mp4). Image thumbnails are PNG data in extensionless files, so they are labelled application/octet-stream.

Renditions are a stream-copy (no re-encode) VOD HLS stream with 6-second MPEG-TS segments, cached under the server's data directory keyed by the SHA-256 of path. One ffmpeg runs at a time; other requests queue.

Without check=true, a video that is neither cached nor in progress starts generating and the response is processing with the probed duration. Poll until ready, then load url in an HLS player. A failed generation is reported once as error and its partial output removed; the next request starts again.

Responses carry Access-Control-Allow-Origin: *.

With path, removes that video's renditions; without it, removes the entire HLS cache. The route is read, but this method always needs admin credentials when Allow Public Access is on (anonymous callers get 401 JSON).

Served by the /media/hls/ prefix route. {hash} is the cache key from the url returned by GET /media/hls. The file must match master.m3u8 or stream.m3u8 at this level (segment names pass validation too, but are served with the playlist content type). Supports Range; carries Access-Control-Allow-Origin: *.

Served by the /media/hls/ prefix route. Normally reached through the master playlist. The server currently only generates the passthrough preset. .ts files are sent as video/MP2T, playlists as application/vnd.apple.mpegurl. Supports Range; carries Access-Control-Allow-Origin: *.

Decodes the face's source media (for a video, the same midpoint frame the face scan used; the stored 600 px thumbnail is a last resort), cuts out the face box with a 35% margin, and scales it so the longer edge is size. Sent with Cache-Control: private, max-age=86400 (a face id's crop never changes; rescans mint new ids). JPEG quality 88.

Returns an object keyed by category label (not an array), in the same shape as the desktop app's taxonomy. Keys are inserted in category weight order, and each category's tags are ordered by tag weight. On large libraries this is a big payload; the web client loads /api/taxonomy/categories and then /api/taxonomy/tags?category= per category instead. The method is not checked.

Ordered by weight. Pairs with /api/taxonomy/tags?category= so a client can load tags one category at a time. The method is not checked.