openapi: 3.0.3
info:
  title: Qobuz Music Albums Artists 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: Artists
  description: Artist metadata retrieval and search
paths:
  /artist/get:
    get:
      operationId: artistGet
      summary: Retrieve artist metadata
      description: Returns detailed metadata for a single artist including biography, image, discography summary, and similar artist IDs.
      tags:
      - Artists
      parameters:
      - name: app_id
        in: query
        required: true
        schema:
          type: string
        description: Your Qobuz application identifier
      - name: artist_id
        in: query
        required: true
        schema:
          type: integer
        description: Qobuz artist identifier
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
        description: Maximum number of albums to include
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
        description: Pagination offset
      - name: extra
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated additional fields (e.g. albums,biography)
      - name: sort
        in: query
        required: false
        schema:
          type: string
        description: Sort field for album list
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
        description: Sort order
      security:
      - AppId: []
      responses:
        '200':
          description: Artist metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Artist'
        '404':
          description: Artist not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /artist/search:
    get:
      operationId: artistSearch
      summary: Search artists
      description: Search the Qobuz catalog for artists matching the supplied query string. Returns a paginated list of Artist objects.
      tags:
      - Artists
      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
      - 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: Paginated list of artists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistList'
        '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'
    Label:
      type: object
      description: Record label
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        albums_count:
          type: integer
    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
    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'
    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