← API reference

Sources

Where listens are polled from. Session-only — holds credentials.

5 of 5 · v0.120.0
POST /api/v1/sources/test #
Session

Test a source's credentials without saving.

Session-only. kind rides in the body rather than the path so a server can be tested before it is saved; pass id instead to re-test one that is, reusing its stored secret.

Request body required

application/json

object

Credentials to try. Anything omitted falls back to the stored source named by id.

kind string | null

Required unless id is given.

id integer | null · int64

Test an existing source, reusing its stored secret.

url string | null
token string | null
username string | null
password string | null
api_key string | null

Responses

200

Result. A failed check is still a 200, with ok: false.

application/json

object

Whether the credentials work. A failed check is a 200 with ok: false.

ok boolean required
account string | null

The account the credential belongs to, where the server can say.

account_error string | null

The server was reached but could not name the account — recoverable by picking one from accounts.

accounts any | null

Empty or absent when the credential may not list them; the picker is then not offered. Jellyfin needs this more than Plex: a dashboard API key belongs to no user.

one of
option 1 array
each item
object

An account on the Plex server — the server owner plus any managed or shared users. id is Plex's own account id; sessions are matched on name, which is what the User element on a session carries.

id integer · int64 required
name string required
option 2 array
each item
object

An account on the server. Sessions are matched on name, which is what SessionInfo.UserName carries.

id string required
name string required
libraries array | null

Plex's music libraries.

each item
string
error string | null

Why it failed.

400

Unknown kind, or not enough to test with.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
404

No such resource, or it belongs to another user.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/sources #
Session

Your configured sources.

Session-only, permanently — these rows hold credentials. The stored token or password is never returned; has_token says whether one is set.

Responses

200

OK.

application/json

object
sources array required
each item
object

A configured source, without its credentials.

id integer · int64 required
kind string required

plex, navidrome, jellyfin, emby or roon.

label string required

Your name for it, so two servers of the same kind are tellable apart.

enabled boolean required
url string required
has_token boolean required

A credential is stored. It is never returned.

remote_account string | null

The account on the server whose plays are scrobbled, resolved on save.

username string | null

Navidrome's login name.

poll_interval_secs integer | null · int64

Null means the engine's default.

libraries_allow array required
each item
string
libraries_block array required
each item
string
devices_allow array required
each item
string
devices_block array required
each item
string
last_polled_at integer | null · int64
last_error string | null
updated_at integer · int64 required
kinds array required

The kinds a source can be created as.

each item
string
401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
POST /api/v1/sources #
Session

Add a source.

Session-only. Sources are per user, and one user can have several of a kind, told apart by label. For Plex the token is resolved to a Plex account via plex.tv and the source is filtered to that account, so there is no name-matching — which means saving needs outbound internet even for a LAN Plex.

Request body required

application/json

object

A source to save. On update every field is optional, and an omitted or empty credential keeps the stored one — it is never sent back, so a client could not echo it anyway.

kind string | null

plex, navidrome, jellyfin, emby or roon. Required on create and ignored afterwards; a source cannot change kind.

label string | null
enabled boolean | null

Enabling needs a complete set of credentials for the kind — a 400 otherwise. Defaults to off on create.

url string | null
token string | null

Plex.

username string | null

Navidrome logs in as a user.

password string | null
api_key string | null

Jellyfin and Emby.

poll_interval_secs integer | null · int64
libraries_allow array | null
each item
string
libraries_block array | null
each item
string
devices_allow array | null
each item
string
devices_block array | null
each item
string
plex_account string | null

Which Plex account's sessions this source should scrobble. Omitted means whoever the token belongs to. Validated against the server's accounts on save.

jellyfin_account string | null

Which Jellyfin or Emby account's sessions to scrobble. Needed whenever the key is a dashboard API key, which belongs to no user.

Responses

201

Created.

application/json

object

A configured source, without its credentials.

id integer · int64 required
kind string required

plex, navidrome, jellyfin, emby or roon.

label string required

Your name for it, so two servers of the same kind are tellable apart.

enabled boolean required
url string required
has_token boolean required

A credential is stored. It is never returned.

remote_account string | null

The account on the server whose plays are scrobbled, resolved on save.

username string | null

Navidrome's login name.

poll_interval_secs integer | null · int64

Null means the engine's default.

libraries_allow array required
each item
string
libraries_block array required
each item
string
devices_allow array required
each item
string
devices_block array required
each item
string
last_polled_at integer | null · int64
last_error string | null
updated_at integer · int64 required
400

Malformed or rejected input.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
PUT /api/v1/sources/{id} #
Session

Update a source.

Session-only. An omitted token keeps the stored one — it is not cleared.

Parameters

id path required
integer · int64

Request body required

application/json

object

A source to save. On update every field is optional, and an omitted or empty credential keeps the stored one — it is never sent back, so a client could not echo it anyway.

kind string | null

plex, navidrome, jellyfin, emby or roon. Required on create and ignored afterwards; a source cannot change kind.

label string | null
enabled boolean | null

Enabling needs a complete set of credentials for the kind — a 400 otherwise. Defaults to off on create.

url string | null
token string | null

Plex.

username string | null

Navidrome logs in as a user.

password string | null
api_key string | null

Jellyfin and Emby.

poll_interval_secs integer | null · int64
libraries_allow array | null
each item
string
libraries_block array | null
each item
string
devices_allow array | null
each item
string
devices_block array | null
each item
string
plex_account string | null

Which Plex account's sessions this source should scrobble. Omitted means whoever the token belongs to. Validated against the server's accounts on save.

jellyfin_account string | null

Which Jellyfin or Emby account's sessions to scrobble. Needed whenever the key is a dashboard API key, which belongs to no user.

Responses

200

Updated.

application/json

object

A configured source, without its credentials.

id integer · int64 required
kind string required

plex, navidrome, jellyfin, emby or roon.

label string required

Your name for it, so two servers of the same kind are tellable apart.

enabled boolean required
url string required
has_token boolean required

A credential is stored. It is never returned.

remote_account string | null

The account on the server whose plays are scrobbled, resolved on save.

username string | null

Navidrome's login name.

poll_interval_secs integer | null · int64

Null means the engine's default.

libraries_allow array required
each item
string
libraries_block array required
each item
string
devices_allow array required
each item
string
devices_block array required
each item
string
last_polled_at integer | null · int64
last_error string | null
updated_at integer · int64 required
400

Malformed or rejected input.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
404

No such resource, or it belongs to another user.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

DELETE /api/v1/sources/{id} #
Session

Delete a source.

Parameters

id path required
integer · int64

Responses

204

Deleted.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
404

No such resource, or it belongs to another user.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.