{ "openapi": "3.1.0", "info": { "title": "Librariarr API", "version": "0.33.0", "description": "The public API for third-party applications. Every request is authenticated with an API key issued under Settings → Authentication → API Keys, sent as `Authorization: Bearer ` or `X-Api-Key: ` — never in the URL, where it is refused.\nEach operation names the scope its key needs (`x-scope`). A read-only key holds every read scope.\n\nScopes:\n- `media:read` — Browse and search movies, series and music; item details, artwork, library stats and watch history.\n- `servers:read` — List media servers and their libraries, and read sync status. Server tokens are never returned.\n- `sync:write` — Start and cancel library syncs.\n- `lifecycle:read` — Rule sets, matches, pending and completed actions, exceptions and deletion stats.\n- `lifecycle:write` — Queue lifecycle detection and add exceptions that protect items.\n- `lifecycle:execute` — Run lifecycle actions on named matches and remove exceptions, at most 25 items a request and 100 an hour across all keys. Either can lead to media being deleted through Sonarr, Radarr and Lidarr.\n- `streams:read` — Active playback sessions — who is watching, on which device and from which address — and maintenance mode status.\n- `streams:write` — Terminate playback sessions and turn maintenance mode on or off.\n- `system:read` — App version, database and library counts.\n\nRate limits: 600 requests per minute per key (a `limit=0` listing, and any read of a listing without paging, counts as 20). Errors are `{ error }`, sometimes with `details`.\n\nDeletion limits: a request can delete (or remove the exception of) at most 25 items, and every key together at most 100 an hour. Every item must be named; nothing acts on \"all matches\"." }, "servers": [ { "url": "{baseUrl}/api/v1", "variables": { "baseUrl": { "default": "https://librariarr.example.com", "description": "Where your Librariarr runs." } } } ], "tags": [ { "name": "Key" }, { "name": "Library" }, { "name": "Servers and syncs" }, { "name": "Lifecycle" }, { "name": "Streams" }, { "name": "System" } ], "paths": { "/me": { "get": { "operationId": "getMe", "tags": [ "Key" ], "summary": "The calling key", "description": "Any valid key. Its id, name, prefix, scopes (only ones this version grants), expiry, creation and last use. Works with any valid key.", "x-scope": null, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/openapi.json": { "get": { "operationId": "getOpenapiJson", "tags": [ "Key" ], "summary": "This OpenAPI document", "description": "Any valid key. Works with any valid key.", "x-scope": null, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/system/info": { "get": { "operationId": "getSystemInfo", "tags": [ "System" ], "summary": "App version, database size and counts", "description": "Scope: `system:read`.", "x-scope": "system:read", "parameters": [ { "name": "updateCheck", "in": "query", "required": false, "description": "`false` leaves out `updateInfo`, the GitHub release lookup, so the answer never waits on GitHub.", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/servers": { "get": { "operationId": "getServers", "tags": [ "Servers and syncs" ], "summary": "Media servers with their libraries and latest sync (tokens masked; addresses, machine ids and owner omitted)", "description": "Scope: `servers:read`.", "x-scope": "servers:read", "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "`basic` returns only each server's `id`, `name`, `type` and `enabled`, without its libraries, item counts or sync jobs.", "schema": { "type": "string", "enum": [ "basic" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/sync/status": { "get": { "operationId": "getSyncStatus", "tags": [ "Servers and syncs" ], "summary": "Running and recent sync jobs (server addresses and machine ids omitted, errors redacted)", "description": "Scope: `servers:read`.", "x-scope": "servers:read", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/servers/{id}/sync": { "post": { "operationId": "postServersByIdSync", "tags": [ "Servers and syncs" ], "summary": "Sync one server", "description": "Scope: `sync:write`.", "x-scope": "sync:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A Librariarr id, as returned by the listing endpoints.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "description": "Optionally one library.", "content": { "application/json": { "schema": { "type": "object", "properties": { "libraryKey": { "type": "string", "maxLength": 200 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A sync is already running for this server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/sync/cancel": { "post": { "operationId": "postSyncCancel", "tags": [ "Servers and syncs" ], "summary": "Stop a server's running or queued sync", "description": "Scope: `sync:write`.", "x-scope": "sync:write", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "serverId" ], "properties": { "serverId": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such server, or it has no running or queued sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/jobs/sync": { "post": { "operationId": "postJobsSync", "tags": [ "Servers and syncs" ], "summary": "Queue a sync of every enabled server", "description": "Scope: `sync:write`. The Settings “Run now” job. Servers already syncing are skipped.", "x-scope": "sync:write", "parameters": [], "responses": { "202": { "description": "Queued: `{ queued: true, jobs }`, `jobs` being how many servers were queued", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "A sync could not be queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/media/movies": { "get": { "operationId": "getMediaMovies", "tags": [ "Library" ], "summary": "Movies", "description": "Scope: `media:read`.", "x-scope": "media:read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page, at most 100 (a larger value is capped). 0 = everything, which counts as 20 requests against the key's budget.", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Skip this many rows; overrides `page`.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "sortBy", "in": "query", "required": false, "description": "Field to sort by.", "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "search", "in": "query", "required": false, "description": "Title search.", "schema": { "type": "string" } }, { "name": "serverId", "in": "query", "required": false, "description": "Limit to one media server.", "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "required": false, "description": "Pipe-separated values, e.g. `4K|1080P`.", "schema": { "type": "string" } }, { "name": "genre", "in": "query", "required": false, "description": "Pipe-separated values.", "schema": { "type": "string" } }, { "name": "yearConditions", "in": "query", "required": false, "description": "Pipe-separated `op:value` pairs, e.g. `gte:2020|lte:2024`.", "schema": { "type": "string" } }, { "name": "yearLogic", "in": "query", "required": false, "description": "How multiple `yearConditions` combine.", "schema": { "type": "string", "enum": [ "and", "or" ] } }, { "name": "startsWith", "in": "query", "required": false, "description": "First letter, or `#` for titles not starting with a letter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/media/series": { "get": { "operationId": "getMediaSeries", "tags": [ "Library" ], "summary": "Episodes", "description": "Scope: `media:read`.", "x-scope": "media:read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page, at most 100 (a larger value is capped). 0 = everything, which counts as 20 requests against the key's budget.", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Skip this many rows; overrides `page`.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "sortBy", "in": "query", "required": false, "description": "Field to sort by.", "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "search", "in": "query", "required": false, "description": "Title search.", "schema": { "type": "string" } }, { "name": "serverId", "in": "query", "required": false, "description": "Limit to one media server.", "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "required": false, "description": "Pipe-separated values, e.g. `4K|1080P`.", "schema": { "type": "string" } }, { "name": "genre", "in": "query", "required": false, "description": "Pipe-separated values.", "schema": { "type": "string" } }, { "name": "yearConditions", "in": "query", "required": false, "description": "Pipe-separated `op:value` pairs, e.g. `gte:2020|lte:2024`.", "schema": { "type": "string" } }, { "name": "yearLogic", "in": "query", "required": false, "description": "How multiple `yearConditions` combine.", "schema": { "type": "string", "enum": [ "and", "or" ] } }, { "name": "seriesKey", "in": "query", "required": false, "description": "One show.", "schema": { "type": "string" } }, { "name": "seasonNumber", "in": "query", "required": false, "description": "One season.", "schema": { "type": "integer" } }, { "name": "itemId", "in": "query", "required": false, "description": "An episode's id: the season it belongs to, in place of `seriesKey` and `seasonNumber`. `404` if it is not one of your episodes.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/media/series/grouped": { "get": { "operationId": "getMediaSeriesGrouped", "tags": [ "Library" ], "summary": "Shows, with episode and watched counts", "description": "Scope: `media:read`.", "x-scope": "media:read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page, at most 200 (a larger value is capped). 0 = everything, which counts as 20 requests against the key's budget.", "schema": { "type": "integer", "minimum": 0, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Skip this many rows; overrides `page`.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "sortBy", "in": "query", "required": false, "description": "Field to sort by.", "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "search", "in": "query", "required": false, "description": "Title search.", "schema": { "type": "string" } }, { "name": "startsWith", "in": "query", "required": false, "description": "First letter, or `#` for titles not starting with a letter.", "schema": { "type": "string" } }, { "name": "serverId", "in": "query", "required": false, "description": "Limit to one media server.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/media/series/seasons": { "get": { "operationId": "getMediaSeriesSeasons", "tags": [ "Library" ], "summary": "Seasons of one show", "description": "Scope: `media:read`.", "x-scope": "media:read", "parameters": [ { "name": "seriesKey", "in": "query", "required": false, "description": "From the grouped listing. Required unless `itemId` is given.", "schema": { "type": "string" } }, { "name": "itemId", "in": "query", "required": false, "description": "An episode's id: the seasons of its show. `404` if it is not one of your episodes.", "schema": { "type": "string" } }, { "name": "serverId", "in": "query", "required": false, "description": "Limit to one media server.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/media/music": { "get": { "operationId": "getMediaMusic", "tags": [ "Library" ], "summary": "Tracks", "description": "Scope: `media:read`.", "x-scope": "media:read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page, at most 100 (a larger value is capped). 0 = everything, which counts as 20 requests against the key's budget.", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Skip this many rows; overrides `page`.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "sortBy", "in": "query", "required": false, "description": "Field to sort by.", "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "search", "in": "query", "required": false, "description": "Title search.", "schema": { "type": "string" } }, { "name": "serverId", "in": "query", "required": false, "description": "Limit to one media server.", "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "required": false, "description": "Pipe-separated values, e.g. `4K|1080P`.", "schema": { "type": "string" } }, { "name": "genre", "in": "query", "required": false, "description": "Pipe-separated values.", "schema": { "type": "string" } }, { "name": "yearConditions", "in": "query", "required": false, "description": "Pipe-separated `op:value` pairs, e.g. `gte:2020|lte:2024`.", "schema": { "type": "string" } }, { "name": "yearLogic", "in": "query", "required": false, "description": "How multiple `yearConditions` combine.", "schema": { "type": "string", "enum": [ "and", "or" ] } }, { "name": "parentTitle", "in": "query", "required": false, "description": "Artist.", "schema": { "type": "string" } }, { "name": "albumTitle", "in": "query", "required": false, "description": "Album.", "schema": { "type": "string" } }, { "name": "itemId", "in": "query", "required": false, "description": "A track's id: the album it belongs to, in place of `parentTitle` and `albumTitle`. `404` if it is not one of your tracks.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/media/music/grouped": { "get": { "operationId": "getMediaMusicGrouped", "tags": [ "Library" ], "summary": "Artists, with track and album counts", "description": "Scope: `media:read`.", "x-scope": "media:read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page, at most 200 (a larger value is capped). 0 = everything, which counts as 20 requests against the key's budget.", "schema": { "type": "integer", "minimum": 0, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Skip this many rows; overrides `page`.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "sortBy", "in": "query", "required": false, "description": "Field to sort by.", "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "search", "in": "query", "required": false, "description": "Artist search.", "schema": { "type": "string" } }, { "name": "startsWith", "in": "query", "required": false, "description": "First letter, or `#` for titles not starting with a letter.", "schema": { "type": "string" } }, { "name": "serverId", "in": "query", "required": false, "description": "Limit to one media server.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/media/music/albums": { "get": { "operationId": "getMediaMusicAlbums", "tags": [ "Library" ], "summary": "Albums of one artist", "description": "Scope: `media:read`.", "x-scope": "media:read", "parameters": [ { "name": "parentTitle", "in": "query", "required": false, "description": "Artist. Required unless `itemId` is given.", "schema": { "type": "string" } }, { "name": "itemId", "in": "query", "required": false, "description": "A track's id: the albums of its artist. `404` if it is not one of your tracks.", "schema": { "type": "string" } }, { "name": "serverId", "in": "query", "required": false, "description": "Limit to one media server.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/media/search": { "get": { "operationId": "getMediaSearch", "tags": [ "Library" ], "summary": "Search by title", "description": "Scope: `media:read`.", "x-scope": "media:read", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search text, at most 200 characters.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "type", "in": "query", "required": false, "description": "Library type. Required unless `types` is given; the answer is `{ items }`.", "schema": { "type": "string", "enum": [ "MOVIE", "SERIES", "MUSIC" ] } }, { "name": "types", "in": "query", "required": false, "description": "Several library types, comma-separated (`MOVIE,SERIES,MUSIC`), searched in one request; the answer is `{ results: { MOVIE: [...], ... } }`, each list what `type` returns for it.", "schema": { "type": "string" } }, { "name": "seriesScope", "in": "query", "required": false, "description": "With `type=SERIES`, return shows rather than episodes.", "schema": { "type": "boolean", "default": false } }, { "name": "musicScope", "in": "query", "required": false, "description": "With `type=MUSIC`, return artists and albums rather than tracks.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/media/recently-added": { "get": { "operationId": "getMediaRecentlyAdded", "tags": [ "Library" ], "summary": "Newest additions", "description": "Scope: `media:read`.", "x-scope": "media:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1–50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "type", "in": "query", "required": false, "description": "Library type.", "schema": { "type": "string", "enum": [ "MOVIE", "SERIES", "MUSIC" ] } }, { "name": "serverId", "in": "query", "required": false, "description": "Limit to one media server.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`serverId` names no server of yours", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/media/stats": { "get": { "operationId": "getMediaStats", "tags": [ "Library" ], "summary": "Library totals and breakdowns", "description": "Scope: `media:read`.", "x-scope": "media:read", "parameters": [ { "name": "serverId", "in": "query", "required": false, "description": "Limit to one media server.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`serverId` names no server of yours", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/media/history": { "get": { "operationId": "getMediaHistory", "tags": [ "Library" ], "summary": "Play history", "description": "Scope: `media:read`.", "x-scope": "media:read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page, at most 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "search", "in": "query", "required": false, "description": "Title search.", "schema": { "type": "string" } }, { "name": "username", "in": "query", "required": false, "description": "Pipe-separated media-server usernames.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Pipe-separated library types.", "schema": { "type": "string" } }, { "name": "serverId", "in": "query", "required": false, "description": "Limit to one media server.", "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "required": false, "description": "Field to sort by.", "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/media/{id}": { "get": { "operationId": "getMediaById", "tags": [ "Library" ], "summary": "One item with streams, external ids and file details (file path and server addresses omitted)", "description": "Scope: `media:read`.", "x-scope": "media:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A Librariarr id, as returned by the listing endpoints.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/media/{id}/plays": { "get": { "operationId": "getMediaByIdPlays", "tags": [ "Library" ], "summary": "One item's plays", "description": "Scope: `media:read`.", "x-scope": "media:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A Librariarr id, as returned by the listing endpoints.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "At most 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "serverId", "in": "query", "required": false, "description": "Limit to one media server.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/media/{id}/image": { "get": { "operationId": "getMediaByIdImage", "tags": [ "Library" ], "summary": "Artwork", "description": "Scope: `media:read`.", "x-scope": "media:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A Librariarr id, as returned by the listing endpoints.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Which artwork; poster by default. `role` is a cast member's photo, picked by `index`.", "schema": { "type": "string", "enum": [ "art", "parent", "season", "role" ] } }, { "name": "index", "in": "query", "required": false, "description": "With `type=role`, the cast member's position in the item's roles.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "w", "in": "query", "required": false, "description": "Width.", "schema": { "type": "integer", "enum": [ 400, 640, 800 ] } } ], "responses": { "200": { "description": "OK", "content": { "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/lifecycle/rules": { "get": { "operationId": "getLifecycleRules", "tags": [ "Lifecycle" ], "summary": "Rule sets (owner omitted)", "description": "Scope: `lifecycle:read`.", "x-scope": "lifecycle:read", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/lifecycle/rules/matches": { "get": { "operationId": "getLifecycleRulesMatches", "tags": [ "Lifecycle" ], "summary": "Current matches per rule set", "description": "Scope: `lifecycle:read`. Each match carries the item snapshot detection stored, without its file path, cast and crew lists, tagline or original title (read `/media/{id}` for those). Not paged: every read counts as 20 requests.", "x-scope": "lifecycle:read", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/lifecycle/actions": { "get": { "operationId": "getLifecycleActions", "tags": [ "Lifecycle" ], "summary": "Actions by status", "description": "Scope: `lifecycle:read`. Grouped by rule set. A series action's `mediaItem.title` is the show, or ` SxxExx` when it acts on a single episode, and its `parentTitle` is null. Each group's `ruleSet.actionsHeldSince` is the time its rules, servers or sticky matches were changed, or it was enabled again, while its actions wait for the next detection run to re-check its matches (executing or retrying one answers 409 until then), and null otherwise. Its `ruleSet.scopeHoldReason` is set, a sentence, while its actions are held because it uses per-episode or per-track criteria with series or artist scope on, or follows them with an action on the whole show or artist (Delete from Sonarr or Lidarr, Change Quality Profile, Arr tags, …) with the scope off (executing or retrying one answers 409 with that reason until the rule set is edited), and null otherwise. Each action's `error` is redacted of internal addresses and paths, and the owner is omitted. Not paged: every read counts as 20 requests.", "x-scope": "lifecycle:read", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Which actions.", "schema": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED", "ALL" ], "default": "PENDING" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/lifecycle/exceptions": { "get": { "operationId": "getLifecycleExceptions", "tags": [ "Lifecycle" ], "summary": "Exceptions (owner omitted)", "description": "Scope: `lifecycle:read`. Not paged: every read counts as 20 requests.", "x-scope": "lifecycle:read", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Library type, or ALL.", "schema": { "type": "string", "enum": [ "MOVIE", "SERIES", "MUSIC", "ALL" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] }, "post": { "operationId": "postLifecycleExceptions", "tags": [ "Lifecycle" ], "summary": "Exclude an item from every rule", "description": "Scope: `lifecycle:write`.", "x-scope": "lifecycle:write", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mediaItemId" ], "properties": { "mediaItemId": { "type": "string" }, "reason": { "type": "string", "maxLength": 1000 }, "scope": { "type": "string", "enum": [ "individual", "series", "artist", "album" ], "default": "individual" } } } } } }, "responses": { "201": { "description": "Created: `{ exception }`, or `{ count, scope }` for a series, artist or album", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such media item, or nothing related to it for that scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] }, "delete": { "operationId": "deleteLifecycleExceptions", "tags": [ "Lifecycle" ], "summary": "Remove exceptions", "description": "Scope: `lifecycle:execute`. Removing an exception lets the rules match the item again, which can lead to its deletion — hence the destructive scope. At most 25 per request, and each removal counts against the API's 100-an-hour deletion budget.", "x-scope": "lifecycle:execute", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "additionalProperties": false, "properties": { "ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 25 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Every API key together has deleted or unprotected 100 items in the last hour; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/lifecycle/stats": { "get": { "operationId": "getLifecycleStats", "tags": [ "Lifecycle" ], "summary": "Deletion statistics", "description": "Scope: `lifecycle:read`.", "x-scope": "lifecycle:read", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/jobs/detection": { "post": { "operationId": "postJobsDetection", "tags": [ "Lifecycle" ], "summary": "Queue lifecycle detection for every enabled rule set", "description": "Scope: `lifecycle:write`.", "x-scope": "lifecycle:write", "parameters": [], "responses": { "202": { "description": "Queued: `{ queued: true, jobs: 1 }`", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The job could not be queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/lifecycle/exceptions/{id}": { "delete": { "operationId": "deleteLifecycleExceptionsById", "tags": [ "Lifecycle" ], "summary": "Remove one exception", "description": "Scope: `lifecycle:execute`. Counts against the API's 100-an-hour deletion budget.", "x-scope": "lifecycle:execute", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A Librariarr id, as returned by the listing endpoints.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Every API key together has deleted or unprotected 100 items in the last hour; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/lifecycle/actions/execute": { "post": { "operationId": "postLifecycleActionsExecute", "tags": [ "Lifecycle" ], "summary": "Run a rule set's action now on named matches", "description": "Scope: `lifecycle:execute`. Acts only on the listed items that are current matches of the rule set; name every item (there is no \"every match\"). At most 25 items per request. When the action deletes (Sonarr, Radarr or Lidarr), the items count against the 100-an-hour deletion budget every key shares. The rule set must be enabled with actions turned on. Listed items that are not current matches, or are protected by an exception, are skipped and the rest run — compare `executed` + `failed` with what you sent (400 when nothing is left). Refused whole — nothing runs — when an item changed identity since it matched, or the rule set was edited (its rules, servers or sticky matches) or enabled again since its matches were detected (409: run detection again), or the rule set uses per-episode or per-track criteria with series or artist scope on, or follows them with an action on the whole show or artist with the scope off (409: edit the rule set), or when a limit would be exceeded. A call naming an item that another execution of the same rule set is acting on right now is refused (409) rather than repeating the deletion; calls naming different items run side by side.", "x-scope": "lifecycle:execute", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ruleSetId", "mediaItemIds" ], "additionalProperties": false, "properties": { "ruleSetId": { "type": "string" }, "mediaItemIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 25 } } } } } }, "responses": { "200": { "description": "`{ executed, failed, errors, stopped? }` — `stopped`, a sentence, when the rule set was edited or held while the items ran: the items not yet reached were left untouched", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such rule set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Another execution of this rule set is acting on one of the named items, an item changed identity since it matched (a re-match on the media server), the rule set was edited (its rules, servers or sticky matches) or enabled again since its matches were detected, or the rule set uses per-episode or per-track criteria with series or artist scope on, or follows them with an action on the whole show or artist with the scope off, or the rule set was edited before the first item ran; nothing was executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Every API key together has deleted or unprotected 100 items in the last hour; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/jobs/execution": { "post": { "operationId": "postJobsExecution", "tags": [ "Lifecycle" ], "summary": "Queue lifecycle execution of every due pending action", "description": "Scope: `lifecycle:execute`. A run queued here is held — nothing deleted, every action left pending for the schedule or the Pending page — when it would delete more than 25 items or exceed the 100-an-hour deletion budget.", "x-scope": "lifecycle:execute", "parameters": [], "responses": { "202": { "description": "Queued: `{ queued: true, jobs: 1 }`", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The job could not be queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/tools/sessions": { "get": { "operationId": "getToolsSessions", "tags": [ "Streams" ], "summary": "Active playback sessions on every enabled server", "description": "Scope: `streams:read`. Who is watching what, on which player and from which address. The path of the file being played is omitted. Answered from a listing at most 5 seconds old, so polling faster than that returns the same answer.", "x-scope": "streams:read", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/tools/maintenance": { "get": { "operationId": "getToolsMaintenance", "tags": [ "Streams" ], "summary": "Maintenance mode status", "description": "Scope: `streams:read`.", "x-scope": "streams:read", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] }, "put": { "operationId": "putToolsMaintenance", "tags": [ "Streams" ], "summary": "Turn maintenance mode on or off", "description": "Scope: `streams:write`. `message` and `delay` keep their current values when left out. Any other field is refused.", "x-scope": "streams:write", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "enabled" ], "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "message": { "type": "string", "maxLength": 500 }, "delay": { "type": "integer", "minimum": 0, "maximum": 3600 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } }, "/tools/sessions/terminate": { "post": { "operationId": "postToolsSessionsTerminate", "tags": [ "Streams" ], "summary": "Stop playback", "description": "Scope: `streams:write`. Omit `sessionIds` to stop every stream on the server; `serverId` may be `all`. Session ids are the `sessionId` values `/tools/sessions` returns (letters, digits, `-` and `_`).", "x-scope": "streams:write", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "serverId", "message" ], "properties": { "serverId": { "type": "string" }, "sessionIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "maxItems": 200 }, "message": { "type": "string", "minLength": 1, "maxLength": 500 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: invalid body or parameters, a key in the URL, or two different keys in the headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, an unknown or deleted key, or an expired key (`WWW-Authenticate: Bearer`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the required scope; `requiredScope` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`serverId` names no enabled server of yours", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication is temporarily unavailable (the database could not be reached); retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "`Authorization: Bearer lbr_…`" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" }, "description": "Validation failures" }, "requiredScope": { "type": "string" } } } } } }