Files
karaoke-gen/docs/API.md
T
Andrew Beveridge ☄️andClaude Opus 4.5 42c304dcdf feat(multitenancy): Implement white-label B2B portal infrastructure (#241)
## Summary

Adds multi-tenant white-label portal infrastructure for B2B customers.
Vocal Star is the first tenant at `vocalstar.nomadkaraoke.com`.

## Changes

### Backend
- **Tenant Models** (`backend/models/tenant.py`): Pydantic models for
TenantConfig with branding, features, defaults, and auth settings
- **Tenant Service** (`backend/services/tenant_service.py`): GCS-backed
config loading with 5-min cache, signed URL generation for logos
- **Tenant API** (`backend/api/routes/tenant.py`): `GET
/api/tenant/config` and `GET /api/tenant/config/{tenant_id}` endpoints
- **Tenant Middleware** (`backend/middleware/tenant.py`): Extracts
tenant from X-Tenant-ID header, query param (dev only), or Host
subdomain
- **Auth Updates**: Email domain validation for tenant-restricted auth,
sender email override
- **Feature Enforcement**: Audio search endpoint checks
`features.audio_search`, returns 403 if disabled
- **Job Scoping**: Added `tenant_id` field to JobCreate

### Frontend
- **Tenant Store** (`frontend/lib/tenant.ts`): Zustand store with tenant
state, `useTenant()` hook, CSS variable application
- **TenantProvider** (`frontend/components/tenant-provider.tsx`):
Hydration-safe initialization via useEffect
- **TenantLogo** (`frontend/components/tenant-logo.tsx`): Dynamic logo
with fallback to Nomad Karaoke
- **Feature-Flagged UI**: Tabs conditionally rendered based on tenant
features, active tab sync
- **Locked Themes**: `defaults.locked_theme` hides theme selector and
enforces specific theme
- **Output Links**: Filtered based on distribution features

### Security
- Query param tenant detection disabled in production (prevents
spoofing)
- Strict subdomain patterns: only `{tenant}.nomadkaraoke.com` or
`{tenant}.gen.nomadkaraoke.com`
- PII masking in logs (`an***@vo***.com`)
- `is_active` check prevents inactive tenants from being used

### Documentation
- ARCHITECTURE.md: New Multitenancy section
- API.md: Tenant Config endpoints
- LESSONS-LEARNED.md: 3 new lessons on multitenancy patterns
- Archive: Comprehensive implementation document

### Setup
- `scripts/setup-vocalstar-tenant.py`: Uploads theme assets, creates
tenant/theme configs in GCS

## Vocal Star Configuration

- **Subdomain**: `vocalstar.nomadkaraoke.com`
- **Features**: File upload only (no audio search, no YouTube URL)
- **Distribution**: Download only (no YouTube/Dropbox/GDrive)
- **Theme**: Locked to "vocalstar" (yellow/blue)
- **Auth**: Restricted to `@vocal-star.com` and `@vocalstarmusic.com`
emails

## Testing

- [x] Frontend TypeScript build passes
- [x] CodeRabbit CLI review completed (3 cycles, all issues fixed)
- [x] Manual testing with `?tenant=vocalstar` query param

## Next Steps (post-merge)

1. Configure DNS: CNAME for `vocalstar.nomadkaraoke.com`
2. Update Cloudflare Pages for subdomain
3. Run setup script to upload Vocal Star assets to GCS
4. Test at `https://vocalstar.nomadkaraoke.com`

@coderabbitai ignore

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

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-08 16:39:56 -05:00

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

Tenant Config

GET /api/tenant/config
GET /api/tenant/config?tenant=vocalstar

No auth required. Returns tenant configuration for white-label portals.

Detection priority:

  1. X-Tenant-ID header (explicitly set by frontend)
  2. tenant query parameter (development/testing only, disabled in production)
  3. Host header subdomain detection (e.g., vocalstar.nomadkaraoke.com)

Response:

{
  "tenant": {
    "id": "vocalstar",
    "name": "Vocal Star",
    "subdomain": "vocalstar.nomadkaraoke.com",
    "is_active": true,
    "branding": {
      "logo_url": "https://storage.googleapis.com/...",
      "logo_height": 60,
      "primary_color": "#ffff00",
      "secondary_color": "#006CF9",
      "accent_color": "#ffffff",
      "background_color": "#000000",
      "favicon_url": null,
      "site_title": "Vocal Star Karaoke Generator",
      "tagline": "Whoever You Are, Be a Vocal Star!"
    },
    "features": {
      "audio_search": false,
      "file_upload": true,
      "youtube_url": false,
      "youtube_upload": false,
      "dropbox_upload": false,
      "gdrive_upload": false,
      "theme_selection": false,
      "color_overrides": false,
      "enable_cdg": true,
      "enable_4k": true,
      "admin_access": false
    },
    "defaults": {
      "theme_id": "vocalstar",
      "locked_theme": "vocalstar",
      "distribution_mode": "download_only"
    }
  },
  "is_default": false
}

When no tenant is detected, returns tenant: null with is_default: true and the default Nomad Karaoke configuration is used.

GET /api/tenant/config/{tenant_id}

Get specific tenant config by ID. Returns 404 if tenant not found or inactive.

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.