← API reference

Sources

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

7 of 7 · v0.132.2
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. The address is held to the same rule as a save — a 400, before anything connects.

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
plugin object | null

Navidrome only: the plugin token made on this source, if there is one. While there is, the source is in plugin mode — not polled, and listens arrive from the Tapedeck plugin inside Navidrome instead. Filled in by the list only.

lyrics boolean required

The token has write, so the plugin also sends lyrics from your files.

created_at integer · int64 required
last_used_at integer | null · int64

When the plugin last used it, to within five minutes. Null means it never has: the token is not pasted into the plugin yet.

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.

A member's source must point at the public internet, or at a private network the operator lists in TAPEDECK_SOURCE_NETWORKS; this server, loopback and link-local addresses are always refused (400). An admin's may point anywhere.

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
plugin object | null

Navidrome only: the plugin token made on this source, if there is one. While there is, the source is in plugin mode — not polled, and listens arrive from the Tapedeck plugin inside Navidrome instead. Filled in by the list only.

lyrics boolean required

The token has write, so the plugin also sends lyrics from your files.

created_at integer · int64 required
last_used_at integer | null · int64

When the plugin last used it, to within five minutes. Null means it never has: the token is not pasted into the plugin yet.

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
plugin object | null

Navidrome only: the plugin token made on this source, if there is one. While there is, the source is in plugin mode — not polled, and listens arrive from the Tapedeck plugin inside Navidrome instead. Filled in by the list only.

lyrics boolean required

The token has write, so the plugin also sends lyrics from your files.

created_at integer · int64 required
last_used_at integer | null · int64

When the plugin last used it, to within five minutes. Null means it never has: the token is not pasted into the plugin yet.

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.

POST /api/v1/sources/{id}/plugin-token #
Session

Make a token for the Tapedeck plugin in Navidrome.

Session-only. Puts the source in plugin mode: the engine stops polling it, and listens submitted with this token that name a Navidrome song are stored as this server's, so cover art and the rest of the library features work for them. The login is still used for those. Calling again replaces the token; the old one stops working.

Parameters

id path required
integer · int64

Request body required

application/json

object
lyrics boolean | null

Also grant write, so the plugin sends the lyrics in your files. A write token can edit and delete your Tapedeck data, and whoever runs the Navidrome server sees it. Default false.

Responses

201

Created.

application/json

object
token string required

Shown once. Paste it into the Tapedeck plugin's settings in Navidrome.

scopes string required
400

Not a Navidrome source.

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}/plugin-token #
Session

Remove the plugin token, and poll the source again.

Session-only. The plugin's listens are refused from now on. Polling picks up from where it last stopped, and plays the plugin already sent are recognised as duplicates.

Parameters

id path required
integer · int64

Responses

204

Removed.

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.