openapi: 3.0.3
info:
  title: Qobuz Music Albums Tracks 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: Tracks
  description: Track metadata, streaming, and download URL generation
paths:
  /track/get:
    get:
      operationId: trackGet
      summary: Retrieve track metadata
      description: Returns detailed metadata for a single track including ISRC, audio quality specifications, performer details, and availability flags.
      tags:
      - Tracks
      parameters:
      - name: app_id
        in: query
        required: true
        schema:
          type: string
        description: Your Qobuz application identifier
      - name: track_id
        in: query
        required: true
        schema:
          type: integer
        description: Qobuz track identifier
      security:
      - AppId: []
      responses:
        '200':
          description: Track metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Track'
        '404':
          description: Track not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /track/search:
    get:
      operationId: trackSearch
      summary: Search tracks
      description: Search the Qobuz catalog for tracks matching the supplied query string. Returns a paginated list of Track objects.
      tags:
      - Tracks
      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 tracks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /track/getFileUrl:
    get:
      operationId: trackGetFileUrl
      summary: Generate streaming or download URL for a track
      description: "Generates an authenticated streaming or download URL for a track in the specified audio format. Requires a valid user_auth_token (X-User-Auth-Token header) and a signed request.\nThe request_sig is computed as:\n  MD5(intent + \"trackid\" + track_id + \"formatid\" + format_id + request_ts + app_secret)\n\nFormat IDs:\n  5  = MP3 320 kbps CBR\n  6  = FLAC 16-bit/44.1 kHz (CD quality)\n  7  = FLAC 24-bit/96 kHz (Hi-Res)\n  27 = FLAC 24-bit/192 kHz (Hi-Res)"
      tags:
      - Tracks
      parameters:
      - name: app_id
        in: query
        required: true
        schema:
          type: string
        description: Your Qobuz application identifier
      - name: track_id
        in: query
        required: true
        schema:
          type: integer
        description: Qobuz track identifier
      - name: format_id
        in: query
        required: true
        schema:
          type: integer
          enum:
          - 5
          - 6
          - 7
          - 27
        description: Audio format code (5=MP3-320, 6=FLAC-CD, 7=FLAC-HiRes-96kHz, 27=FLAC-HiRes-192kHz)
      - name: intent
        in: query
        required: true
        schema:
          type: string
          enum:
          - stream
          - download
        description: Intended use — stream or download
      - name: request_ts
        in: query
        required: true
        schema:
          type: integer
        description: Current Unix timestamp used in signature
      - name: request_sig
        in: query
        required: true
        schema:
          type: string
        description: MD5 signature authenticating the request
      security:
      - AppId: []
      - UserAuthToken: []
      responses:
        '200':
          description: Streaming or download URL and audio metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUrl'
        '400':
          description: Bad request or invalid signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — invalid or expired auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — subscription does not permit this format
          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'
    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'
    FileUrl:
      type: object
      description: Streaming or download URL for a track
      properties:
        track_id:
          type: integer
        duration:
          type: integer
          description: Track duration in seconds
        url:
          type: string
          format: uri
          description: Authenticated CDN URL for the audio file
        format_id:
          type: integer
          description: Audio format code (5=MP3-320, 6=FLAC-CD, 7=FLAC-HiRes-96kHz, 27=FLAC-HiRes-192kHz)
        mime_type:
          type: string
          example: audio/flac
        sampling_rate:
          type: number
          description: Sampling rate in kHz
        bit_depth:
          type: integer
          description: Bit depth (16 or 24)
        blob:
          type: string
          description: Opaque CDN delivery token
  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