REST API

Dubby provides a REST API at /v1/ for programmatic access to all server functionality. The API follows OpenAPI 3.1 conventions with auto-generated documentation.

Interactive docs

• OpenAPI spec: GET /v1/openapi.json
• Swagger UI: GET /docs

The Swagger UI lets you explore endpoints, view request/response schemas, and make test requests directly from your browser.

Authentication

Session-based (web)

The web client uses better-auth session cookies. Same-origin requests include the cookie automatically.

Bearer token (API / TV / mobile)

1. Sign in to get a token:

curl -X POST http://localhost:3000/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'

2. Use the token in subsequent requests:

curl http://localhost:3000/v1/movies \
  -H "Authorization: Bearer <token>"

Sessions last 7 days and auto-extend every 24 hours on activity.

Conventions

Convention	Details
Content type	application/json for request and response bodies
IDs	Nanoid strings (21 characters)
Pagination	Cursor-based via cursor query parameter
Page size	limit parameter (1-100, default 20)
Errors	{ "error": "description" } with appropriate HTTP status
Validation	422 with { "error": "Validation error", "details": [{ "path": "...", "message": "..." }] }
Max body	1 MB (returns 413 if exceeded)

Endpoint reference

The REST API has 34 route groups. Below are the most commonly used endpoints. For the complete list, use the interactive Swagger UI at /docs or fetch the OpenAPI spec at /v1/openapi.json.

Auth

Method	Endpoint	Description
POST	/api/auth/sign-in/email	Sign in with email and password
POST	/api/auth/sign-out	Sign out

Libraries

Method	Endpoint	Description
GET	/v1/libraries	List libraries (filtered by user permissions)
POST	/v1/libraries	Create a library
GET	/v1/libraries/:id	Get library details
PATCH	/v1/libraries/:id	Update a library
DELETE	/v1/libraries/:id	Delete a library (files on disk are not deleted)
POST	/v1/libraries/:id/scan	Start a library scan
GET	/v1/libraries/:id/stats	Library statistics

Movies

Method	Endpoint	Description
GET	/v1/movies	List movies with filters and sorting
GET	/v1/movies/recently-added	Recently added movies
GET	/v1/movies/:id	Movie details
GET	/v1/movies/:id/credits	Cast and crew
PUT	/v1/movies/:id/watched	Mark as watched
DELETE	/v1/movies/:id/watched	Mark as unwatched
GET	/v1/movies/:id/file-stats	File codec/resolution details

Shows

Method	Endpoint	Description
GET	/v1/shows	List TV shows with filters and sorting
GET	/v1/shows/recently-added	Recently added shows
GET	/v1/shows/:id	Show details
GET	/v1/shows/:id/seasons	List seasons
GET	/v1/shows/:id/seasons/:num	Season details
GET	/v1/shows/:id/seasons/:num/episodes	List episodes in a season
GET	/v1/shows/:id/seasons/:num/episodes/:num	Episode details

Playback

Method	Endpoint	Description
POST	/v1/playback/sessions	Create a playback session
POST	/v1/playback/sessions/:id/heartbeat	Keep session alive, update position
POST	/v1/playback/sessions/:id/seek	Seek to a position
DELETE	/v1/playback/sessions/:id	End a session
GET	/v1/playback/continue-watching	Continue watching list
GET	/v1/playback/sessions/active	Active sessions

Search

Method	Endpoint	Description
GET	/v1/search	Full-text search across all media types
GET	/v1/search/suggestions	Autocomplete search suggestions

Collections

Method	Endpoint	Description
GET	/v1/collections	List collections
POST	/v1/collections	Create a collection
GET	/v1/collections/:id	Get collection details
PATCH	/v1/collections/:id	Update a collection
DELETE	/v1/collections/:id	Delete a collection
GET	/v1/collections/:id/items	List items in a collection
POST	/v1/collections/:id/items	Add an item
POST	/v1/collections/:id/items/batch	Add multiple items
DELETE	/v1/collections/:id/items/:mediaType/:mediaId	Remove an item
PUT	/v1/collections/:id/items/order	Reorder items
POST	/v1/collections/:id/refresh	Refresh an auto-collection
POST	/v1/collections/preview-rules	Preview rule match count

AI & Enrichment

