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 ships a built-in Lidarr v1 API shim mounted at /api/v1/. This means any iOS app (or other client) that speaks the Lidarr API can point at your Crate server and manage your library — browsing artists and albums, toggling monitoring, searching for missing tracks, and triggering downloads — without any additional software or configuration. No Lidarr installation is needed. The shim translates between Lidarr’s data model and Crate’s, so operations in the client app flow through to Crate’s actual library database and download engine.

​
Authentication

The shim accepts any API key in the X-Api-Key request header or the apikey query parameter. Crate has no built-in authentication of its own — the API key is accepted unconditionally and is never validated. If you need to restrict access, place a reverse proxy with auth (for example Cloudflare Zero Trust, Authelia, or nginx basic auth) in front of Crate. 
GET /api/v1/system/status HTTP/1.1
X-Api-Key: any-string-you-like

GET /api/v1/system/status?apikey=any-string-you-like

​
No extra configuration

Point your app at your Crate URL. That is all. There are no settings to enable or API keys to generate inside Crate — the /api/v1/ routes are always active.
  1. Open Helmarr and go to Settings → Servers → Add Server.
  2. Set the Server URL to your Crate URL, for example http://192.168.1.10:6969.
  3. Enter any string in the API Key field.
  4. Tap Test — Helmarr will connect and load your library.

​
Concept mapping

Lidarr and Crate model music libraries differently. The shim translates between them transparently.
Lidarr conceptCrate equivalentNotes
Monitor "all"Artist status watchedFull discography tracked
Monitor "latest"Watch newest album + enable new releasesMost recent album by year; future albums are auto-added
Quality profile"Crate Quality"Crate uses priority-ordered quality tiers instead of Lidarr-style profiles
Metadata profileActive provider nameShows whichever provider is set as primary (MusicBrainz, Deezer, etc.)
Root folderCRATE_LIBRARY_PATHLibrary directory with real disk stats from statfs
Monitored albumAlbum status watchedTracks set to wanted
Unmonitored albumAlbum status ignoredTracks cascade to ignored; existing owned and downloading states are preserved
ArtistSearch commandQueue all wanted tracks for artistSame as “Search wanted tracks” in the Crate UI
AlbumSearch commandQueue wanted tracks for album(s)Same as “Search wanted tracks” on the album page
”Search for missing albums” on addAuto-queue after watchQueues all wanted tracks for the artist immediately after it is added

​
Supported endpoints

MethodPathDescription
GET/api/v1/system/statusServer info, version, OS, runtime
GET/api/v1/healthHealth check; surfaces unreachable providers as warnings
GET/api/v1/diskspaceFree and total space for CRATE_LIBRARY_PATH
GET/api/v1/qualityprofileReturns the single "Crate Quality" profile
GET/api/v1/metadataprofileReturns the active provider as the metadata profile
GET/api/v1/rootfolderReturns CRATE_LIBRARY_PATH with live disk stats
GET/api/v1/customfilterReturns empty array (no custom filters)
GET/api/v1/tagReturns empty array
GET/api/v1/languageprofileReturns a stub English profile
MethodPathDescription
GET/api/v1/artistList all watched artists with statistics
GET/api/v1/artist/lookup?term=…Search provider for artists (flat array)
GET/api/v1/artist/{id}Get single artist with full album/track data
POST/api/v1/artistAdd artist; honours monitor (all/latest) and searchForMissingAlbums in addOptions
PUT/api/v1/artist/{id}Update artist (returns current state)
DELETE/api/v1/artist/{id}Remove artist from library
MethodPathDescription
GET/api/v1/album?artistId=…List albums for an artist with track statistics
GET/api/v1/album/{id}Get single album with tracks
PUT/api/v1/album/monitorToggle monitoring for one or more album IDs; cascades track statuses
DELETE/api/v1/album/{id}Remove album from library
Commands are submitted as POST /api/v1/command with a JSON body. Crate responds immediately with status: "completed" while the actual work runs in the background.
Command nameBody fieldsWhat Crate does
ArtistSearchartistId (integer)Enqueues all wanted tracks for the artist
AlbumSearchalbumIds (array of integers) or albumId (integer)Enqueues all wanted tracks for the specified album(s)
// ArtistSearch
{ "name": "ArtistSearch", "artistId": 42 }

// AlbumSearch — single album
{ "name": "AlbumSearch", "albumId": 7 }

// AlbumSearch — multiple albums
{ "name": "AlbumSearch", "albumIds": [7, 8, 9] }

​
What is not supported

Interactive search (GET /api/v1/release and POST /api/v1/release) is not implemented — the endpoints return an empty array. Interactive search is a Crate UI feature: open the track in the Crate web app, tap Search, and browse every scored slskd result to pick one manually. This cannot be replicated through the Lidarr shim.
Unknown endpoints return an empty JSON array with HTTP 200 rather than a 404, which prevents well-behaved Lidarr clients from treating unimplemented endpoints as errors.

​
Tested apps

Helmarr

iOS — Full artist and album management, provider search, monitoring toggles, and download queue. The primary tested client for the Crate Lidarr shim.

Your app here

Tested another Lidarr-compatible app against Crate? Contributions to expand shim coverage and update the tested-apps list are welcome in the Crate repository.
If you test Crate against another Lidarr-compatible app and find missing or misbehaving endpoints, open an issue or pull request on the Crate repository. The shim logs every request at INFO level under the [LIDARR SHIM] prefix — check your Crate logs to see exactly what the client is sending and what Crate returns.

Build docs developers (and LLMs) love

Get started for freeTalk to us