- feat(storage): provider_settings table (provider, enabled, api_key, contact);
migration 0007 for both drivers. A provider with no row, or turned off, is
never contacted
- feat(providers): a service that validates and applies settings: a Last.fm key
is 32 hexadecimal characters, enabling a provider that needs a key without
one is refused, clearing the key turns the provider off, a contact cannot
contain parentheses or control characters. Each provider states what it sends
and under which terms, and what it never sends
- feat(api): admin-only GET /providers and PUT /providers/{name}. The API key is
write-only: responses carry only has_api_key, errors never repeat it and the
request log never contains it (tested)
- feat(providers/outbound): the only way Sonda talks to the outside: plain GET
with an identifiable User-Agent, no cookies, no Referer, no Authorization, no
redirects, bounded answers, a timeout per attempt, a minimum interval between
requests, retries with exponential backoff that honour Retry-After without
waiting past the caller's deadline or for an absurd time, and a circuit
breaker that makes a failing provider fail fast
- feat(providers): UserAgent builds "Sonda/version ( contact )" as MusicBrainz
asks, defaulting to the project address so no personal address is sent
- breaking(config): providers.lastfm and SONDA_LASTFM_API_KEY are gone; an old
config, or the variable, fails with a hint instead of being ignored
- docs: OpenAPI operations and schemas, README section on the providers and on
what leaves the server
- test: fake servers and a fake clock only; no network in the suite
1308 lines
46 KiB
YAML
1308 lines
46 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: 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, or nothing of it can be played (`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 the provider off. A provider that needs a key (Last.fm) 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'}
|
|
|
|
/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.
|
|
|
|
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}
|