Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TheOutdoorProgrammer/crate/llms.txt

Use this file to discover all available pages before exploring further.

Crate connects to one or more music metadata providers and lets you search for artists, browse their full discographies, and tell Crate which music you want. When you watch an artist, album, or track, Crate marks the relevant tracks as wanted and queues them for automatic download. Every entity you watch is stored in your library database, so status, ownership, and provider linkage all persist across restarts.

​
How Search Works

The search endpoint (GET /api/search) queries the active provider and returns a list of artists with metadata. Three query parameters control its behavior:
ParameterRequiredDefaultDescription
qYes—The artist name to search for
providerNoPrimaryOverride the provider for this request only
limitNo25Maximum results to return
offsetNo0Pagination offset
When provider is omitted, Crate uses whichever provider is configured as primary. Passing a provider name explicitly lets you compare results across providers without changing the default.

​
Switching Providers on the Fly

The search UI includes a provider selector. Switching it reruns the current query against the chosen provider without navigating away. Provider health is checked on each list load — orphaned artists (whose provider is unreachable) are flagged in the library view.

​
Browsing an Artist

Selecting a search result opens the artist’s full discography via GET /api/browse/artist/{id}. The response includes every release grouped by record type:
  • album — full-length studio releases
  • single — single tracks or double A-sides
  • ep — extended plays
  • compilation — greatest hits, anthologies, and label compilations
The browse response also indicates which albums are already watched in your library (watched_album_ids) and whether the artist is fully watched (artist_watched), so the UI can render accurate watch/unwatch controls.

​
Watch Modes

Watch Artist

Saves the artist with status watched and queues the entire discography as wanted tracks. All future albums discovered by new-release detection are added automatically.

Watch Album

Saves the album with status watched and creates every track on it as wanted. The parent artist is saved as partial if it was not already watched.

Watch Track

Saves a single track as wanted, creating stub artist and album records as needed. The smallest unit of tracking.

​
Status Transitions

Every track moves through a well-defined lifecycle. The download system advances the status automatically; you can also trigger transitions manually from the track or album page.
1

wanted

The track has been added to your library and is waiting to be downloaded. Scheduled scans and the queue button both pick up wanted tracks.
2

downloading

Crate found a suitable file on Soulseek and a transfer is actively in progress. The track moves to this status when the slskd transfer starts; it stays here through the organizing phase until the file is fully moved and recorded.
3

owned

The file has been downloaded, organized into the library folder, and tagged. The track record holds the relative file path.
Tracks can also be ignored. Ignoring an album cascades to all wanted tracks on it (preserving any that are already owned or downloading). Unignoring flips them back to wanted.

​
New Release Detection

Each artist has an optional Watch New Releases toggle. When enabled, Crate records a watch_new_releases_since timestamp. On each scheduled scan, albums released after that timestamp are automatically added to the artist’s discography and their tracks are created as wanted. Enable new release detection from the artist page, or pass "watch_new_releases": true in the watch-artist request body: 
POST /api/watch/artist/{providerId}
{
  "watch_new_releases": true,
  "provider": "musicbrainz"
}
You can search within an artist’s catalog by title using GET /api/browse/artist/{id}/tracks?q={query}. This is useful for finding a specific track on a large discography without scrolling through every album. Results are returned scored and ready to watch individually.

​
Unwatching Entities

Removing an artist, album, or track from your library is non-destructive toward files already on disk — DELETE /api/artists/{id} removes the library record but does not delete owned files. To delete the file as well, use ?delete=true when deleting a track.

​
Relinking to a Different Provider

If an artist was originally watched via one provider and you want to switch (for example, to pick up better metadata or cover art from Deezer instead of MusicBrainz), use the relink endpoint: 
POST /api/relink/artist/{id}
{
  "provider_id": "the-new-provider-artist-id"
}
Crate updates the provider and provider_id fields without touching any track statuses, owned files, or download history. If the artist was previously imported under the local provider, relinking triggers a full discography reconcile: albums are matched by title and year, tracks by title, and unmatched entries are flagged for manual review. Owned files are re-pointed, never lost.
The duplicate guard prevents the same artist from being added twice under the same provider. If you search for an artist you already watch, the watch button shows as active rather than creating a second record.

Build docs developers (and LLMs) love

Get started for freeTalk to us