tidarr/docs/API_DOCUMENTATION.md

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
• Authentication
• Download Endpoints
• Configuration Endpoints
• Synchronization Endpoints
• Custom CSS Endpoints
• Usage Examples

---

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/check \
  -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"
    }
  }'

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

---

Configuration Endpoints

Get Tidarr configuration

curl http://localhost:8484/api/check \
  -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 http://localhost:8484/api/delete_token \
  -H "Authorization: Bearer $TIDARR_TOKEN"

Response: Status 201 Created

---

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 POST http://localhost:8484/api/sync/remove \
  -H "Authorization: Bearer $TIDARR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"id": "abc123-def456"}'

Response: Status 201 Created

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"
}

---

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

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