API Reference
API Reference
Section titled “API Reference”The Sublarr REST API is documented live, generated from the running backend so it cannot drift from the code.
Where the docs live
Section titled “Where the docs live”| Surface | URL | Purpose |
|---|---|---|
| Swagger UI | http://<HOST>:5765/api/docs | Interactive browser — click any endpoint, fill the form, run a real request. |
| OpenAPI JSON | http://<HOST>:5765/api/v1/openapi.json | Machine-readable spec. Feed this into Postman, Insomnia, Bruno, or a code generator. |
Both endpoints are anonymous-readable so you can browse them before authenticating.
Authentication
Section titled “Authentication”All API calls require an X-Api-Key header. The key is set in Settings → General → Authentication. Paste it once into Swagger UI’s Authorize dialog (top right) and every “Try it out” call you make from there will include it.
curl -H "X-Api-Key: <API_KEY>" http://<HOST>:5765/api/v1/healthMost common endpoints
Section titled “Most common endpoints”| Endpoint | What it does |
|---|---|
GET /api/v1/health | Liveness probe — returns { "status": "ok" }. |
GET /api/v1/library | Paginated list of every series Sublarr knows about. |
GET /api/v1/wanted | Items currently waiting for a subtitle search. |
POST /api/v1/wanted/{id}/search | Trigger an immediate provider search for one wanted item. |
GET /api/v1/activity | Recent download + translation history. |
GET /api/v1/scheduler/jobs | List background jobs and their next-fire time. |
For everything else — and the full request/response schemas — open Swagger UI.
Why no static endpoint catalogue here
Section titled “Why no static endpoint catalogue here”A hand-maintained list would lag behind the code on every release. The Swagger UI is generated from Python type hints and Pydantic models at runtime, so it is always in sync with the running version. Treat the live UI as the source of truth.