Back to Library

API Documentation

v1.0 (REST)

Watch Library API Documentation

This directory contains complete documentation and curl examples for every API endpoint available in the Watch Library backend.


Documentation Index


Base URL

During local development with Bun:

text
http://localhost:3001

Security & Access Model

  1. 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.
  1. 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 Requests with Retry-After: 1.

Authentication Modes

Pass your API key using any of the following standard headers:

  1. Bearer Token (Recommended):

http Authorization: Bearer wl_live_YOUR_API_KEY

  1. Custom Header:

http x-api-key: wl_live_YOUR_API_KEY

  1. 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, OPTIONS
  • Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With, Accept, x-api-key
  • Preflight OPTIONS requests are handled automatically on all routes.