sonda/internal/api/openapi/openapi.yaml
tgiachi 9d28a8a99c feat(api): OpenAPI spec and an offline Swagger UI
- feat: internal/api/openapi/openapi.yaml describes every operation (OpenAPI
  3.0.3), written by hand and embedded in the binary; GET /api/v1/openapi.yaml
  serves it
- feat: GET /api/docs/ serves Swagger UI from assets embedded in the binary
  (github.com/swaggest/swgui, v5emb), so opening it never contacts another
  server; both are public because they contain no data
- feat: response objects in the spec are closed (additionalProperties: false)
- test: the spec is valid OpenAPI; the router and the spec describe the same
  operations in both directions; every operation has an id, a summary, a tag,
  a documented 401 when it needs a token and a 403 when it is admin only
- test: a contract test drives every operation through the real services,
  including a real scan and real streaming, and validates each response
  (status, headers, JSON body) against the spec with kin-openapi; it fails if
  an operation was never exercised. Checked by breaking the code and the spec
  on purpose
- test: the docs page loads without any external address and every asset it
  references is served
- docs: README section on the interactive documentation and on keeping the
  spec in step with the code

Closes #15
2026-11-11 14:35:16 +01:00

1077 lines
36 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.
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 `<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}
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.
headers:
Content-Range:
description: The range sent and the size of the file, for example `bytes 0-99/40635`.
schema: {type: string}
content:
audio/mpeg:
schema: {type: string, format: binary}
audio/flac:
schema: {type: string, format: binary}
'304': {description: Not modified since `If-Modified-Since`.}
'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}
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}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {description: No such track or file.}
'416': {description: The range cannot be satisfied.}
/listens:
post:
tags: [Playback]
operationId: recordListen
summary: Record a listen
description: |
Clients report what the listener did. The `idempotency_key` makes a retry harmless: the
same key from the same user is recorded once and answered with `duplicate`.
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. Default 50; values above 200 are lowered to 200.
schema: {type: integer, minimum: 0}
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, minLength: 8, maxLength: 256}
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, minLength: 8, maxLength: 256}
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
minProperties: 1
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:
nullable: true
description: The album artist, if the album has one.
allOf:
- $ref: '#/components/schemas/ArtistRef'
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:
nullable: true
allOf:
- $ref: '#/components/schemas/AlbumRef'
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}
idempotency_key: {type: string, minLength: 1, maxLength: 128}
ListenResult:
type: object
additionalProperties: false
required: [status]
properties:
status: {type: string, enum: [recorded, duplicate]}