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’s REST API is a JSON-over-HTTP interface that gives you full programmatic control over your music library. Every route lives under the /api prefix, every successful response carries Content-Type: application/json, and every error is a plain JSON object so it’s easy to handle in scripts, home-automation flows, or third-party integrations.

​
Base URL

http://localhost:6969/api
Crate binds to port 6969 by default. Override it with the CRATE_PORT environment variable. When deployed behind a reverse proxy, substitute your public hostname — the API path prefix /api stays the same.

​
Request Limits

ConstraintValue
Request timeout120 seconds
Maximum request body5 MB
Content-Type for POST/PUTapplication/json
CORS is pre-configured to allow http://localhost:5173 and http://localhost:6969. If you access Crate from a different origin (e.g., your own dashboard), add a reverse proxy that injects the appropriate headers.

​
Authentication

Crate has no built-in authentication. All API endpoints are open to anyone who can reach the server. Restrict access at the network layer using a reverse proxy with authentication:
  • Cloudflare Zero Trust — identity-aware proxy, no port exposure needed
  • Authelia — self-hosted SSO and 2FA in front of your reverse proxy
  • nginx basic auth — simple username/password via auth_basic
Do not expose Crate directly on a public IP without a protecting reverse proxy. There is no API key, session token, or rate limiting built into the application.

​
Lidarr Shim

A Lidarr v1 API compatibility shim is mounted at /api/v1/. This allows iOS apps like Helmarr to manage your library as though Crate were a Lidarr instance. The shim accepts any value in the X-Api-Key header or apikey query parameter. See the Lidarr Compatibility section for the full concept mapping.

​
Error Format

All errors — validation failures, not-found responses, and internal errors — use the same envelope: 
{ "error": "descriptive message here" }
HTTP status codes follow standard semantics: 400 for bad input, 404 for missing resources, 500 for unexpected server errors, and 204 No Content for successful deletes.

​
GET /api/status

The status endpoint provides a live health snapshot of your Crate instance — total library size, download queue depth, and the running version. It is useful for monitoring integrations and quick sanity checks. Request 
curl http://localhost:6969/api/status
Response — 200 OK 
{
  "status": "ok",
  "version": "v1.2.0",
  "artists_count": 42,
  "total_tracks": 3810,
  "owned_tracks": 3204,
  "pending_downloads": 7,
  "active_downloads": 2
}
​
status
string
Always "ok" when the server is healthy.
​
version
string
The running Crate build version string.
​
artists_count
integer
Number of artists currently in the library (all statuses).
​
total_tracks
integer
Sum of total_tracks across all watched artists.
​
owned_tracks
integer
Sum of owned_tracks across all watched artists — tracks with files on disk.
​
pending_downloads
integer
Number of download queue entries with status pending.
​
active_downloads
integer
Number of queue entries currently searching or downloading.

​
API Reference

Search

Search providers for artists, browse full discographies, and watch artists, albums, or individual tracks.

Artists

List your library, get artist details, toggle new-release detection, queue downloads, and unwatch.

Albums

Retrieve album details, queue tracks, link to a provider, toggle ignore status, and unwatch.

Tracks

Manage individual tracks — ignore, queue, link, manual search, and reject bad copies.

Downloads

List the download queue, check live transfer progress, retry failures, and clear by status.

Settings

Read and write all configurable settings, and preview naming templates live.

Blocked Sources

Browse and remove blacklisted files and shadow-banned Soulseek users.

Build docs developers (and LLMs) love

Get started for freeTalk to us