## Summary - Add optional "Display As" fields to audio search, allowing users to search for audio by one artist/title but display a different artist/title on title screens and filenames - Useful for Broadway casts, covers, remixes where tracker metadata differs from desired display ## Changes - Add `display_artist`/`display_title` fields to `AudioSearchRequest` model - Update job creation to use display values for output (title screens, filenames, YouTube, distribution) - Add "Display As" optional fields to frontend search UI - Update API documentation ## Example Use Case - **Search For**: Artist = "Jeremy Kushnier", Title = "I Can't Stand Still" - **Display As**: Artist = "Footloose (Broadway Cast)" - **Result**: Audio found using "Jeremy Kushnier", but title screen shows "Footloose (Broadway Cast) - I Can't Stand Still" ## Test plan - [ ] Search with display override → verify title screen shows display values - [ ] Search without display override → verify search values used (backwards compatible) - [ ] Verify filenames use display values @coderabbitai ignore 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>
12 KiB
API Reference
Base URL: https://api.nomadkaraoke.com (production) or http://localhost:8000 (local)
Authentication
All endpoints except /health and /api/themes require authentication.
curl -H "Authorization: Bearer YOUR_TOKEN" ...
Endpoints
Health
GET /health
No auth required. Returns service status.
Jobs
Create Job with Upload
POST /api/jobs/upload
Content-Type: multipart/form-data
file: <audio file>
artist: "Artist Name"
title: "Song Title"
Returns job ID. Triggers async processing.
Get Job Status
GET /api/jobs/{job_id}
Response includes:
status- Current job statefile_urls- Signed URLs for outputs (when ready)state_data- Worker progress detailstimeline- Processing history
List Jobs
GET /api/jobs
GET /api/jobs?status=complete
GET /api/jobs?limit=10&offset=0
Delete Job
DELETE /api/jobs/{job_id}
Review
Get Correction Data
GET /api/review/{job_id}/correction-data
Returns lyrics correction data for the review UI.
Complete Review
POST /api/review/{job_id}/complete
Content-Type: application/json
{
"corrections": [...],
"corrected_segments": [...]
}
Saves corrections and triggers video rendering.
Generate Preview
POST /api/review/{job_id}/preview-video
Generates preview video during review.
Stream Audio
GET /api/review/{job_id}/audio/{stem_type}
Streams audio for review playback.
Instrumental Selection
POST /api/jobs/{job_id}/select-instrumental
Content-Type: application/json
{
"selection": "clean" // or "with_backing"
}
Audio Search
Search for Audio
POST /api/audio-search/search
Content-Type: application/json
{
"artist": "Artist Name",
"title": "Song Title",
"auto_download": false,
"theme_id": "nomad",
"display_artist": "Display Artist (optional)",
"display_title": "Display Title (optional)"
}
Searches for audio sources (flacfetch integration). Creates a job and returns search results.
Key fields:
artist,title- Used to search for audio on trackersdisplay_artist,display_title- Optional overrides for how artist/title appear on title screens and filenames. If omitted, search values are used.auto_download- If true, automatically selects best result and starts processingtheme_id- Video theme to use
Use case: Search for "Jeremy Kushnier" but display "Footloose (Broadway Cast)" on the karaoke video.
Get Search Results
GET /api/audio-search/{job_id}/results
Returns cached search results for a job awaiting audio selection.
Select Audio Source
POST /api/audio-search/{job_id}/select
Content-Type: application/json
{
"selection_index": 0
}
Selects an audio source from the search results and starts processing.
Themes
GET /api/themes
No auth required. Returns available video themes.
Internal (Admin Only)
These endpoints are used by workers and require admin tokens.
POST /api/internal/jobs/{job_id}/trigger-audio
POST /api/internal/jobs/{job_id}/trigger-lyrics
POST /api/internal/jobs/{job_id}/trigger-screens
POST /api/internal/jobs/{job_id}/trigger-render-video
POST /api/internal/jobs/{job_id}/trigger-video
Job States
| State | Description |
|---|---|
pending |
Created, not started |
downloading |
Processing input |
separating_stage1 |
Audio separation (1/2) |
separating_stage2 |
Audio separation (2/2) |
transcribing |
Lyrics transcription |
generating_screens |
Title/end screens |
awaiting_review |
Waiting for human review |
in_review |
Human reviewing |
review_complete |
Review submitted |
rendering_video |
Generating karaoke video |
awaiting_instrumental_selection |
Waiting for selection |
instrumental_selected |
Selection made |
generating_video |
Final encoding |
complete |
Done |
failed |
Error |
Error Responses
{
"detail": "Error message"
}
Common status codes:
400- Bad request401- Unauthorized404- Job not found500- Server error
User Authentication
Send Magic Link
POST /api/users/auth/magic-link
Content-Type: application/json
{"email": "user@example.com"}
Verify Magic Link
GET /api/users/auth/verify?token=TOKEN
Returns session token and user info.
Get Current User
GET /api/users/me
Authorization: Bearer SESSION_TOKEN
Logout
POST /api/users/auth/logout
Authorization: Bearer SESSION_TOKEN
Credits & Payments (PR #90)
List Credit Packages
GET /api/users/credits/packages
No auth required. Returns available packages and prices.
Create Checkout Session
POST /api/users/credits/checkout
Content-Type: application/json
{"package_id": "5_credits", "email": "user@example.com"}
Returns Stripe checkout URL.
Stripe Webhook
POST /api/users/webhooks/stripe
Handles checkout.session.completed events.
Beta Tester Program (PR #90)
Enroll as Beta Tester
POST /api/users/beta/enroll
Content-Type: application/json
{
"email": "user@example.com",
"promise_text": "I promise to provide feedback...",
"accept_corrections_work": true
}
Returns 1 free credit and session token.
Submit Feedback
POST /api/users/beta/feedback
Authorization: Bearer SESSION_TOKEN
Content-Type: application/json
{
"overall_rating": 4,
"ease_of_use_rating": 5,
"lyrics_accuracy_rating": 4,
"correction_experience_rating": 3,
"what_went_well": "...",
"what_could_improve": "..."
}
Bonus credit for detailed feedback (50+ chars).
Admin Endpoints
All admin endpoints require an admin-role session token.
Admin Dashboard Stats
GET /api/admin/stats/overview
Authorization: Bearer ADMIN_TOKEN
Returns platform statistics:
{
"total_users": 100,
"active_users_7d": 25,
"active_users_30d": 60,
"total_jobs": 500,
"jobs_last_7d": 50,
"jobs_last_30d": 150,
"jobs_by_status": {
"pending": 5,
"processing": 3,
"awaiting_review": 10,
"complete": 400,
"failed": 20
},
"total_credits_issued_30d": 200,
"total_beta_testers": 30
}
List Users (Admin)
GET /api/users/admin/users
GET /api/users/admin/users?search=user@example.com
GET /api/users/admin/users?limit=20&offset=0&sort_by=created_at&sort_order=desc
Authorization: Bearer ADMIN_TOKEN
Returns paginated user list with total count.
User Detail (Admin)
GET /api/users/admin/users/{email}/detail
Authorization: Bearer ADMIN_TOKEN
Returns full user profile including:
- User info and stats
- Recent credit transactions (last 20)
- Recent jobs (last 10)
- Active sessions count
Add Credits (Admin)
POST /api/users/admin/credits
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json
{
"email": "user@example.com",
"amount": 5,
"reason": "Beta reward"
}
Set User Role (Admin)
POST /api/users/admin/users/{email}/role
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json
{"role": "admin"}
Enable/Disable User (Admin)
POST /api/users/admin/users/{email}/enable
POST /api/users/admin/users/{email}/disable
Authorization: Bearer ADMIN_TOKEN
Beta Stats (Admin)
GET /api/users/admin/beta/stats
Authorization: Bearer ADMIN_TOKEN
Beta Feedback List (Admin)
GET /api/users/admin/beta/feedback?limit=50
Authorization: Bearer ADMIN_TOKEN
Delete Job (Admin)
DELETE /api/jobs/{job_id}?delete_files=true
Authorization: Bearer ADMIN_TOKEN
Admins can delete any job. Regular users can only delete their own jobs.
Audio Search Management (Admin)
List Audio Searches
GET /api/admin/audio-searches
GET /api/admin/audio-searches?limit=50&status_filter=awaiting_audio_selection
Authorization: Bearer ADMIN_TOKEN
Returns jobs with cached audio search results. Useful for:
- Monitoring search activity
- Identifying stale cached results (YouTube-only when lossless should be available)
- Clearing cache for specific jobs
Response:
{
"jobs": [
{
"job_id": "abc123",
"status": "awaiting_audio_selection",
"user_email": "user@example.com",
"audio_search_artist": "Artist Name",
"audio_search_title": "Song Title",
"created_at": "2026-01-03T12:00:00Z",
"results_count": 5,
"has_lossless": false,
"providers": ["YouTube"],
"results_summary": [...]
}
],
"total": 1
}
Clear Audio Search Cache
POST /api/admin/audio-searches/{job_id}/clear-cache
Authorization: Bearer ADMIN_TOKEN
Clears cached search results and resets job to pending status, allowing a new search.
Use when:
- Cached results are stale (e.g., flacfetch was updated with new providers)
- User wants to search again
- Results appear incomplete (YouTube-only when lossless should exist)
Response:
{
"status": "success",
"job_id": "abc123",
"message": "Cleared 5 cached search results. Job reset to pending. Flacfetch cache also cleared.",
"previous_status": "awaiting_audio_selection",
"new_status": "pending",
"results_cleared": 5,
"flacfetch_cache_cleared": true,
"flacfetch_error": null
}
Note: This endpoint now also clears the flacfetch GCS cache for the artist/title combination, ensuring the next search hits trackers fresh.
Clear All Flacfetch Cache
DELETE /api/admin/cache
Authorization: Bearer ADMIN_TOKEN
Clears the entire flacfetch search cache (GCS-backed). Use when flacfetch has been updated and you want all subsequent searches to use fresh tracker results.
Response:
{
"status": "success",
"message": "Cleared 15 cache entries from flacfetch.",
"deleted_count": 15
}
Get Flacfetch Cache Stats
GET /api/admin/cache/stats
Authorization: Bearer ADMIN_TOKEN
Returns statistics about the flacfetch search cache.
Response:
{
"count": 42,
"total_size_bytes": 128000,
"oldest_entry": "2025-12-15T10:30:00Z",
"newest_entry": "2026-01-03T15:45:00Z",
"configured": true
}
Email Notifications (Admin)
Get Completion Message
GET /api/admin/jobs/{job_id}/completion-message
Authorization: Bearer ADMIN_TOKEN
Returns the rendered completion message for a job (for copying to clipboard).
Response:
{
"job_id": "abc123",
"message": "Hi there! Your karaoke video is ready...",
"subject": "Your Karaoke Video is Ready! 🎤",
"youtube_url": "https://youtube.com/watch?v=...",
"dropbox_url": "https://dropbox.com/..."
}
Send Completion Email
POST /api/admin/jobs/{job_id}/send-completion-email
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json
{
"to_email": "customer@example.com",
"cc_admin": true
}
Sends the job completion email to the specified address. When cc_admin is true (default), CCs gen@nomadkaraoke.com.
Response:
{
"success": true,
"job_id": "abc123",
"to_email": "customer@example.com",
"message": "Completion email sent successfully"
}
Internal Email Endpoints
These endpoints are used by Cloud Tasks for automated notifications.
Check Idle Reminder
POST /api/internal/jobs/{job_id}/check-idle-reminder
Authorization: Bearer ADMIN_TOKEN
Called by Cloud Tasks 5 minutes after a job enters a blocking state (awaiting_review or awaiting_instrumental_selection). Sends a reminder email if the user is still idle and no reminder has been sent yet.
Rate Limits
No rate limits currently implemented.
Webhooks
Stripe webhooks implemented at /api/users/webhooks/stripe.
Job status webhooks not yet implemented.