Agent skill

tidal-api

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

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/tidal-api

SKILL.md

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)

Resource Description Key Endpoints
albums Album metadata, tracks, artists /albums, /albums/{id}
artists Artist info, discography /artists, /artists/{id}
tracks Track metadata, lyrics, audio /tracks, /tracks/{id}
playlists User playlists /playlists, /playlists/{id}
searchResults Search across catalog /searchResults/{query}
searchSuggestions Autocomplete /searchSuggestions/{query}
userCollections User's saved library /userCollections/{id}
users User profiles /users/me
lyrics Song lyrics /lyrics, /lyrics/{id}
artworks Image assets /artworks, /artworks/{id}
videos Music videos /videos, /videos/{id}
genres Genre metadata /genres, /genres/{id}
providers Content providers /providers, /providers/{id}

Common Endpoints

Search

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

Tracks

GET /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

GET /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

GET /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)

GET /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)

GET /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

bash
# 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

bash
# 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

bash
# 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

bash
# 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)

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results