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)

Key endpoints

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

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

Users

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

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