Docs API reference Items API reference
Items Browse a library, read an item, its children and tree. include= expands relations (docs/05 §1).
Paths are relative to /api/v1 on your server.
Read an item Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)includequery string
200 Success. application/json · Item 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 · ErrorEnvelopeAn item’s children Seasons of a show, episodes of a season, sections of a course, tracks of an album. A show library may list a show’s episodes in place of its seasons (settings.seasons: hide, or hide-single for a show with one season), each still under its season, and a season’s episodes newest first (settings.episodeSort).
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 · ErrorEnvelopeYour bookmarks and highlights in a book The caller’s own, in the book’s order (how far into it each one is). Where a mark is, is the reader engine’s own word for it: an EPUB CFI (a range, for a highlight), page:<n> in a PDF, fraction:<f> otherwise.
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.
NOT_FOUND: no item the caller can see has that id application/json · ErrorEnvelopeBookmark a page, or highlight words A bookmark on a place already bookmarked is that bookmark, answered as it is. A highlight is yellow unless it names a colour, and may carry a note.
Authorisation Bearer token or API key · Session cookie Body application/json · objectParameter In Type Description id required path string (uuid)
201 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.
NOT_FOUND: no item the caller can see has that id application/json · ErrorEnvelopeGET /items/{id} /resources# The files beside an item Sidecars attached at scan time (a PDF, a zip, an exercise folder); each names its download URL.
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 · ErrorEnvelopeAn item with its whole subtree Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)includequery string
200 Success. application/json · Item 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 /libraries/{id} /facets# Count the values a library can be filtered by Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)limitquery integer
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 · ErrorEnvelopeGET /libraries/{id} /game-facets# What a games library’s filters offer Counted over the games the caller can see, the most first: platforms, the caller’s own statuses (none for the games they have not marked), regions, developers, publishers, series and play modes — a game made by two studios counts under each — and how many are the caller’s favourites and how many they have never started. limit caps each list.
Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)limitquery integer
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 · ErrorEnvelopeGET /libraries/{id} /game-platforms# A games library’s platforms Each platform the library holds games for, with how many the caller can see, the most first.
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 /libraries/{id} /items# Browse a library Cursor pagination (docs/05 §1). filter is the filter DSL of docs/05 §2; sort a comma-separated list of field:asc|desc.
Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)limitquery integercursorquery stringfilterquery stringsortquery stringincludequery string
200 Success. application/json · ItemPage 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 /libraries/{id} /latest# Recently added Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)limitquery 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 · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopeGET /libraries/{id} /markers# Named moments across a library Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)titlequery stringlimitquery integeroffsetquery integer
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 · ErrorEnvelopeGET /libraries/{id} /on-this-day# Photos and home videos from this day in earlier years Grouped by year, the most recent first, each year’s first perYear in the order they were taken and how many there were. date is the day as the caller has it (YYYY-MM-DD); the server’s today when absent.
Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)datequery stringperYearquery integeryearsquery integer
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 · ErrorEnvelopeGET /libraries/{id} /people# People across a library Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)rolequery stringgenderquery stringhiddenquery sortquery "count" | "name"limitquery integeroffsetquery integer
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 · ErrorEnvelopeGET /libraries/{id} /places# Where a library’s photos and home videos were taken Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)limitquery integer
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 · ErrorEnvelopeGET /libraries/{id} /recently-played# Recently played, per account Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)limitquery 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 · ErrorEnvelope404 NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelopeGET /libraries/{id} /series# A books or audiobook library’s series 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 /libraries/{id} /series/books# One series in reading order Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)name required query stringincludequery 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 · ErrorEnvelopeGET /libraries/{id} /timeline# A photo library by month 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 · ErrorEnvelopePATCH /reading-marks/{markId} # Change a highlight’s colour or note Authorisation Bearer token or API key · Session cookie Body application/json · objectParameter In Type Description markId 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.
NOT_FOUND: the caller has no mark with that id application/json · ErrorEnvelopeDELETE /reading-marks/{markId} # Delete a bookmark or highlight Authorisation Bearer token or API key · Session cookie Parameter In Type Description markId required path string (uuid)
204 Done; no body. 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.
NOT_FOUND: the caller has no mark with that id application/json · ErrorEnvelopeGET /resources/{id} /download# Download a resource Authorisation Bearer token or API key · Session cookie Parameter In Type Description id required path string (uuid)
200 Success. application/octet-stream · 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 · ErrorEnvelopeNo endpoint here matches. Try another word, or look in another area .