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.

Every track in Crate’s library carries a lifecycle status — wanted, downloading, owned, or ignored — and the endpoints below move a track between those states or trigger side-effects like slskd searches and file deletion. All endpoints return JSON; errors always include an "error" string field.

​
POST /api/tracks/{id}/queue

Adds a single track to the download queue. If the track already has an active queue entry (status pending, searching, downloading, or organizing) the database unique constraint prevents a duplicate from being created and the request returns an error.
​
id
integer
required
The internal track ID.
Response
​
status
string
Always "queued" on success.
curl -X POST http://localhost:6969/api/tracks/42/queue

​
POST /api/tracks/{id}/search

Starts an asynchronous manual search against slskd for the given track. Because a slskd search can take up to 30 seconds, this endpoint returns immediately with a search_id you can poll. An optional override query can be provided in the request body; if omitted, Crate constructs the query from the track’s artist and title.
​
id
integer
required
The internal track ID.
Request body (optional)
​
query
string
Custom search string to send to slskd. Defaults to "Artist Title" when omitted.
Response
​
search_id
string
UUID of the slskd search in progress. Pass this to the poll endpoint.
​
track_id
integer
Echo of the requested track ID.
​
query
string
The exact query string sent to slskd.
curl -X POST http://localhost:6969/api/tracks/42/search \
  -H "Content-Type: application/json" \
  -d '{"query": "Radiohead Karma Police"}'

​
GET /api/tracks/{id}/search/{searchId}

Polls the results of a manual search. When the search is still running, status is "pending". Once slskd finishes, status becomes "complete" and results is populated with every file that matched, scored and annotated.
​
id
integer
required
The internal track ID.
​
searchId
string
required
The UUID returned by the start-search endpoint.
Response
​
status
string
"pending" while the slskd search is still running, "complete" when results are available.
​
results
array
Present and populated when status is "complete". Each element describes one candidate file.
curl http://localhost:6969/api/tracks/42/search/d4e5f6a7-b8c9-4d0e-a1b2-c3d4e5f6a7b8

​
DELETE /api/tracks/{id}/search/{searchId}

Cancels and cleans up a manual search, asking slskd to delete the search on its side. Returns 204 No Content on success. This is called automatically by the UI when you close the manual-search modal.
​
id
integer
required
The internal track ID.
​
searchId
string
required
The UUID returned by the start-search endpoint.
curl -X DELETE \
  http://localhost:6969/api/tracks/42/search/d4e5f6a7-b8c9-4d0e-a1b2-c3d4e5f6a7b8

​
POST /api/tracks/{id}/download

Manually selects a specific result from a completed manual search and immediately starts downloading it, bypassing the auto-scorer. The size and bit_rate fields are stored on the download queue item for progress tracking and upgrade decisions respectively.
​
id
integer
required
The internal track ID.
Request body
​
username
string
required
The slskd username to download from.
​
filename
string
required
The full remote file path, as returned by the poll endpoint.
​
size
integer
Expected file size in bytes (used for progress tracking).
​
bit_rate
integer
Bitrate in kbps; 0 for lossless formats such as FLAC.
Response
​
status
string
Always "downloading" on success.
curl -X POST http://localhost:6969/api/tracks/42/download \
  -H "Content-Type: application/json" \
  -d '{
    "username": "vinylhead99",
    "filename": "music/Radiohead/OK Computer/06 - Karma Police.flac",
    "size": 28311552,
    "bit_rate": 0
  }'

​
POST /api/tracks/{id}/link

Claims a wanted provider track using an owned local track’s file — “this local file is that track”. The local track’s file path and quality metadata are transferred to the target track, which is marked owned. The local track record is then deleted. Both tracks must belong to the same album.
​
id
integer
required
The internal track ID of the owned local track whose file you want to claim.
Request body
​
target_track_id
integer
required
The Crate internal track ID of the wanted provider track to claim the file for. Must be in the same album as the source track.
Response
​
status
string
Always "linked" on success.
​
claimed
integer
The internal ID of the target track that was claimed.
curl -X POST http://localhost:6969/api/tracks/99/link \
  -H "Content-Type: application/json" \
  -d '{"target_track_id": 203}'

​
POST /api/tracks/{id}/reject

Rejects the current copy of an owned track in one atomic operation: the file is deleted from the library, the username+filename pair is added to the permanent blacklist, and the track’s status is reset to wanted so Crate will search for a replacement. A Navidrome/Music Assistant library rescan is triggered asynchronously after rejection.
This endpoint only works on tracks with status owned. Attempting to reject a track that is not owned returns 400 Bad Request with "track is not owned".
​
id
integer
required
The internal track ID.
Response
​
status
string
Always "rejected" on success.
curl -X POST http://localhost:6969/api/tracks/42/reject

​
POST /api/tracks/reject

Rejects an owned track identified by artist name and title rather than by internal ID. This endpoint is used by the Music Assistant integration — when you add a track to the reject playlist in Music Assistant, MA calls this endpoint with the track metadata, and Crate handles the deletion, blacklisting, and re-queue automatically. Request body
​
artist
string
required
The artist name to look up. Matched case-insensitively against owned tracks.
​
title
string
required
The track title to look up. Matched case-insensitively against owned tracks.
Response
​
status
string
Always "rejected" on success.
curl -X POST http://localhost:6969/api/tracks/reject \
  -H "Content-Type: application/json" \
  -d '{"artist": "Radiohead", "title": "Karma Police"}'

​
PUT /api/tracks/{id}/ignore

Marks a track as ignored, preventing it from being included in any future download queue scans. Ignored tracks remain in the library and can be un-ignored at any time.
​
id
integer
required
The internal track ID.
Response
​
status
string
Always "ignored" on success.
curl -X PUT http://localhost:6969/api/tracks/42/ignore

​
DELETE /api/tracks/{id}/ignore

Removes the ignored status from a track, restoring it to wanted. From the next scheduled scan, Crate will include this track in search runs again.
​
id
integer
required
The internal track ID.
Response
​
status
string
Always "wanted" on success.
curl -X DELETE http://localhost:6969/api/tracks/42/ignore

​
DELETE /api/tracks/{id}

Removes a track from Crate’s watch list entirely. Accepts an optional delete=true query parameter: when set and the track status is owned, Crate also deletes the file from disk and triggers an async library rescan.
​
id
integer
required
The internal track ID.
​
delete
boolean
When true, deletes the physical file from the library directory (only if the track is owned). Defaults to false.
Returns 204 No Content on success. 
# Remove from watch list only
curl -X DELETE http://localhost:6969/api/tracks/42

# Remove from watch list AND delete the file
curl -X DELETE "http://localhost:6969/api/tracks/42?delete=true"

​
POST /api/relink/track/{id}

Relinks a track to a different provider ID within the currently active primary provider. This is a leaf operation — unlike artist or album relinks, there is no downstream reconciliation. Use this to correct a track that was matched to the wrong provider entry during an import or sync.
​
id
integer
required
The internal track ID.
Request body
​
provider_id
string
required
The new provider-specific track ID to assign (e.g. a MusicBrainz recording MBID).
Response
​
status
string
Always "relinked" on success.
​
reconciling
boolean
Always false for track relinks — tracks are leaf nodes with nothing to reconcile beneath them.
curl -X POST http://localhost:6969/api/relink/track/42 \
  -H "Content-Type: application/json" \
  -d '{"provider_id": "f3b5a6c2-1d4e-4a7b-9c0d-2e3f4a5b6c7d"}'

Build docs developers (and LLMs) love

Get started for freeTalk to us