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 `. 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 `