openapi: 3.0.3
info:
  title: Audiomack Data Artist Playlist API
  version: '1.0'
  description: The Audiomack Data API provides programmatic access to Audiomack's music streaming catalog, artists, playlists, charts, search, and authenticated user resources. All requests use HTTPS against https://api.audiomack.com/v1 and authenticated requests are signed with OAuth 1.0a. Response payloads are JSON and most list endpoints support page-based pagination, the `fields` parameter for sparse fieldsets, and a `limit` parameter.
  contact:
    name: Audiomack Business
    url: https://creators.audiomack.com/contact-us
  license:
    name: Audiomack Terms of Service
    url: https://audiomack.com/about/terms-of-service
servers:
- url: https://api.audiomack.com/v1
  description: Production
security:
- oauth1: []
tags:
- name: Playlist
  description: Playlist creation, editing, favoriting, and discovery.
paths:
  /playlist/{genre}/trending:
    get:
      tags:
      - Playlist
      summary: List Trending Playlists By Genre
      operationId: getTrendingPlaylistsByGenre
      parameters:
      - $ref: '#/components/parameters/Genre'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Playlist collection.
  /playlist:
    post:
      tags:
      - Playlist
      summary: Create Playlist
      operationId: createPlaylist
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - title
              - genre
              properties:
                title:
                  type: string
                genre:
                  type: string
                private:
                  type: boolean
                music_id:
                  type: string
                image:
                  type: string
                  format: binary
      responses:
        '201':
          description: Playlist created.
  /playlist/{id}:
    get:
      tags:
      - Playlist
      summary: Get Playlist
      operationId: getPlaylist
      parameters:
      - $ref: '#/components/parameters/PlaylistId'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: Playlist object.
    put:
      tags:
      - Playlist
      summary: Update Playlist
      operationId: updatePlaylist
      parameters:
      - $ref: '#/components/parameters/PlaylistId'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                title:
                  type: string
                genre:
                  type: string
                music_id:
                  type: string
                private:
                  type: boolean
                image:
                  type: string
                  format: binary
      responses:
        '200':
          description: Playlist updated.
    delete:
      tags:
      - Playlist
      summary: Delete Playlist
      operationId: deletePlaylist
      parameters:
      - $ref: '#/components/parameters/PlaylistId'
      responses:
        '204':
          description: Playlist deleted.
  /playlist/{id}/track:
    post:
      tags:
      - Playlist
      summary: Add Track To Playlist
      operationId: addPlaylistTrack
      parameters:
      - $ref: '#/components/parameters/PlaylistId'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - music_id
              properties:
                music_id:
                  type: string
      responses:
        '200':
          description: Track added.
  /playlist/{id}/{music_id}:
    delete:
      tags:
      - Playlist
      summary: Remove Track From Playlist
      operationId: deletePlaylistTrack
      parameters:
      - $ref: '#/components/parameters/PlaylistId'
      - in: path
        name: music_id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Track removed.
  /playlist/{artistSlug}/{playlistSlug}:
    get:
      tags:
      - Playlist
      summary: Get Playlist By Slug
      operationId: getPlaylistBySlug
      parameters:
      - in: path
        name: artistSlug
        required: true
        schema:
          type: string
      - in: path
        name: playlistSlug
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: Playlist object.
  /playlist/{id}/favorite:
    put:
      tags:
      - Playlist
      summary: Favorite Playlist
      operationId: favoritePlaylist
      parameters:
      - $ref: '#/components/parameters/PlaylistId'
      responses:
        '200':
          description: Favorited.
    delete:
      tags:
      - Playlist
      summary: Unfavorite Playlist
      operationId: unfavoritePlaylist
      parameters:
      - $ref: '#/components/parameters/PlaylistId'
      responses:
        '200':
          description: Unfavorited.
  /playlist/{id}/metrics:
    get:
      tags:
      - Playlist
      summary: Get Playlist Metrics
      operationId: getPlaylistMetrics
      parameters:
      - $ref: '#/components/parameters/PlaylistId'
      responses:
        '200':
          description: Metrics response.
components:
  parameters:
    Genre:
      in: path
      name: genre
      required: true
      schema:
        type: string
      description: Audiomack genre slug (e.g. `hip-hop-rap`, `afrobeats`, `reggae`, `electronic`).
    Fields:
      in: query
      name: fields
      schema:
        type: string
      description: Comma-separated list of fields to include (sparse fieldsets), e.g. `id,title,artist:name`.
    PlaylistId:
      in: path
      name: id
      required: true
      schema:
        type: string
      description: Audiomack playlist identifier.
    Limit:
      in: query
      name: limit
      schema:
        type: integer
        default: 20
      description: Maximum results to return. Pass `0` to return all results.
  securitySchemes:
    oauth1:
      type: http
      scheme: OAuth
      description: OAuth 1.0a signed request. Obtain a request token via `POST /v1/request_token`, redirect the user to `https://audiomack.com/oauth/authenticate?oauth_token=...`, then exchange for an access token via `POST /v1/access_token`. Access tokens are valid for one year.