---

name: tidal-api description: Navigate the Tidal API specification (23,000+ lines OpenAPI spec). Use when implementing Tidal API integrations, adding new endpoints, or understanding API structure.

Tidal API Navigation Skill

Use this skill to navigate the Tidal API specification located at tidal/tidal-api-oas.json (23,000+ lines).

API Overview

The Tidal API is a JSON:API-compliant REST API at https://openapi.tidal.com/v2.

Key Characteristics

• Content-Type: application/vnd.api+json
• Pagination: Cursor-based (page[cursor] parameter)
• Batch limits: Most endpoints support max 20 items per request
• Filtering: Use filter[field] query params (e.g., filter[id], filter[isrc])
• Includes: Use include param to embed related resources in response

Resource Types (Tags)

Common Endpoints

Search

CopyGET /searchResults/{query}
  - countryCode: required (e.g., "US")
  - include: albums,artists,playlists,topHits,tracks,videos
  - explicitFilter: INCLUDE|EXCLUDE

Tracks

CopyGET /tracks
  - filter[id]: comma-separated track IDs (max 20)
  - filter[isrc]: comma-separated ISRCs (max 20)
  - include: albums,artists,genres,lyrics,providers

GET /tracks/{id}
  - include: albums,artists,genres,lyrics

GET /tracks/{id}/relationships/albums
GET /tracks/{id}/relationships/artists
GET /tracks/{id}/relationships/lyrics

Albums

CopyGET /albums
  - filter[id]: comma-separated album IDs (max 20)
  - filter[barcodeId]: barcode/EAN/UPC
  - include: artists,coverArt,genres,items

GET /albums/{id}
  - include: artists,coverArt,genres,items

GET /albums/{id}/relationships/items  # Track listing
  - include: items

Artists

CopyGET /artists
  - filter[id]: comma-separated artist IDs

GET /artists/{id}
  - include: albums,biography,profileArt,tracks

GET /artists/{id}/relationships/albums
GET /artists/{id}/relationships/tracks

Playlists (requires user auth)

CopyGET /playlists
  - filter[id]: playlist UUIDs
  - filter[owners.id]: user ID
  - include: coverArt,items,ownerProfiles
  - sort: createdAt,-createdAt,lastModifiedAt,-lastModifiedAt,name,-name

POST /playlists  # Create playlist
  - Body: { data: { type: "playlists", attributes: { name, accessType } } }
  - accessType: PUBLIC|UNLISTED|PRIVATE

GET /playlists/{id}/relationships/items
POST /playlists/{id}/relationships/items  # Add tracks
DELETE /playlists/{id}/relationships/items  # Remove tracks

User Library (requires user auth)

CopyGET /users/me  # Get authenticated user

GET /userCollections/{userId}/relationships/albums
GET /userCollections/{userId}/relationships/tracks
GET /userCollections/{userId}/relationships/playlists
GET /userCollections/{userId}/relationships/artists
  - include: albums|tracks|playlists|artists (matching resource type)
  - Returns meta.addedAt for each item

Key Schema Types

Track Attributes

• title, version (remix info)
• isrc (International Standard Recording Code)
• duration (ISO 8601, e.g., "PT3M45S")
• explicit (boolean)
• popularity (0.0-1.0)
• bpm, key, keyScale
• toneTags (mood tags like "Happy")
• mediaTags (quality: HIRES_LOSSLESS, LOSSLESS)

Album Attributes

• title, version
• barcodeId (EAN-13/UPC-A)
• duration (ISO 8601)
• numberOfItems, numberOfVolumes
• releaseDate (ISO 8601 date)
• type (ALBUM|EP|SINGLE)
• explicit, popularity

Artist Attributes

• name, handle
• popularity (0.0-1.0)
• contributionsEnabled, contributionsSalesPitch

Playlist Attributes

• name, description
• accessType (PUBLIC|UNLISTED|PRIVATE)
• createdAt, lastModifiedAt
• numberOfItems, duration

How to Search the Spec

Find endpoint details

Copy# List all paths
jq -r '.paths | keys[]' tidal/tidal-api-oas.json

# Get specific endpoint
jq '.paths["/tracks"]' tidal/tidal-api-oas.json
jq '.paths["/albums/{id}/relationships/items"]' tidal/tidal-api-oas.json

# Search for endpoints containing a term
jq -r '.paths | keys[] | select(contains("playlist"))' tidal/tidal-api-oas.json

Find schema definitions

Copy# List all schemas
jq -r '.components.schemas | keys[]' tidal/tidal-api-oas.json

# Get specific schema
jq '.components.schemas.Tracks_Attributes' tidal/tidal-api-oas.json
jq '.components.schemas.Albums_Attributes' tidal/tidal-api-oas.json
jq '.components.schemas.Playlists_Attributes' tidal/tidal-api-oas.json

# Search for schemas by pattern
jq -r '.components.schemas | keys[] | select(contains("Playlist"))' tidal/tidal-api-oas.json

Find request/response bodies

Copy# Get POST request body schema
jq '.paths["/playlists"].post.requestBody' tidal/tidal-api-oas.json

# Find the referenced schema
jq '.components.schemas.PlaylistCreateOperation_Payload' tidal/tidal-api-oas.json

# Get response schema
jq '.paths["/tracks/{id}"].get.responses["200"]' tidal/tidal-api-oas.json

Find security requirements

Copy# Check auth for an endpoint
jq '.paths["/playlists"].post.security' tidal/tidal-api-oas.json

# List all security schemes
jq '.components.securitySchemes' tidal/tidal-api-oas.json

Authentication

Two methods:

1. Client Credentials - App-level access (search, catalog browsing)

   • Scope: None needed for public catalog

2. Authorization Code PKCE - User-level access (playlists, library)

   • Scopes: playlists.read, playlists.write, collection.read, r_usr, w_usr

Existing Implementation Reference

See backend/src/services/tidalService.ts for working implementations of:

• Search with include=albums,tracks
• Batch track fetch by ISRC (filter[isrc])
• Batch album fetch by ID (filter[id])
• Album track listing via relationships
• Playlist creation and track addition
• User library sync (albums/tracks)

Key patterns used:

• Rate limiting with exponential backoff
• Chunking requests to 20 items max
• Building lookup maps from included resources
• Extracting relationships to resolve IDs

Tips

1. Always check include options - Each endpoint lists available includes
2. Use batch endpoints - Fetch up to 20 items per request with filter[id]
3. Parse ISO 8601 durations - Format is PT{hours}H{minutes}M{seconds}S
4. Handle cursor pagination - Check links.next or links.meta.nextCursor
5. Artwork sizes - Files array contains multiple sizes (80, 160, 320, 640, 1280)