ApiClient. ApiClient

Authenticate user by username and password

Build a request AA to exchange an APPROVED Quick Connect secret for an auth token, for use with fetchAsync() / fetchRes().

The body's field name changed at 10.8.0, a FINER boundary than the V1/V2 apiVersion split, so it reads the server version directly rather than m.getApiVersion(): 10.7.x: { "Token": secret } (QuickConnectDto.Token, required) 10.8.0+: { "Secret": secret } (QuickConnectDto.Secret, required) Confirmed against every published spec from 10.7.0 to 10.11.8: the rename lands at exactly 10.8.0, with no version carrying both names.

DON'T BRANCH ON THE ERROR CODE HERE. The spec declares only 400 ("Missing token") plus 503 from 10.11.0, but a live 10.11.11 answered 404 for a secret it had not seen approved, an undeclared code. So a non-ok response means "this secret cannot be exchanged" and nothing finer; quickConnectExchangeFailure (source/utils/quickConnect.bs) owns the one distinction worth making.

Build a request AA to cancel a Live TV series recording timer, for use with SubmitSideEffect().

Build a request AA to cancel a Live TV recording timer, for use with SubmitSideEffect().

Build a request AA to close a live stream the server opened for PlaybackInfo, for use with SubmitSideEffect(). Each close releases one consumer; the server closes the stream when none remain. The same endpoint and query on every supported server (10.7.0 through 12.x).

Build a request AA to poll whether a Quick Connect secret has been approved, for use with fetchAsync() / fetchRes(). Responds 200 with the same QuickConnectResult shape Initiate returned, its Authenticated flag now true once someone approved the code.

An UNKNOWN or EXPIRED secret answers 404 ("Unknown quick connect secret"), declared by every published spec from 10.7.0 to 10.11.8 and corroborated by a live 10.11.11. That is the only signal separating "not approved yet" from "this code is dead", and it is invisible to a caller that only parses the body, which is why this endpoint has to go through the pool (res.statusCode) rather than a sync JSON helper.

Build a request AA to create a Live TV series recording timer, for use with fetchRes() or fetchJson().

Build a request AA to create a Live TV recording timer, for use with fetchRes() or fetchJson().

Build a request AA to delete an item, for use with SubmitSideEffect().

Build a request AA to delete an EXTERNAL subtitle file from an item, for use with fetchRes().

It takes the stream, not an index, and that is the point. The server deletes MediaStream.Path unconditionally, and for an EMBEDDED stream that path is the media container, so aiming this at the wrong stream destroys the user's movie, not a subtitle. This used to accept a bare integer and warn the caller in prose to check IsExternal first. Prose is not a guard: the subtitle panel's list was ALSO external-only at the time, so the safety rested on two separate places staying in agreement, and the moment that list grew to include embedded streams (so it could describe the item honestly) the only thing standing between a mis-wired row and a deleted container was a comment. Requiring the stream means the check happens here, once, and cannot be forgotten by a future caller.

A non-external stream returns INVALID rather than raising: callers already treat an invalid request as "cannot do this" (validatedReq does the same when no server URL is set), so refusing degrades into an inert button instead of a crash.

The one hazard left with the caller: Index must come from a FRESH item fetch. A download inserts a subtitle at index 0 and renumbers every other stream, so a stale index deletes the wrong file, or errors (observed as HTTP 400) if it now points past the end.

Unlike download, delete is SYNCHRONOUS end-to-end: the controller awaits RefreshMetadata, so the next GET /Items/{id} already reflects the new stream list (verified: correct at t+0s).

external subtitle, has no index, or the server URL is not set

Build a request AA to have the SERVER download a remote subtitle onto the item, for use with fetchRes() (not SubmitSideEffect: see below).

The response carries NO success information: the controller wraps the download in try/catch, logs any failure, and returns 204 either way, then queues the metadata refresh ASYNCHRONOUSLY (QueueRefresh). A missing provider, absent credentials, and an exhausted daily quota all yield the same 204 as a success. The only honest completion signal is re-fetching the item and diffing its subtitle MediaStreams: see newSubtitleStreams().

Build a request AA for GetAdditionalParts, for use with fetchRes() or fetchJson().

Build a request AA to fetch all album artists, for use with fetchRes() or fetchJson(). Mirrors GetAlbumArtists(): applies injectDefaults and injects UserId.

Build a request AA to get similar artists, for use with fetchRes() or fetchJson().

Build a request AA to fetch all artists, for use with fetchRes() or fetchJson(). Mirrors GetArtists(): applies injectDefaults and injects UserId.

Build a request AA for GetBrandingConfiguration, for use with fetchRes() or fetchJson().

Build a request AA for the server's culture list, for use with fetchRes() or fetchJson(). Returns an array of CultureDto.

