# API Reference Base URL: `https://api.nomadkaraoke.com` (production) or `http://localhost:8000` (local) > **Edge:** production traffic must go through `https://api.nomadkaraoke.com` > (proxied by Cloudflare — WAF + rate limiting). The Cloud Run origin is > **origin-locked**: requests hitting the raw `*.run.app` URL directly are > rejected with `403` unless they carry the Cloudflare-injected `X-Edge-Auth` > header (`/` and `/api/health*` are exempt for probes). See > [ARCHITECTURE.md § Edge Security](ARCHITECTURE.md#edge-security-cloudflare). ## Authentication All endpoints except `/health` and `/api/themes` require authentication. ```bash curl -H "Authorization: Bearer YOUR_TOKEN" ... ``` ## Endpoints ### Health ```http GET /health ``` No auth required. Returns service status. #### Encoding Worker Health ```http GET /health/encoding-worker ``` No auth required. Returns GCE encoding worker status for frontend display. Response: ```json { "available": true, "status": "ok", "version": "0.95.1", "active_jobs": 0, "queue_length": 0 } ``` Status values: - `ok` - Worker is healthy and available - `offline` - Worker is unavailable (includes `error` field) - `not_configured` - Encoding worker not configured on backend #### Flacfetch Service Health ```http GET /health/flacfetch ``` No auth required. Returns flacfetch service status for frontend display. Response: ```json { "available": true, "status": "ok", "version": "1.2.3" } ``` Status values: - `ok` - Flacfetch service is healthy and available - `offline` - Service is unavailable (includes `error` field) - `not_configured` - Flacfetch service not configured on backend ### Jobs #### Create Job from URL ```http POST /api/jobs Content-Type: application/json { "url": "https://www.youtube.com/watch?v=...", "artist": "Artist Name", // optional, auto-detected if omitted "title": "Song Title", // optional, auto-detected if omitted "is_private": false, // optional "duration_seconds": 245.3, // optional — from /api/jobs/estimate; drives pre-flight credit deduction "acknowledged_credits": 1 // optional — if provided, server validates it equals the computed cost; 409 on mismatch } ``` Creates a job from a YouTube (or other supported) URL. Credit cost is `max(1, ceil(minutes/10))` (10-minute tiers). If `duration_seconds` is omitted the system deducts 1 credit as a hold and settles the true cost after download (see [Duration-Based Pricing](#duration-based-pricing)). Admin jobs bypass all credit deduction. `acknowledged_credits` is **optional**. If provided, the server validates it equals the server-computed credit cost and returns 409 on mismatch (race-condition guard for the UI). If omitted, the server charges the computed cost without client confirmation. Returns `JobResponse` (job id, status, etc.). **Errors:** - `402` — Insufficient credits (see [Credit Enforcement](#credit-enforcement)) - `409` — `acknowledged_credits` was provided and does not match server-computed cost; client should refresh and re-confirm - `422` — Input exceeds 60-minute hard limit #### Estimate URL Duration (pre-flight) ```http POST /api/jobs/estimate Content-Type: application/json {"url": "https://www.youtube.com/watch?v=..."} ``` Probes the URL (via flacfetch `/check-youtube`) **without creating a job or downloading audio**. Use this before `POST /api/jobs` to show the user the credit cost. Response: ```json { "duration_seconds": 245.3, "credits": 1, "blocked": false, "source": "youtube_metadata" } ``` - `duration_seconds`: `null` if the probe fails (bot challenge, unsupported URL, etc.) - `source`: `"youtube_metadata"` | `"unknown"` (probe failed) - `blocked`: `true` when `duration_seconds > 3600` (60 min) — create will be rejected - `credits`: computed from `max(1, ceil(duration_seconds / 600))`; `1` when duration unknown When `duration_seconds` is `null`, warn the user that the final cost will be confirmed after download and create the job with a 1-credit hold. #### Confirm Duration (resume paused job) ```http POST /api/jobs/{job_id}/confirm-duration Content-Type: application/json {"acknowledged_credits": 3} ``` Called when a job is paused in `AWAITING_DURATION_CONFIRM` state. Two scenarios: - **`preflight`** — upload flow: duration measured after file lands in GCS; no charge applied yet. `acknowledged_credits` must equal the full cost (`pending_additional_credits` in `state_data`). - **`reconcile`** — post-download: actual duration costs more than was already charged. `acknowledged_credits` must equal the new total (`credits_charged + pending_additional_credits`). On success, deducts the owed credits and resumes by triggering both audio and lyrics workers. Returns the updated job. **Errors:** - `402` — Insufficient credits; user should buy more and retry - `409` — `acknowledged_credits` doesn't match server's current figure (race/refresh); client should re-fetch the job and re-show the dialog #### Create Job with Upload ```http POST /api/jobs/upload Content-Type: multipart/form-data file: