openapi: 3.0.3
info:
  title: Qobuz Music Albums Authentication 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: Authentication
  description: User login and session management
paths:
  /user/login:
    get:
      operationId: userLogin
      summary: Authenticate a user
      description: Authenticates a user with email and password. Returns a user_auth_token that must be supplied in the X-User-Auth-Token header for protected endpoints. The password should be sent as an MD5 hash. Requires app_id.
      tags:
      - Authentication
      parameters:
      - name: app_id
        in: query
        required: true
        description: Your Qobuz application identifier
        schema:
          type: string
      - name: email
        in: query
        required: true
        description: User's email address
        schema:
          type: string
          format: email
      - name: password
        in: query
        required: true
        description: MD5 hash of the user's password
        schema:
          type: string
      responses:
        '200':
          description: Successful authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '400':
          description: Bad request or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — invalid app_id or credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /favorite/getUserFavorites:
    get:
      operationId: favoriteGetUserFavorites
      summary: Retrieve user favorites
      description: Returns the authenticated user's favorited albums, artists, and tracks. Requires a valid user_auth_token.
      tags:
      - Authentication
      parameters:
      - name: app_id
        in: query
        required: true
        schema:
          type: string
        description: Your Qobuz application identifier
      - 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: type
        in: query
        required: false
        schema:
          type: string
          enum:
          - albums
          - artists
          - tracks
        description: Filter favorites by content type
      security:
      - AppId: []
      - UserAuthToken: []
      responses:
        '200':
          description: User's favorites
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFavorites'
        '401':
          description: Unauthorized — invalid or expired auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    UserFavorites:
      type: object
      description: Authenticated user's favorited content
      properties:
        albums:
          $ref: '#/components/schemas/AlbumList'
        artists:
          $ref: '#/components/schemas/ArtistList'
        tracks:
          $ref: '#/components/schemas/TrackList'
    Genre:
      type: object
      description: Music genre
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        color:
          type: string
    User:
      type: object
      description: Qobuz user account details
      properties:
        id:
          type: integer
        publicId:
          type: string
        email:
          type: string
          format: email
        login:
          type: string
        firstname:
          type: string
        lastname:
          type: string
        display_name:
          type: string
        country_code:
          type: string
          example: US
        language_code:
          type: string
          example: en
        zone:
          type: string
        store:
          type: string
        country:
          type: string
        avatar:
          type: string
          format: uri
        creation_date:
          type: string
        subscription:
          $ref: '#/components/schemas/Subscription'
        credential:
          $ref: '#/components/schemas/Credential'
    Subscription:
      type: object
      description: User subscription details
      properties:
        offer:
          type: string
          description: Subscription plan name (e.g. Studio, Sublime)
        periodicity:
          type: string
          description: Billing period (e.g. monthly, yearly)
        start_date:
          type: string
        end_date:
          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
    LoginResponse:
      type: object
      description: Response returned by /user/login on successful authentication
      properties:
        user:
          $ref: '#/components/schemas/User'
        user_auth_token:
          type: string
          description: Authentication token to use in X-User-Auth-Token header
    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'
    Credential:
      type: object
      description: User credential / entitlement details
      properties:
        id:
          type: integer
        label:
          type: string
        description:
          type: string
        parameters:
          type: object
          additionalProperties: true
  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