Worth caching for the session: it is static per server (192 entries on 10.11.11) and is only needed to populate a language picker.

Build a request AA for GetEpisodes, for use with fetchRes() or fetchJson().

Build a request AA for GetFilters2, for use with fetchRes() or fetchJson().

A SECOND filters endpoint, not a replacement: the two return disjoint sets. /items/filters carries OfficialRatings and Years, which this one does not; this one carries AudioLanguages and SubtitleLanguages (12.0+), which that one does not. A caller wanting both has to ask twice, verified against the 10.11.11 and 12.0.0 OpenAPI specs, where QueryFiltersLegacy and QueryFilters are separate schemas.

On servers below 12.0 the response omits the language keys entirely, so their absence is a usable capability probe rather than an empty-list ambiguity.

Build a request AA for GetFilters, for use with fetchRes() or fetchJson().

Build a request AA to fetch genres, for use with fetchRes() or fetchJson().

Build a request AA for GetInstantMix, for use with fetchJson().

Build a request AA for GetIntros, for use with fetchJson().

Build a request AA for the collections an item belongs to, for use with fetchRes(). Jellyfin 12.0+ only, so there is no V1 path: older servers answer 404. Decide with extrasRows.supportsItemCollections() before building it.

Build a request AA for GetItemImageInfos: every image the item has, with each one's original Width and Height. The same path on every supported server (10.7.0 onward).

Build a request AA for GetItemLyrics, for use with fetchJson().

Build a request AA to get a single item WITHOUT image/version field injection.

Get a single item by ID with automatic image and version field injection Build a request AA to get a single item with automatic image/version field injection.

Build a request AA for one item's UserData (position, played, favorite), for use with fetchRes() or fetchAsync(). Returns a UserItemDataDto, about 150 bytes, where the full item is kilobytes.

It reads the play state of an ALTERNATE VERSION, which no item query returns on Jellyfin 12.0 (/Items?ids= filters versions out). Only per-version servers need that, so callers gate on versionResume.isPerVersionServer(). The route is not in the 10.7.0 floor spec, so a V1 server gets no request rather than a guessed path.

Build a request AA for GetItemsByQuery, for use with fetchRes() or fetchJson().

Build a request AA for GetLatestMedia, for use with fetchRes() or fetchJson(). Both V1 and V2 return a bare array of BaseItemDto (not paginated). V1: /users/{id}/items/latest (10.7.x–10.8.x) V2: /Items/Latest?userId= (10.9+)

Build a request AA for the server's library options, for use with fetchRes() or fetchJson(). Returns a LibraryOptionsResultDto.

Used to learn which metadata PLUGINS the server has installed (SubtitleFetchers lists every installed subtitle provider by name), so a feature that needs one can be hidden rather than offered and then fail empty. Read by source/utils/serverCapabilities.bs.

Unchanged from 10.7.0 through 12.0, and authorized for ANY signed-in user (Policies.FirstTimeSetupOrDefault), so it needs no V1/V2 branch and no admin. libraryContentType is omitted on purpose: the server then reports plugins for Series, Season, Episode and Movie, exactly the types subtitle search supports.

Build a request AA to fetch Live TV channels, for use with fetchRes() or fetchJson().

Build a request AA for GetLiveTVPrograms (full EPG search), for use with fetchRes() or fetchJson(). Mirrors GetLiveTVPrograms(): applies injectDefaults.

Build a request AA to fetch a single Live TV program, for use with fetchRes() or fetchJson().

Build a request AA to get recommended Live TV programs (On Now), for use with fetchRes() or fetchJson().

Build a request AA to get Live TV recordings, for use with fetchRes() or fetchJson().

Build a request AA to fetch the Live TV schedule, for use with fetchRes() or fetchJson(). Uses POST because the channelIds list can exceed URL length limits.

Build a request AA to fetch Live TV timer defaults for a program, for use with fetchRes() or fetchJson().

Build a request AA for GetLocalTrailers, for use with submitApiRequest() or fetchJson(). Version-aware: V2 uses /Items/{id}/LocalTrailers, V1 uses /users/{userId}/items/{id}/localtrailers.

Build a request AA for GetMediaSegments, for use with fetchJson(). Only available on Jellyfin 10.10.0+ servers.

Build a request AA for GetNextUp, for use with fetchRes() or fetchJson(). Mirrors GetNextUp(): applies injectDefaults and injects UserId.

Build a request AA for GetPersons, for use with fetchRes() or fetchJson(). Applies injectDefaults and injects UserId.

