# API Reference

This reference covers v1.18.0; consult the [changelog](../CHANGELOG.md) for release changes. Unversioned `/api/*` routes have been removed; use `/api/v1/*`.

All endpoints require either a `digarr_session` cookie or an
`Authorization: Bearer <token>` header unless marked as public. Bearer sessions
remain the compatibility path for non-browser API clients. Only
`/api/v1/pipeline/events` and `/api/v1/preview/audio` also accept
`?token=<token>` for SSE and `<audio>` clients that cannot send headers.

Cookie- or proxy-authenticated `POST`, `PUT`, `PATCH`, and `DELETE` requests
must send `X-Digarr-CSRF: 1` plus exact same-origin browser evidence. The
bundled UI handles this automatically. Verified bearer requests do not require
the CSRF header. Browser-shaped public mutations, including login and
registration, also require the header; non-browser requests without browser
origin signals remain compatible. OpenAPI expresses protected mutations as
`sessionCookie` + `csrfHeader`, or `bearerToken`. Set `ALLOWED_ORIGIN` to the
exact public origin when a reverse proxy or TLS terminator changes the scheme
or host seen by the application; the value controls CSRF origin checks and the
OIDC callback URL. Production session and OIDC cookies default to `Secure` even
when the backend request arrives over HTTP behind a TLS terminator; a
production instance served directly over plain HTTP must set
`DIGARR_ALLOW_INSECURE_COOKIES=true` (with a matching `http://` `ALLOWED_ORIGIN`)
and is vulnerable to network interception. See
[Authentication](AUTHENTICATION.md#cookie-secure-policy).

Locale-aware routes accept `X-Digarr-Locale` to override the saved user locale for that request. If the header is absent, Digarr falls back to the saved user preference and then `Accept-Language`.

Admin-only endpoints return 403 for non-admin users.

---

## Pagination Shapes

Digarr uses three pagination styles depending on the route's compatibility history.

Shared cursor pagination is opt-in: callers that omit both `limit` and `cursor` receive the legacy array response, while callers that send either parameter receive:

```json
{
  "data": [],
  "meta": {
    "limit": 50,
    "nextCursor": null
  }
}
```

Routes using this shared cursor shape:
- `GET /api/v1/subscriptions`
- `GET /api/v1/targets`
- `GET /api/v1/batches`
- `GET /api/v1/users`
- `GET /api/v1/playlists`
- `GET /api/v1/analytics/batches`

For these routes, non-integer `limit` values return `400`. `meta.nextCursor` is an opaque string when another page exists and `null` when the page is exhausted.

`GET /api/v1/artist-blocks` uses a route-specific cursor shape:

```json
{
  "items": [],
  "nextCursor": null
}
```

Offset-paginated routes:
- `GET /api/v1/recommendations` returns `{ "items": [], "total": 0 }` and accepts `limit` plus `offset`
- `GET /api/v1/jobs` returns `{ "items": [], "total": 0 }` and accepts `limit` plus `offset`
- `GET /api/v1/listening/top-artists` returns `{ "tracks": [], "total": 0, "offset": 0, "limit": 5, "source": null, "status": "not_configured" }`

---

## API Metadata

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/docs` | No | Minimal HTML entry point for API documentation |
| GET | `/api/v1/docs/openapi.json` | No | OpenAPI 3.1 document with shared schemas plus selected stable route groups |

OpenAPI coverage currently includes auth status/login/register/session
migration, recommendations, artist blocks, jobs, library reconciliation lists
and bulk ignore, and settings service probes. The Markdown reference remains
the complete route inventory.

---

## Auth

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/v1/auth/register` | No | Create account. First user becomes admin. Rate limited: 5/min |
| POST | `/api/v1/auth/login` | No | Login with username/password. Rate limited: 10/min |
| POST | `/api/v1/auth/session/migrate` | Bearer session | Atomically replace an active bearer session with an HttpOnly cookie session |
| POST | `/api/v1/auth/logout` | Yes | Invalidate current session |
| GET | `/api/v1/auth/status` | No | Login-screen auth requirement and OIDC availability |
| GET | `/api/v1/auth/meta` | Yes | Deployment metadata: version and enabled auth integrations |
| GET | `/api/v1/auth/me` | Yes | Current user profile |
| GET | `/api/v1/auth/validate` | Yes | Lightweight token/session validity check. Returns `204` when valid |
| PATCH | `/api/v1/auth/me/locale` | Yes | Update the saved user locale. Session auth only. |
| PATCH | `/api/v1/auth/me/email` | Yes | Set or clear the user's email. Session auth only. |
| POST | `/api/v1/auth/change-password` | Yes | Change password. Invalidates all sessions. Rate limited: 5/min |
| GET | `/api/v1/auth/me/preferences` | Yes | Get merged user preferences |
| PATCH | `/api/v1/auth/me/preferences` | Yes | Update user preferences (partial merge). Session auth only. |

**PATCH /api/v1/auth/me/locale** body:
```json
{ "preferredLocale": "fr" }
```

**PATCH /api/v1/auth/me/email** body:
```json
{ "email": "you@example.com" }
```

Notes:
- Login and registration return `{ user, token }` for API clients by default.
  Send `X-Digarr-Auth-Mode: cookie` to receive an HttpOnly session cookie and a
  `{ user }` response without the raw token.
- Registration returns `201`; closed registration returns `403`, an existing
  username returns `409`, and the sixth request from one source within a minute
  returns `429`.
- `POST /api/v1/auth/session/migrate` accepts only an active per-user session
  bearer. It returns `204` after rotating that bearer into a cookie, `403` for
  the deprecated shared token or another auth method, and `409` when the source
  session was already replaced.
- An `Authorization` header suppresses cookie fallback, including when the
  header is malformed or its token is invalid.
- Password changes invalidate every session for the user. Cookie callers
  receive a replacement cookie and `204`; bearer callers receive
  `{ "token": "..." }` for the replacement session. The password verification
  and session replacement run in one atomic transaction under a user-row lock,
  so a password verified before a concurrent reset cannot mint a post-reset
  session.
- `preferredLocale` may be a supported locale string or `null`
- Supported locales: `en`, `es`, `fr`, `de`, `pt-BR`, `it`, `nl`, `ro`, `pl`, `tr`, `uk`, `ru`, `ja`, `ko`, `zh-CN`
- `email` may be a valid address, an empty string, or `null`; empty/null clears it
- A non-empty `email` must be unique across users; a collision returns `409`
  (`code: errors.auth.emailTaken`). Digarr does not auto-link OIDC identities by
  email; see [OIDC account matching](AUTHENTICATION.md#oidc-account-matching)
- Legacy token auth is rejected with `403`; this route requires a session-authenticated user
- `POST /api/v1/auth/change-password` also rejects legacy token auth with `403`; password changes require a session-authenticated user
- `PATCH /api/v1/auth/me/preferences` also rejects legacy token auth with `403`; preference writes require a session-authenticated user
- `GET /api/v1/auth/status` returns `required: true` as soon as setup is complete, even if no users exist yet, so the frontend can force registration/login instead of treating the app as public

### OIDC / OAuth

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/auth/oidc/login` | No | Redirect to OIDC provider. Requires `ALLOWED_ORIGIN` env var. Sets a browser-bound, one-time, 10-min `HttpOnly` transaction cookie. Rate limited: 10/min |
| POST | `/api/v1/auth/oidc/link` | Cookie session | Start account linking after current-password verification. Returns `{ url }`. Requires CSRF protection and an unlinked local account. Rate limited: 5/min |
| GET | `/api/v1/auth/oidc/callback` | Transaction-bound | OIDC callback; consumes the browser-bound transaction once. Login creates the user if needed and sets a session cookie. Linking also requires the initiating session and updates only its account's OIDC subject. Not rate limited |
| POST | `/api/v1/auth/oauth/:provider/initiate` | Yes | Start OAuth flow (`spotify`, `deezer`, `tidal`). Sets a browser-bound, 10-min `HttpOnly` transaction cookie scoped to the provider's callback path. Rate limited: 5/min |
| GET | `/api/v1/auth/oauth/:provider/callback` | No | OAuth callback; requires the transaction cookie from initiate. The pending authorization is consumed on read, so a `state` works exactly once. Not rate limited |
| GET | `/api/v1/auth/oauth/:provider/status` | Yes | Check OAuth connection status |
| DELETE | `/api/v1/auth/oauth/:provider` | Yes | Disconnect OAuth provider |

**POST /api/v1/auth/oidc/link** body:

```json
{ "currentPassword": "your-current-password" }
```

The authorization URL uses the existing registered OIDC callback. Linking
returns to `/settings?tab=account` with `oidc_link=success`, `identity_in_use`,
or `failed`. It does not create a session, merge accounts, or match by email.
Logging out or changing the password before the callback invalidates the
attempt. See [Authentication](AUTHENTICATION.md#oidc-account-matching).

**POST /api/v1/auth/oauth/:provider/initiate** notes:
- For `tidal`, the body `clientId` / `clientSecret` are ignored: the server reads the one admin-registered TIDAL app from settings, so the bundled UI sends empty strings. Returns `400` with `TIDAL app credentials are not configured on the server` when no admin app is registered.
- For `tidal`, the body `redirectUri` is ignored whenever `ALLOWED_ORIGIN` is set; the server pins the callback to `${ALLOWED_ORIGIN}/api/v1/auth/oauth/tidal/callback`. With `ALLOWED_ORIGIN` unset, the client-supplied value is accepted only outside production and only for a loopback host; production returns `400 ALLOWED_ORIGIN must be set to connect TIDAL`. The registered URI at TIDAL must match whichever value applies.
- In-flight authorizations live in their own table, so calling initiate on an already-connected provider no longer disturbs the stored token: an abandoned re-connect leaves the existing connection intact. Starting a new flow discards the previous unfinished one for the same user and provider.
- Only digests of the `state` and of the browser binding are persisted, and the row expires after 10 minutes.

**GET /api/v1/auth/oauth/:provider/callback** redirects to `/settings` with either `oauth_success=<provider>` or `oauth_error=<stage>`. The settings page renders both as a dismissible banner and then strips the parameter from the URL. Stages:

| `oauth_error` | Meaning |
|---------------|---------|
| *(provider value)* | The provider returned an `error` query param; passed through verbatim |
| `missing_code_or_state` | The provider redirected without `code` or `state` |
| `no_pending_auth` | No pending authorization matches the `state` (never initiated, already consumed, or superseded by a newer flow) |
| `state_expired` | The pending authorization matched but is older than its 10-minute TTL |
| `browser_mismatch` | The transaction cookie is missing or does not match the browser that started the flow |
| `missing_credentials` | The stored client ID/secret for the provider are gone |
| `token_exchange_unreachable` | The token request threw before a response (DNS, TLS, reset, or the 10s timeout) |
| `token_exchange_failed` | The token endpoint answered non-2xx. The upstream error body is logged, truncated to 300 chars |
| `token_exchange_malformed` | The token endpoint answered 2xx with a non-JSON body. Not reachable for Deezer, which is allowed to answer form-encoded |
| `token_exchange_no_token` | The token endpoint answered 2xx but the body carried no `access_token` |
| `unknown_provider` | The `:provider` path segment is not a supported provider |

Treat these as untrusted when rendering: the pass-through case is provider-controlled. The settings banner maps only the known stages above to their own message; anything else renders a generic failure message with the raw value echoed back as inert, sanitized, length-capped text.

---

## Setup

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/setup/status` | No | Check if setup is complete |
| POST | `/api/v1/setup/complete` | No | Complete initial setup |

Setup validation rules:
- `aiProvider` and `aiModel` are required
- Lidarr is optional, but `lidarrUrl` and `lidarrApiKey` must be provided together when used
- Emby is optional, but `embyUrl`, `embyApiKey`, and `embyUserId` must be provided together when used
- When Lidarr is provided during setup, Digarr auto-creates the default Lidarr target for the first user
- When Emby is provided during setup, Digarr stores the per-user Emby connection and auto-creates an Emby playlist target
- Completing setup does not create a user account. If setup finishes before any user exists, the next step is to register or sign in; protected routes stay locked until then

**POST /api/v1/setup/complete** body:
```json
{
  "aiProvider": "openai",
  "aiModel": "gpt-4o-mini",
  "lidarrUrl": "http://lidarr:8686",
  "lidarrApiKey": "abc123",
  "embyUrl": "http://emby:8096",
  "embyApiKey": "abc123",
  "embyUserId": "user-1",
  "skipTlsVerify": false
}
```

---

## Pipeline

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/v1/pipeline/run` | Yes | Start a full discovery scan, or queue it behind an in-flight run. Returns 202 with `{ queued, position }`. |
| POST | `/api/v1/pipeline/cancel` | Yes | Stop the in-flight run and drop the queue. Returns 202 with `{ cancelled }` (`false` when nothing was running). |
| GET | `/api/v1/pipeline/status` | Yes | Current pipeline status (running, stage, last run, `queueLength`, caller `queuePosition`) |
| GET | `/api/v1/pipeline/events` | Yes | SSE stream of pipeline progress events |
| POST | `/api/v1/pipeline/quick-discover` | Yes | Fire-and-forget: discover artists similar to a given name. Rate limited: 5/min |
| POST | `/api/v1/pipeline/rescan` | Admin | Re-fetch images/metadata for up to 200 existing recommendations. Deduplicates artists, safely reuses shared-provider misses for seven days, and returns `{ attempted, updated, failed, total }` (`total` is a compatibility alias for `attempted`). Rate limited to 2/min; concurrent rescans return 409. |

`POST /api/v1/pipeline/run` is intentionally available to any authenticated
user: "Run Scan" is a core regular-user action on the dashboard and discover
screens. The orchestrator is single-flight (one run at a time, shared API/RAM
budgets), but a run requested while one is active is **queued FIFO**, not
rejected: the response is still 202 with `queued: true` and the caller's 1-based
`position`. A given user is deduped (a double-click does not stack two runs).
The queue drains automatically when the active run finishes. The queue is
in-memory and per-process.

`POST /api/v1/pipeline/cancel` stops a wedged or unwanted scan without a
restart. It is available to any authenticated user (symmetric with "Run Scan":
single-flight means one run total). Cancellation is cooperative -- the run
checks an abort signal at every stage boundary and inside artist resolution, so
a stop lands within about one request timeout. The queue is cleared so nothing
starts behind the stopped run, the job is recorded with status `cancelled`, and
a terminal `cancelled` progress event closes the SSE stream. A run that ignores
the signal is force-reset after a short grace window so the app is never left
permanently "running".

`POST /api/v1/pipeline/rescan` is admin-only because it writes shared artist
metadata using the requesting admin's configured providers. It runs one rescan
at a time and processes artists sequentially, bounding upstream concurrency and
preventing overlapping calls from multiplying shared provider traffic.

The rescan image policy matches normal discovery: TheAudioDB runs first. On a
miss, the configured Lidarr/SkyHook, fanart.tv, and musicinfo.pro fallbacks run
concurrently; results still prefer Lidarr, then fanart.tv, then musicinfo.pro.
A failed fallback does not stop the remaining image providers or the independent
MusicBrainz disambiguation refresh. Complete misses from the globally shared
AudioDB/Lidarr configuration refresh the seven-day negative cache so repeated
rescans do not immediately repeat the same work. User-scoped fanart.tv or
musicinfo.pro configurations bypass that shared cache, and transient or
rate-limited lookups are not cached as misses.

**POST /api/v1/pipeline/quick-discover** body:
```json
{ "artistName": "Radiohead" }
```

Locale notes:
- `POST /api/v1/pipeline/run` and `POST /api/v1/pipeline/quick-discover` honor `X-Digarr-Locale`
- For authenticated users, the explicit request locale wins over the saved user locale for that request
- AI responses follow the resolved UI locale; prompt-language detection is handled separately for freeform inputs

---

## Discovery Modes

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/discovery-modes` | Yes | List discovery modes with current availability, fallback, and field metadata |
| POST | `/api/v1/discovery-modes/run` | Yes | Start a manual discovery-mode run. Returns 202 with a `jobId`, but no batch ID. |

**GET /api/v1/discovery-modes** notes:
- Always returns the shipped discovery-mode catalog, including modes that are visible but currently unavailable
- In the web UI, these modes are exposed from Discover -> Discovery Modes
- Each mode includes `availability.enabled`, `availability.fallbackUsed`, `availability.providerPath`, and an optional `availability.reason`
- Each mode also includes a `stability` field (`stable` or `experimental`), mirroring the search-source field. `tidal-favorite-artists` is `experimental`: live-account validation of TIDAL connect, token refresh, and populated favorite-artist results is deferred. Clients should badge experimental modes rather than hide them. See [TIDAL feedback](../README.md#tidal-feedback) for safe community reports.
- Unavailable modes stay visible for roadmap transparency, should be treated as read-only UI metadata, and are not runnable jobs

**POST /api/v1/discovery-modes/run** body:
```json
{
  "modeId": "release-radar",
  "settingsMode": "easy",
  "rawUserSettings": { "windowDays": 14 },
  "normalizedSettings": { "windowDays": 14 },
  "providerContext": { "providerPath": ["lastfm"] },
  "fallbackPolicy": "allow-fallback"
}
```

**POST /api/v1/discovery-modes/run** behavior:
- Returns `202 { "message": "Discovery run started" }` after validation; the actual run continues in the background
- The accepted response now includes `jobId`, so clients can poll the job detail endpoint while the run continues in the background
- The server re-evaluates availability and execution context from the current user connections before starting the run
- Returns `400` with the availability reason when a mode is currently unavailable, matching the `availability.reason` shown in the UI
- Mode-specific preflight preparation can still reject the request before `202`; for example, Artist Radio resolves free-text artist seeds to MusicBrainz IDs before the job is accepted

---

## Recommendations

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/recommendations` | Yes | List recommendations (paginated, filterable) |
| GET | `/api/v1/recommendations/:id` | Yes | Get single recommendation with artist data |
| PATCH | `/api/v1/recommendations/:id` | Yes | Approve, reject, or restore a recommendation |
| POST | `/api/v1/recommendations/bulk` | Yes | Bulk approve/reject (reject accepts an optional shared `reason` + `permanent` block) |
| GET | `/api/v1/recommendations/feedback-summary` | Yes | Genre approval rates (top 20), scoped to the calling user's own feedback |
| GET | `/api/v1/recommendations/popular-albums/availability` | Yes | Which popularity sources are reachable for the caller; backs the popular-album approve option. Returns `{ available, spotify, lastfm }` (booleans). |

**GET /api/v1/recommendations** query params:
- `status` - `pending`, `approved`, `rejected`, `added_to_lidarr`, `add_failed` (comma-separated)
- `kind` - `artist` or `album`; omit to return both. Backs the Discover kind filter and the Albums tab (`?kind=album`)
- `batchId` - filter by batch
- `sort` - `score_desc` (default), `score_asc`, `created_desc`, `acted_on_desc`, `taste`
- `tasteTier` - optional `primary` or `secondary`; secondary excludes primary matches

- `decades` - era filter, comma-separated: `60s`, `70s`, `80s`, `90s`, `00s`, `10s`, `20s`
- `limit` - 1-200 (default 20)
- `offset` - pagination offset

Taste ordering reads only the authenticated user's optional `primaryGenres` and `secondaryGenres` preferences. It orders primary matches, secondary matches, then other recommendations, using descending score within each group and ID for ties. Genres match exact names after trimming and lowercasing; there is no inferred genre taxonomy. Missing preferences retain score ordering. Filtering and ordering do not change stored scores, statuses, thresholds, or auto-approval.

Save either list through `PATCH /api/v1/auth/me/preferences`: `{"primaryGenres":["metal","jazz"],"secondaryGenres":["ambient"]}`. Each list accepts up to 24 nonempty names of at most 64 characters. Names are trimmed, lowercased, and deduplicated. Empty lists clear the preference.

Each item carries a `kind` field (`artist` or `album`). For `kind: "album"`, `recommendedReleaseGroupId` / `recommendedReleaseGroupTitle` identify the album (its `artistId` still points at the album's artist), and the UI renders the album as the primary unit.

**PATCH /api/v1/recommendations/:id** body:
```json
{
  "status": "approved",
  "approvalMode": "combined_lidarr_slskd",
  "monitorOption": "popular",
  "selectedAlbumIds": ["release-group-mbid"],
  "lidarrTargetId": "lidarr-1",
  "targetId": "slskd-7",
  "qualityProfileId": 1,
  "metadataProfileId": 1,
  "rootFolderId": 1
}
```

Approval notes:
- `approvalMode` defaults to `single_target`
- `monitorOption` accepts `all`, `new`, `selected`, `popular`, or `none`, and defaults to `none` when omitted: the artist is added to Lidarr without monitoring any albums and no search is triggered. These are Digarr's names, translated to the target's own vocabulary at the boundary: `all` monitors the whole discography and triggers a search for missing albums, and `new` monitors only future releases (Lidarr's `future`) without searching for anything existing. `popular` resolves the artist through Spotify, ranks album releases by Spotify popularity, maps the top 3 matches back to MusicBrainz release groups, and sends them to Lidarr as selected albums.
- `selectedAlbumIds` contains MusicBrainz release-group MBIDs when `monitorOption` is `selected`; clients may omit it for `popular` because Digarr resolves the top albums server-side.
- use `approvalMode: "combined_lidarr_slskd"` with an `slskd-*` `targetId` to add to Lidarr first and then queue the matched release in `slskd`
- `lidarrTargetId` is optional; when the selected `slskd` target is linked to a Lidarr target, Digarr uses that linked target as the fallback, and an explicit `lidarrTargetId` only overrides that default
- approving a `kind: "album"` recommendation routes to targets with the `addAlbum` capability: it adds the artist **unmonitored** (no whole-discography grab, and reuses the artist if already tracked), then monitors and searches only the approved album. `monitorOption` / `selectedAlbumIds` are ignored for album recs since the album is resolved from `recommendedReleaseGroupId`
- rejected recommendations may include `reason`, `reasonText`, and `permanent`; `permanent: true` also adds the artist to the caller's blocklist

Approve response (status `approved`):
```json
{
  "status": "added_to_lidarr",
  "targetActions": { "lidarr-1": { "status": "added", "externalId": 42 } },
  "targetSummary": { "total": 2, "succeeded": 1, "failed": 1,
    "failures": [{ "id": "lidarr-2", "name": "Lidarr Backup", "error": "connection refused" }] }
}
```
- Adds are **best-effort per target, not transactional**: a target that fails does not roll back targets that already succeeded (Digarr never deletes an artist from a target that took it).
- `targetActions` is the full merged map persisted on the rec; `targetSummary` describes only the targets attempted by *this* request, so clients can report partial outcomes at submit time.
- To retry just the failed targets, re-`PATCH` once per failed `targetId` (this preserves the successful targets' actions and will not regress the rec to `add_failed` if others already succeeded).

## Artist Blocks

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/artist-blocks` | Yes | List the caller's permanently blocked artists |
| POST | `/api/v1/artist-blocks` | Yes | Permanently block an artist for the caller |
| DELETE | `/api/v1/artist-blocks/:artistId` | Yes | Remove an artist from the caller's blocklist |

**GET /api/v1/artist-blocks** query params:
- `q` - optional artist-name search
- `limit` - integer, clamped to 1-200 (default 50). Non-integer values return `400`
- `cursor` - opaque cursor from `nextCursor`

**POST /api/v1/artist-blocks** body:
```json
{
  "artistId": 123,
  "reason": "wrong_style",
  "reasonText": null
}
```

## Album Blocks

Album blocks are created when the caller permanently rejects an album recommendation. They
are keyed by MusicBrainz release-group MBID and are independent of artist blocks.

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/album-blocks` | Yes | List up to 500 albums permanently blocked by the caller |
| DELETE | `/api/v1/album-blocks/:releaseGroupMbid` | Yes | Remove an album from the caller's blocklist |

**GET /api/v1/album-blocks** response:

```json
{
  "items": [
    {
      "id": 42,
      "artistId": 17,
      "artistName": "Example Artist",
      "artistMbid": "11111111-1111-1111-1111-111111111111",
      "releaseGroupMbid": "00000000-0000-0000-0000-000000000000",
      "reason": "wrong_style",
      "reasonText": null,
      "blockedAt": "2026-07-12T00:00:00.000Z"
    }
  ]
}
```

`:releaseGroupMbid` must be a UUID. Invalid values return `400`; a successful delete
returns `204` even when the row is already absent.

---

## Artists

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/artists/:id` | Yes | Get artist by ID |
| GET | `/api/v1/artists/:id/top-tracks` | Yes | Top 5 tracks (Deezer, MB fallback) |
| GET | `/api/v1/artists/:id/enrichment` | Yes | Cached Wikidata description and external links |
| GET | `/api/v1/albums/:mbid` | Yes | Release groups for an artist MBID |
| GET | `/api/v1/preview/audio` | Yes | Proxy Deezer preview audio (CORS bypass) |

Path params:
- `:id` values are positive integers. Fractional, negative, zero, or unsafe integer values return `400`

**GET /api/v1/preview/audio** query params:
- `url` - Deezer CDN preview URL (must match `*.dzcdn.net`)
- `token` - auth token (for `<audio>` elements that can't send headers)

**GET /api/v1/artists/:id/enrichment** query params:
- `locale` - optional BCP 47-ish locale token; invalid tokens fall back to `en`

---

## Media

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/media/image-proxy` | Yes | Proxy whitelisted AudioDB image URLs when image proxying is enabled |

**GET /api/v1/media/image-proxy** query params:
- `src` - required `http` or `https` URL on `img.theaudiodb.com`, `theaudiodb.com`, or `www.theaudiodb.com`

Notes:
- Returns `404` when AudioDB image proxying is disabled
- Rejects non-image content, redirects, private addresses, and non-whitelisted hosts

---

## Batches

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/batches` | Admin | List all recommendation batches |
| GET | `/api/v1/batches/:id` | Admin | Get batch details |

Path params:
- `:id` values are positive integers. Fractional, negative, zero, or unsafe integer values return `400`

---

## Subscriptions

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/subscriptions` | Yes | List user subscriptions |
| POST | `/api/v1/subscriptions` | Yes | Create subscription |
| PATCH | `/api/v1/subscriptions/:id` | Yes | Update subscription |
| DELETE | `/api/v1/subscriptions/:id` | Yes | Delete subscription |
| POST | `/api/v1/subscriptions/:id/run` | Yes | Trigger manual run (202) |
| GET | `/api/v1/subscriptions/:id/runs` | Yes | Run history |
| POST | `/api/v1/subscriptions/import/spotify-liked-songs` | Yes | Create/reuse the helper Spotify Liked Songs subscription and trigger an import run (202) |
| POST | `/api/v1/subscriptions/import/spotify-playlist` | Yes | Import from a Spotify playlist (accepts URL, URI, or bare ID). Returns 202. |
| POST | `/api/v1/subscriptions/import/csv` | Yes | Upload CSV of artist names (multipart form, field: `file`, max 1MB, 500 artists). Returns 202. |
| POST | `/api/v1/subscriptions/import/deezer-favorites` | Yes | Create/reuse Deezer Favorites subscription and trigger import (202) |
| POST | `/api/v1/subscriptions/import/deezer-followed` | Yes | Create/reuse Deezer Followed Artists subscription and trigger import (202) |
| GET | `/api/v1/subscriptions/import/deezer-playlists` | Yes | List user's Deezer playlists |
| POST | `/api/v1/subscriptions/import/deezer-playlists` | Yes | Import from a Deezer playlist (202) |
| GET | `/api/v1/subscriptions/adapter-types` | Yes | Available adapter types with config schemas |
| GET | `/api/v1/subscriptions/scheduler` | Yes | Scheduler job status, scoped to the calling user's own subscriptions |
| POST | `/api/v1/subscriptions/bulk-toggle` | Yes | Enable/disable all subscriptions |

**Adapter types**: `genre`, `similar`, `discovery-mode`, `spotify-liked-songs`, `spotify-playlist`, `spotify-charts`, `deezer-favorites`, `deezer-followed`, `deezer-flow`, `deezer-playlists`, `lastfm-tag`, `lastfm-charts`, `listenbrainz`, `csv-import`

**POST /api/v1/subscriptions** body:
```json
{
  "name": "Weekly jazz",
  "sourceType": "lastfm-tag",
  "sourceProvider": "lastfm",
  "sourceConfig": { "tag": "jazz" },
  "cron": "0 0 * * 0",
  "maxArtistsPerRun": 20
}
```

Path params:
- `:id` values are positive integers. Fractional, negative, zero, or unsafe integer values return `400`

**Discovery-mode subscription body example:**
```json
{
  "name": "Release Radar Weekly",
  "sourceType": "discovery-mode",
  "sourceProvider": "release-radar",
  "sourceConfig": {
    "modeId": "release-radar",
    "settingsMode": "easy",
    "settings": { "windowDays": 14 },
    "providerContext": { "providerPath": ["lastfm"] },
    "fallbackPolicy": "allow-fallback"
  },
  "cron": "0 8 * * 1",
  "maxArtistsPerRun": 20
}
```

Discovery-mode subscription notes:
- Creation and updates re-check current availability and reject unavailable modes with `400`
- The saved `providerContext` and `fallbackPolicy` mirror the execution path chosen for the manual form, so scheduled runs stay aligned with what the user configured

---

## Targets

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/targets` | Yes | List targets with masked secrets. Admins see all targets; non-admins see only their own |
| POST | `/api/v1/targets` | Admin | Create target |
| PATCH | `/api/v1/targets/:id` | Admin | Update target |
| DELETE | `/api/v1/targets/:id` | Admin | Delete target |
| POST | `/api/v1/targets/:id/test` | Admin or owner | Test target connection |

Create and update accept an optional positive integer `userId` to assign the target to an existing user. Creation defaults to the calling admin. Admins can manage assigned targets; only the assigned user can use them for approvals. Create a separate target for each user who needs the same destination. Updating a config preserves omitted or masked secrets.

A linked `slskd` target requires an enabled Lidarr target assigned to the same user. To move a linked pair, clear `lidarrTargetId` first, reassign both targets, then restore the link. Active jobs for the previous owner stop instead of using the reassigned connections.

Example create body: `{"type":"lidarr","name":"Music","userId":2,"config":{"url":"http://lidarr:8686","apiKey":"<key>"}}`.

The target test uses the saved provider configuration for `plex-playlist`, `jellyfin-playlist`, `navidrome-playlist`, and `emby-playlist`. Plex playlist export fails before creation when no local tracks resolve or the server identity is missing.

**Target types**: `lidarr`, `slskd`, `spotify-playlist`, `navidrome-playlist`, `jellyfin-playlist`, `emby-playlist`, `plex-playlist`, `export`

## slskd

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/slskd/jobs` | Admin | Inspect active `slskd` orchestration jobs and current sync state. |
| POST | `/api/v1/slskd/sync` | Admin | Trigger a manual `slskd` orchestration sync. Returns 202 immediately. |

**POST /api/v1/slskd/sync** notes:
- No request body
- The route acknowledges immediately and lets the sync continue in the background
- The sync worker polls linked Lidarr wanted releases, creates deduped `slskd` jobs, advances active jobs through search and transfer states, and verifies Lidarr imports before marking linked jobs complete
- Linked target config requires `lidarrDownloadPath`, the completed downloads root visible to Lidarr. All queued files must succeed before `ManualImport`; partial, rejected, ambiguous, or unidentified files are refused. Imports use `move` and are verified through track `hasFile` values. Releases are capped at 500 files and 20 GiB, with a 2,048-character path limit; rejected manifests never enqueue downloads.
- Failed work reuses its work-key job after a one-hour cooldown and increments `attempts`. Historical duplicate failures are retained in terminal `superseded` state.

**GET /api/v1/slskd/jobs** response shape:

```json
{
  "syncing": true,
  "jobs": [
    {
      "id": 101,
      "targetId": 7,
      "recommendationId": 40,
      "state": "downloading",
      "releaseTitle": "Geogaddi"
    }
  ]
}
```

---

## Genres

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/genres` | Yes | List genres with artist counts and examples |
| GET | `/api/v1/genres/search` | Yes | Search genres |
| GET | `/api/v1/genres/:slug` | Yes | Genre detail with sub-genres and library artists |
| GET | `/api/v1/genres/:slug/artists` | Yes | Artists by genre (view: recommended/trending/deep_cuts) |
| POST | `/api/v1/genres/seed` | Admin | Seed genre database from Lidarr library (202) |

**GET /api/v1/genres/search** query params:
- `q` - required search string, minimum 2 characters

---

## Playlists

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/playlists` | Yes | List user playlists |
| POST | `/api/v1/playlists` | Yes | Create playlist |
| GET | `/api/v1/playlists/:id` | Yes | Playlist with tracks |
| PATCH | `/api/v1/playlists/:id` | Yes | Update playlist |
| DELETE | `/api/v1/playlists/:id` | Yes | Delete playlist |
| POST | `/api/v1/playlists/:id/generate` | Yes | Generate playlist tracks (202) |
| GET | `/api/v1/playlists/:id/export/:format` | Yes | Export as json/csv/m3u/xspf |
| GET | `/api/v1/playlists/scheduler` | Yes | Playlist scheduler status |

**POST /api/v1/playlists/:id/generate** returns `202` with `{ "status": "generating" }` before generation finishes. Generated tracks are saved locally before exports to selected enabled playlist targets. Exports to selected enabled Navidrome, Jellyfin, Emby, Plex, and Spotify targets are all attempted; an export failure marks the job failed in Job History, while local tracks and successful remote exports remain. There is no remote rollback.

**GET /api/v1/playlists/:id** adds `generation`, either `null` for legacy/no-history playlists or `{ jobId, status, startedAt, completedAt, resolution }` for the latest owned generation job. `resolution` is `null` until its local result is recorded, and includes `requestedArtistCount`, `resolvedArtistCount`, `includedArtistCount`, `trackCount` and `outcomes` when available. Each outcome has `artistName`, optional `artistMbid`, `status`, `resolvedTrackCount` and `includedTrackCount`. Outcome statuses are `resolved`, `unmatched`, `unavailable`, `error` and `limited`. A partially included artist remains `resolved` with both counts; `limited` means tracks resolved but none fit the playlist cap. A failed target export can coexist with a saved local resolution summary. This projection does not expose raw job errors, secrets, other users' results, or remote read-back verification.

**Strategies**: `audition`, `weekly_digest`, `genre_focus`, `mood_mix`, `rediscover`

`audition` selects the playlist owner's pending recommendations in descending score order, deduplicates artists, and resolves one track per artist up to `config.size`. It does not approve recommendations and skips unresolved tracks instead of inventing placeholder titles. It uses the existing on-demand generation endpoint, schedule, and target selection. Local media-server targets require matching tracks in their libraries.

---

## Mood Discovery

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/v1/mood/discover` | Yes | AI-powered mood-based discovery. Rate limited: 10/min |

**Body**:
```json
{ "query": "rainy day jazz with piano" }
```

**Response**:
```json
{
  "results": [
    {
      "artistName": "Brad Mehldau",
      "confidence": 0.9,
      "reasoning": "...",
      "inLibrary": false
    }
  ]
}
```

Locale notes:
- `POST /api/v1/mood/discover` honors `X-Digarr-Locale`
- The response reasoning follows the resolved UI locale, while prompt-language detection uses the submitted mood text

Errors:
- `400` when no AI provider is configured
- `502` with `{ "error": "AI provider request failed (<provider>/<model>): <detail>" }` when the provider call fails; `<detail>` includes the upstream status and response body (e.g. an Ollama `model not found` -- pull the model or fix the model name in Settings, and use the Settings test button, which verifies the configured model exists)

---

## Search

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/search` | Yes | Cross-platform artist search |
| GET | `/api/v1/search/sources` | Yes | Available search sources |

**Sources**: `spotify`, `deezer`, `musicbrainz`, `tidal`, `bandcamp`

Each source includes a `stability` field (`stable` or `experimental`). TIDAL and Bandcamp are experimental.

**GET /api/v1/search** query params:
- `q` - required search string
- `sources` - optional comma-separated source IDs
- `limit` - integer, clamped to 1-50 (default 20). Non-integer values return `400`

When one enabled source fails, Digarr still returns results from the healthy sources when possible.

---

## Analytics (Admin)

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/analytics/overview` | Admin | Summary stats |
| GET | `/api/v1/analytics/batches` | Admin | Batch history |
| GET | `/api/v1/analytics/genres` | Admin | Top genres by recommendation count |
| GET | `/api/v1/analytics/sources` | Admin | Source effectiveness |
| GET | `/api/v1/analytics/scores` | Admin | Score distribution |
| GET | `/api/v1/analytics/trend` | Admin | Approval trend over time |
| GET | `/api/v1/analytics/time-to-act` | Admin | Time-to-decision metrics |

---

## Library Health (Admin)

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/library/health` | Admin | Health check results, persisted snapshot timestamps, last error, and configured auto-sync interval |
| POST | `/api/v1/library/health/scan` | Admin | Start background health scan (202) |
| POST | `/api/v1/library/health/:checkId/fix` | Admin | Apply fix for a health check |
| GET | `/api/v1/library/stats` | Admin | Library statistics |
| POST | `/api/v1/library/warm` | Admin | Warm SkyHook cache for MBIDs (202) |
| GET | `/api/v1/library/warm/status` | Admin | SkyHook warm status |
| GET | `/api/v1/library/sources` | Admin | Per-source sync state for global + per-user library sources |
| POST | `/api/v1/library/sync` | Admin | Run a manual library sync for all sources or a specific source |
| GET | `/api/v1/library/unreconciled` | Admin | List unreconciled library artists still needing a match |
| GET | `/api/v1/library/unreconciled-albums` | Admin | List unreconciled library albums still needing a release-group match |
| POST | `/api/v1/library/overrides/bulk-ignore` | Admin | Atomically save ignore overrides for 1-200 unique artist identities (204) |
| POST | `/api/v1/library/album-overrides/bulk-ignore` | Admin | Atomically save ignore overrides for 1-200 unique album identities (204) |
| GET | `/api/v1/library/album-coverage/:artistMbid` | Yes | Owned/missing album counts for an artist, used by the recommendation card coverage badge |
| POST | `/api/v1/library/overrides` | Admin | Save a manual artist MBID override or an “ignore forever” decision |
| POST | `/api/v1/library/album-overrides` | Admin | Save a manual album release-group MBID override or an ignore decision |
| DELETE | `/api/v1/library/overrides/:source/:sourceArtistId` | Admin | Remove a saved manual artist override |
| POST | `/api/v1/library/reconcile` | Admin | Trigger a background reconcile pass after override changes |

**GET /api/v1/library/sources** response notes:
- `lastSyncCounts.albumsSynced` is present for album-capable sources after a successful sync
- Lidarr, Plex, and Jellyfin source rows now include artist sync counts plus the number of reconciled album rows written for that source snapshot
- `lastSyncCounts.unreconciledLookupFailed` counts artist rows left unresolved because their MusicBrainz lookup failed. It is optional and may be absent from historical stored count objects; consumers treat absence as zero
- `lastSyncCounts.mbApiCallsFailed` is the number of MusicBrainz lookups that failed after internal retries. A non-zero value means the sync completed with partial reconciliation; affected artists and albums are retried on the next sync

**POST /api/v1/library/warm** body:
```json
{
  "mbids": ["f59c5520-5f46-4d2c-b2c4-822eabf53419"]
}
```

Notes:
- `mbids` must be a non-empty array of strings
- Only the first 50 MBIDs are queued per request

**GET /api/v1/library/warm/status** query params:
- `mbids` - comma-separated MBIDs to inspect (up to 100)

**POST /api/v1/library/sync** notes:
- Rate limited: 5/min
- Empty body runs global source sync plus a forced sync for the current user and returns `202`
- `{ "source": "lidarr" }` runs a single source and returns `200` on completion, `202` if still running, or `502` on sync failure
- If the requested source is not configured for the current user, Digarr retries it as a global source
- A source album-fetch failure marks the source sync and its job failed and preserves the previous source snapshot. A single-source request returns `502`; for all-source or scheduled runs, inspect the source status and Job History. This differs from MusicBrainz reconciliation failures, which are counted within an otherwise completed sync.

**POST /api/v1/library/sync** body:
```json
{
  "source": "plex"
}
```

**GET /api/v1/library/unreconciled** response notes:
- Returns unreconciled rows from both the current user's sources and any global sources visible to that user
- Each row's `unreconciledReason` is `no_candidate` when MusicBrainz returned no safe match, `ambiguous` when multiple plausible matches remain, or `lookup_failed` when the lookup failed after retries. `null` remains possible for legacy or otherwise unclassified rows.

**POST /api/v1/library/overrides/bulk-ignore** body:
```json
{
  "items": [
    { "source": "plex", "sourceArtistId": "artist-123" }
  ]
}
```

**POST /api/v1/library/album-overrides/bulk-ignore** body:
```json
{
  "items": [
    { "source": "plex", "sourceAlbumId": "album-456" }
  ]
}
```

Bulk-ignore notes:
- `items` must contain 1-200 identities, and every `(source, sourceArtistId)` or `(source, sourceAlbumId)` pair must be unique. Empty, oversized, duplicate, incomplete, or extra-field payloads return `400` without writing overrides.
- A successful request stores every ignore override in one database transaction and returns `204 No Content`. If any write fails, the transaction rolls back instead of leaving a partially ignored selection.
- The operation does not trigger reconciliation. The web review removes the completed selection by refreshing the unreconciled lists and source summary after the `204` response.

**POST /api/v1/library/overrides** body:
```json
{
  "source": "plex",
  "sourceArtistId": "artist-123",
  "correctMbid": "f59c5520-5f46-4d2c-b2c4-822eabf53419",
  "note": "Matched against album overlap"
}
```

Override notes:
- Set `correctMbid` to `null` or `""` to store an ignore decision instead of a correction
- `correctMbid`, when present, must be a valid UUID

**POST /api/v1/library/album-overrides** body:
```json
{
  "source": "plex",
  "sourceAlbumId": "album-456",
  "correctAlbumMbid": "d8564bdd-5be3-4f3e-9d2b-3c4b5a6b7c8d",
  "note": "Matched against tracklist"
}
```

Album override notes:
- Set `correctAlbumMbid` to `null` or `""` to store an ignore decision instead of a correction
- `correctAlbumMbid`, when present, must be a valid release-group UUID
- Album overrides persist in a separate `album_override` table keyed by `(userId, source, sourceAlbumId)`

**GET /api/v1/library/album-coverage/:artistMbid** notes:
- `artistMbid` must be a valid UUID
- Returns owned and missing album counts derived from the user's reconciled library snapshot
- Powers the coverage badge shown on recommendation cards

**GET /api/v1/library/unreconciled-albums** response notes:
- Returns unreconciled album rows from both the current user's sources and any global sources visible to that user
- `unreconciledReason` uses the same `no_candidate`, `ambiguous`, and `lookup_failed` values as the artist route; `null` remains possible for legacy or otherwise unclassified rows.

**POST /api/v1/library/reconcile** notes:
- Triggers a forced sync for the current user and returns `202`
- This currently re-fetches source data; there is no reconcile-only path yet

---

## Exports

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/exports/:format` | Yes | Export recommendations as json/csv/m3u/xspf |

Query params: `status`, `batchId`. Limit: 10,000 rows.

---

## Dashboard

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/dashboard/taste` | Yes | Top genres from user's library |
| GET | `/api/v1/dashboard/genre-coverage` | Yes | Latest listening-artist genre coverage |
| GET | `/api/v1/dashboard/activity` | Yes | Recent activity feed |

`GET /api/v1/dashboard/genre-coverage` returns the latest completed pipeline
run's user-scoped coverage as `{ coveredArtists, pendingArtists, totalArtists }`,
or `null` before a run has recorded coverage. `pendingArtists` can overlap with
covered artists when a populated cache entry is due for refresh.

**GET /api/v1/dashboard/activity** query params:
- `limit` - integer, clamped to 1-20 (default 5). Non-integer values return `400`

---

## Listening

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/listening/top-artists` | Yes | Top artists by play count for a given period (ListenBrainz primary, Last.fm and mapped Plex fallback) |
| GET | `/api/v1/listening/recent-tracks` | Yes | Most recent scrobbles (Last.fm primary, ListenBrainz, Jellyfin, Emby and mapped Plex fallback) |

**GET /api/v1/listening/top-artists** query params:
- `range` - `this_week`, `this_month`, `this_year`, `all_time` (default `this_month`). Calendar-aligned ongoing periods, not rolling windows. Legacy `week`/`month`/`year` map to `this_week`/`this_month`/`this_year` for back-compat.
- `offset` - 0-10000 (default 0)
- `limit` - 1-50 (default 5)

Response: `{ tracks, total, offset, limit, source, status }`. `source` is `"listenbrainz"`, `"lastfm"`, `"plex"`, or `null`. Last.fm periods are rolling windows (`7day`, `1month`, `12month`, `overall`) and map approximately to the requested calendar range.

**GET /api/v1/listening/recent-tracks** query params:
- `limit` - 1-50 (default 5)

Response: `{ tracks, hasSource, source, status }`. `hasSource` is `false` when no scrobble-capable source is connected (UI should hide the tile). `source` identifies the last successful source attempt, including an empty result.

Both listening endpoints return `status`: `not_configured` means no eligible source or application settings; `empty` means attempts succeeded but returned no entries; `error` means no entries were available and at least one attempted source failed; `ok` means entries were returned, including a successful fallback after another source failed. Existing fallback priorities are unchanged. Raw upstream errors are not returned. ListenBrainz artist-statistics HTTP 204 responses count as empty success.

---

## Jobs (Admin)

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/jobs` | Admin | Paginated job list |
| GET | `/api/v1/jobs/:id` | Admin | Single job detail |
| GET | `/api/v1/jobs/health` | Admin | System health summary (pipeline, subscriptions, playlists, library sync, sources) |

**GET /api/v1/jobs** query params:
- `type` - `pipeline`, `quick_discover`, `subscription`, `target`, `playlist`, `library_sync`
- `status` - `running`, `completed`, `failed`, `stuck`
- `limit` - 1-100 (default 50)
- `offset` - pagination offset (minimum 0)
- Invalid `type` or `status` values return `400`

Pipeline job `sourceResults` describe each source's discovery contribution. Configured listening sources without `similarArtists` report `{ "status": "skipped", "reason": "unsupported_capability" }`. Supported sources not queried because of an explicit discovery mode or an empty seed list use `explicit_run` or `no_seeds`; absent connections use `not_configured`. Successful similarity lookups use `ok` with an `artists` count, including zero. Any failed seed lookup uses `error` with the redacted upstream message, even when other seeds return candidates. Profile collection and library sync are separate operations. Existing job records retain their recorded outcomes.

---

## Settings

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/settings` | Yes | Get settings (secrets masked) |
| PATCH | `/api/v1/settings` | Yes | Update settings (admin for global, any user for own connections) |
| POST | `/api/v1/settings/test/:service` | Admin, or own Plex connection | Test service connection |
| POST | `/api/v1/settings/test-webhook` | Admin | Send a synthetic notification to one channel |

**Testable services**: `lidarr`, `listenbrainz`, `lastfm`, `ai`, `plex`, `jellyfin`, `emby`, `subsonic`, `discogs`, `spotify`, `oidc`, `tidal`

Settings notes:
- Plex listener mapping is per user: `plexAccountId` is a positive integer or `null` in PATCH. The server verifies the selected account and derives `plexAccountName` and `plexMachineIdentifier`; clients cannot supply those identity fields. GET returns the stored mapping. Changing the Plex URL or token without selecting an account clears the mapping.
- The Plex probe returns `accounts: [{id, name}]` and `machineIdentifier` alongside music-library `sections`. Non-admins may probe their own Plex connection, never shared admin credentials. Other service probes stay admin-only. Listening requests require an explicit mapped account and reject mismatched history rows; library sync does not require listener mapping. Plex top-artist analysis requires complete history for the requested period and fails if it exceeds 5,000 entries or 25 pages. Recent-track requests intentionally return only their requested sample. The probe accepts `accountId` (number or explicit `null`); omission uses the saved listener, while `null` tests library-only access.
- Non-admin users can update only their own connection fields; global setting changes return `403`
- Service probes require admin access when user-session auth is active, except for probing the current user's own Plex connection
- TIDAL client credentials and the TIDAL probe are global, admin-managed settings. TIDAL is *additionally* a per-user OAuth connection: each user authorizes their own account using the admin-registered app via `/api/v1/auth/oauth/tidal/initiate`
- `GET /api/v1/settings` returns `_tidalAppConfigured` (boolean), a read-only capability flag telling non-admins whether an admin has registered a TIDAL app, so the UI can enable the Connect button without exposing the credentials. Underscore-prefixed keys are derived flags, never stored settings, and are ignored on `PATCH`
- Successful service probes return `200` with a required `message` plus optional metadata:
  `{ "message": "Connected", "version": "1.2.3", "latencyMs": 42 }`
- Failed service probes return `application/problem+json`: `400` for missing or unknown input,
  `403` for non-admin callers, and `502` when the upstream service probe fails
- The `502` body's `detail` field carries the upstream failure message (secrets redacted,
  capped at 300 chars) so the caller can see e.g. which model name the provider rejected
- Probe fields omitted from the request body fall back to the stored settings, so an empty
  body tests exactly what is saved
- The `plex` probe additionally returns the selected library and every music-type library on
  the server: `{ "sectionId": "5", "sections": [{ "key": "5", "title": "Music" }] }`. Save the
  chosen key as the per-user `plexSectionId` setting; empty/null means auto-detect (first
  music-type library). Useful when a server has several `artist`-type libraries (e.g.
  audiobooks next to music)
- The `jellyfin` and `emby` probes likewise return the user's music libraries (and the
  selected one when configured): `{ "libraryId": "abc", "libraries": [{ "id": "abc", "name":
  "Music" }] }`. Save the chosen id as the per-user `jellyfinLibraryId` / `embyLibraryId`
  setting; empty/null means all music libraries (server-wide, the default). When set, top
  artists, favorites, recent listening, and library sync are scoped to that library

Notification channels:
- `GET /api/v1/settings` returns a `channels` array under `preferences`, and `PATCH` accepts the
  same. Each channel is one of four shapes, discriminated on `type`. Shared fields: `id` (opaque
  string, stable edit/remove key), `enabled` (boolean), `events` (subset of `["batch_complete",
  "digest"]`), and the admin-only `allowPrivateTarget` (boolean, optional).
  - `webhook` - `{ ..., url }` (Discord/Slack payloads auto-detected)
  - `ntfy` - `{ ..., server, topic, priority?, token? }` (`priority` 1-5)
  - `telegram` - `{ ..., botToken, chatId }` (plain-text messages)
  - `apprise` - `{ ..., endpoint, urls }` (`urls` newline-separated, fans out to 80+ services)
- Channel secrets (`telegram.botToken`, `ntfy.token`, `apprise.urls`) are returned masked as `***`;
  sending `***` back on `PATCH` preserves the stored ciphertext instead of overwriting it.
  Webhook URLs are partially masked so their destination remains recognizable; submitting the unchanged masked URL preserves the saved value. Encryption at rest requires `DIGARR_ENCRYPTION_KEY`.
- The `channels` array is stripped from `GET` responses for non-admins, and non-admin `PATCH` of it
  returns `403` (same rule as other global settings).
- `allowPrivateTarget: true` relaxes only RFC1918 ranges (`10/8`, `172.16/12`, `192.168/16`) for
  that one channel; cloud-metadata (`169.254.169.254`), link-local, and ULA stay blocked, and
  DNS-pinning plus `redirect: manual` stay on regardless.
- `POST /api/v1/settings/test-webhook` sends a synthetic `batch_complete` notification to a single
  channel and returns `204` on success. Post the channel config inline in the body (any secret
  left as `***` is restored from the stored channel), or `{ "id": "<channelId>" }` (or `?id=`) to
  test a stored channel; with no id it tests the first configured channel. Delivery failure returns
  `application/problem+json` `502` with the upstream message in `detail` (secret-redacted, capped
  at 300 chars); `400` when no channel is configured.

---

## Users (Admin)

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/users` | Admin | List all users |
| POST | `/api/v1/users` | Admin | Create user |
| PATCH | `/api/v1/users/:id` | Admin | Update user (admin status) |
| DELETE | `/api/v1/users/:id` | Admin | Delete user |

Admins can promote other users. First-user admin creation is serialized in the database. Deleting a user removes their recommendations, subscriptions, and other owned records; shared artists and batch history remain. Admins cannot delete themselves or remove the last admin.

---

## Lidarr

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/lidarr/stats` | Admin | Artist count, monitored count |
| GET | `/api/v1/lidarr/profiles` | Admin | Quality profiles |
| GET | `/api/v1/lidarr/metadataprofiles` | Admin | Metadata profiles |
| GET | `/api/v1/lidarr/rootfolders` | Admin | Root folders |
| GET | `/api/v1/lidarr/approve-options` | Yes | Non-admin picker data for the approve dialog: quality/metadata profile names and root-folder paths only (no freeSpace/structure) |
| POST | `/api/v1/lidarr/add` | Admin | Add artist to Lidarr |

---

## Admin (Admin)

All `/api/v1/admin/*` endpoints require admin authentication.

### Backup & Restore

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/v1/admin/backup` | Admin | Download backup JSON. Query: `?includeCaches=true` |
| POST | `/api/v1/admin/restore` | Admin | Replace data from a backup. Requires `?confirm=true`; add `&force=true` only to proceed despite an encryption-key mismatch (affected credentials need re-entry). Accepts multipart form (field: `file`) or raw JSON body. |
| GET | `/api/v1/admin/backup/last` | Admin | Last auto-backup metadata. |

Backup files use a version-1 envelope. Current exports omit `data.oidcTokens`.
Restore accepts an optional legacy `data.oidcTokens` array for compatibility:
an absent or empty array is silent, while nonempty rows are never restored and
add `Ignored 1 legacy OIDC token record.` or
`Ignored N legacy OIDC token records.` to `warnings`.

### Upgrade

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/admin/migrations/pending` | Admin | Pending migration status. |

### Database Migration

Copy all stateful data from the current backend (PGlite or PostgreSQL) into a different one. The source is never modified. See [Switching the Database Backend](guides/switching-backends.md).

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/v1/admin/migrate-backend/test` | Admin | Validate target reachability. Non-destructive (for PGlite it only checks path containment, no file is created). Body: `{ backend: 'pglite', path }` or `{ backend: 'postgres', ... }`. Returns `{ ok, backend, description }`, or `502 { ok: false, code, error }` on failure. |
| POST | `/api/v1/admin/migrate-backend` | Admin | Run the copy. Body: `{ target, overwrite? }`. Returns the `MigrationReport` `{ ok, verified, contentVerified, tablesMigrated, mismatches, targetEnvHint, ... }` **only on `200`**. All error statuses use the `application/problem+json` envelope `{ type, title, status, code, ... }`: a verification failure is `422 code: migration_verify_failed` (the full report rides under a `report` extension); `409 code: pipeline_running` when a pipeline is running; `409 code: migration_in_progress` when a migration is already running; `409 code: target_not_empty` when the target is non-empty without `overwrite`; `422 code: encryption_mismatch` when the source and target `DIGARR_ENCRYPTION_KEY` differ. |

### Data Hygiene

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/v1/admin/hygiene/clear-image-failures` | Admin | Reset image failure cache. Query: `?olderThan=7d` |
| POST | `/api/v1/admin/hygiene/rebuild-genres` | Admin | Rebuild genre table from artist data. |
| POST | `/api/v1/admin/hygiene/rescore` | Admin | Re-score the current user's recommendations using saved component evidence and current weights. Incompatible legacy rows and concurrently changed rows are skipped. Query: `?status=pending` (default), `?status=pending,approved` |
| POST | `/api/v1/admin/hygiene/dedupe` | Admin | Find and remove duplicate recommendations. |
| POST | `/api/v1/admin/hygiene/ai-audit` | Admin | Audit AI reasoning. Query: `?autoFix=true`. Returns 202 when auto-fix starts. |
| GET | `/api/v1/admin/hygiene/ai-audit/results` | Admin | Poll auto-fix progress. |
| POST | `/api/v1/admin/hygiene/purge-sessions` | Admin | Delete expired login sessions. |

## Health

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/health` | No | Liveness check. On success returns `{ status: 'ok', version, gitSha, channel, dbBackend }`; `503 { status: 'draining' }` while shutting down, or `503 { status: 'error', db: 'unavailable' }` when the DB check fails. |