Endpoints¶

Every route, grouped by family. All limits are per client IP.

Health¶

GET /health¶

Unauthenticated liveness probe. Used by the container health check.

{"status": "ok"}

Pages¶

Authentication¶

See API Authentication.

Jobs¶

POST /api/submit¶

Form-encoded, CSRF-protected. 10/minute. Like every other mutating route under /api/*, it requires the X-CSRF-Token header (or a csrf_token field) — see API Authentication.

Returns the created job. 409 with {"detail": "duplicate_job", "existing_job": {...}} when an active or completed job already matches. 503 when the queue is full.

The metadata probe runs with an 8 s budget and fills video_title and duration_seconds on the new row, so the job carries a title and a length before the download starts. A probe that fails or times out leaves both null and the job is still created.

GET /api/jobs¶

60/minute. Query: offset (≥ 0, default 0), limit (1–100, default 50).

Returns an array of job objects:

[
  {
    "id": "0f5c...", "url": "https://...", "platform": "youtube",
    "video_title": "...", "video_meta_hover": "...",
    "type": "audio", "quality": "max", "status": "analysis_done",
    "created_at": "2026-09-01 12:00:00", "finished_at": "2026-09-01 12:01:14",
    "message": null, "filesize_bytes": 5242880, "duration_seconds": 214,
    "codec": "mp3", "bitrate_kbps": 192,
    "bpm": 128, "bpm_confidence": 0.87,
    "audio_hash": "...", "filename": "Some Track.mp3"
  }
]

GET /api/jobs/{job_id}¶

60/minute. One job, same shape. 404 if unknown.

POST /api/jobs/{job_id}/cancel¶

30/minute. Terminates the running subprocess.

POST /api/jobs/{job_id}/retry¶

10/minute. Allowed only from error and cancelled — retrying an in-flight or successful job would race the worker or duplicate a finished download. The existing row is reset in place, keeping its id and its position in the list, and every result field from the failed attempt (message, filesize, codec, …) is cleared so no stale data shows while the retry runs.

POST /api/jobs/remove-all¶

2/minute. Deletes every job row and its artifacts. No undo.

GET /api/info¶

20/minute. Query: url. Resolves title, duration, and thumbnail before submitting.

Events (SSE)¶

text/event-stream, keep-alive every 5 s, 32-event queue per client, 200 concurrent connections maximum.

Media¶

Thumbnail routes validate the content type against the actual bytes, and only fetch from allow-listed hosts.

Trimming¶

Audio jobs only, downloadable status, 1 second to 10 minutes. trim_id is <start_ms>_<end_ms>. See Audio Trimming.

Lalal.ai¶

Lalal.ai always performs a vocals/instrumental split; stem selects which result comes back. See Stem Separation.

Cookies¶

platform is youtube, tiktok, instagram, or facebook. Max 256 KiB, UTF-8. See Platform Cookies.

Share links¶

{"ok": true, "url": "https://.../share/aB3xY7_q", "max_uses": 5}

Every redeem failure returns the same 404 page. See Share Links.

Settings¶

Writable keys: retention_days, enable_authentication, admin_username, admin_password, session_idle_minutes, download_concurrent_fragments, download_compatible_output, video_watermark, lalalaai_duration_guard, share_link_max_uses, public_hostname.

• Unknown keys are silently ignored, not rejected with an error
• Values are parsed and range-checked server-side
• download_concurrent_fragments accepts 0 for automatic host-based sizing
• admin_username and admin_password must be sent as a pair — the salt is username-derived, so a rename re-hashes and needs the plaintext
• Enabling authentication without stored credentials returns 400
• Internal keys (admin_password_hash, session_version, statistics_reset_at) are never writable
• The watermark logo endpoint takes a PNG, never an SVG: the Settings page accepts both, uploads a PNG unchanged and rasterizes a dropped SVG in the browser first. The server re-derives format, size, aspect ratio and transparency from the uploaded bytes and answers 400 with the reason when any of them fails — see Downloads

Statistics and system¶

Error shape¶

{"detail": "Invalid type. Allowed: audio, video"}