Developer

Multipass Server API

Browse, search, and control your Multipass media server from your own apps.

The public API for a Multipass media server. Use it to browse and search your libraries, filter with the same rich rules the smart-collections editor uses, list the devices currently connected to your server, and remote-control playback on them (start, pause, seek, stop).

Authentication. Every request carries an API token you create on your server's Settings page (Server → API tokens): Authorization: Bearer mpt_…. A Read token can browse, search, and list clients; a Full token can additionally control playback. The token acts as the server owner.

Base URL. Point requests at your own server, e.g. http://192.168.1.10:32600/api/v1 on your LAN, or whatever address you reach it at remotely. This documentation's live console calls the address you enter — nothing goes through Multipass's servers.

Stability. v1 is additive-only: new fields and endpoints may appear, but existing ones won't change or disappear under v1. A breaking change would ship as v2.

Profiles. Reads are per-profile where watch state matters. Send X-Profile-Id: <id> (see GET /profiles) to act as a specific profile; omit it for the default.

Console setup

Enter your server's address and an API token to run calls right here. Requests go straight from your browser to your server, never through Multipass.

Server base URL API token

Create a token in your server under Settings → API tokens. Saved only in this browser.

Discovery

Server identity, profiles, and filter vocabulary.

GET /openapi.json Public

This OpenAPI document

The machine-readable API description. Public — no token required.

Responses

200 The OpenAPI 3.1 document.

GET /server

Server identity

Name, software version, and server id. A quick way to confirm your token works.

Responses

200 Server identity.
401 Missing, invalid, or disabled API token.

GET /profiles

List profiles

The household's profiles. Use an id as X-Profile-Id on reads to get that profile's watch state.

Responses

200 Profiles and the default id.
401 Missing, invalid, or disabled API token.

Library

Browse libraries, items, and series.

GET /libraries

List libraries

Responses

200 The server's libraries.
401 Missing, invalid, or disabled API token.

GET /libraries/{id}/items

List items in a movie library

One page of a movie library's items. For show libraries use /libraries/{id}/series.

Parameters

`id`	path · required	Library id.
`sort`	query	Sort order.
`limit`	query	Page size (max 100).
`offset`	query	Page offset.

id sort limit offset

Responses

200 A page of items. `X-Total-Count` carries the full count.
401 Missing, invalid, or disabled API token.
404 No such library, item, series, or collection.

GET /libraries/{id}/series

List series in a show library

Parameters

`id`	path · required	Library id.
`sort`	query	Sort order.
`limit`	query	Page size (max 100).
`offset`	query	Page offset.

id sort limit offset

Responses

200 A page of series.
401 Missing, invalid, or disabled API token.
404 No such library, item, series, or collection.

GET /items/{id}

Get one item

A single movie or episode, with the requesting profile's progress attached.

Parameters

id path · required Item id.

Responses

200 The item.
401 Missing, invalid, or disabled API token.
404 No such library, item, series, or collection.

GET /series/{id}

Get one series with episodes

Parameters

id path · required Series id.

Responses

200 The series and its episodes in order.
401 Missing, invalid, or disabled API token.
404 No such library, item, series, or collection.

PUT /items/{id}/watched

Set watched state

Manually mark an item watched or unwatched for the acting profile. Marking unwatched also clears the resume position — the item leaves Keep Watching and replays from the start. through: true (episodes only, with watched: true) is catch-up: the target episode plus every earlier episode in the show becomes watched; specials (season 0) are never swept unless targeted directly. Play history is untouched. Requires a Full token.

Parameters

id path · required Item id.

Request body

Responses

200 The updated item, progress included.
400 The request was malformed.
401 Missing, invalid, or disabled API token.
403 The token is read-only; this action needs a Full token.
404 No such library, item, series, or collection.

PUT /series/{id}/watched

Bulk-set watched state for a series

