sonda/docs/api.md
tgiachi 11077f40e1
All checks were successful
release / release (push) Successful in 36s
release / base (push) Has been skipped
release / image (amd64) (push) Has been skipped
release / image (arm64) (push) Has been skipped
release / manifest (push) Has been skipped
docs: split the README into pages under docs/
The README had grown to about 500 lines. It now holds the intro, a quick
start and an index, and the rest lives in docs/.

- docs: add docs/README.md as the index of all pages
- docs: move install, configuration, demo, providers, OpenSubsonic, API,
  security and backups, web app, Android app and development/releases
  to their own pages, text unchanged
- docs: split the feature list into five pages under docs/features/
- docs: rewrite internal anchors as links between the new pages
- chore: add docs to .dockerignore, next to README.md
2026-11-17 14:50:52 +01:00

8 KiB

The API at a glance

Docs · Sonda

Everything lives under /api/v1. Bodies are JSON. Errors always look like {"error":{"code":"...","message":"..."}}.

Interactive documentation: open http://127.0.0.1:8080/api/docs/ in a browser. Use Authorize with the access_token from the login to try the protected operations. The OpenAPI file itself is at /api/v1/openapi.yaml. Both are public, since they describe the API and contain no data.

Who Method and path What it does
anyone GET /health Liveness check.
signed in GET /version The version of Sonda and, when the binary knows it, the commit it was built from. The web app shows it under the menu and in Settings.
anyone POST /auth/register Create the first user (admin). Closed afterwards.
anyone POST /auth/login, /auth/refresh, /auth/logout Open, renew and end a session.
signed in GET /auth/me, POST /auth/password Your account; change your password (signs you out everywhere).
signed in GET /artists, /albums, /tracks and /…/{id} Browse and search. Query: q, limit (default 50, max 200), offset, library_id, artist_id, album_id, and for /albums sort=recent (the albums added last first, by the date of their newest file; the default is by title).
signed in GET /artists/{id}/tags What Last.fm and MusicBrainz say about the artist's kind of music, from each provider that is on.
signed in GET, HEAD /artists/{id}/image, GET /artists/{id}/image/credit A free picture of the artist from Wikimedia Commons (query size=small|large, also ?access_token=) and its credit.
signed in GET /artists/{id}/description What Wikipedia says about the artist, with its page and licence, from the Wikipedia provider when an admin switched it on.
signed in GET /artists/{id}/similar Artists similar to one, from Last.fm when an admin switched it on. Query: limit (default 20, max 50).
signed in GET, HEAD /tracks/{id}/stream Stream the original file. Also accepts ?access_token=.
signed in POST /listens Record a play, complete or skip; the answer says whether it counts as a listen.
signed in GET /listens Your own history, newest first, with counted per event. Query: limit, offset, counted=true.
signed in GET /stats/library, GET /stats/listening What the library holds; what you listened to, for all time or a period. Query of the second: from, until, tz.
signed in GET /discover Artists you may like, with a score and its parts. Query: seed (an artist id, up to 5 times), limit (default 20, max 30), in_library=true|false.
signed in GET, HEAD /albums/{id}/cover The cover of an album, a JPEG made from your own files. Query: size=small|large. Also accepts ?access_token=.
signed in GET /mixes, GET /mixes/{id}, POST /mixes/{id}/playlist Your mixes: list them, read one (query variant), keep one as a playlist. Made for you alone, from your history and your genres; nothing is stored.
signed in GET /genres The genres of the library with their number of songs, the biggest first, spellings merged: what the rules of a smart playlist choose from.
signed in GET /smart-playlists, POST /smart-playlists, GET, PATCH, DELETE /smart-playlists/{id} Your smart playlists: list them (query limit, offset), make one from rules, read, change or delete one. Never anybody else's.
signed in GET /naming Whether names are made by themselves (auto): true when the anthropic provider is on.
signed in POST /playlists/{id}/suggest-name, POST /mixes/{id}/suggest-name, POST /smart-playlists/{id}/suggest-name A name and a line of description for a list of songs (body: lang, variant): Claude's when an admin turned the anthropic provider on, a local one otherwise (source).
signed in GET /smart-playlists/suggested, GET /smart-playlists/suggested/{key}/tracks, POST /smart-playlists/suggested/{key}/playlist The smart playlists Sonda makes for everybody (a fixed set), their songs for you now (query variant), and one kept as a normal playlist.
signed in GET /smart-playlists/{id}/tracks, POST /smart-playlists/preview, POST /smart-playlists/{id}/playlist The songs the rules give now (query variant), a preview of rules that are not kept, and a smart playlist kept as a normal playlist.
signed in GET /playlists, POST /playlists, GET, PATCH, DELETE /playlists/{id} Your playlists: list them (query limit, offset), make one, read, rename or delete one. Never anybody else's.
signed in GET /playlists/{id}/tracks, POST /playlists/{id}/tracks, PATCH, DELETE /playlists/{id}/tracks/{item} The songs of a playlist: list them in order, add some (at the end or at a position), move or remove an item.
signed in GET /wishlist, PUT /wishlist/{id}, DELETE /wishlist/{id} Your wishlist: list it (query limit, offset), add an artist, take one off.
signed in GET /discover/dismissed, POST /discover/{id}/dismiss, DELETE /discover/{id}/dismiss The artists you are not interested in: list them, dismiss one, bring it back.
signed in GET /me/taste The artists and tags Sonda learned you like, from your own listening. Query: limit (default 20, max 50).
signed in GET /me/settings, PATCH /me/settings Your own settings (today: discover_from_listening, off by default).
signed in GET /library/covers, GET /library/artist-images, GET /library/descriptions Progress of the job that builds the covers, looks for the artist pictures or for the artist descriptions, and how the last one ended.
signed in GET /library/scan Scan status and the last result.
admin GET, POST /libraries; PATCH, DELETE /libraries/{id} Manage libraries. Deleting one removes its index entries, never your files.
admin POST, DELETE /library/covers; POST, DELETE /library/artist-images; POST, DELETE /library/descriptions Start, in the background, a job that builds the cover of every album, looks for the picture of every artist or for the description of every artist (?refresh=true for all), or stop it. One of each at a time.
admin POST /library/scan, POST /libraries/{id}/scan Scan everything, or one library. ?full=true reads every file again.
admin GET /library/duplicates; POST, GET, DELETE /library/duplicates/check; POST /library/duplicates/clean Find the songs that are in more than one file, read their files to tell the identical ones, and delete the extra copies. See Duplicates.
admin GET /providers, PUT /providers/{name}, POST /providers/{name}/test, DELETE /providers/{name}/data See, set up and check the providers (Last.fm, MusicBrainz, Wikipedia, Commons, the Cover Art Archive, Lidarr), and remove what they gave. The API key is write-only.
admin GET /providers/anthropic/usage What the Claude provider costs over the last days (query days, 1 to 365): totals, a row for each day with calls and an estimate in dollars.
admin GET /providers/lidarr/options The profiles and root folders that Lidarr offers, to choose the ones artists are sent with.
admin POST /artists/{id}/lidarr Send an artist to your own Lidarr, by its MusicBrainz id, which then looks for the music. Never by name, never by itself.
signed in GET /artists/{id}/lidarr Whether Lidarr has the artist and monitors it.
admin GET, POST /users; PATCH, DELETE /users/{id}; PUT /users/{id}/password Manage users and the admin role. The last admin cannot be demoted or deleted.

A library path must be an absolute, existing folder, never the filesystem root, and never inside or around another library. Search is a case- and accent-insensitive substring match: bjork, BJORK and BJÖRK all find Björk, and strasse finds Straße. Accents still tell artists apart: Beyoncé and Beyonce stay two artists, and a search for either finds both.