openapi: 3.1.0
info:
  title: Deezer Public Album User API
  description: Public REST API for the Deezer music streaming service. Catalog endpoints (tracks, albums, artists, playlists, charts, genres, radios, editorial, search) are available unauthenticated; user-scoped endpoints require an OAuth 2.0 access token issued via the Deezer Connect flow.
  version: 1.0.0
servers:
- url: https://api.deezer.com
  description: Deezer public REST API
security: []
tags:
- name: User
paths:
  /user/me:
    get:
      tags:
      - User
      summary: Get the authenticated user
      security:
      - oauth2:
        - basic_access
      responses:
        '200':
          description: User profile
  /user/{id}:
    get:
      tags:
      - User
      summary: Get a user by id
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User
  /user/{id}/playlists:
    get:
      tags:
      - User
      summary: List a user's playlists
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Playlists
    post:
      tags:
      - User
      summary: Create a playlist for the user (OAuth required)
      security:
      - oauth2:
        - manage_library
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - in: query
        name: title
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Playlist id returned
  /user/{id}/tracks:
    get:
      tags:
      - User
      summary: List a user's favorite tracks
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Tracks
  /user/{id}/albums:
    get:
      tags:
      - User
      summary: List a user's favorite albums
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Albums
  /user/{id}/artists:
    get:
      tags:
      - User
      summary: List a user's favorite artists
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Artists
  /user/{id}/history:
    get:
      tags:
      - User
      summary: Get a user's listening history (OAuth required)
      security:
      - oauth2:
        - listening_history
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: History
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://connect.deezer.com/oauth/auth.php
          tokenUrl: https://connect.deezer.com/oauth/access_token.php
          scopes:
            basic_access: Basic profile info
            email: Get user's email address
            offline_access: Long-lived access
            manage_library: Manage user's library
            manage_community: Manage user's community
            delete_library: Delete from user's library
            listening_history: Read listening history