API reference

Libraries

Libraries and their folders, ordering and trash.

Paths are relative to /api/v1 on your server.

GET/libraries#

List the libraries the caller may see

Authorisation: Bearer token or API key · Session cookie

200Success. application/json · Library[]
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

POST/libraries#

Create a library

Authorisation: Bearer token or API key · Session cookie
Body: application/json · object

201Success. application/json · Library
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

GET/libraries/{id}#

Read a library

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

200Success. application/json · Library
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

PATCH/libraries/{id}#

Update a library

Authorisation: Bearer token or API key · Session cookie
Body: application/json · object

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

200Success. application/json · Library
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

DELETE/libraries/{id}#

Delete a library

Rows and state go; media files are never touched.

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

204Done; no body.
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

POST/libraries/{id}/analyze#

Analyse the library now

Plex’s Manage Library → Analyze (2026-10-11): every analysis switched on — on the server (analysis.*) and for the library (previewThumbnails, introDetection, creditsDetection, voiceActivity) — queued now on the added queue for what in the library still lacks it, not held to the maintenance window; one job at a time, each waiting while anyone streams. Nothing already done is queued again. Credits named by chapters are marked there and then (creditsFromChapters). An analysis that cannot apply to the library’s type is neither queued nor listed in off. library:manage.

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

200Success. application/json · object
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: there is no such library application/json · ErrorEnvelope

POST/libraries/{id}/auto-tag#

Tag items from their file names

Authorisation: Bearer token or API key · Session cookie
Body: application/json · object

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

200Success. application/json · object
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

GET/libraries/{id}/duplicates#

List duplicate groups by fingerprint

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`
`distance`	query	`integer`

200Success. application/json · object
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

GET/libraries/{id}/fingerprints#

Read fingerprinting progress

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

200Success. application/json · object
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

POST/libraries/{id}/fingerprints#

Fingerprint the library’s files

Authorisation: Bearer token or API key · Session cookie
Body: application/json · object

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

200Success. application/json · object
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

POST/libraries/{id}/folders#

Add folders of a storage to a library

An admin adds any storage’s folders; a member adds folders of a cloud drive they connected to a photo library they may upload to (P6-15). A quick scan follows.

Authorisation: Bearer token or API key · Session cookie
Body: application/json · object

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

200Success. application/json · Library
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

GET/libraries/{id}/trash#

List the library’s trash

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

200Success. application/json · object
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

DELETE/libraries/{id}/trash#

Empty the trash

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

200Success. application/json · object
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

DELETE/libraries/{id}/trash/{itemId}#

Purge one trashed item

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`
`itemId` required	path	`string (uuid)`

200Success. application/json · object
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

POST/libraries/{id}/trash/restore#

Restore trashed items

Authorisation: Bearer token or API key · Session cookie
Body: application/json · object

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

200Success. application/json · object
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

DELETE/libraries/{id}/trickplay#

Delete a library’s preview thumbnails

Every trickplay sprite sheet made for the library’s files is deleted (2026-10-11, Plex’s “Delete preview thumbnails”); removed is how many files had some. New ones are made again only while the library’s settings.previewThumbnails and the server’s analysis.preview_thumbnails allow, which reads each video once more. library:manage.

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

200Success. application/json · object
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

PUT/libraries/order#

Reorder the sidebar

Authorisation: Bearer token or API key · Session cookie
Body: application/json · object

200Success. application/json · Library[]
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

GET/metadata/agents#

The metadata agents a library can order

Every built-in provider and every installed plugin that provides metadata (P6-10): the id settings.agents names it by, the item types it describes, and whether it answers now. A built-in waiting for a key lists the environment variables it goes in; a plugin that is off is available: false. An agent that cannot answer is skipped at refresh, not an error. library:manage.

Authorisation: Bearer token or API key · Session cookie

200Success. application/json · object
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

GET/metadata/keys#

Read where each catalogue key comes from

Plex’s Settings → Metadata Agents: every key a catalogue or OpenSubtitles needs, with the agent it is for, the environment variable it otherwise comes from, and whether the one in use was saved in the app, comes from the environment, or is missing. A username is shown as it is; a secret never is. settings:manage.

Authorisation: Bearer token or API key · Session cookie

200Success. application/json · object
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

PUT/metadata/keys#

Save or remove catalogue keys

A string is saved, sealed with SECRET_KEY, and used in place of the environment’s; null removes the saved one, so the environment’s applies again. Keys not named are left alone. The agents answer with the keys now in use from the next refresh, without a restart, in the worker too. settings:manage.

Authorisation: Bearer token or API key · Session cookie
Body: application/json · object

200Success. application/json · object
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope