Docs API reference Playback API reference
Playback The playback decision, progress, watched state, reading position and sessions. docs/08.
Paths are relative to /api/v1 on your server.
POST /items/{id} /favorite# Favourite an item 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 · ErrorEnvelopeDELETE /items/{id} /favorite# Unfavourite an item 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 · ErrorEnvelopeWhat plays after this Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)includequery string
200 Success. application/json · object 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} /o-counter# Bump the O-counter Authorisation Bearer token or API key · Session cookie Body application/json · objectParameter In Type Description id required path string (uuid)
200 Success. application/json · object 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} /playback-info# Decide how to play an item The client describes itself (docs/05 §4); the server answers direct play, remux or transcode, with reasons[] always. Starts a session.
Authorisation Bearer token or API key · Session cookie Body application/json · objectParameter In Type Description id required path string (uuid)
200 Success. application/json · PlaybackInfo 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.
MEDIA_FILE_MISSING: the file is not where the scan left it application/json · ErrorEnvelope415 MEDIA_NOT_PLAYABLE: nothing about the file can be delivered to this device application/json · ErrorEnvelope429 STREAM_LIMIT_REACHED: the account is already playing as many streams as it may application/json · ErrorEnvelope503 TRANSCODE_LIMIT_REACHED: the server is at its transcode cap application/json · ErrorEnvelopeMark watched On a show, season or course, marks everything beneath it.
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 · ErrorEnvelopeDELETE /items/{id} /played# Mark unwatched 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 · ErrorEnvelopeSet the position outside a session Authorisation Bearer token or API key · Session cookie Body application/json · objectParameter In Type Description id required path string (uuid)
200 Success. application/json · object 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 · ErrorEnvelopeRead a book’s reading position 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 · ErrorEnvelopeSet a book’s reading position Authorisation Bearer token or API key · Session cookie Body application/json · objectParameter In Type Description id required path string (uuid)
200 Success. application/json · object 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 an item’s theme music The theme.mp3 beside a show or film (P3-26). Range requests honoured.
Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)
200 Success. audio/* · 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 · ErrorEnvelopeGET /playback/continue-watching# Continue watching Authorisation Bearer token or API key · Session cookie Parameter In Type Description typesquery stringlimitquery integerincludequery string
200 Success. application/json · object 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 · ErrorEnvelopeDELETE /playback/continue-watching/{id} # Hide an item from continue watching 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 · ErrorEnvelopeGET /playback/preroll/{itemId} # The pre-roll plan for a film Which pre-roll files play first, or none — a library, a setting or the item type can each say no.
Authorisation Bearer token or API key · Session cookie Parameter In Type Description itemId required path string
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 · ErrorEnvelopeReport a playback position Authorisation Bearer token or API key · Session cookie Body application/json · object200 Success. application/json · object 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 · ErrorEnvelopeEnd a playback session A sendBeacon target: the body may be text/plain JSON carrying clientId in place of the header.
Authorisation Bearer token or API key · Session cookie Body application/json · object204 Done; no body. 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 · ErrorEnvelopeList active sessions An account sees its own; session:manage sees everyone’s.
Authorisation Bearer token or API key · Session cookie 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 · ErrorEnvelopeTerminate a session Authorisation Bearer token or API key · Session cookie Body application/json · objectParameter In Type Description id required path string (uuid)
204 Done; no body. 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 · ErrorEnvelopeRead a transcode session’s FFmpeg log 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 session:manage, 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 .