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 Albums API lets you work with individual album records in your Crate library. Albums are created automatically when you watch an artist or watch a standalone album via the browse/watch flow. Every album carries a status — watched, owned, or ignored — and a nested list of tracks. Use these endpoints to inspect content, trigger downloads, suppress unwanted releases, and clean up the library.

​
The Album Object

​
id
integer
Crate’s internal auto-increment album ID. Use this for all /api/albums/{id} calls.
​
artist_id
integer
Internal ID of the parent artist.
​
title
string
Album title as recorded by the provider.
​
year
integer | null
Release year. Omitted from JSON when unknown.
​
provider
string
The provider this album is linked to (e.g. deezer, musicbrainz, local).
​
provider_id
string
Provider-specific album ID.
​
cover_url
string | null
Album artwork URL from the provider. Omitted when null.
​
record_type
string
Release type as reported by the provider (e.g. album, single, ep).
​
status
string
One of watched (tracks queued for download), owned (all tracks on disk), or ignored (excluded from download queuing).
​
created_at
string
RFC 3339 timestamp when this album was added to the library.
​
updated_at
string
RFC 3339 timestamp of the most recent change.
​
artist_name
string
Denormalized artist name for display. Omitted in list contexts.
​
tracks
Track[]
Populated by GET /api/albums/{id}. See the Track Object below.

​
The Track Object

​
id
integer
Crate’s internal track ID.
​
album_id
integer
Internal ID of the parent album.
​
title
string
Track title.
​
track_number
integer
Position within the disc.
​
disc_number
integer
Disc number (1 for single-disc releases).
​
duration_ms
integer
Track duration in milliseconds.
​
provider
string
Provider this track is linked to.
​
provider_id
string
Provider-specific track ID.
​
status
string
One of wanted (not yet downloaded), downloading (active transfer), owned (file on disk), or ignored (excluded from download queuing).
​
file_path
string | null
Relative path within the library directory, e.g. Radiohead/OK Computer (1997)/01 - Airbag.flac. Present only when status is owned.
​
downloaded_from
string | null
Soulseek username the file was downloaded from. Omitted when null.
​
download_format
string | null
File format as detected at download time (e.g. flac, mp3).
​
download_bitrate
integer | null
Bitrate in kbps as detected at download time.
​
created_at
string
RFC 3339 creation timestamp.
​
updated_at
string
RFC 3339 last-modified timestamp.

​
GET /api/albums/

Returns a single album by Crate’s internal ID with the complete tracks[] array nested. Path Parameters
​
id
integer
required
Crate’s internal album ID. Obtain from GET /api/artists/{id} or from a watch/browse response.
Example 
curl http://localhost:6969/api/albums/17
Response — 200 OK 
{
  "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",
  "artist_name": "Radiohead",
  "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",
      "downloaded_from": "some_user",
      "download_format": "flac",
      "download_bitrate": 900,
      "created_at": "2024-01-15T10:05:00Z",
      "updated_at": "2024-06-01T08:32:11Z"
    },
    {
      "id": 204,
      "album_id": 17,
      "title": "Paranoid Android",
      "track_number": 2,
      "disc_number": 1,
      "duration_ms": 383000,
      "provider": "deezer",
      "provider_id": "3135552",
      "status": "wanted",
      "created_at": "2024-01-15T10:05:00Z",
      "updated_at": "2024-01-15T10:05:00Z"
    }
  ]
}
Response — 404 Not Found 
{ "error": "album not found" }

​
POST /api/albums//queue

Enqueues all wanted tracks in this album for download. Tracks with status owned, downloading, or ignored are not touched. Returns the count of newly created queue entries. Path Parameters
​
id
integer
required
Crate’s internal album ID.
Example 
curl -X POST http://localhost:6969/api/albums/17/queue
Response — 200 OK 
{ "queued": 3 }
If the album has no wanted tracks (everything is owned or ignored), the response is { "queued": 0 } — not an error.

​
POST /api/albums//link

Merges a local-provider album into another album by the same artist that is already linked to a real provider. This is used after importing local files: when automatic reconciliation cannot match a local album, you can manually point it at the correct provider album. Each owned local track is matched to a wanted provider track by title (disc/track number as a tiebreak); tracks with no provider match are moved over as-is; the now-empty local album record is deleted. Path Parameters
​
id
integer
required
Crate’s internal album ID of the local album to merge away.
Request Body
​
target_album_id
integer
required
The Crate internal album ID of the target (provider-linked) album to merge into. Must be another album by the same artist and must not be a local-provider album.
Example 
curl -X POST http://localhost:6969/api/albums/5/link \
  -H "Content-Type: application/json" \
  -d '{"target_album_id": 17}'
Response — 200 OK 
{ "status": "linked", "merged_into": 17 }
​
status
string
Always "linked" on success.
​
merged_into
integer
The Crate internal album ID of the target album that the local album was merged into.

​
PUT /api/albums//ignore

Marks the album as ignored. All tracks currently in wanted status are cascaded to ignored as well. Tracks that are already owned or downloading are not changed, preserving files already on disk. Useful for suppressing live albums, compilations, or re-releases you don’t want in your library. Path Parameters
​
id
integer
required
Crate’s internal album ID.
Example 
curl -X PUT http://localhost:6969/api/albums/17/ignore
Response — 200 OK 
{ "status": "ignored" }

​
DELETE /api/albums//ignore

Removes the ignored status from an album, restoring it to watched. All tracks that were previously cascaded to ignored by this album’s ignore action are restored to wanted. Tracks that are owned or downloading are untouched. Path Parameters
​
id
integer
required
Crate’s internal album ID.
Example 
curl -X DELETE http://localhost:6969/api/albums/17/ignore
Response — 200 OK 
{ "status": "watched" }
After unignoring, you’ll typically want to call POST /api/albums/{id}/queue to immediately enqueue the restored wanted tracks.

​
DELETE /api/albums/

Removes an album and all its tracks from the library. The deletion cascades to all track records. Files on disk are not removed. The parent artist record is preserved even if this was the last album — delete the artist separately if needed. Path Parameters
​
id
integer
required
Crate’s internal album ID.
Example 
curl -X DELETE http://localhost:6969/api/albums/17
Response — 204 No Content No body on success.
This action is irreversible. All track records for this album are deleted. If you re-watch the album later (via POST /api/watch/album/{id}), all tracks will start over with wanted status, even if files were already on disk.

​
POST /api/relink/album/

Reassigns an album to a different provider ID, using the configured primary provider. If the album has locally-imported tracks, a background reconciliation is triggered to match them to the provider’s track list, preserving owned file paths and marking gaps as wanted. Path Parameters
​
id
integer
required
Crate’s internal album ID.
Request Body
​
provider_id
string
required
The new provider-specific album ID. The active primary provider is used automatically.
Example 
curl -X POST http://localhost:6969/api/relink/album/17 \
  -H "Content-Type: application/json" \
  -d '{"provider_id": "302127"}'
Response — 200 OK 
{ "status": "relinked", "reconciling": true }
​
status
string
Always "relinked" on success.
​
reconciling
boolean
true when a background track reconciliation was triggered because the album contains local tracks. false for a plain provider re-stamp with no local tracks to reconcile.

Build docs developers (and LLMs) love

Get started for freeTalk to us