Skip to content

Tidarr API Documentation

Jump to bottom
cl.st edited this page Nov 26, 2025 · 7 revisions

Tidarr API Documentation

This documentation describes how to use the Tidarr REST API with curl to automate downloads and manage your instance.

Table of Contents

Basic Configuration

API base URL: http://your-host:8484

All API endpoints (except /api/is-auth-active) require authentication if ADMIN_PASSWORD is set in your Docker configuration.

Authentication

Check if authentication is active

curl http://localhost:8484/api/is-auth-active

Response:

{
  "isAuthActive": true
}

Login and get a JWT token

If authentication is active, you must first obtain a JWT token:

curl -X POST http://localhost:8484/api/auth \
  -H 'Content-Type: application/json' \
  -d '{"password": "your_password"}'

Response:

{
  "status": "ok",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Use the token for subsequent requests:

export TIDARR_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

curl http://localhost:8484/api/settings \
  -H "Authorization: Bearer $TIDARR_TOKEN"

Download Endpoints

Add an item to the download queue

Endpoint: POST /api/save

Important: The API uses full Tidal URLs (not numeric IDs).

Album

curl -X POST http://localhost:8484/api/save \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "url": "https://listen.tidal.com/album/251082404",
      "type": "album",
      "status": "queue"
    }
  }'

Track (single song)

curl -X POST http://localhost:8484/api/save \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "url": "https://listen.tidal.com/track/123456789",
      "type": "track",
      "status": "queue"
    }
  }'

Video

curl -X POST http://localhost:8484/api/save \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "url": "https://listen.tidal.com/video/123456789",
      "type": "video",
      "status": "queue"
    }
  }'

Playlist

curl -X POST http://localhost:8484/api/save \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "url": "https://listen.tidal.com/playlist/abc123-def456",
      "type": "playlist",
      "status": "queue"
    }
  }'

Mix Tidal

curl -X POST http://localhost:8484/api/save \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "url": "https://listen.tidal.com/mix/000000000000000000000000",
      "type": "mix",
      "status": "queue"
    }
  }'

Artist (all albums)

curl -X POST http://localhost:8484/api/save \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "url": "https://listen.tidal.com/artist/3566315",
      "type": "artist",
      "status": "queue"
    }
  }'

Artist (all videos)

curl -X POST http://localhost:8484/api/save \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "url": "https://listen.tidal.com/artist/3566315",
      "type": "artist_videos",
      "status": "queue"
    }
  }'

Favorites

# Favorite albums
curl -X POST http://localhost:8484/api/save \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "type": "favorite_albums",
      "status": "queue"
    }
  }'

# Favorite tracks
curl -X POST http://localhost:8484/api/save \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "type": "favorite_tracks",
      "status": "queue"
    }
  }'

# Favorite playlists
curl -X POST http://localhost:8484/api/save \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "type": "favorite_playlists",
      "status": "queue"
    }
  }'

# Favorite videos
curl -X POST http://localhost:8484/api/save \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "type": "favorite_videos",
      "status": "queue"
    }
  }'

# Favorite artists
curl -X POST http://localhost:8484/api/save \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "type": "favorite_artists",
      "status": "queue"
    }
  }'

Response: Status 201 Created

Remove an item from the queue

curl -X DELETE http://localhost:8484/api/remove \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"id": "12345"}'

Response: Status 204 No Content

Clear the entire download queue

curl -X DELETE http://localhost:8484/api/remove-all \
  -H "Authorization: Bearer $TIDARR_TOKEN"

Response: Status 204 No Content

Remove finished items

curl -X DELETE http://localhost:8484/api/remove-finished \
  -H "Authorization: Bearer $TIDARR_TOKEN"

Response: Status 204 No Content

Pause the download queue

Pauses the download queue. If an item is currently being processed, it will be cancelled and returned to the queue with status "queue". Queued items will not start processing until the queue is resumed.

curl -X POST http://localhost:8484/api/queue/pause \
  -H "Authorization: Bearer $TIDARR_TOKEN"

Response: Status 204 No Content

Behavior:

  • Stops processing of new items from the queue
  • Cancels the currently processing item (if any) and resets it to "queue" status
  • Cleans up incomplete downloads
  • Items can be added to the queue while paused, but won't process until resumed

Resume the download queue

Resumes the download queue after it has been paused.

curl -X POST http://localhost:8484/api/queue/resume \
  -H "Authorization: Bearer $TIDARR_TOKEN"

Response: Status 204 No Content

Get queue status

Returns the current status of the download queue (paused or active).

curl http://localhost:8484/api/queue/status \
  -H "Authorization: Bearer $TIDARR_TOKEN"

Response:

{
  "isPaused": false
}

Configuration Endpoints

Get Tidarr configuration

curl http://localhost:8484/api/settings \
  -H "Authorization: Bearer $TIDARR_TOKEN"

Response:

{
  "noToken": false,
  "quality": "high",
  "enableBeetsAutotag": true,
  "enablePlexUpdate": true,
  "enableGotify": false,
  "enableAppriseApi": false,
  "tiddl_config": {
    "auth": {
      "token": "...",
      "refresh_token": "...",
      "token_expiry": "..."
    },
    "format": {
      "quality": "high",
      "album_template": "{album_artist}/{album}/{number:02d}. {title}",
      "track_template": "{artist}/_tracks/{artist} - {title}",
      "video_template": "_videos/{artist}/{artist} - {title}",
      "playlist_template": "_playlists/{playlist}/{playlist_number:02d}. {artist} - {title}"
    }
  }
}

Delete Tidal token

