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 separates two distinct ideas of search: querying a remote provider (MusicBrainz, Deezer, or a custom gRPC backend) to discover artists and albums, and querying your local library to find content you’re already watching. The browse endpoints sit in between — they fetch rich detail from a provider about a specific artist or album without adding anything to your library. Once you’ve found what you want, the watch endpoints commit it.

​
GET /api/search

Queries the active provider for artists matching the given string. By default it uses whichever provider is set as primary in Settings; pass provider to override per-request. Results are paginated with limit and offset. Query Parameters
​
q
string
required
The artist search query. Returns a 400 error if omitted.
​
provider
string
Provider name to search against (e.g. deezer, musicbrainz). Defaults to the configured primary provider.
​
limit
integer
Maximum number of results to return. Defaults to 25.
​
offset
integer
Number of results to skip for pagination. Defaults to 0.
Example 
curl "http://localhost:6969/api/search?q=Radiohead&limit=5"
Response — 200 OK 
{
  "artists": [
    {
      "id": "409702",
      "name": "Radiohead",
      "image_url": "https://cdn.example.com/radiohead.jpg",
      "album_count": 9,
      "rank": 1000000,
      "metadata": {
        "nb_fan": "3500000"
      }
    }
  ],
  "total": 1
}
​
artists
ArtistResult[]
Array of artist results from the provider.
​
total
integer
Total number of matching results available on the provider.

​
GET /api/library/search

Searches your local library — artists, albums, and tracks that are already in Crate’s database. Returns up to 50 results across all entity types. Pass an empty q and the endpoint returns an empty array rather than an error. Query Parameters
​
q
string
required
Search string matched against artist names, album titles, and track titles in the local database.
Example 
curl "http://localhost:6969/api/library/search?q=ok+computer"
Response — 200 OK Returns an array of LibrarySearchResult objects. Each result represents a matching track and carries IDs and display names for the track, its parent album, and its artist, so the UI can navigate to any level without additional requests. 
[
  {
    "artist_id": 1,
    "artist_name": "Radiohead",
    "album_id": 17,
    "album_title": "OK Computer",
    "track_id": 203,
    "track_title": "Karma Police"
  }
]
​
artist_id
integer
Crate’s internal ID for the artist.
​
artist_name
string
Display name of the artist.
​
album_id
integer
Crate’s internal ID for the album.
​
album_title
string
Title of the album.
​
track_id
integer
Crate’s internal ID for the matching track.
​
track_title
string
Title of the matching track.

​
GET /api/browse/artist/

Fetches full artist detail from the provider — including the complete album list — without modifying the local library. Also returns which albums and tracks are already watched so the UI can highlight them. The watched_album_ids field contains the provider IDs of albums already in your library. Path Parameters
​
id
string
required
Provider-specific artist ID (string). Obtained from GET /api/search.
Query Parameters
​
provider
string
Provider to query. Defaults to the configured primary.
Example 
curl "http://localhost:6969/api/browse/artist/409702"
Response — 200 OK 
{
  "id": "409702",
  "name": "Radiohead",
  "image_url": "https://cdn.example.com/radiohead.jpg",
  "metadata": { "nb_fan": "3500000" },
  "album_count": 9,
  "albums": [ ],
  "watched_album_ids": ["302127", "302128"],
  "artist_watched": true
}
​
id
string
Provider-specific artist ID.
​
name
string
Artist display name.
​
image_url
string
Artist image URL from the provider.
​
metadata
object
Arbitrary provider metadata key-value pairs.
​
album_count
integer
Total number of albums returned by the provider.
​
albums
AlbumSummary[]
Full list of albums from the provider, each with id, title, cover_url, year, and record_type.
​
watched_album_ids
string[]
Provider IDs of albums already in your Crate library.
​
artist_watched
boolean
true if this artist is in your library with watched status.

​
GET /api/browse/artist//tracks