Leaves out the Artist and AlbumArtist kinds unless the caller passes its own ExcludePersonTypes. From 12.0 the server lists music artists as people (jellyfin#16721), and the app lists artists from /Artists, so search showed a musician twice. jellyfin-web sends the same filter, marked to go once artists move to /Persons; drop it here then. Every supported server accepts the parameter, so it is not version-gated.

Build a request AA for GetPlaylistItems, for use with fetchRes() or fetchJson().

Build a request AA for GetQuickConnectEnabled, for use with fetchRes() or fetchJson(). Server responds with a plain boolean body (true = enabled, false = disabled). Lowercase path matches the existing /quickconnect/initiate convention - Jellyfin's routing is case-insensitive but reverse proxies in the wild sometimes are not.

Build a request AA for GetResumeItems (Continue Watching), for use with fetchRes() or fetchJson(). Mirrors GetResumeItems(): applies injectDefaults, version-aware endpoint.

The server hardcodes Recursive, OrderBy=DatePlayed and IsResumable on this endpoint, so MediaTypes is the only narrowing a client controls. Don't bother sending recursive / SortBy / SortOrder / Filters, they are ignored. Since 12.0 a folder also matches IsResumable when a descendant is in progress, so an unfiltered query returns Seasons and Series (by design) mixed in with the episodes. Every JellyRock resume flow is video, so default to Video; pass MediaTypes as a comma-separated STRING to widen it.

Build a request AA for GetSeasons, for use with fetchRes() or fetchJson(). Mirrors GetSeasons(): applies injectDefaults and injects UserId.

Build a request AA for the server configuration, for use with fetchRes() or fetchAsync(). Returns a ServerConfiguration.

Read for MaxResumePct: the percentage past which the server records playback as finished instead of storing a resume position (source/utils/versionResume.bs). Authorized for ANY signed-in user, not only admins: a non-admin account got 200 on 10.7.7, 10.10.7, 10.11.11 and 12.0.0.

Build a request AA to get active sessions, for use with fetchJson().

Build a request AA to get similar items, for use with fetchRes() or fetchJson().

Build a request AA for GetSpecialFeatures, for use with fetchRes() or fetchJson(). Mirrors GetSpecialFeatures(): version-aware endpoint.

Build a request AA to fetch studios, for use with fetchRes() or fetchJson().

Build a request AA for GetViews, for use with fetchRes() or fetchJson(). Mirrors GetViews(): version-aware endpoint.

Build a HEAD request AA to check if an item image exists, for use with fetchRes() or fetchJson(). Caller checks res.ok: no body is returned for HEAD requests.

Build a request AA to start a Quick Connect request, for use with fetchAsync() / fetchRes(). The response carries the Secret we poll with and the Code the user types on their other device.

The HTTP METHOD moved at the same boundary as the apiVersion split: apiVersion 1 (10.7.0 - 10.8.13): GET (no POST route exists) apiVersion 2 (10.9.0+): POST (no GET route exists) Confirmed against every published spec from 10.7.0 to 10.11.8: each version declares exactly one of the two verbs, and the swap is at exactly 10.9.0.

Sending the wrong method to a modern server yields 401 ("Quick connect is not active on this server"), which reads as a feature gate but is actually a route mismatch, so the dispatch matters; it is not cosmetic. That collision is also why quickConnectInitiateFailure treats 401 as "disabled": it is the same code either way, and a route mismatch is our bug, not something to tell a user.

Build a request AA to mark an item as favorite, for use with SubmitSideEffect().

Build a request AA to mark an item as played, for use with SubmitSideEffect(). Includes default DatePlayed (now) and PlaybackPositionTicks (0) matching Jellyfin API expectations.

Build a playstate request AA for use with SubmitSideEffect(). Applies default playstate fields and routes to the correct session endpoint.

Build a request AA for PostPlaybackInfo, for use with fetchJson().

Build a request AA to post full session capabilities, for use with SubmitSideEffect().

Build a request AA to search a server's configured subtitle providers, for use with fetchRes() or fetchJson(). Returns an array of RemoteSubtitleInfo.

language is passed straight through to the server, which resolves it via LocalizationManager.FindLanguageInfo(), which matches case-insensitively on DisplayName, Name, TwoLetterISOLanguageName, OR either ISO 639-2 variant (/T and /B both live in ThreeLetterISOLanguageNames). So "fra", "fre", "fr" and "French" are all accepted. Prefer the TWO-letter form from /Localization/Cultures: it is what reaches the provider, and it preserves regional variants that the 3-letter form collapses (zh-tw / zh-cn / zh-hk all share "zho"; es-419 shares "spa" with Castilian).

a true value returns only results whose IsHashMatch is set, which is frequently an empty list.

Build a request AA to unmark an item as favorite, for use with SubmitSideEffect().

Build a request AA to mark an item as unplayed, for use with SubmitSideEffect().

Get display preferences

Get image URL

Get public users Synchronous, so it bypasses the pool's shape check (listReq); the list is read here instead.

Get user by ID

Get user image URL