curl -X DELETE http://localhost:8484/api/token \
  -H "Authorization: Bearer $TIDARR_TOKEN"

Response: Status 204 No Content

Synchronization Endpoints

Synchronization allows automatic downloading of new songs from a playlist according to a cron schedule.

Get synchronized playlists list

curl http://localhost:8484/api/sync/list \
  -H "Authorization: Bearer $TIDARR_TOKEN"

Response:

[
  {
    "id": "abc123-def456",
    "title": "My Playlist",
    "url": "https://listen.tidal.com/playlist/abc123-def456",
    "type": "playlist"
  }
]

Add a playlist to synchronization

curl -X POST http://localhost:8484/api/sync/save \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "id": "abc123-def456",
      "title": "My Playlist",
      "url": "https://listen.tidal.com/playlist/abc123-def456",
      "type": "playlist"
    }
  }'

Response: Status 201 Created

Remove a playlist from synchronization

curl -X DELETE http://localhost:8484/api/sync/remove \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"id": "abc123-def456"}'

Response: Status 204 No Content

Sync all items now

Manually trigger synchronization of all items in the watch list (instead of waiting for the cron schedule):

curl -X POST http://localhost:8484/api/sync/trigger \
  -H "Authorization: Bearer $TIDARR_TOKEN"

Response: Status 202 Accepted

This endpoint will immediately queue all items from the watch list for download. Items already in the queue with status "processing" will be skipped. Items with status "finished" or "downloaded" will be removed from the queue and re-added.

Note: The synchronization cron is configured via the SYNC_CRON_EXPRESSION environment variable (default: 0 3 * * * = every day at 3 AM).

Custom CSS Endpoints

Get custom CSS

curl http://localhost:8484/api/custom-css \
  -H "Authorization: Bearer $TIDARR_TOKEN"

Response:

{
  "css": "body { background-color: #1a1a1a; }"
}

Save custom CSS

curl -X POST http://localhost:8484/api/custom-css \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "css": "body { background-color: #1a1a1a; }"
  }'

Response:

{
  "success": true,
  "message": "Custom CSS saved successfully"
}

Tiddl Configuration Endpoints

Get Tiddl TOML configuration

Retrieve the current Tiddl configuration file (config.toml):

curl http://localhost:8484/api/tiddl/config \
  -H "Authorization: Bearer $TIDARR_TOKEN"

Response:

{
  "toml": "[download]\nquality = \"high\"\nthreads = 6\n..."
}

Save Tiddl TOML configuration

Update the Tiddl configuration file:

curl -X POST http://localhost:8484/api/tiddl/config \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "toml": "[download]\nquality = \"max\"\nthreads = 8\n..."
  }'

Response:

{
  "success": true,
  "message": "Tiddl config saved successfully"
}

Usage Examples

Bash script to download multiple albums

#!/bin/bash

# Configuration
TIDARR_URL="http://localhost:8484"
TIDARR_PASSWORD="your_password"

# Get JWT token
TOKEN=$(curl -s -X POST $TIDARR_URL/api/auth \
  -H 'Content-Type: application/json' \
  -d "{\"password\": \"$TIDARR_PASSWORD\"}" | jq -r '.token')

# List of albums to download
albums=(
  "https://listen.tidal.com/album/251082404"
  "https://listen.tidal.com/album/123456789"
  "https://listen.tidal.com/album/987654321"
)

# Add each album to the queue
for album in "${albums[@]}"; do
  echo "Adding $album..."
  curl -s -X POST $TIDARR_URL/api/save \
    -H "Authorization: Bearer $TOKEN" \
    -H 'Content-Type: application/json' \
    -d "{
      \"item\": {
        \"url\": \"$album\",
        \"type\": \"album\",
        \"status\": \"queue\"
      }
    }"
  echo " ✓"
done

echo "All albums have been added to the download queue!"

Python script to add items to the queue

#!/usr/bin/env python3
import requests
import json
import time

TIDARR_URL = "http://localhost:8484"
PASSWORD = "your_password"

# Authentication
auth_response = requests.post(
    f"{TIDARR_URL}/api/auth",
    json={"password": PASSWORD}
)
token = auth_response.json()["token"]
headers = {"Authorization": f"Bearer {token}"}

# Add an album
album_data = {
    "item": {
        "url": "https://listen.tidal.com/album/251082404",
        "type": "album",
        "status": "queue"
    }
}
requests.post(
    f"{TIDARR_URL}/api/save",
    headers=headers,
    json=album_data
)

print("Album added to download queue")

Use Docker CLI to download directly

If you prefer to download directly without going through the download queue:

docker compose exec tidarr tiddl url https://listen.tidal.com/album/251082404 download

Important Notes

  1. Data format: The API expects a full Tidal URL, not a numeric ID alone.

  2. Supported types: album, track, video, playlist, mix, artist, artist_videos, favorite_albums, favorite_tracks, favorite_playlists, favorite_videos, favorite_artists

  3. Authentication: If ADMIN_PASSWORD is not set in your Docker configuration, authentication is not required.

  4. Status: When adding an item, always use "status": "queue".

  5. SSE Endpoints: The /api/stream-processing and /api/stream-item-output/:id endpoints use Server-Sent Events (SSE) for real-time updates. They are not intended to be used with curl, but rather with EventSource JavaScript clients or SSE libraries.

HTTP Status Codes

  • 200 OK - Request successful
  • 201 Created - Resource created successfully
  • 204 No Content - Deletion successful
  • 400 Bad Request - Invalid data
  • 403 Forbidden - Missing or invalid token
  • 500 Internal Server Error - Server error

Some part of this documentation was generated by AI

Clone this wiki locally