Searches within a specific artist’s catalog on the provider. Useful for finding individual tracks before using the watch-track endpoint. Path Parameters
​
id
string
required
Provider-specific artist ID.
Query Parameters
​
q
string
required
Search query to match against the artist’s tracks. Returns an empty { "tracks": [] } if omitted.
​
provider
string
Provider to query. Defaults to the configured primary.
Example 
curl "http://localhost:6969/api/browse/artist/409702/tracks?q=karma+police"
Response — 200 OK 
{
  "tracks": [
    {
      "id": "3135556",
      "title": "Karma Police",
      "track_number": 6,
      "disc_number": 1,
      "duration_ms": 263000,
      "album_id": "302127",
      "album_title": "OK Computer"
    }
  ]
}

​
GET /api/browse/album/

Fetches full album detail from the provider, including the complete track list. Also returns which tracks from this album are already in your library (watched_track_ids) and whether the entire album is considered watched. Path Parameters
​
id
string
required
Provider-specific album ID (string). Obtain from GET /api/browse/artist/{id} album list.
Query Parameters
​
provider
string
Provider to query. Defaults to the configured primary.
Example 
curl "http://localhost:6969/api/browse/album/302127"
Response — 200 OK 
{
  "id": "302127",
  "title": "OK Computer",
  "artist_name": "Radiohead",
  "year": 1997,
  "cover_url": "https://cdn.example.com/okcomputer.jpg",
  "tracks": [
    {
      "id": "3135551",
      "title": "Airbag",
      "track_number": 1,
      "disc_number": 1,
      "duration_ms": 292000
    }
  ],
  "metadata": {},
  "album_watched": false,
  "watched_track_ids": [],
  "library_id": null
}
​
id
string
Provider-specific album ID.
​
title
string
Album title.
​
artist_name
string
Display name of the album artist.
​
year
integer
Release year. May be 0 if unknown.
​
cover_url
string
URL to album artwork from the provider.
​
tracks
TrackSummary[]
Complete ordered track list with id, title, track_number, disc_number, and duration_ms.
​
metadata
object
Arbitrary provider metadata.
​
album_watched
boolean
true if every track on this album is already in your library.
​
watched_track_ids
string[]
Provider IDs of individual tracks already in your Crate library.
​
library_id
integer | null
The Crate internal album ID if this album is already in the library, otherwise null.

​
Watch Endpoints

The watch endpoints add a provider entity into your Crate library. All three accept an optional provider field in the request body to specify which provider to use; if omitted, the configured primary is used.
Watch endpoints return 201 Created for new entities and 200 OK if the entity already exists in your library.

​
POST /api/watch/artist/

Watches a full artist discography. All albums are fetched from the provider and saved with status watched; all tracks are created as wanted and enqueued for download in the background. Pass watch_new_releases: true to automatically add albums released after this moment.
​
id
string
required
Provider-specific artist ID.
Request Body 
{
  "watch_new_releases": true,
  "provider": "deezer"
}
Example 
curl -X POST http://localhost:6969/api/watch/artist/409702 \
  -H "Content-Type: application/json" \
  -d '{"watch_new_releases": true}'
Response — 201 Created Returns the newly created Artist object (see Artists API for the full model).

​
POST /api/watch/album/

Watches a single album. If the album’s artist is not yet in the library, a partial artist entry is created automatically. Tracks are created as wanted.
​
id
string
required
Provider-specific album ID.
Request Body 
{
  "artist_provider_id": "409702",
  "artist_name": "Radiohead",
  "artist_image_url": "https://cdn.example.com/radiohead.jpg",
  "provider": "deezer"
}
Example 
curl -X POST http://localhost:6969/api/watch/album/302127 \
  -H "Content-Type: application/json" \
  -d '{
    "artist_provider_id": "409702",
    "artist_name": "Radiohead",
    "artist_image_url": ""
  }'
Response — 201 Created Returns the newly created Album object.

