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 Artists API exposes your Crate library at the artist level. An artist record is created whenever you watch a full discography (via POST /api/watch/artist/{id}) or as a side-effect of watching an individual album or track. The endpoints here let you inspect the library, control per-artist settings, trigger bulk downloads, and remove entries you no longer want.

​
The Artist Object

Every endpoint that returns an artist uses the following shape:
​
id
integer
Crate’s internal auto-increment artist ID. Use this for all /api/artists/{id} calls.
​
name
string
Artist display name as returned by the provider at watch time.
​
provider
string
The provider this artist is linked to (e.g. deezer, musicbrainz, local).
​
provider_id
string
The provider-specific artist ID used for re-fetching discography data.
​
image_url
string | null
Artist photo URL. Omitted from JSON when null.
​
status
string
One of watched (full discography tracked), partial (added as a stub when watching an album/track), or owned (imported from local files, not yet linked to a provider).
​
watch_new_releases
boolean
Whether Crate will automatically add newly released albums for this artist.
​
watch_new_releases_since
string | null
RFC 3339 timestamp. Only albums released after this date trigger auto-add. Omitted when watch_new_releases is false.
​
created_at
string
RFC 3339 timestamp when this artist was first added to the library.
​
updated_at
string
RFC 3339 timestamp of the most recent modification.
​
albums
Album[]
Only populated by GET /api/artists/{id}. Contains full album objects with nested tracks[].
​
total_tracks
integer
Total number of tracks across all watched albums for this artist.
​
owned_tracks
integer
Number of tracks with files on disk (status owned).
​
orphaned
boolean
true when the artist’s provider is currently unreachable. Orphaned artists still function — you can queue and download tracks — but browsing and relinking require the provider to be healthy.

​
GET /api/artists/

Returns all artists in the library as an array. Each entry includes total_tracks and owned_tracks counts. Albums and tracks are not nested here — use GET /api/artists/{id} for that level of detail. The orphaned flag is set per-artist based on a live provider health check (results are cached per request to avoid N provider pings per call). Example 
curl http://localhost:6969/api/artists/
Response — 200 OK 
[
  {
    "id": 1,
    "name": "Radiohead",
    "provider": "deezer",
    "provider_id": "409702",
    "image_url": "https://cdn.example.com/radiohead.jpg",
    "status": "watched",
    "watch_new_releases": true,
    "watch_new_releases_since": "2024-01-15T10:00:00Z",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-06-01T08:32:11Z",
    "total_tracks": 102,
    "owned_tracks": 98,
    "orphaned": false
  }
]
Returns an empty array [] when the library has no artists.

​
GET /api/artists/

Returns a single artist by Crate’s internal ID, with full album and track data nested. This is the most complete artist view — every album is included with its tracks[] array populated. Path Parameters
​
id
integer
required
Crate’s internal artist ID. Obtain from GET /api/artists/ or from a watch response.
Example 
curl http://localhost:6969/api/artists/1
Response — 200 OK 
{
  "id": 1,
  "name": "Radiohead",
  "provider": "deezer",
  "provider_id": "409702",
  "status": "watched",
  "watch_new_releases": true,
  "watch_new_releases_since": "2024-01-15T10:00:00Z",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-06-01T08:32:11Z",
  "total_tracks": 102,
  "owned_tracks": 98,
  "orphaned": false,
  "albums": [
    {
      "id": 17,
      "artist_id": 1,
      "title": "OK Computer",
      "year": 1997,
      "provider": "deezer",
      "provider_id": "302127",
      "cover_url": "https://cdn.example.com/okcomputer.jpg",
      "record_type": "album",
      "status": "owned",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-06-01T08:32:11Z",
      "tracks": [
        {
          "id": 203,
          "album_id": 17,
          "title": "Airbag",
          "track_number": 1,
          "disc_number": 1,
          "duration_ms": 292000,
          "provider": "deezer",
          "provider_id": "3135551",
          "status": "owned",
          "file_path": "Radiohead/OK Computer (1997)/01 - Airbag.flac",
          "download_format": "flac",
          "download_bitrate": 900,
          "created_at": "2024-01-15T10:05:00Z",
          "updated_at": "2024-06-01T08:32:11Z"
        }
      ]
    }
  ]
}
Response — 404 Not Found 
{ "error": "artist not found" }

​
PUT /api/artists//new-releases

Enables or disables automatic new-release detection for this artist. When enabled, Crate’s scheduled scanner adds any album released after watch_new_releases_since (set to the current time when first enabled). Returns the updated boolean. Path Parameters
​
id
integer
required
Crate’s internal artist ID.
Request Body
​
enabled
boolean
required
true to enable new-release detection; false to disable it.
Example 
curl -X PUT http://localhost:6969/api/artists/1/new-releases \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
Response — 200 OK 
{ "watch_new_releases": true }

​
POST /api/artists//queue

Queues all wanted tracks for this artist across every album. Only tracks with status wanted are enqueued — owned, downloading, and ignored tracks are skipped. Returns the count of newly enqueued entries. Path Parameters
​
id
integer
required
Crate’s internal artist ID.
Example 
curl -X POST http://localhost:6969/api/artists/1/queue
Response — 200 OK 
{ "queued": 4 }
Use POST /api/downloads/queue to queue all wanted tracks across your entire library at once, rather than calling this endpoint per artist.

​
DELETE /api/artists/

Removes an artist from the library entirely. The deletion cascades: all albums and tracks belonging to the artist are deleted. Downloaded files on disk are not removed — only the database records. Path Parameters
​
id
integer
required
Crate’s internal artist ID.
Example 
curl -X DELETE http://localhost:6969/api/artists/1
Response — 204 No Content No body. A 400 is returned if the id is not a valid integer; a 500 is returned if the deletion fails.
This action is irreversible. All album and track records are deleted from the database. Re-watching the artist from the search UI will re-create everything, but your watch_new_releases preference and any manual link overrides will be lost.

​
POST /api/relink/artist/

Reassigns an artist to a different provider ID without losing any library data. This is commonly used after importing a local library: the local artist is linked to a real provider match, triggering a background discography reconciliation that folds owned files into the provider’s album/track structure and marks the gaps as wanted. Path Parameters
​
id
integer
required
Crate’s internal artist ID.
Request Body
​
provider_id
string
required
The new provider-specific artist ID to link to. The provider is always the configured primary provider.
Example 
curl -X POST http://localhost:6969/api/relink/artist/1 \
  -H "Content-Type: application/json" \
  -d '{"provider_id": "409702"}'
Response — 200 OK 
{ "status": "relinked", "reconciling": true }
​
status
string
Always "relinked" on success.
​
reconciling
boolean
true when Crate has started a background reconciliation (e.g., relinking from local to a real provider). The process runs asynchronously — poll the artist endpoint to track progress.
When relinking a local artist to a real provider, Crate fetches the full discography, matches albums by title and year and tracks by title, preserves all owned file paths, and marks any unmatched gaps as wanted. Unmatched items are flagged for manual review on the album page.

Build docs developers (and LLMs) love

Get started for freeTalk to us