Crate Settings API — Get, Update, and Preview Naming

Crate’s runtime configuration is stored as key-value pairs in the settings table of crate.db and is fully manageable via the API. Most settings can also be changed from the Settings UI; the API is useful for scripting configuration changes or integrating Crate into a larger automation setup. A companion endpoint renders a live naming-template preview using sample metadata so you can validate a template string before saving it.

Some keys are hidden — they can be set via environment variables at startup but are never returned by GET /api/settings and are silently ignored by PUT /api/settings. Hidden keys are: slskd_url, slskd_api_key, library_path, scan_interval, download_format_preference, and min_bitrate. Configure these via environment variables (CRATE_SLSKD_URL, CRATE_SLSKD_API_KEY, CRATE_LIBRARY_PATH, CRATE_SCAN_INTERVAL) or from the Settings UI.Sensitive keys (navidrome_password, music_assistant_token) are returned as "••••••••" in GET responses. Sending that redacted placeholder back in a PUT is a no-op — the stored value is left unchanged.

GET /api/settings/

Returns all non-hidden settings as a flat JSON object mapping string keys to string values. Response — object with string keys and string values

provider_primary

string

The name of the active default provider used for searches and browse operations (e.g. "musicbrainz" or "deezer").

cache_ttl_hours

string

How long provider API responses are cached, in hours (e.g. "24").

quality_tiers

string

A JSON-encoded array of QualityTier objects, each with format (string), min_bitrate (integer, 0 for lossless), and label (string). Tiers are evaluated in order — the first matching tier wins.

upgrade_last_artist_id

string

Internal cursor used by the upgrade scanner. Stores the ID of the last artist scanned for quality upgrades. You can reset it to "0" to restart the upgrade sweep from the beginning.

navidrome_url

string

Base URL for the Navidrome instance (e.g. "http://navidrome:4533"). Leave blank to disable the Navidrome integration.

navidrome_user

string

Navidrome username used to authenticate the library rescan trigger.

navidrome_password

string

Always returned as "••••••••". Send the actual password in PUT to update it.

activity_retention_days

string

How many days to keep entries in the activity log before they are purged (e.g. "30").

naming_template

string

The folder/file layout template for organizing downloaded files. Empty string means the default ({artist}/{album} ({year})/{track:2} - {title}). See naming tokens below.

shadow_ban_duration

string

How long a user is temporarily blocked (shadow-banned) after going offline mid-transfer or stalling in queue. Expressed as a Go duration string, e.g. "60m" (default). See Blocked Sources for more detail.

negative_keywords

string

Comma-separated list of keywords that cause a file to be skipped during auto-download scoring (e.g. "acapella,instrumental,karaoke"). Manual search still shows matching files.

curl http://localhost:6969/api/settings/

Example response

{
  "provider_primary": "musicbrainz",
  "cache_ttl_hours": "24",
  "quality_tiers": "[{\"format\":\"flac\",\"min_bitrate\":0,\"label\":\"FLAC\"},{\"format\":\"mp3\",\"min_bitrate\":320,\"label\":\"MP3 320\"}]",
  "navidrome_url": "http://navidrome:4533",
  "navidrome_user": "admin",
  "navidrome_password": "••••••••",
  "activity_retention_days": "30",
  "naming_template": "{artist}/{album} ({year})/{track:2} - {title}",
  "shadow_ban_duration": "60m",
  "negative_keywords": "acapella,instrumental",
  "upgrade_last_artist_id": "0"
}

PUT /api/settings/

Updates one or more settings. Send a partial JSON object — only the keys you include are updated; all others are left as-is. Hidden keys are silently ignored. The naming template is validated before any values are saved, so a bad template string will return a 400 without writing anything.

provider_primary

string

Switch the active provider (e.g. "deezer").

cache_ttl_hours

string

New cache TTL in hours.

quality_tiers

string

JSON-encoded array of QualityTier objects. Each object must have a format string and optional min_bitrate integer and label string.

navidrome_url

string

Navidrome base URL, or empty string to disable the integration.

navidrome_user

string

Navidrome username.

