API

Base path#

Every route is prefixed with /api (app.setGlobalPrefix('api') in backend/src/main.ts). The server listens on PORT, 4848 when unset, so against a local server that means http://localhost:4848/api/.... The dev setups override it: 3001 with backend/.env.example, 3000 in the Docker dev stack (see Dev environment).

Request bodies are validated against their DTO class by a global ValidationPipe with whitelist and forbidNonWhitelisted: a property the DTO doesn't declare is rejected with a 400, not silently dropped. So don't send back a whole object you fetched (with its id, createdAt, updatedAt) as the body of an update; send only the fields you change.

Authentication#

• POST /api/auth/register creates an account with the default role. (Only the very first account in an empty database would become an admin, and the server already creates a default admin account at first start, so in practice a registered account never is.)
• POST /api/auth/login, body { "username": "...", "password": "..." }, returns an access token and a refresh token, and also sets the access token as an httpOnly cookie for browser clients.
• POST /api/auth/refresh, body { "refreshToken": "..." }, rotates both tokens. Replaying an already-rotated refresh token revokes every refresh token on the account, every device then has to log back in.
• POST /api/auth/logout clears the cookie and revokes the given refresh token.

A browser gets the access token from its cookie automatically. Any other client sends it as Authorization: Bearer <accessToken>. The server also reads it from a ?token= query parameter, for requests that can't carry a header (EventSource, media URLs). It checks the cookie first, then the header, then the query parameter.

GET /api/system/liveness needs no token at all; it is meant for container health checks.

See Users and permissions for what a role can be granted.

Resource groups#

See Streaming and transcoding and Plugins overview for what those two areas do.

Realtime: server-sent events#

GET /api/system/events?device=<id>&ff=<formFactor>&tvPlatform=<platform>&name=<deviceName>

A single server-sent events stream per signed-in device. It is opened as a plain EventSource, which can't set headers: a browser authenticates with the access token cookie, and a native client appends its access token as ?token=. The long-lived, read-only stream tokens baked into media URLs are refused here (SessionTokenGuard). It carries background task progress, subtitle sync/download/translation results, remote-control target announcements, and library-change notifications. Fliks has no WebSocket or socket.io endpoint; this is the entire realtime transport.

Examples#

# Log in, keep the session cookie
curl -c cookies.txt -X POST http://localhost:4848/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"password"}'

# Reuse the cookie for anything else
curl -b cookies.txt http://localhost:4848/api/libraries

# A script or native client: send the access token directly
curl http://localhost:4848/api/media \
  -H "Authorization: Bearer $ACCESS_TOKEN"