​
POST /api/watch/track/

Watches a single track. Creates minimal artist and album stubs if they don’t already exist in the library. The track is created with status wanted.
​
id
string
required
Provider-specific track ID.
Request Body 
{
  "artist_provider_id": "409702",
  "artist_name": "Radiohead",
  "artist_image_url": "",
  "album_provider_id": "302127",
  "album_title": "OK Computer",
  "album_cover_url": "",
  "album_year": 1997,
  "title": "Karma Police",
  "track_number": 6,
  "disc_number": 1,
  "duration_ms": 263000,
  "provider": "deezer"
}
Example 
curl -X POST http://localhost:6969/api/watch/track/3135556 \
  -H "Content-Type: application/json" \
  -d '{
    "artist_provider_id": "409702",
    "artist_name": "Radiohead",
    "artist_image_url": "",
    "album_provider_id": "302127",
    "album_title": "OK Computer",
    "album_year": 1997,
    "title": "Karma Police",
    "track_number": 6,
    "disc_number": 1,
    "duration_ms": 263000
  }'
Response — 201 Created Returns the newly created Track object.
When watching individual tracks or albums from a browse result, pass the artist_provider_id, album_provider_id, and related name/image fields from the browse response body. Crate uses these to build or locate the parent stubs without making additional provider calls.

​
Library Import

These endpoints drive the built-in library importer, which reads embedded tags from MP3 and FLAC files on disk and creates the corresponding artist, album, and track records in Crate. The importer never modifies any audio files.

​
POST /api/library/import

Starts an import run. Only one import can run at a time; sending a second request while one is already running returns 409 Conflict. Pass dry_run: true to preview what would be imported without writing anything to the database. Request body (optional)
​
path
string
Absolute path to a directory to scan. Defaults to the configured library path when omitted.
​
dry_run
boolean
When true, the importer scans and reports results without making any database changes. Defaults to false.
Response — 202 Accepted Returns the initial ImportState object (see GET /api/library/import below for the full shape). Poll that endpoint to track progress. 
# Start a full import
curl -X POST http://localhost:6969/api/library/import

# Start a dry run against a specific path
curl -X POST http://localhost:6969/api/library/import \
  -H "Content-Type: application/json" \
  -d '{"path": "/mnt/music", "dry_run": true}'

​
GET /api/library/import

Returns the current state of the importer. Poll this endpoint while status is "running" to track progress. Response — 200 OK
​
status
string
Current importer state: "idle" (not yet started), "running" (scan in progress), "done" (finished successfully), or "failed" (encountered a fatal error).
​
dry_run
boolean
Whether this run was a dry run.
​
path
string
The directory path that was (or is being) scanned. Omitted when idle.
​
started_at
string
RFC 3339 timestamp when the import started. Omitted when idle.
​
processed
integer
Number of files processed so far.
​
total
integer
Total number of files to process.
​
report
object
Populated when status is "done" or "failed". Contains a summary of what the import did.
​
error
string
Error message when status is "failed". Omitted otherwise.
curl http://localhost:6969/api/library/import
Example response (running) 
{
  "status": "running",
  "dry_run": false,
  "path": "/mnt/music",
  "started_at": "2024-06-01T10:00:00Z",
  "processed": 312,
  "total": 1480
}
Example response (done) 
{
  "status": "done",
  "dry_run": false,
  "path": "/mnt/music",
  "started_at": "2024-06-01T10:00:00Z",
  "processed": 1480,
  "total": 1480,
  "report": {
    "artists_added": 12,
    "albums_added": 47,
    "tracks_added": 1382,
    "tracks_claimed": 94,
    "tracks_known": 4,
    "musicbrainz_linked": 901,
    "duplicate_files": 0,
    "files_skipped": 2,
    "skipped_samples": [
      { "path": "/mnt/music/unknown/track.wav", "reason": "unsupported format" }
    ]
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us