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. 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/Credentials'} 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. 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: "Signs you out everywhere: every refresh token of the account is revoked." 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 sessions. 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. Signs that user out everywhere. security: [{bearerAuth: []}] requestBody: required: true content: application/json: schema: type: object required: [password] properties: password: {type: string, format: password, minLength: 8, maxLength: 256} 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. 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 `