sonda/internal/api/openapi/openapi.yaml
tgiachi 175b87a4cc fix(discovery): ids from files, adoption and the scanner lock
- fix: a discovered artist adopted by id under another spelling kept its old
  match key, so the next file with the new spelling and no id created a second
  artist. The key now follows the name
- fix: when a real artist without an id and a discovered artist holding the id
  have the same name, the id now goes to the real artist and the discovered one
  lets go of it. Before, the scan created a second real artist and a second
  album, and could not repair it because the id was taken
- fix: when a file without an id adopts a discovered artist that had a provider
  id, the tags, the fetch records and the similar artists read under that id
  are dropped, since they are not known to be about the user's artist. Links
  from other artists to it stay. A file that confirms the very same id keeps
  everything
- fix: the album artist id is only read when the file has an album artist tag;
  with the tag missing the name is a fallback and the id would have landed on the
  wrong artist (a Various Artists id on the track's own artist)
- fix: one artist credit with one id ("X feat. Y" with the id of X, how beets
  writes it) is not paired: no id is safer than a wrong one. A name that is
  itself a single letter or contains a slash still gets its id
- fix: on PostgreSQL the scanner took the artist lock after it had already
  changed artist rows, which could deadlock with a concurrent similar-artists
  save. SaveFile now takes the lock first, once
- fix: Last.fm does not know every MusicBrainz id: when it does not know the id
  and there is a name, the name is tried, never autocorrected, as before ids
  were read from files
- fix: waiting for one provider's tags is bounded at 20 seconds, so a rate
  limited provider cannot hold a page for a minute
- docs: the tag range is 1 to 100 (a tag with no votes is dropped), the spec says
  where an artist's id can come from, and the README says when Last.fm gets an id
- test: adoption by spelling, the real artist with a discovered namesake,
  dropping and keeping what was read, album artist fallback, credits, an ID3
  frame, and the id-then-name fallback of Last.fm
2026-11-11 17:13:31 +01:00

1511 lines
55 KiB
YAML

openapi: 3.0.3
info:
title: Sonda API
version: 0.1.0
description: |
Sonda is a privacy-first, self-hosted music server. This is its first-party REST API.
**Authentication.** Log in with `POST /auth/login` and send the access token as
`Authorization: Bearer <token>`. Access tokens are short-lived; renew the session with
`POST /auth/refresh`. Each refresh token works once.
**Roles.** Operations marked *admin* need an account with the admin role. The first user
who registers is the admin.
**Errors.** Every error has the same shape: `{"error": {"code": "...", "message": "..."}}`.
The `code` is stable and meant for programs; the `message` is for people.
**Paging.** Lists take `limit` (default 50, at most 200; a larger value is lowered to 200)
and `offset`, and answer with `items`, `total`, `limit` and `offset`.
servers:
- url: /api/v1
tags:
- name: System
- name: Auth
description: Accounts and sessions.
- name: Users
description: User management (admin).
- name: Libraries
description: Named folders of music (admin).
- name: Scan
description: Indexing the libraries.
- name: Catalog
description: Browsing and searching what can be played.
- name: Playback
description: Streaming and listening history.
- name: Discovery
description: Music outside the library, from external providers an admin switched on.
- name: Providers
description: External services Sonda can ask about artists, set up by an admin.
paths:
/health:
get:
tags: [System]
operationId: getHealth
summary: Liveness check
responses:
'200':
description: The server is up.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [status]
properties:
status: {type: string, enum: [ok]}
/openapi.yaml:
get:
tags: [System]
operationId: getOpenAPI
summary: This document
responses:
'200':
description: The OpenAPI description of the API.
content:
application/yaml:
schema: {type: string}
/auth/register:
post:
tags: [Auth]
operationId: register
summary: Create the first user
description: |
Only works while no user exists. The new user is the admin. Afterwards registration is
closed and admins create accounts with `POST /users`.
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/Credentials'}
responses:
'201':
description: The admin account.
content:
application/json:
schema: {$ref: '#/components/schemas/User'}
'400': {$ref: '#/components/responses/InvalidInput'}
'403':
description: A user already exists (`registration_closed`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'409':
description: The username is taken (`username_taken`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/auth/login:
post:
tags: [Auth]
operationId: login
summary: Open a session
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/LoginRequest'}
responses:
'200':
description: A new session.
content:
application/json:
schema: {$ref: '#/components/schemas/Session'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401':
description: Wrong username or password (`invalid_credentials`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/auth/refresh:
post:
tags: [Auth]
operationId: refresh
summary: Renew a session
description: |
Exchanges a refresh token for a new access token and a new refresh token. The old refresh
token stops working. Presenting a spent one again, more than ten seconds after it was used,
ends every session of that user; inside those ten seconds it only fails, so two tabs
refreshing together do not log each other out. This holds for any spent token, including
one revoked by logout or by a password change.
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/RefreshRequest'}
responses:
'200':
description: A new session.
content:
application/json:
schema: {$ref: '#/components/schemas/Session'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401':
description: The refresh token is unknown, expired or already used (`invalid_refresh_token`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/auth/logout:
post:
tags: [Auth]
operationId: logout
summary: End a session
description: Revokes one refresh token. Always answers 204, so it never reveals whether the token existed.
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/RefreshRequest'}
responses:
'204': {description: Done.}
'400': {$ref: '#/components/responses/InvalidInput'}
/auth/me:
get:
tags: [Auth]
operationId: getMe
summary: The signed-in account
security: [{bearerAuth: []}]
responses:
'200':
description: Your account.
content:
application/json:
schema: {$ref: '#/components/schemas/User'}
'401': {$ref: '#/components/responses/Unauthorized'}
/auth/password:
post:
tags: [Auth]
operationId: changePassword
summary: Change your password
description: |
Revokes every refresh token of the account, so no session can be renewed. An access token
that was already issued keeps working until it expires (15 minutes by default).
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/PasswordChange'}
responses:
'204': {description: Password changed.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403':
description: The current password is wrong (`invalid_credentials`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/users:
get:
tags: [Users]
operationId: listUsers
summary: List users
description: Admin only.
security: [{bearerAuth: []}]
responses:
'200':
description: Every account, oldest first.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [users]
properties:
users:
type: array
items: {$ref: '#/components/schemas/User'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
post:
tags: [Users]
operationId: createUser
summary: Create a user
description: Admin only.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/CreateUser'}
responses:
'201':
description: The new account.
content:
application/json:
schema: {$ref: '#/components/schemas/User'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'409':
description: The username is taken (`username_taken`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/users/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
patch:
tags: [Users]
operationId: updateUser
summary: Grant or remove the admin role
description: Admin only. The last admin cannot be demoted.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [is_admin]
properties:
is_admin: {type: boolean}
responses:
'200':
description: The updated account.
content:
application/json:
schema: {$ref: '#/components/schemas/User'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such user (`user_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'409':
description: This is the last admin (`last_admin`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
delete:
tags: [Users]
operationId: deleteUser
summary: Delete a user
description: |
Admin only. Removes the account and its refresh tokens. Access tokens already issued stop
working at once on admin routes, `/auth/me`, `/auth/password` and `/listens`; other routes
accept them until they expire (15 minutes by default). The last admin cannot be deleted.
security: [{bearerAuth: []}]
responses:
'204': {description: Deleted.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such user (`user_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'409':
description: This is the last admin (`last_admin`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/users/{id}/password:
parameters:
- {$ref: '#/components/parameters/Id'}
put:
tags: [Users]
operationId: resetUserPassword
summary: Reset a user's password
description: |
Admin only. Revokes every refresh token of that user, so no session can be renewed. Access
tokens already issued keep working until they expire (15 minutes by default).
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [password]
properties:
password:
type: string
format: password
description: 8 to 256 bytes (UTF-8).
responses:
'204': {description: Password reset.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such user (`user_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/libraries:
get:
tags: [Libraries]
operationId: listLibraries
summary: List libraries
description: Admin only.
security: [{bearerAuth: []}]
responses:
'200':
description: Every library, oldest first.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [libraries]
properties:
libraries:
type: array
items: {$ref: '#/components/schemas/Library'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
post:
tags: [Libraries]
operationId: createLibrary
summary: Add a library
description: |
Admin only. The path must be an absolute, existing directory, never the filesystem root,
and never inside or around another library (a bad path or an overlap is `400 invalid_input`).
A name or path that another library already uses is `409 library_exists`. Names are unique
ignoring case.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/NewLibrary'}
responses:
'201':
description: The new library.
content:
application/json:
schema: {$ref: '#/components/schemas/Library'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'409':
description: Another library has this name or path (`library_exists`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/libraries/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
patch:
tags: [Libraries]
operationId: updateLibrary
summary: Rename or move a library
description: |
Admin only. Send `name`, `path` or both. Files keep their identity when the path changes.
Changing the path is refused while a scan runs.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/LibraryUpdate'}
responses:
'200':
description: The updated library.
content:
application/json:
schema: {$ref: '#/components/schemas/Library'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404': {$ref: '#/components/responses/LibraryNotFound'}
'409':
description: The name or path is used by another library (`library_exists`), or a scan is running (`scan_running`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
delete:
tags: [Libraries]
operationId: deleteLibrary
summary: Remove a library
description: |
Admin only. Removes the library and its index entries. Tracks and listening history stay;
the music on disk is never touched. Refused while a scan runs.
security: [{bearerAuth: []}]
responses:
'204': {description: Removed.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404': {$ref: '#/components/responses/LibraryNotFound'}
'409':
description: A scan is running (`scan_running`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/libraries/{id}/scan:
parameters:
- {$ref: '#/components/parameters/Id'}
post:
tags: [Scan]
operationId: scanLibrary
summary: Scan one library
description: Admin only. Starts a scan in the background; follow it with `GET /library/scan`.
security: [{bearerAuth: []}]
responses:
'202': {$ref: '#/components/responses/ScanStarted'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404': {$ref: '#/components/responses/LibraryNotFound'}
'409':
description: A scan is already running (`scan_running`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/library/scan:
get:
tags: [Scan]
operationId: getScanStatus
summary: Scan status
description: Whether a scan is running and how the last one ended.
security: [{bearerAuth: []}]
responses:
'200':
description: The current state.
content:
application/json:
schema: {$ref: '#/components/schemas/ScanStatus'}
'401': {$ref: '#/components/responses/Unauthorized'}
post:
tags: [Scan]
operationId: scanAll
summary: Scan every library
description: |
Admin only. Starts a scan in the background. Only MP3 and FLAC files are read; other audio
formats are counted as `unsupported`. Housekeeping folders of NAS boxes (`@Recycle`,
`#recycle`, `@eaDir`, `.@__thumb`, `$RECYCLE.BIN`) are skipped.
security: [{bearerAuth: []}]
responses:
'202': {$ref: '#/components/responses/ScanStarted'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'409':
description: A scan is already running (`scan_running`), or there is no library yet (`no_libraries`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/artists:
get:
tags: [Catalog]
operationId: listArtists
summary: List artists
description: |
Artists credited on a playable track, or that are the album artist of an album with one.
Sorted by name.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- {$ref: '#/components/parameters/LibraryId'}
responses:
'200':
description: A page of artists.
content:
application/json:
schema: {$ref: '#/components/schemas/ArtistPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
/artists/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Catalog]
operationId: getArtist
summary: One artist
security: [{bearerAuth: []}]
responses:
'200':
description: The artist.
content:
application/json:
schema: {$ref: '#/components/schemas/Artist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: |
No such artist (`artist_not_found`). An artist with nothing to play is not found either,
unless a provider named it as similar to another artist: those can be shown, with
`track_count` and `album_count` of 0, but they are never part of the lists.
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/artists/{id}/similar:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Discovery]
operationId: getSimilarArtists
summary: Artists similar to one
description: |
Artists an external provider (Last.fm) finds similar to this one, best first. Each says
whether it is in the library, and `id` works with `GET /artists/{id}`; one that is not in the
library has no files.
The provider is only asked when an admin switched it on and the stored answer is missing or
old (7 days; a "no such artist" answer is kept 1 day). What is sent is the artist's name or
MusicBrainz id and nothing about any user. Several requests for the same artist at once
make one call.
A provider that is off or failing is not an error: the answer is `200` and `provider_status`
says why. Then `items` holds whatever was stored before, if anything, and `stale` is true
when it is older than it should be.
`score` is the provider's own number between 0 and 1. It is relative to the list it came
in (the best one is usually 1), so it only compares artists inside one answer. `rank` is the
position. Show `attribution` where you show the data.
security: [{bearerAuth: []}]
parameters:
- name: limit
in: query
description: How many to return. 20 when absent or 0; values above 50 are lowered to 50, the most that is kept.
schema: {type: integer, minimum: 0, default: 20}
responses:
'200':
description: The similar artists.
content:
application/json:
schema: {$ref: '#/components/schemas/SimilarArtists'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such artist (`artist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/artists/{id}/tags:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Discovery]
operationId: getArtistTags
summary: Tags of an artist, from each provider
description: |
What each provider says kind of music this artist plays: Last.fm's top tags and
MusicBrainz's tags and genres. There is always one entry for each, Last.fm first. The
weights are the providers' own numbers, kept as they came and never mixed: Last.fm's is
relative to the artist (1 to 100, the top tag is usually 100; a tag with no votes is dropped),
MusicBrainz's is a count of votes. `genre` is true for a MusicBrainz tag that it also lists among its curated genres.
A provider is only asked when an admin switched it on and its stored answer is missing or
old (7 days; a "no such artist" answer is kept 1 day), with the same rules as
`GET /artists/{id}/similar`. What is sent is the artist's name or MusicBrainz id to
Last.fm (its id when known), and only the MusicBrainz id to MusicBrainz: Sonda never looks
an id up by name. An artist's id comes from the tags in the music files, or from Last.fm
for an artist it named that is not in the library; for any other artist the MusicBrainz
entry says `no_id`. Show each `attribution` where you show the tags.
security: [{bearerAuth: []}]
responses:
'200':
description: One entry per provider.
content:
application/json:
schema: {$ref: '#/components/schemas/ArtistTags'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such artist (`artist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/albums:
get:
tags: [Catalog]
operationId: listAlbums
summary: List albums
description: |
Albums with a playable track, sorted by title. `artist_id` matches the albums an artist
owns plus those where it is credited on a playable track, the same set as its `album_count`.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- {$ref: '#/components/parameters/LibraryId'}
- {$ref: '#/components/parameters/ArtistId'}
responses:
'200':
description: A page of albums.
content:
application/json:
schema: {$ref: '#/components/schemas/AlbumPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
/albums/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Catalog]
operationId: getAlbum
summary: One album
security: [{bearerAuth: []}]
responses:
'200':
description: The album.
content:
application/json:
schema: {$ref: '#/components/schemas/Album'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such album, or nothing of it can be played (`album_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/tracks:
get:
tags: [Catalog]
operationId: listTracks
summary: List tracks
description: |
Tracks with at least one file that is not flagged missing; a track with several files
appears once. Grouped by album, then disc and track number.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- {$ref: '#/components/parameters/LibraryId'}
- {$ref: '#/components/parameters/ArtistId'}
- {$ref: '#/components/parameters/AlbumId'}
responses:
'200':
description: A page of tracks.
content:
application/json:
schema: {$ref: '#/components/schemas/TrackPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
/tracks/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Catalog]
operationId: getTrack
summary: One track
security: [{bearerAuth: []}]
responses:
'200':
description: The track.
content:
application/json:
schema: {$ref: '#/components/schemas/Track'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such track, or it has no playable file (`track_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/tracks/{id}/stream:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Playback]
operationId: streamTrack
summary: Stream a track
description: |
Serves the original audio file. Supports `Range` requests, so players can seek, and
conditional requests. Streaming never records a listen; report one with `POST /listens`.
An `<audio>` element cannot send headers, so this is the only operation that also accepts
the access token as the `access_token` query parameter. A header, when present, always wins.
security:
- bearerAuth: []
- streamQueryToken: []
parameters:
- name: Range
in: header
required: false
description: A byte range, for example `bytes=0-99`.
schema: {type: string}
- name: If-Modified-Since
in: header
required: false
schema: {type: string}
- name: If-Unmodified-Since
in: header
required: false
schema: {type: string}
responses:
'200':
description: The whole file.
headers:
Accept-Ranges: {$ref: '#/components/headers/AcceptRanges'}
Content-Length: {$ref: '#/components/headers/ContentLength'}
Last-Modified: {$ref: '#/components/headers/LastModified'}
content:
audio/mpeg:
schema: {type: string, format: binary}
audio/flac:
schema: {type: string, format: binary}
'206':
description: |
The requested byte range. Several ranges in one request are answered as
`multipart/byteranges`.
headers:
Content-Range:
description: The range sent and the size of the file, for example `bytes 0-99/40635`. Absent for a multipart answer.
schema: {type: string}
content:
audio/mpeg:
schema: {type: string, format: binary}
audio/flac:
schema: {type: string, format: binary}
multipart/byteranges:
schema: {type: string, format: binary}
'304': {description: Not modified since `If-Modified-Since`.}
'412': {description: '`If-Unmodified-Since` names a date before the last change of the file.'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such track (`track_not_found`), or its file is not available (`file_missing`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'416':
description: The range cannot be satisfied.
headers:
Content-Range:
description: '`bytes */<size of the file>`.'
schema: {type: string}
head:
tags: [Playback]
operationId: headTrackStream
summary: Headers of a stream
description: Same as `GET`, without the body.
security:
- bearerAuth: []
- streamQueryToken: []
parameters:
- name: Range
in: header
required: false
schema: {type: string}
- name: If-Modified-Since
in: header
required: false
schema: {type: string}
- name: If-Unmodified-Since
in: header
required: false
schema: {type: string}
responses:
'200':
description: Headers of the whole file.
headers:
Accept-Ranges: {$ref: '#/components/headers/AcceptRanges'}
Content-Length: {$ref: '#/components/headers/ContentLength'}
Last-Modified: {$ref: '#/components/headers/LastModified'}
'206':
description: Headers of the requested range.
headers:
Content-Range:
schema: {type: string}
'304': {description: Not modified since `If-Modified-Since`.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {description: No such track or file.}
'412': {description: '`If-Unmodified-Since` names a date before the last change of the file.'}
'416': {description: The range cannot be satisfied.}
/providers:
get:
tags: [Providers]
operationId: listProviders
summary: List the external providers
description: |
Admin only. Every provider Sonda knows (Last.fm, MusicBrainz), with whether it is on and
what it would send. Providers are off by default: nothing leaves the server until an admin
enables one. The API key is never returned; `has_api_key` says whether one is stored.
security: [{bearerAuth: []}]
responses:
'200':
description: The providers, in a fixed order.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [providers]
properties:
providers:
type: array
items: {$ref: '#/components/schemas/Provider'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
/providers/{name}:
parameters:
- name: name
in: path
required: true
schema: {type: string, enum: [lastfm, musicbrainz]}
put:
tags: [Providers]
operationId: updateProvider
summary: Set up a provider
description: |
Admin only. Send any of `enabled`, `api_key` and `contact`; fields you leave out are kept.
The key is write-only: it is never returned and never logged. Sending an empty `api_key`
clears it, and turns a provider that needs a key (Last.fm) off; a provider that needs none
(MusicBrainz) is not affected. A provider that needs a key cannot be enabled without one. `contact` goes into the User-Agent sent to the provider (MusicBrainz
asks for a URL or an e-mail address); empty means the project address.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/ProviderUpdate'}
responses:
'200':
description: The provider as it is now.
content:
application/json:
schema: {$ref: '#/components/schemas/Provider'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such provider (`provider_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/providers/{name}/test:
parameters:
- name: name
in: path
required: true
schema: {type: string, enum: [lastfm, musicbrainz]}
post:
tags: [Providers]
operationId: testProvider
summary: Check a provider's API key
description: |
Admin only. Asks the provider one cheap question with the stored key, to find out whether
it works. It works whether the provider is on or off, so you can check before switching it on.
It is the only request Sonda makes at an admin's command rather than for a listener, and it
sends nothing but the key. A provider that cannot be reached or refuses the key is not an
error here: the answer is `200` with `ok` false and the reason in `status`.
MusicBrainz has no key: its test only asks whether the service answers. A provider that
has no test is a `400`.
security: [{bearerAuth: []}]
responses:
'200':
description: The outcome of the check.
content:
application/json:
schema: {$ref: '#/components/schemas/ProviderTest'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such provider (`provider_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/listens:
get:
tags: [Playback]
operationId: listListens
summary: Your listening history
description: |
The events you reported, newest first, each with `counted`: whether it counts as a listen
under the current rule (see `POST /listens`). Nobody else's history is visible.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- name: counted
in: query
description: Send `true` to list only the events that count as a listen.
schema: {type: boolean, enum: [true]}
responses:
'200':
description: A page of events.
content:
application/json:
schema: {$ref: '#/components/schemas/ListenPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
post:
tags: [Playback]
operationId: recordListen
summary: Record a listen
description: |
Clients report what the listener did: **one event per play**, when the play ends or is
abandoned, with the time actually played (`complete` if it finished, `skip` if the listener
moved on, `play` if it simply stopped).
Use **one `idempotency_key` per play**. A retry with the same key from the same user is
recorded once and answered with `duplicate`. An event cannot be upgraded afterwards: a later
event with a key that was already used is ignored, even if its type or duration differ, and
sending it with a new key would count the same play twice.
**What counts as a listen.** An event counts when its type is `complete`, or when
`duration_played_ms` is at least `listening.min_listen_seconds` (20 seconds by default).
A `play` or `skip` shorter than that is stored but does not count. The rule is applied when
the history is read, so changing the setting re-reads the past. The answer says whether this
event counts; for a `duplicate` it describes the event you sent.
**Plausibility.** When the length of the track is known, `duration_played_ms` may not exceed
twice that length plus 10 seconds (a listener can seek back and loop). Streaming a file never
records anything on its own.
security: [{bearerAuth: []}]
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/Listen'}
responses:
'201':
description: Recorded.
content:
application/json:
schema: {$ref: '#/components/schemas/ListenResult'}
'200':
description: Already recorded (same `idempotency_key`).
content:
application/json:
schema: {$ref: '#/components/schemas/ListenResult'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such track (`track_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: The `access_token` from `POST /auth/login` or `POST /auth/refresh`.
streamQueryToken:
type: apiKey
in: query
name: access_token
description: The same access token, for stream URLs used by an `<audio>` element. Accepted only on `/tracks/{id}/stream`.
parameters:
Id:
name: id
in: path
required: true
schema: {type: integer, format: int64, minimum: 1}
Q:
name: q
in: query
description: |
Case-insensitive substring of the name or title. Accented letters are matched ignoring
case (`BJÖRK` finds `Björk`), but accents are kept (`bjork` does not). At most 200 characters.
schema: {type: string, maxLength: 200}
Limit:
name: limit
in: query
description: Page size. 50 when absent or 0; values above 200 are lowered to 200.
schema: {type: integer, minimum: 0, default: 50}
Offset:
name: offset
in: query
schema: {type: integer, minimum: 0, default: 0}
LibraryId:
name: library_id
in: query
description: Only items with a playable file in this library.
schema: {type: integer, format: int64, minimum: 1}
ArtistId:
name: artist_id
in: query
schema: {type: integer, format: int64, minimum: 1}
AlbumId:
name: album_id
in: query
schema: {type: integer, format: int64, minimum: 1}
headers:
AcceptRanges:
description: Always `bytes`.
schema: {type: string}
ContentLength:
schema: {type: integer}
LastModified:
schema: {type: string}
responses:
InvalidInput:
description: The request is malformed or a value is out of range (`invalid_input`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
Unauthorized:
description: The access token is missing, invalid or expired (`unauthorized`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
AdminRequired:
description: The account is not an admin (`admin_required`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
LibraryNotFound:
description: No such library (`library_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
ScanStarted:
description: The scan was started in the background.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [status]
properties:
status: {type: string, enum: [started]}
schemas:
Error:
type: object
additionalProperties: false
required: [error]
properties:
error:
type: object
additionalProperties: false
required: [code, message]
properties:
code:
type: string
description: |
A stable identifier, for example `invalid_input`, `unauthorized`, `admin_required`,
`user_not_found`, `last_admin`, `library_exists`, `scan_running`, `track_not_found`.
message: {type: string}
Credentials:
type: object
required: [username, password]
properties:
username:
type: string
minLength: 3
maxLength: 64
pattern: '^[A-Za-z0-9._-]+$'
password:
type: string
format: password
description: 8 to 256 bytes (UTF-8).
LoginRequest:
type: object
required: [username, password]
properties:
username: {type: string}
password: {type: string, format: password}
CreateUser:
allOf:
- $ref: '#/components/schemas/Credentials'
- type: object
properties:
is_admin: {type: boolean, default: false}
User:
type: object
additionalProperties: false
required: [id, username, is_admin]
properties:
id: {type: integer, format: int64}
username: {type: string}
is_admin: {type: boolean}
Session:
type: object
additionalProperties: false
required: [access_token, access_expires_at, refresh_token, refresh_expires_at, user]
properties:
access_token: {type: string}
access_expires_at: {type: string, format: date-time}
refresh_token: {type: string, description: Works once.}
refresh_expires_at: {type: string, format: date-time}
user: {$ref: '#/components/schemas/User'}
RefreshRequest:
type: object
required: [refresh_token]
properties:
refresh_token: {type: string}
PasswordChange:
type: object
required: [current_password, new_password]
properties:
current_password: {type: string, format: password}
new_password:
type: string
format: password
description: 8 to 256 bytes (UTF-8).
Library:
type: object
additionalProperties: false
required: [id, name, path, created_at]
properties:
id: {type: integer, format: int64}
name: {type: string}
path: {type: string, description: Absolute directory on the server.}
created_at: {type: string, format: date-time}
NewLibrary:
type: object
required: [name, path]
properties:
name: {type: string, minLength: 1, maxLength: 100}
path: {type: string, description: "Absolute, existing directory."}
LibraryUpdate:
type: object
anyOf:
- required: [name]
- required: [path]
properties:
name: {type: string, minLength: 1, maxLength: 100}
path: {type: string}
ScanSummary:
type: object
additionalProperties: false
required: [libraries, found, added, updated, unchanged, renamed, restored, missing, failed, skipped, unsupported]
properties:
libraries: {type: integer, description: Libraries covered by the scan.}
found: {type: integer, description: Audio files seen on disk (MP3 and FLAC).}
added: {type: integer}
updated: {type: integer}
unchanged: {type: integer}
renamed: {type: integer, description: Files that moved; they keep their track.}
restored: {type: integer, description: Files that were missing and are back.}
missing: {type: integer, description: Files newly flagged as missing. They are never deleted.}
failed: {type: integer, description: Files that could not be read.}
skipped: {type: integer, description: Symlinks and special files.}
unsupported: {type: integer, description: "Audio files in formats Sonda cannot read yet, such as m4a, ogg or wav."}
ScanStatus:
type: object
additionalProperties: false
required: [running]
properties:
running: {type: boolean}
started_at: {type: string, format: date-time}
last_finished_at: {type: string, format: date-time}
last: {$ref: '#/components/schemas/ScanSummary'}
last_error: {type: string}
ArtistRef:
type: object
additionalProperties: false
required: [id, name]
properties:
id: {type: integer, format: int64}
name: {type: string}
AlbumRef:
type: object
additionalProperties: false
required: [id, title]
properties:
id: {type: integer, format: int64}
title: {type: string}
Artist:
type: object
additionalProperties: false
required: [id, name, album_count, track_count]
properties:
id: {type: integer, format: int64}
name: {type: string}
album_count: {type: integer}
track_count: {type: integer, description: Playable tracks the artist is credited on.}
Album:
type: object
additionalProperties: false
required: [id, title, artist, track_count, duration_ms]
properties:
id: {type: integer, format: int64}
title: {type: string}
artist:
type: object
nullable: true
description: The album artist; null when the album has none.
additionalProperties: false
required: [id, name]
properties:
id: {type: integer, format: int64}
name: {type: string}
track_count: {type: integer}
duration_ms: {type: integer, format: int64}
Track:
type: object
additionalProperties: false
required: [id, title, duration_ms, track_no, disc_no, album, artists, format]
properties:
id: {type: integer, format: int64}
title: {type: string}
duration_ms: {type: integer, format: int64}
track_no: {type: integer, description: 0 when unknown.}
disc_no: {type: integer, description: 0 when unknown.}
album:
type: object
nullable: true
description: The album; null for a track that belongs to none.
additionalProperties: false
required: [id, title]
properties:
id: {type: integer, format: int64}
title: {type: string}
artists:
type: array
items: {$ref: '#/components/schemas/ArtistRef'}
format: {type: string, description: 'Format of the first playable file, for example `mp3` or `flac`.'}
ArtistPage:
type: object
additionalProperties: false
required: [items, total, limit, offset]
properties:
items:
type: array
items: {$ref: '#/components/schemas/Artist'}
total: {type: integer, description: "Size of the whole result, not of this page."}
limit: {type: integer}
offset: {type: integer}
AlbumPage:
type: object
additionalProperties: false
required: [items, total, limit, offset]
properties:
items:
type: array
items: {$ref: '#/components/schemas/Album'}
total: {type: integer}
limit: {type: integer}
offset: {type: integer}
TrackPage:
type: object
additionalProperties: false
required: [items, total, limit, offset]
properties:
items:
type: array
items: {$ref: '#/components/schemas/Track'}
total: {type: integer}
limit: {type: integer}
offset: {type: integer}
Listen:
type: object
required: [track_id, event_type, idempotency_key]
properties:
track_id: {type: integer, format: int64, minimum: 1}
event_type: {type: string, enum: [play, complete, skip]}
occurred_at: {type: string, format: date-time, description: Defaults to now.}
duration_played_ms:
type: integer
format: int64
minimum: 0
description: Milliseconds actually played. Up to twice the track length plus 10 seconds when that length is known.
idempotency_key: {type: string, description: "One per play, 1 to 128 bytes (UTF-8). A key that was already used is ignored."}
Provider:
type: object
additionalProperties: false
required: [name, enabled, needs_api_key, has_api_key, contact, sends, notes, updated_at]
properties:
name: {type: string, enum: [lastfm, musicbrainz]}
enabled: {type: boolean, description: Whether Sonda may contact this provider.}
needs_api_key: {type: boolean}
has_api_key: {type: boolean, description: Whether a key is stored. The key itself is never returned.}
contact: {type: string, description: Contact in the User-Agent; empty means the project address.}
sends: {type: string, description: "Plain statement of what is sent to the provider, and what never is."}
notes: {type: string, description: Terms of use and attribution that apply to the provider's data.}
updated_at:
type: string
format: date-time
nullable: true
description: When the settings last changed; null if they never did.
ProviderUpdate:
type: object
anyOf:
- required: [enabled]
- required: [api_key]
- required: [contact]
properties:
enabled: {type: boolean}
api_key:
type: string
format: password
description: A Last.fm key is 32 hexadecimal characters. Empty clears it.
contact:
type: string
maxLength: 200
description: A URL or e-mail address, without parentheses. Empty restores the default.
ProviderTest:
type: object
additionalProperties: false
required: [ok, status]
properties:
ok: {type: boolean}
status:
type: string
enum: [ok, no_api_key, key_refused, rate_limited, unreachable, error]
description: |
`no_api_key`: none is stored, so nobody was asked. `key_refused`: the provider does not accept
it. `rate_limited`: try again later. `unreachable`: the provider did not answer. `error`: anything else.
ArtistTags:
type: object
additionalProperties: false
required: [sources]
properties:
sources:
type: array
items:
type: object
additionalProperties: false
required: [provider, provider_status, stale, retrieved_at, attribution, tags]
properties:
provider: {type: string, enum: [lastfm, musicbrainz]}
provider_status:
type: string
enum: [ok, disabled, error, no_id]
description: |
`ok`: the data is as fresh as it needs to be. `disabled`: the provider is off or has no
key, so it was not asked. `error`: it was asked and failed. `no_id`: it needs the
MusicBrainz id of the artist, which is not known, so it was not asked.
stale: {type: boolean, description: "True when `tags` are older than they should be because the provider could not be asked."}
retrieved_at:
type: string
format: date-time
nullable: true
description: When the provider was last read for this artist; null if never.
attribution: {type: string, description: Credit to show where the tags are shown.}
tags:
type: array
description: The heaviest tags first, at most 50.
items:
type: object
additionalProperties: false
required: [name, weight, genre]
properties:
name: {type: string, description: Lower case.}
weight: {type: number, description: "The provider's own number; see the operation."}
genre: {type: boolean}
SimilarArtists:
type: object
additionalProperties: false
required: [provider, provider_status, stale, retrieved_at, attribution, items]
properties:
provider: {type: string, enum: [lastfm]}
provider_status:
type: string
enum: [ok, disabled, error]
description: |
`ok`: the data is as fresh as it needs to be. `disabled`: the provider is off or has no key,
so it was not asked. `error`: it was asked and failed.
stale: {type: boolean, description: "True when `items` are older than they should be because the provider could not be asked."}
retrieved_at:
type: string
format: date-time
nullable: true
description: When the provider was last read for this artist; null if never.
attribution: {type: string, description: Credit to show where the data is shown.}
items:
type: array
items:
type: object
additionalProperties: false
required: [artist, in_library, score, rank]
properties:
artist: {$ref: '#/components/schemas/ArtistRef'}
in_library: {type: boolean, description: Whether the artist has something playable in the library.}
score: {type: number, minimum: 0, maximum: 1, description: "The provider's own number, relative to this list."}
rank: {type: integer, minimum: 1, description: "Position in the provider's list, 1 first."}
ListenResult:
type: object
additionalProperties: false
required: [status, counted]
properties:
status: {type: string, enum: [recorded, duplicate]}
counted: {type: boolean, description: Whether the event counts as a listen.}
ListenItem:
type: object
additionalProperties: false
required: [id, track, event_type, occurred_at, duration_played_ms, counted]
properties:
id: {type: integer, format: int64}
track:
type: object
additionalProperties: false
required: [id, title]
properties:
id: {type: integer, format: int64}
title: {type: string}
event_type: {type: string, enum: [play, complete, skip]}
occurred_at: {type: string, format: date-time}
duration_played_ms: {type: integer, format: int64}
counted: {type: boolean, description: Whether the event counts as a listen under the current rule.}
ListenPage:
type: object
additionalProperties: false
required: [items, total, limit, offset]
properties:
items:
type: array
items: {$ref: '#/components/schemas/ListenItem'}
total: {type: integer, description: "Size of the whole result, not of this page."}
limit: {type: integer}
offset: {type: integer}