openapi: 3.0.1
info:
title: TIDAL Catalog acceptedTerms albums API
version: 1.10.14
description: 'Browse TIDAL''s high-fidelity music catalog: albums, artists, tracks, videos, genres, lyrics, credits, and artwork. JSON:API compliant with relationship traversal.'
x-source: https://tidal-music.github.io/tidal-api-reference/tidal-api-oas.json
servers:
- url: https://openapi.tidal.com/v2
description: Production
tags:
- name: albums
paths:
/albums:
get:
description: Retrieves multiple albums by available filters, or without if applicable.
parameters:
- description: Server-generated cursor value pointing a certain page of items. Optional, targets first page if not specified
in: query
name: page[cursor]
required: false
schema:
type: string
- description: Values prefixed with "-" are sorted descending; values without it are sorted ascending.
in: query
name: sort
required: false
schema:
type: array
items:
type: string
example: createdAt
enum:
- createdAt
- -createdAt
- title
- -title
default: -createdAt
x-enum-varnames:
- CreatedAtAsc
- CreatedAtDesc
- TitleAsc
- TitleDesc
- description: ISO 3166-1 alpha-2 country code
example: US
in: query
name: countryCode
required: false
schema:
type: string
- description: 'Allows the client to customize which related resources should be returned. Available options: albumStatistics, artists, coverArt, genres, items, owners, priceConfig, providers, replacement, shares, similarAlbums, suggestedCoverArts, usageRules'
example: albumStatistics
in: query
name: include
required: false
schema:
type: array
items:
type: string
example: albumStatistics
- description: 'List of barcode IDs (EAN-13 or UPC-A). NOTE: Supplying more than one barcode ID will currently only return one album per barcode ID. (e.g. `196589525444`)'
in: query
name: filter[barcodeId]
required: false
schema:
type: array
items:
type: string
- description: Album id (e.g. `251380836`)
in: query
name: filter[id]
required: false
schema:
type: array
items:
type: string
- description: User id. Use `me` for the authenticated user
in: query
name: filter[owners.id]
required: false
schema:
type: array
items:
type: string
- description: Share code that grants access to UNLISTED resources. When provided, allows non-owners to access resources that would otherwise be restricted.
in: query
name: shareCode
required: false
schema:
type: string
example: xyz
responses:
'200':
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Albums_Multi_Resource_Data_Document'
description: Successful response
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'415':
$ref: '#/components/responses/Default415Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Client_Credentials: []
- Authorization_Code_PKCE:
- r_usr
summary: Get multiple albums.
tags:
- albums
x-path-item-properties:
required-access-tier: THIRD_PARTY
post:
description: Creates a new album.
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/AlbumsCreateOperation_Payload'
responses:
'201':
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Albums_Single_Resource_Data_Document'
description: Successful response
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'409':
$ref: '#/components/responses/Idempotency409Response'
'415':
$ref: '#/components/responses/Default415Response'
'422':
$ref: '#/components/responses/Idempotency422Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Authorization_Code_PKCE:
- w_usr
summary: Create single album.
tags:
- albums
x-path-item-properties:
required-access-tier: INTERNAL
/albums/{id}:
delete:
description: Deletes existing album.
parameters:
- description: Album id
example: '251380836'
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/IdempotencyKey'
responses:
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'409':
$ref: '#/components/responses/Idempotency409Response'
'415':
$ref: '#/components/responses/Default415Response'
'422':
$ref: '#/components/responses/Idempotency422Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Authorization_Code_PKCE:
- w_usr
summary: Delete single album.
tags:
- albums
x-path-item-properties:
required-access-tier: INTERNAL
get:
description: Retrieves single album by id.
parameters:
- description: Album id
example: '251380836'
in: path
name: id
required: true
schema:
type: string
- description: ISO 3166-1 alpha-2 country code
example: US
in: query
name: countryCode
required: false
schema:
type: string
- description: 'Allows the client to customize which related resources should be returned. Available options: albumStatistics, artists, coverArt, genres, items, owners, priceConfig, providers, replacement, shares, similarAlbums, suggestedCoverArts, usageRules'
example: albumStatistics
in: query
name: include
required: false
schema:
type: array
items:
type: string
example: albumStatistics
- description: Share code that grants access to UNLISTED resources. When provided, allows non-owners to access resources that would otherwise be restricted.
in: query
name: shareCode
required: false
schema:
type: string
example: xyz
responses:
'200':
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Albums_Single_Resource_Data_Document'
description: Successful response
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'415':
$ref: '#/components/responses/Default415Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Client_Credentials: []
- Authorization_Code_PKCE: []
summary: Get single album.
tags:
- albums
x-path-item-properties:
required-access-tier: THIRD_PARTY
patch:
description: Updates existing album.
parameters:
- description: Album id
example: '251380836'
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/AlbumsUpdateOperation_Payload'
responses:
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'409':
$ref: '#/components/responses/Idempotency409Response'
'415':
$ref: '#/components/responses/Default415Response'
'422':
$ref: '#/components/responses/Idempotency422Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Authorization_Code_PKCE:
- w_usr
summary: Update single album.
tags:
- albums
x-path-item-properties:
required-access-tier: INTERNAL
/albums/{id}/relationships/albumStatistics:
get:
description: Retrieves albumStatistics relationship.
parameters:
- description: Album id
example: '251380836'
in: path
name: id
required: true
schema:
type: string
- description: 'Allows the client to customize which related resources should be returned. Available options: albumStatistics'
example: albumStatistics
in: query
name: include
required: false
schema:
type: array
items:
type: string
example: albumStatistics
- description: Share code that grants access to UNLISTED resources. When provided, allows non-owners to access resources that would otherwise be restricted.
in: query
name: shareCode
required: false
schema:
type: string
example: xyz
responses:
'200':
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Albums_Single_Relationship_Data_Document'
description: Successful response
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'415':
$ref: '#/components/responses/Default415Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Authorization_Code_PKCE:
- r_usr
summary: Get albumStatistics relationship ("to-one").
tags:
- albums
x-path-item-properties:
required-access-tier: INTERNAL
/albums/{id}/relationships/artists:
get:
description: Retrieves artists relationship.
parameters:
- description: Album id
example: '251380836'
in: path
name: id
required: true
schema:
type: string
- description: Server-generated cursor value pointing a certain page of items. Optional, targets first page if not specified
in: query
name: page[cursor]
required: false
schema:
type: string
- description: ISO 3166-1 alpha-2 country code
example: US
in: query
name: countryCode
required: false
schema:
type: string
- description: 'Allows the client to customize which related resources should be returned. Available options: artists'
example: artists
in: query
name: include
required: false
schema:
type: array
items:
type: string
example: artists
- description: Share code that grants access to UNLISTED resources. When provided, allows non-owners to access resources that would otherwise be restricted.
in: query
name: shareCode
required: false
schema:
type: string
example: xyz
responses:
'200':
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Albums_Multi_Relationship_Data_Document'
description: Successful response
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'415':
$ref: '#/components/responses/Default415Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Client_Credentials: []
- Authorization_Code_PKCE: []
summary: Get artists relationship ("to-many").
tags:
- albums
x-path-item-properties:
required-access-tier: THIRD_PARTY
/albums/{id}/relationships/coverArt:
get:
description: Retrieves coverArt relationship.
parameters:
- description: Album id
example: '251380836'
in: path
name: id
required: true
schema:
type: string
- description: Server-generated cursor value pointing a certain page of items. Optional, targets first page if not specified
in: query
name: page[cursor]
required: false
schema:
type: string
- description: ISO 3166-1 alpha-2 country code
example: US
in: query
name: countryCode
required: false
schema:
type: string
- description: 'Allows the client to customize which related resources should be returned. Available options: coverArt'
example: coverArt
in: query
name: include
required: false
schema:
type: array
items:
type: string
example: coverArt
- description: Share code that grants access to UNLISTED resources. When provided, allows non-owners to access resources that would otherwise be restricted.
in: query
name: shareCode
required: false
schema:
type: string
example: xyz
responses:
'200':
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Albums_Multi_Relationship_Data_Document'
description: Successful response
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'415':
$ref: '#/components/responses/Default415Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Client_Credentials: []
- Authorization_Code_PKCE: []
summary: Get coverArt relationship ("to-many").
tags:
- albums
x-path-item-properties:
required-access-tier: THIRD_PARTY
patch:
description: Updates coverArt relationship.
parameters:
- description: Album id
example: '251380836'
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/AlbumsCoverArtRelationshipUpdateOperation_Payload'
responses:
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'409':
$ref: '#/components/responses/Idempotency409Response'
'415':
$ref: '#/components/responses/Default415Response'
'422':
$ref: '#/components/responses/Idempotency422Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Authorization_Code_PKCE:
- w_usr
summary: Update coverArt relationship ("to-many").
tags:
- albums
x-path-item-properties:
required-access-tier: INTERNAL
/albums/{id}/relationships/genres:
get:
description: Retrieves genres relationship.
parameters:
- description: Album id
example: '251380836'
in: path
name: id
required: true
schema:
type: string
- description: Server-generated cursor value pointing a certain page of items. Optional, targets first page if not specified
in: query
name: page[cursor]
required: false
schema:
type: string
- description: ISO 3166-1 alpha-2 country code
example: US
in: query
name: countryCode
required: false
schema:
type: string
- description: 'Allows the client to customize which related resources should be returned. Available options: genres'
example: genres
in: query
name: include
required: false
schema:
type: array
items:
type: string
example: genres
- description: Share code that grants access to UNLISTED resources. When provided, allows non-owners to access resources that would otherwise be restricted.
in: query
name: shareCode
required: false
schema:
type: string
example: xyz
responses:
'200':
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Albums_Multi_Relationship_Data_Document'
description: Successful response
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'415':
$ref: '#/components/responses/Default415Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Client_Credentials: []
- Authorization_Code_PKCE: []
summary: Get genres relationship ("to-many").
tags:
- albums
x-path-item-properties:
required-access-tier: INTERNAL
/albums/{id}/relationships/items:
get:
description: Retrieves items relationship.
parameters:
- description: Album id
example: '251380836'
in: path
name: id
required: true
schema:
type: string
- description: Server-generated cursor value pointing a certain page of items. Optional, targets first page if not specified
in: query
name: page[cursor]
required: false
schema:
type: string
- description: ISO 3166-1 alpha-2 country code
example: US
in: query
name: countryCode
required: false
schema:
type: string
- description: 'Allows the client to customize which related resources should be returned. Available options: items'
example: items
in: query
name: include
required: false
schema:
type: array
items:
type: string
example: items
- description: Share code that grants access to UNLISTED resources. When provided, allows non-owners to access resources that would otherwise be restricted.
in: query
name: shareCode
required: false
schema:
type: string
example: xyz
responses:
'200':
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Albums_Items_Multi_Relationship_Data_Document'
description: Successful response
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'415':
$ref: '#/components/responses/Default415Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Client_Credentials: []
- Authorization_Code_PKCE: []
summary: Get items relationship ("to-many").
tags:
- albums
x-path-item-properties:
required-access-tier: THIRD_PARTY
patch:
description: Updates items relationship.
parameters:
- description: Album id
example: '251380836'
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/AlbumsItemsRelationshipUpdateOperation_Payload'
responses:
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'409':
$ref: '#/components/responses/Idempotency409Response'
'415':
$ref: '#/components/responses/Default415Response'
'422':
$ref: '#/components/responses/Idempotency422Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Authorization_Code_PKCE:
- w_usr
summary: Update items relationship ("to-many").
tags:
- albums
x-path-item-properties:
required-access-tier: INTERNAL
/albums/{id}/relationships/owners:
get:
description: Retrieves owners relationship.
parameters:
- description: Album id
example: '251380836'
in: path
name: id
required: true
schema:
type: string
- description: 'Allows the client to customize which related resources should be returned. Available options: owners'
example: owners
in: query
name: include
required: false
schema:
type: array
items:
type: string
example: owners
- description: Server-generated cursor value pointing a certain page of items. Optional, targets first page if not specified
in: query
name: page[cursor]
required: false
schema:
type: string
- description: Share code that grants access to UNLISTED resources. When provided, allows non-owners to access resources that would otherwise be restricted.
in: query
name: shareCode
required: false
schema:
type: string
example: xyz
responses:
'200':
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Albums_Multi_Relationship_Data_Document'
description: Successful response
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'415':
$ref: '#/components/responses/Default415Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Client_Credentials: []
- Authorization_Code_PKCE: []
summary: Get owners relationship ("to-many").
tags:
- albums
x-path-item-properties:
required-access-tier: THIRD_PARTY
/albums/{id}/relationships/priceConfig:
get:
description: Retrieves priceConfig relationship.
parameters:
- description: Album id
example: '251380836'
in: path
name: id
required: true
schema:
type: string
- description: ISO 3166-1 alpha-2 country code
example: US
in: query
name: countryCode
required: false
schema:
type: string
- description: 'Allows the client to customize which related resources should be returned. Available options: priceConfig'
example: priceConfig
in: query
name: include
required: false
schema:
type: array
items:
type: string
example: priceConfig
- description: Share code that grants access to UNLISTED resources. When provided, allows non-owners to access resources that would otherwise be restricted.
in: query
name: shareCode
required: false
schema:
type: string
example: xyz
responses:
'200':
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Albums_Single_Relationship_Data_Document'
description: Successful response
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'415':
$ref: '#/components/responses/Default415Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Client_Credentials: []
- Authorization_Code_PKCE: []
summary: Get priceConfig relationship ("to-one").
tags:
- albums
x-path-item-properties:
required-access-tier: INTERNAL
/albums/{id}/relationships/providers:
get:
description: Retrieves providers relationship.
parameters:
- description: Album id
example: '251380836'
in: path
name: id
required: true
schema:
type: string
- description: ISO 3166-1 alpha-2 country code
example: US
in: query
name: countryCode
required: false
schema:
type: string
- description: 'Allows the client to customize which related resources should be returned. Available options: providers'
example: providers
in: query
name: include
required: false
schema:
type: array
items:
type: string
example: providers
- description: Server-generated cursor value pointing a certain page of items. Optional, targets first page if not specified
in: query
name: page[cursor]
required: false
schema:
type: string
- description: Share code that grants access to UNLISTED resources. When provided, allows non-owners to access resources that would otherwise be restricted.
in: query
name: shareCode
required: false
schema:
type: string
example: xyz
responses:
'200':
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Albums_Multi_Relationship_Data_Document'
description: Successful response
'400':
$ref: '#/components/responses/Default400Response'
'404':
$ref: '#/components/responses/Default404Response'
'405':
$ref: '#/components/responses/Default405Response'
'406':
$ref: '#/components/responses/Default406Response'
'415':
$ref: '#/components/responses/Default415Response'
'429':
$ref: '#/components/responses/Default429Response'
'500':
$ref: '#/components/responses/Default500Response'
'503':
$ref: '#/components/responses/Default503Response'
security:
- Client_Credentials: []
- Authorization_Code_PKCE: []
summary: Get providers relationship ("to-many").
tags:
- albums
x-path-item-properties:
required-access-tier: THIRD_PARTY
/albums/{id}/relationships/replacement:
get:
description: Retrieves replacement relationship.
parameters:
- description: Album id
example: '251380836'
in: path
name: id
required: true
schema:
type: string
- description: ISO 3166-1 alpha-2 country code
example: US
in: query
name: countryCode
required: false
schema:
type: string
- description: 'Allows the client to customize which related resources should be returned. Available options: replacement'
example: replacement
in: query
name: include
required: false
schema:
type: array
items:
type: string
example: replacement
- description: Share code that grants access to UNLISTED resources. When provided, allows non-owners to access resources that would otherwise be restricted.
in: query
name: shareCode
required: false
schema:
type: string
# --- truncated at 32 KB (184 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tidal/refs/heads/main/openapi/tidal-albums-api-openapi.yml