← API reference

Account

Your own account — password, display name, bio, profile picture. Scoped to the caller and never takes an id, unlike the admin routes under /admin/users. Session-only: a scrobble client has no business changing the credential it authenticates with.

6 of 6 · v0.120.0
GET /api/v1/profile #
Token reador Session

The caller's own account.

Scope: read (since v0.120). Takes no id — it is always the caller's own account, which is the point: an account created for someone else was previously only changeable by the admin who created it.

Responses

200

OK.

application/json

object

Your own account, as the profile screen shows it.

id integer · int64 required
username string required
display_name string | null
role string required

admin or user.

created_at integer · int64 required

Unix seconds.

bio string | null
avatar string | null

A URL the browser can load: the external URL you set, or /api/v1/profile/avatar when a file was uploaded. The path on disk is never returned.

disabled boolean required
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."
}
PATCH /api/v1/profile #
Session

Change your display name, bio or avatar URL.

Session-only. Role, disabled state, username and password are deliberately not here.

Request body required

application/json

object

Each field distinguishes absent ("leave alone") from an explicit null ("clear"), so a misspelled key cannot silently blank a field it failed to name. A value that is only whitespace clears too.

display_name string | null

At most 80 characters.

bio string | null

At most 500 characters.

avatar_url string | null

Must be an http(s) URL. A relative value is refused with 400 — only the upload endpoint may write a path this server serves.

Responses

200

Updated. status is updated.

application/json

object

An acknowledgement with nothing else to report.

status names what happened — ok, updated, deleted, cleared, started and so on; the operation says which it sends. A client needs only the HTTP status to know it worked.

status string 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."
}
POST /api/v1/profile/password #
Session

Change your own password.

Session-only. current_password is required — the caller already holds a session, so without it an unlocked browser would be enough to lock the real owner out. This is what separates it from the admin reset on PATCH /admin/users/{id}.

On success every existing session for the user is dropped and a new cookie is issued to the caller, so other browsers are logged out but the tab making the request is not.

Request body required

application/json

object
current_password string required
new_password string required

At least 8 characters.

Responses

200

Updated; a fresh session cookie is set. status is updated.

application/json

object

An acknowledgement with nothing else to report.

status names what happened — ok, updated, deleted, cleared, started and so on; the operation says which it sends. A client needs only the HTTP status to know it worked.

status string 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."
}
403

The current password is wrong.

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/profile/avatar #
Token reador Session

The caller's uploaded profile picture.

Scope: read (since v0.120), and scoped to the caller, like the artwork proxy. Cached private — a shared cache holding one would serve it to the next person through the proxy. 404 when the avatar is an external URL rather than an uploaded file.

Responses

200

The image bytes.

image/*

string · binary
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/profile/avatar #
Session

Upload a profile picture.

Session-only, multipart/form-data, 4 MB maximum. The extension comes from the declared content type, never from the client's filename. The picture it replaces is deleted.

Request body required

multipart/form-data

object

A multipart/form-data upload of one file.

The server takes the first file part whatever its field name; file is the name to use. Its declared Content-Type decides how the file is stored — a filename from the client never reaches a path on disk.

file string · binary required

Responses

200

Stored.

application/json

object

Where the stored picture is served from.

avatar string required

Always /api/v1/profile/avatar.

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."
}
413

Larger than 4 MB.

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.

415

Not an image type we store.

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/profile/avatar #
Session

Remove your profile picture.

Session-only. Falls back to the lettered tile.

Responses

200

Removed. status is removed.

application/json

object

An acknowledgement with nothing else to report.

status names what happened — ok, updated, deleted, cleared, started and so on; the operation says which it sends. A client needs only the HTTP status to know it worked.

status string required
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."
}