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.

The download queue is the engine room of Crate. Every track that needs to be fetched passes through a DownloadQueueItem whose status progresses from pending → searching → downloading → organizing → complete (or failed). The endpoints below let you inspect the queue, control retries, and clear old entries. Related utility endpoints for the activity log and provider cache are also documented here.

​
GET /api/downloads/

Returns all download queue items, optionally filtered by status. Each item embeds the full nested Track object so you have everything needed to display queue state without additional requests.
​
status
string
Filter results to items with this status. Accepted values: pending, searching, downloading, organizing, complete, failed. Omit to return all items.
Response — array of DownloadQueueItem
​
id
integer
The queue entry’s internal ID.
​
track_id
integer
ID of the track being downloaded.
​
slskd_search_id
string
The slskd search UUID, or a "username|transferID" composite during an active transfer. May be null before a search starts.
​
status
string
Current lifecycle status: pending, searching, downloading, organizing, complete, or failed.
​
attempts
integer
How many download attempts have been made for this queue entry.
​
last_attempt
string
RFC 3339 timestamp of the most recent attempt, or null if no attempt has been made yet.
​
error
string
Error message from the last failed attempt, or null.
​
next_retry_at
string
RFC 3339 timestamp when the next automatic retry is scheduled. null if not waiting to retry.
​
source
string
How the queue entry was created: "user" for entries added via the API or UI, "scheduler" for entries re-queued by the automatic download scheduler.
​
last_progress_bytes
integer
Bytes transferred as of the last progress update. Used to detect stalled transfers.
​
created_at
string
RFC 3339 timestamp when the entry was created.
​
track
object
Nested Track object. Contains id, title, track_number, disc_number, status, file_path, download_format, download_bitrate, artist_name, album_title, and other fields from the track model.
# All downloads
curl http://localhost:6969/api/downloads/

# Only failed downloads
curl "http://localhost:6969/api/downloads/?status=failed"

​
GET /api/downloads/progress

Returns the bytes-transferred progress for all currently active (downloading-state) transfers, queried live from slskd. Use this to drive a progress bar without polling the full queue list. 
curl http://localhost:6969/api/downloads/progress

​
POST /api/downloads/queue

Bulk-queues all currently wanted tracks across the entire library. This is the same action as “Queue all wanted” in the UI. Already-queued tracks are skipped by the unique partial index on download_queue(track_id) where status is active, so it is safe to call repeatedly. Response
​
queued
integer
Number of new queue entries that were created.
curl -X POST http://localhost:6969/api/downloads/queue

​
POST /api/downloads/{id}/retry

Immediately retries a failed download by resetting its status to pending and clearing any scheduled next_retry_at value. The downloader loop will pick it up on its next tick.
​
id
integer
required
The download queue entry ID (not the track ID).
Response
​
status
string
Always "pending" on success.
curl -X POST http://localhost:6969/api/downloads/7/retry

​
DELETE /api/downloads/{id}

Removes a single download queue entry. If the entry is in an active state (pending, searching, or downloading), Crate also cancels the corresponding slskd transfer and resets the track’s status back to wanted.
​
id
integer
required
The download queue entry ID.
Returns 204 No Content on success. 
curl -X DELETE http://localhost:6969/api/downloads/7

​
DELETE /api/downloads/clear

Bulk-removes all download queue entries that match a given status. For active statuses (pending, searching, downloading), the corresponding tracks are reset to wanted before deletion so they are not lost.
This operation is not reversible. Clearing complete entries removes them permanently; clearing failed entries removes them without re-queuing the tracks.
​
status
string
required
The status bucket to clear. Must be one of: failed, complete, pending, downloading, searching.
Response
​
deleted
integer
Number of queue entries that were removed.
# Clear all completed downloads
curl -X DELETE "http://localhost:6969/api/downloads/clear?status=complete"

# Clear all failed downloads
curl -X DELETE "http://localhost:6969/api/downloads/clear?status=failed"

​
GET /api/activity

Returns recent entries from the activity log, which records every significant download event (search started, download completed, file organized, error, etc.). Results are returned newest-first, paginated via limit and offset.
​
limit
integer
Maximum number of entries to return. Defaults to 50.
​
offset
integer
Number of entries to skip for pagination. Defaults to 0.
Response
​
items
array
Array of ActivityLog entries.
​
total
integer
Total number of activity log entries (before pagination), useful for building paginated UIs.
# Latest 50 entries
curl http://localhost:6969/api/activity

# Entries 50–99
curl "http://localhost:6969/api/activity?limit=50&offset=50"
The activity log lives in a separate SQLite file (activity.db). Its retention period is controlled by the activity_retention_days setting. The file can be deleted entirely without affecting the main crate.db database.

​
DELETE /api/cache

Clears the provider response cache stored in cache.db. Useful if you suspect stale data from a provider or if you have changed providers and want fresh results on the next search. The cache repopulates automatically on the next provider request. Response
​
status
string
Always "cleared" on success.
curl -X DELETE http://localhost:6969/api/cache

Build docs developers (and LLMs) love

Get started for freeTalk to us