Watch Library API Documentation
This directory contains complete documentation and curl examples for every API endpoint available in the Watch Library backend.
Documentation Index
- **CURL Quick Cheatsheet** - One-liner
curlcommands for all endpoints. - **Authentication & API Keys** - Managing API Keys, rate limits, and using Bearer tokens across external projects.
- **Movies API** - Full CRUD examples for movie records.
- **Series API** - Full CRUD and progress tracking examples for TV series.
- **Last Seen & IMDb Lookup API** - Fast lookups for most recently updated titles and IMDb ID searches.
- **Unified Library & Utilities API** - Unified catalog queries, OMDB proxy, image caching, and DB status.
- **Advanced Endpoints** - Analytics stats, fast search, random title picker, bulk batch import, backups/export, and Plex/Jellyfin scrobble webhook.
Base URL
During local development with Bun:
text
http://localhost:3001Security & Access Model
- Mutating Endpoints (`POST`, `PUT`, `PATCH`, `DELETE`):
- Strictly protected. Require an authenticated API Key or Admin Session Token.
- Missing or invalid credentials return
HTTP 401 Unauthorized.
- Read-Only Endpoints (`GET`):
- With API Key: Full, unrestricted, unthrottled access (
X-RateLimit-Limit: unlimited). - Without API Key (Public): Allowed, with an automated rate limit shield of 30 requests per second per IP address.
- Exceeding 30 req/sec returns
HTTP 429 Too Many RequestswithRetry-After: 1.
Authentication Modes
Pass your API key using any of the following standard headers:
- Bearer Token (Recommended):
http Authorization: Bearer wl_live_YOUR_API_KEY
- Custom Header:
http x-api-key: wl_live_YOUR_API_KEY
- Query Parameter:
?apiKey=wl_live_YOUR_API_KEY
CORS & Cross-Project Access
All /api/* endpoints have Cross-Origin Resource Sharing (CORS) enabled by default:
Access-Control-Allow-Origin: *Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONSAccess-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With, Accept, x-api-key- Preflight
OPTIONSrequests are handled automatically on all routes.