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
8 KiB
8 KiB
The API at a glance
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.