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