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.
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.
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
option 2 array
each item object
An account on the server. Sessions are matched on name, which is what
SessionInfo.UserName carries.
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
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
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
error string required
Human-readable. Not a stable identifier — do not branch on it.
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.
enabled boolean | null
Enabling needs a complete set of credentials for the kind — a 400
otherwise. Defaults to off on create.
username string | null
Navidrome logs in as a user.
poll_interval_secs integer | null · int64
libraries_allow array | null
libraries_block array | null
devices_allow array | null
devices_block array | null
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
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.
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.
poll_interval_secs integer | null · int64
Null means the engine's default.
libraries_allow array required
libraries_block array required
devices_allow array required
devices_block array required
last_polled_at integer | null · int64
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
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
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/{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.
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
application/json
object
token string required
Shown once. Paste it into the Tapedeck plugin's settings in Navidrome.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
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
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
error string required
Human-readable. Not a stable identifier — do not branch on it.