openapi: 3.0.3
info:
title: Qobuz Music Albums API
description: 'The Qobuz Music API (v0.2) is a REST interface served at https://www.qobuz.com/api.json/0.2 returning JSON responses. It covers user authentication (email/password or token-based with MD5-hashed credentials plus app_id and app_secret), catalog operations (search albums, artists, tracks, and playlists), detailed metadata retrieval, streaming and download URL generation, and user account management.
API access requires a valid Qobuz subscription (Studio or Sublime) and partner credentials (app_id and app_secret) issued by Qobuz. Contact api@qobuz.com to request access.
Request signing for protected endpoints (e.g. track/getFileUrl) uses an MD5 hash of concatenated path parameters, a unix timestamp, and the app_secret.'
version: '0.2'
contact:
name: Qobuz API Support
email: api@qobuz.com
url: https://www.qobuz.com/us-en/discover/apps-partners
termsOfService: http://static.qobuz.com/apps/api/QobuzAPI-TermsofUse.pdf
license:
name: Qobuz API Terms of Use
url: http://static.qobuz.com/apps/api/QobuzAPI-TermsofUse.pdf
servers:
- url: https://www.qobuz.com/api.json/0.2
description: Qobuz REST API v0.2
security:
- AppId: []
tags:
- name: Albums
description: Album metadata retrieval and search
paths:
/album/get:
get:
operationId: albumGet
summary: Retrieve album metadata
description: Returns detailed metadata for a single album including track listing, artist, label, genre, audio quality details, and availability flags.
tags:
- Albums
parameters:
- name: app_id
in: query
required: true
schema:
type: string
description: Your Qobuz application identifier
- name: album_id
in: query
required: true
schema:
type: string
description: Qobuz album identifier
- name: limit
in: query
required: false
schema:
type: integer
default: 1200
description: Maximum number of tracks to include in the response
- name: offset
in: query
required: false
schema:
type: integer
default: 0
description: Pagination offset for track listings
- name: extra
in: query
required: false
schema:
type: string
description: Comma-separated list of additional fields to include (e.g. tracks,artist)
security:
- AppId: []
- UserAuthToken: []
responses:
'200':
description: Album metadata
content:
application/json:
schema:
$ref: '#/components/schemas/Album'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Album not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/album/search:
get:
operationId: albumSearch
summary: Search albums
description: Search the Qobuz catalog for albums matching the supplied query string. Returns a paginated list of Album objects.
tags:
- Albums
parameters:
- name: app_id
in: query
required: true
schema:
type: string
description: Your Qobuz application identifier
- name: query
in: query
required: true
schema:
type: string
description: Search query string
- name: limit
in: query
required: false
schema:
type: integer
default: 50
description: Maximum number of results to return
- name: offset
in: query
required: false
schema:
type: integer
default: 0
description: Pagination offset
security:
- AppId: []
responses:
'200':
description: Paginated list of albums
content:
application/json:
schema:
$ref: '#/components/schemas/AlbumList'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
Genre:
type: object
description: Music genre
properties:
id:
type: integer
name:
type: string
slug:
type: string
color:
type: string
ErrorResponse:
type: object
description: Standard error envelope returned by all endpoints on failure
properties:
status:
type: string
example: error
code:
type: integer
example: 400
message:
type: string
example: Bad Request
TrackList:
type: object
description: Paginated list of tracks
properties:
limit:
type: integer
offset:
type: integer
total:
type: integer
items:
type: array
items:
$ref: '#/components/schemas/Track'
AlbumList:
type: object
description: Paginated list of albums
properties:
limit:
type: integer
offset:
type: integer
total:
type: integer
items:
type: array
items:
$ref: '#/components/schemas/Album'
Image:
type: object
description: Set of image URLs at various resolutions
properties:
small:
type: string
format: uri
medium:
type: string
format: uri
large:
type: string
format: uri
extralarge:
type: string
format: uri
mega:
type: string
format: uri
Label:
type: object
description: Record label
properties:
id:
type: integer
name:
type: string
slug:
type: string
albums_count:
type: integer
Biography:
type: object
description: Artist biography
properties:
summary:
type: string
content:
type: string
source:
type: string
language:
type: string
Artist:
type: object
description: Qobuz artist metadata
properties:
id:
type: integer
name:
type: string
albums_as_primary_artist_count:
type: integer
albums_as_primary_composer_count:
type: integer
albums_count:
type: integer
slug:
type: string
picture:
type: string
format: uri
image:
$ref: '#/components/schemas/Image'
similar_artist_ids:
type: array
items:
type: integer
biography:
$ref: '#/components/schemas/Biography'
album_last_release:
$ref: '#/components/schemas/Album'
albums:
$ref: '#/components/schemas/AlbumList'
Track:
type: object
description: Qobuz track metadata
properties:
id:
type: integer
title:
type: string
version:
type: string
isrc:
type: string
description: International Standard Recording Code
maximum_bit_depth:
type: integer
description: Maximum available bit depth (e.g. 16, 24)
maximum_channel_count:
type: integer
description: Number of audio channels
maximum_sampling_rate:
type: number
description: Maximum sampling rate in kHz (e.g. 44.1, 96.0, 192.0)
performer:
type: object
properties:
id:
type: integer
name:
type: string
performers:
type: string
composer:
type: object
properties:
id:
type: integer
name:
type: string
copyright:
type: string
album:
$ref: '#/components/schemas/Album'
track_number:
type: integer
media_number:
type: integer
release_date_original:
type: string
release_date_download:
type: string
release_date_stream:
type: string
release_date_purchase:
type: string
purchasable:
type: boolean
streamable:
type: boolean
previewable:
type: boolean
sampleable:
type: boolean
downloadable:
type: boolean
displayable:
type: boolean
hires:
type: boolean
hires_streamable:
type: boolean
parental_warning:
type: boolean
duration:
type: integer
description: Track duration in seconds
Album:
type: object
description: Qobuz album metadata
properties:
id:
type: string
qobuz_id:
type: integer
title:
type: string
subtitle:
type: string
version:
type: string
slug:
type: string
url:
type: string
format: uri
released_at:
type: integer
description: Unix timestamp of release
release_date_original:
type: string
release_date_download:
type: string
release_date_stream:
type: string
maximum_bit_depth:
type: integer
maximum_sampling_rate:
type: number
maximum_channel_count:
type: integer
hires:
type: boolean
hires_streamable:
type: boolean
purchasable:
type: boolean
streamable:
type: boolean
previewable:
type: boolean
sampleable:
type: boolean
downloadable:
type: boolean
displayable:
type: boolean
parental_warning:
type: boolean
artist:
$ref: '#/components/schemas/Artist'
label:
$ref: '#/components/schemas/Label'
genre:
$ref: '#/components/schemas/Genre'
description:
type: string
description_language:
type: string
catchline:
type: string
copyright:
type: string
recording_information:
type: string
upc:
type: string
description: Universal Product Code
popularity:
type: number
tracks_count:
type: integer
media_count:
type: integer
duration:
type: integer
description: Total album duration in seconds
tracks:
$ref: '#/components/schemas/TrackList'
image:
$ref: '#/components/schemas/Image'
securitySchemes:
AppId:
type: apiKey
in: query
name: app_id
description: Qobuz application identifier issued to partners
UserAuthToken:
type: apiKey
in: header
name: X-User-Auth-Token
description: User authentication token obtained from /user/login