navidrome_password

string

Navidrome password. Sending "••••••••" (the redacted placeholder) is a no-op.

activity_retention_days

string

Number of days to retain activity log entries.

naming_template

string

New naming template. Must use only recognized tokens. Validated before saving; returns 400 if invalid.

shadow_ban_duration

string

Go duration string for how long users are shadow-banned (e.g. "30m", "2h").

negative_keywords

string

Comma-separated keywords to filter out during auto-download.

Response — the submitted settings object (echoed back as sent).

curl -X PUT http://localhost:6969/api/settings/ \
  -H "Content-Type: application/json" \
  -d '{
    "quality_tiers": "[{\"format\":\"flac\",\"min_bitrate\":0,\"label\":\"FLAC\"},{\"format\":\"mp3\",\"min_bitrate\":320,\"label\":\"MP3 320\"},{\"format\":\"mp3\",\"min_bitrate\":256,\"label\":\"MP3 256\"}]",
    "naming_template": "{artist}/{album} ({year})/{disc}-{track:2} - {title}",
    "shadow_ban_duration": "30m"
  }'

GET /api/settings/naming-preview

Validates a naming template and renders it using a fixed set of sample metadata so you can see exactly what the resulting path will look like. The sample data used is:

Field	Sample value
Artist	Radiohead
Album	OK Computer
Year	1997
Disc	1
Track	6
Title	Karma Police

If the template is invalid, the endpoint returns 400 with an error message describing the problem. If the template query parameter is omitted or blank, the default template is used.

template

string

The naming template string to preview. Uses the same token syntax as the naming_template setting.

Response

path

string

The rendered file path including the .flac extension appended automatically, e.g. "Radiohead/OK Computer (1997)/06 - Karma Police.flac".

# Preview the default template
curl "http://localhost:6969/api/settings/naming-preview"

# Preview a custom template
curl -G http://localhost:6969/api/settings/naming-preview \
  --data-urlencode "template={artist}/{album} ({year})/{disc}-{track:2} - {title}"

Example response

{
  "path": "Radiohead/OK Computer (1997)/1-06 - Karma Police.flac"
}

Naming tokens

The following tokens are recognized in naming templates:

Token	Meaning
`{artist}` / `{albumartist}`	Artist name (identical in Crate — tracks are always album-artist-based)
`{album}`	Album title
`{year}`	Album release year; renders empty and cleans up surrounding decoration when unknown
`{track}`	Track number; zero-pad with a width specifier, e.g. `{track:2}` → `06`
`{disc}`	Disc number; supports padding; renders empty when unknown
`{title}`	Track title

When an empty token leaves dangling decoration — for example {album} ({year}) when the year is unknown — Crate removes the now-empty parentheses automatically, producing Album Title rather than Album Title ().

GET /api/providers

Returns the list of all configured provider plugins with their name, display name, version, and current health status. The name field is what you use as the value for provider_primary in settings. Response — array of provider objects

name

string

Internal provider name (e.g. "musicbrainz", "deezer"). Used in settings and entity provider fields.

display_name

string

Human-readable label shown in the UI.

version

string

Version string reported by the provider plugin.

healthy

boolean

true if the provider gRPC connection is up and responding. Artists and albums whose provider is unhealthy are shown as “orphaned” in the library.

curl http://localhost:6969/api/providers

Example response

[
  {
    "name": "musicbrainz",
    "display_name": "MusicBrainz",
    "version": "1.0.0",
    "healthy": true
  },
  {
    "name": "deezer",
    "display_name": "Deezer",
    "version": "1.0.0",
    "healthy": true
  }
]

Overview

Endpoints

Crate Settings API — Get, Update, and Preview Naming

GET /api/settings/

PUT /api/settings/

GET /api/settings/naming-preview

Naming tokens

GET /api/providers

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/settings/

​PUT /api/settings/

​GET /api/settings/naming-preview

​Naming tokens

​GET /api/providers

Build docs developers (and LLMs) love

GET /api/settings/

PUT /api/settings/

GET /api/settings/naming-preview

Naming tokens

GET /api/providers