openapi: 3.0.3
info:
title: Qobuz Music Albums Search 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: Search
description: Cross-catalog search across all content types
paths:
/catalog/search:
get:
operationId: catalogSearch
summary: Cross-catalog search
description: Searches across all content types (albums, artists, tracks, playlists, articles, focus, stories) and returns aggregated results. Use the limit and offset parameters for pagination within each content-type bucket.
tags:
- Search
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 per content type
- name: offset
in: query
required: false
schema:
type: integer
default: 0
description: Pagination offset
- name: sort
in: query
required: false
schema:
type: string
description: Sort field
- name: order
in: query
required: false
schema:
type: string
enum:
- asc
- desc
description: Sort order
security:
- AppId: []
responses:
'200':
description: Aggregated search results across content types
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResults'
'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
ArtistList:
type: object
description: Paginated list of artists
properties:
limit:
type: integer
offset:
type: integer
total:
type: integer
items:
type: array
items:
$ref: '#/components/schemas/Artist'
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
PlaylistList:
type: object
description: Paginated list of playlists
properties:
limit:
type: integer
offset:
type: integer
total:
type: integer
items:
type: array
items:
$ref: '#/components/schemas/Playlist'
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
Playlist:
type: object
description: Qobuz playlist metadata and tracks
properties:
id:
type: integer
name:
type: string
slug:
type: string
description:
type: string
created_at:
type: integer
description: Unix timestamp of creation
updated_at:
type: integer
description: Unix timestamp of last update
public_at:
type: integer
duration:
type: integer
description: Total duration in seconds
tracks_count:
type: integer
users_count:
type: integer
is_public:
type: boolean
is_collaborative:
type: boolean
is_featured:
type: boolean
owner:
type: object
properties:
id:
type: integer
name:
type: string
images:
type: array
items:
type: string
format: uri
images150:
type: array
items:
type: string
format: uri
images300:
type: array
items:
type: string
format: uri
featured_artists:
type: array
items:
$ref: '#/components/schemas/Artist'
genres:
type: array
items:
$ref: '#/components/schemas/Genre'
stores:
type: array
items:
type: string
tracks:
type: array
items:
$ref: '#/components/schemas/Track'
tracks_ids:
type: array
items:
type: integer
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'
SearchResults:
type: object
description: Aggregated search results across all content types
properties:
query:
type: string
albums:
$ref: '#/components/schemas/AlbumList'
artists:
$ref: '#/components/schemas/ArtistList'
tracks:
$ref: '#/components/schemas/TrackList'
playlists:
$ref: '#/components/schemas/PlaylistList'
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