Docs API reference Artwork API reference
Artwork Posters, backdrops and portraits: serve, list candidates, upload and choose.
Paths are relative to /api/v1 on your server.
GET /collections/{id} /poster# Serve a collection’s poster Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)wquery integerfmtquery "webp" | "jpeg"vquery string
200 Success. image/* · 400 VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopePOST /collections/{id} /poster# Upload a collection’s poster Authorisation Bearer token or API key · Session cookie Body image/* · Parameter In Type Description id required path string (uuid)
200 Success. application/json · Collection 400 VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks playlist:own, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopeGET /items/{id} /artwork-candidates# List the artwork on offer Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)
200 Success. application/json · object 401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopePOST /items/{id} /artwork-candidates/{artworkId} /select# Choose a candidate Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)artworkId required path string (uuid)
200 Success. application/json · ArtworkCandidate 401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopeGET /items/{id} /artwork/{kind} # Serve an item’s artwork kind is poster, backdrop, logo, thumb… Answers 304 to a matching If-None-Match.
Authorisation Bearer token or API key · Session cookie · Cast ticket Parameter In Type Description id required path string (uuid)kind required path stringwquery integerfmtquery "webp" | "jpeg"vquery string
200 Success. image/* · 400 VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopePOST /items/{id} /artwork/{kind} # Upload artwork The raw image as the body, with its content type. made=designer says it was drawn in the poster designer, which is Collectoh Plus’s (P6-20).
Authorisation Bearer token or API key · Session cookie Body image/* · Parameter In Type Description id required path string (uuid)kind required path stringmadequery "designer"
201 Success. application/json · ArtworkCandidate 400 VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopeGET /items/{id} /chapter-thumbnails.json# Read which chapters have a picture The pictures made for a file’s chapters when analysis.chapter_thumbnails asks (Plex’s “Generate chapter thumbnails”, 2026-10-11): those of the file asked for when it is the item’s and has some, else the primary file’s. A client matches them to the chapters it shows by startMs; a chapter without one shows the trickplay tile nearest its start. 404 when the item has none.
Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)fileIdquery string (uuid)
200 Success. application/json · ChapterThumbnailIndex 400 VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopeGET /items/{id} /chapter-thumbnails/{chapter} # Serve a chapter’s picture :chapter is <n>.jpg, n the chapter’s place in the index’s chapters; fileId the index’s mediaFileId, v its generatedAt (which makes the answer immutable).
Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)chapter required path stringfileIdquery string (uuid)vquery string
200 Success. image/jpeg · 400 VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopeGET /items/{id} /trickplay.json# Read the trickplay index Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)fileIdquery string (uuid)
200 Success. application/json · TrickplayIndex 400 VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopeGET /items/{id} /trickplay/{sheet} # Serve a trickplay sprite sheet Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)sheet required path stringfileIdquery string (uuid)vquery string
200 Success. image/jpeg · 400 VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopeServe a person’s portrait Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)wquery integerfmtquery "webp" | "jpeg"vquery string
200 Success. image/* · 400 VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopeList a person’s portraits Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)
200 Success. application/json · object 401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopeUpload a portrait Authorisation Bearer token or API key · Session cookie Body image/* · Parameter In Type Description id required path string (uuid)
201 Success. application/json · PersonImage 400 VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopeGET /people/{id} /images/{imageId} # Serve one portrait Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)imageId required path string (uuid)wquery integerfmtquery "webp" | "jpeg"vquery string
200 Success. image/* · 400 VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopePOST /people/{id} /images/{imageId} /select# Choose a portrait Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)imageId required path string (uuid)
200 Success. application/json · PersonImage 401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopeServe a studio’s logo Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)wquery integerfmtquery "webp" | "jpeg"vquery string
200 Success. image/* · 400 VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope401 UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope403 FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopeNo endpoint here matches. Try another word, or look in another area .