Mark a whole series (or one season) watched or unwatched for the acting profile. Omit season for the whole series, specials included; season: 0 targets the specials explicitly. Unwatching clears resume positions (see PUT /items/{id}/watched). Requires a Full token.

Parameters

id path · required Series id.

Request body

Responses

200 How many episodes were updated.
400 The request was malformed.
401 Missing, invalid, or disabled API token.
403 The token is read-only; this action needs a Full token.
404 No such library, item, series, or collection.

GET /images/{file}

Fetch cached artwork

A poster/backdrop by its cache filename (the poster/backdrop fields on items and series).

Parameters

file path · required The image cache filename.

file

Responses

200 The image.
401 Missing, invalid, or disabled API token.
404 No such library, item, series, or collection.

Search

Search and rule-based filtering.

GET /search

Search movies and shows

Full-text search over titles and cast. Shows match at the series level.

Parameters

`q`	query · required	The search query.
`limit`	query	Page size (max 100).

q limit

Responses

200 Matching movies and series.
400 The request was malformed.
401 Missing, invalid, or disabled API token.

POST /browse

Browse and filter a library or collection

One page of a library or collection, optionally narrowed by filter rules (the same vocabulary the smart-collections editor exposes — see GET /filters). Sort and page as needed.

Request body

Responses

200 Matching entries and the total count.
400 The request was malformed.
401 Missing, invalid, or disabled API token.
404 No such library, item, series, or collection.

GET /filters

Filter vocabulary + values

The available filter fields and operators, plus the concrete values present in this server's catalog (genres, studios, people, crew jobs, libraries). Render your filter UI from this — it stays in sync with the server.

Responses

200 Filter metadata.
401 Missing, invalid, or disabled API token.

Clients

Connected devices and playback control.

GET /clients

List connected clients

Every device with a live connection to the server right now, including what each is playing. controllable: true means the device runs an app that accepts control commands; a device only appears while its app is open (there is no push wake).

Responses

200 Connected clients.
401 Missing, invalid, or disabled API token.

POST /clients/{deviceId}/play Full token

Start playback on a client

Tell a connected client to start playing an item, optionally from a position. Requires a Full token.

Parameters

deviceId path · required The client device id (from GET /clients).

deviceId

Request body

Responses

202 The command was delivered to the client.
400 The request was malformed.
401 Missing, invalid, or disabled API token.
403 The token is read-only; this action needs a Full token.
404 No such library, item, series, or collection.
409 The target client isn't connected or can't be controlled.

POST /clients/{deviceId}/pause Full token

Pause a client

Requires a Full token.

Parameters

deviceId path · required The client device id (from GET /clients).

deviceId

Responses

202 The command was delivered to the client.
401 Missing, invalid, or disabled API token.
403 The token is read-only; this action needs a Full token.
409 The target client isn't connected or can't be controlled.

POST /clients/{deviceId}/resume Full token

Resume a client

Requires a Full token.

Parameters

deviceId path · required The client device id (from GET /clients).

deviceId

Responses

202 The command was delivered to the client.
401 Missing, invalid, or disabled API token.
403 The token is read-only; this action needs a Full token.
409 The target client isn't connected or can't be controlled.

POST /clients/{deviceId}/stop Full token

Stop a client

Requires a Full token.

Parameters

deviceId path · required The client device id (from GET /clients).

deviceId

Responses

202 The command was delivered to the client.
401 Missing, invalid, or disabled API token.
403 The token is read-only; this action needs a Full token.
409 The target client isn't connected or can't be controlled.

POST /clients/{deviceId}/seek Full token

Seek a client

Jump the client to a position in the current item. Requires a Full token.

Parameters

deviceId path · required The client device id (from GET /clients).

deviceId

Request body

Responses

202 The command was delivered to the client.
400 The request was malformed.
401 Missing, invalid, or disabled API token.
403 The token is read-only; this action needs a Full token.
409 The target client isn't connected or can't be controlled.

Full machine-readable schema: download the OpenAPI 3.1 document, or fetch GET /api/v1/openapi.json from your server.