Files
karaoke-gen/docs/API.md
T
Andrew Beveridge ☄️andClaude 80b8d9c5ae feat(admin): Add toggle to hide/show test data in admin dashboard (#239)
## Summary

- Filter out E2E test data from admin dashboard by default (emails
ending in `@inbox.testmail.app`)
- Add "Show test data" toggle in admin header that persists to
localStorage
- Add `exclude_test` query parameter to all admin list/stats endpoints
(defaults to `true`)
- Add streaming limits with warnings to prevent memory issues on large
datasets

## Changes

**Backend:**
- New `backend/utils/test_data.py` with `is_test_email()` utility
- Updated admin stats endpoint with test data filtering
- Updated users list, jobs list, beta stats, and audio searches
endpoints
- Added USERS_STREAM_LIMIT (2000) and JOBS_STREAM_LIMIT (10000) with
warning logs

**Frontend:**
- New `frontend/lib/admin-settings.ts` zustand store for admin
preferences
- Toggle switch in admin layout header
- All admin pages pass `exclude_test: !showTestData` to API calls

**Docs:**
- Updated API.md with exclude_test parameter documentation

## Test Plan

- [x] Backend tests pass (68 passed)
- [x] Frontend tests pass (128 passed)
- [x] Frontend build succeeds
- [x] CodeRabbit review passed
- [ ] Manual: Visit `/admin` - stats should show lower numbers by
default
- [ ] Manual: Toggle "Show test data" ON - counts should increase
- [ ] Manual: Toggle persists across page refreshes

<!-- @coderabbitai ignore -->

🤖 Generated with [Claude Code](https://claude.ai/code)

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-01-08 16:21:34 +00:00

13 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.

Encoding Worker Health

GET /health/encoding-worker

No auth required. Returns GCE encoding worker status for frontend display.

Response:

{
  "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

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 state
  • file_urls - Signed URLs for outputs (when ready)
  • state_data - Worker progress details
  • timeline - Processing history

List Jobs

GET /api/jobs
GET /api/jobs?status=complete
GET /api/jobs?limit=10&offset=0
GET /api/jobs?exclude_test=false

Query parameters:

  • exclude_test (bool, default: true) - Admin only: filter out jobs from test users
  • status - Filter by job status
  • limit / offset - Pagination

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"
}

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 trackers
  • display_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 processing
  • theme_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 request
  • 401 - Unauthorized
  • 404 - Job not found
  • 500 - Server error

User Authentication

POST /api/users/auth/magic-link
Content-Type: application/json

{"email": "user@example.com"}
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.

Test Data Filtering

Most admin list/stats endpoints support an exclude_test query parameter (default: true) to filter out E2E test data:

  • Test users: email addresses ending in @inbox.testmail.app
  • Test jobs: jobs created by test users
GET /api/admin/stats/overview?exclude_test=true   # Default - hide test data
GET /api/admin/stats/overview?exclude_test=false  # Show all data including tests

The frontend admin dashboard includes a "Show test data" toggle that controls this filter globally.

Admin Dashboard Stats

GET /api/admin/stats/overview
GET /api/admin/stats/overview?exclude_test=false
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
GET /api/users/admin/users?exclude_test=false
Authorization: Bearer ADMIN_TOKEN

Query parameters:

  • exclude_test (bool, default: true) - Filter out test users
  • limit / offset - Pagination
  • search - Email prefix search
  • sort_by / sort_order - Sorting

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
GET /api/users/admin/beta/stats?exclude_test=false
Authorization: Bearer ADMIN_TOKEN

Query parameters:

  • exclude_test (bool, default: true) - Filter out test users from beta statistics

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
GET /api/admin/audio-searches?exclude_test=false
Authorization: Bearer ADMIN_TOKEN

Query parameters:

  • exclude_test (bool, default: true) - Filter out searches from test users
  • limit - Max results to return
  • status_filter - Filter by job status

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.