Method	Endpoint	Description
GET	/v1/ai/available	Check if AI inference is available
POST	/v1/ai/search	Interpret natural language search query
POST	/v1/ai/suggest-collections	AI-powered collection suggestion
POST	/v1/ai/enrich-metadata	Submit AI metadata enrichment job
GET	/v1/ai/usage	Get inference usage and credit balance
GET	/v1/ai/requests	Paginated inference request log (admin)
GET	/v1/enrichment/:mediaType/:mediaId	Get AI enrichment for a media item
POST	/v1/enrichment/enrich	Enrich a single item
POST	/v1/enrichment/enrich-library	Bulk enrich a library
GET	/v1/enrichment/stats	Enrichment statistics

Watchlist

Method	Endpoint	Description
GET	/v1/watchlist	List watchlist items
POST	/v1/watchlist	Add item to watchlist
DELETE	/v1/watchlist/:id	Remove from watchlist

Discovery

Method	Endpoint	Description
GET	/v1/discover	Browse trending/popular from TMDB

People

Method	Endpoint	Description
GET	/v1/people/:id	Person details and roles

Podcasts

Method	Endpoint	Description
GET	/v1/podcasts	List subscribed podcasts
POST	/v1/podcasts	Subscribe to a podcast
DELETE	/v1/podcasts/:id	Unsubscribe
GET	/v1/podcasts/:id/episodes	List episodes

Migration

Method	Endpoint	Description
GET	/v1/migration/discover	Auto-discover media servers on network
POST	/v1/migration/test-connection	Test connectivity to a source server
POST	/v1/migration/preview	Preview libraries and users on source
POST	/v1/migration/sources	Create a migration source connection
GET	/v1/migration/sources	List migration sources
POST	/v1/migration/import	Start a migration import workflow
GET	/v1/migration/gap-report	Count shell records awaiting files

Parental Controls

Method	Endpoint	Description
POST	/v1/parental-controls/pin	Set or update profile PIN
POST	/v1/parental-controls/pin/verify	Verify a PIN
GET	/v1/parental-controls/profiles	List managed profiles
POST	/v1/parental-controls/profiles	Create a managed profile
PATCH	/v1/parental-controls/profiles/:profileId	Update a profile
DELETE	/v1/parental-controls/profiles/:profileId	Delete a profile
POST	/v1/parental-controls/switch-profile	Switch active profile

Backups

Method	Endpoint	Description
GET	/v1/backups	List backups
POST	/v1/backups	Create a backup
GET	/v1/backups/:id	Get backup details
DELETE	/v1/backups/:id	Delete a backup
POST	/v1/backups/restore	Restore from a backup

Administration

Method	Endpoint	Description
GET	/v1/admin/dashboard	Dashboard analytics
GET	/v1/admin/users	List all users
GET	/v1/audit-logs	Query audit logs (admin)
GET	/v1/feature-flags	List feature flags
PATCH	/v1/feature-flags/:key	Toggle flag default
GET	/v1/jobs	List background jobs
GET	/v1/workflows	List workflow runs

Additional route groups

These route groups are fully documented in the Swagger UI:

Route group	Description
/v1/settings	Server settings CRUD
/v1/setup	First-run setup wizard
/v1/config	Unified server configuration
/v1/metadata	Metadata search, identification, refresh
/v1/integrations	TMDB, Trakt, Radarr/Sonarr configuration
/v1/subtitles	Subtitle track management
/v1/audio	Audio track information
/v1/playback-preferences	Per-user audio/subtitle language rules
/v1/optimization	Ahead-of-time transcoding profiles
/v1/seerr	Seerr integration management
/v1/health	Liveness and readiness probes
/v1/users	User profile management

Error responses

Status	Meaning
400	Bad request
401	Missing or invalid authentication
403	Insufficient permissions
404	Resource not found
409	Conflict (e.g., scan already running)
413	Request body too large
422	Validation error
429	Rate limit exceeded (check Retry-After header)
503	Service unavailable

Rate limiting

Scope	Limit
General API	100 requests/minute
Speedtest	3 requests/minute

Rate-limited responses include a Retry-After header indicating when you can retry.

Streaming endpoints

Streaming uses separate routes outside the /v1/ prefix. See Stream Tokens for authentication details.

Route	Description
GET /api/stream/:sessionId/master.m3u8	HLS master playlist
GET /api/stream/:sessionId/:quality/playlist.m3u8	Quality-specific playlist
GET /api/stream/:sessionId/:quality/:filename	HLS segment
GET /api/stream/:sessionId/file	Direct file (HTTP Range)
GET /api/stream/:sessionId/subtitles/:filename	WebVTT subtitle