openapi: 3.0.3
info:
  title: Audiomack Data 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: Music
    description: Songs, albums, streaming, favorites, reposts, and metrics.
  - name: Artist
    description: Artist profiles, uploads, favorites, followers, and pinned items.
  - name: Playlist
    description: Playlist creation, editing, favoriting, and discovery.
  - name: Chart
    description: Aggregate song, album, and playlist charts across timeframes and genres.
  - name: Search
    description: Free-text search and autosuggest across music, albums, and artists.
  - name: Stats
    description: Tokenised view and play event reporting.
  - name: User
    description: Authenticated user profile, feed, uploads, playlists, and notifications.
  - name: OAuth
    description: OAuth 1.0a request-token and access-token exchanges.
paths:
  /request_token:
    post:
      tags: [OAuth]
      summary: Obtain Request Token
      description: Issue an unauthorised OAuth 1.0a request token. Supply an `oauth_callback` parameter. Request tokens are valid for one hour.
      operationId: postRequestToken
      responses:
        '200':
          description: Request token issued.
  /access_token:
    post:
      tags: [OAuth]
      summary: Exchange Access Token
      description: Exchange an authorised OAuth request token for a long-lived access token. Access tokens expire one year after issuance.
      operationId: postAccessToken
      responses:
        '200':
          description: Access token issued.
  /music/{id}:
    get:
      tags: [Music]
      summary: Get Music By Id
      description: Retrieve song or album metadata by Audiomack music ID.
      operationId: getMusicById
      parameters:
        - $ref: '#/components/parameters/MusicId'
        - $ref: '#/components/parameters/Key'
      responses:
        '200':
          description: Music object.
  /music/{type}/{artist}/{slug}:
    get:
      tags: [Music]
      summary: Get Music By Slug
      description: Retrieve a song or album by artist slug and music slug.
      operationId: getMusicBySlug
      parameters:
        - in: path
          name: type
          required: true
          schema:
            type: string
            enum: [song, album]
        - $ref: '#/components/parameters/ArtistSlug'
        - in: path
          name: slug
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/Key'
      responses:
        '200':
          description: Music object.
    patch:
      tags: [Music]
      summary: Flag Music Unplayable
      description: Report a song or album as unplayable.
      operationId: patchMusicBySlug
      parameters:
        - in: path
          name: type
          required: true
          schema:
            type: string
            enum: [song, album]
        - $ref: '#/components/parameters/ArtistSlug'
        - in: path
          name: slug
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum: [unplayable]
      responses:
        '200':
          description: Status updated.
  /music/preview/{id}:
    get:
      tags: [Music]
      summary: Get Music Preview
      description: Fetch the preview audio resource for a given music ID.
      operationId: getMusicPreview
      parameters:
        - $ref: '#/components/parameters/MusicId'
      responses:
        '200':
          description: Preview metadata.
  /music/recent:
    get:
      tags: [Music]
      summary: List Recent Music
      description: List most recently uploaded music.
      operationId: getRecentMusic
      parameters:
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Music collection.
  /music/{genre}/recent:
    get:
      tags: [Music]
      summary: List Recent Music By Genre
      description: List most recently uploaded music for a specific genre (e.g. `hip-hop-rap`, `afrobeats`).
      operationId: getRecentMusicByGenre
      parameters:
        - $ref: '#/components/parameters/Genre'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Music collection.
  /music/trending:
    get:
      tags: [Music]
      summary: List Trending Music
      description: List trending music across all genres.
      operationId: getTrendingMusic
      parameters:
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Music collection.
  /music/{genre}/trending:
    get:
      tags: [Music]
      summary: List Trending Music By Genre
      description: List trending music for a specific genre.
      operationId: getTrendingMusicByGenre
      parameters:
        - $ref: '#/components/parameters/Genre'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Music collection.
  /music/{id}/play:
    post:
      tags: [Music]
      summary: Get Music Stream Url
      description: Request a streaming URL for a music resource. The returned URL is valid for approximately 10 seconds.
      operationId: postMusicPlay
      parameters:
        - $ref: '#/components/parameters/MusicId'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                session:
                  type: string
                album_id:
                  type: string
                playlist_id:
                  type: string
                hq:
                  type: boolean
                key:
                  type: string
      responses:
        '200':
          description: Stream URL response.
  /music/{id}/ads:
    post:
      tags: [Music]
      summary: Record Music Ad Event
      description: Track an advertisement event for a music resource.
      operationId: postMusicAd
      parameters:
        - $ref: '#/components/parameters/MusicId'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                status:
                  type: string
      responses:
        '200':
          description: Ad event recorded.
  /music/{id}/favorite:
    put:
      tags: [Music]
      summary: Favorite Music
      operationId: favoriteMusic
      parameters:
        - $ref: '#/components/parameters/MusicId'
      responses:
        '200':
          description: Favorited.
    delete:
      tags: [Music]
      summary: Unfavorite Music
      operationId: unfavoriteMusic
      parameters:
        - $ref: '#/components/parameters/MusicId'
      responses:
        '200':
          description: Unfavorited.
  /music/{id}/repost:
    put:
      tags: [Music]
      summary: Repost Music
      operationId: repostMusic
      parameters:
        - $ref: '#/components/parameters/MusicId'
      responses:
        '200':
          description: Reposted.
    delete:
      tags: [Music]
      summary: Remove Music Repost
      operationId: deleteMusicRepost
      parameters:
        - $ref: '#/components/parameters/MusicId'
      responses:
        '200':
          description: Repost removed.
  /music/{id}/metrics:
    get:
      tags: [Music]
      summary: Get Music Metrics
      description: Retrieve play and engagement metrics for a music resource.
      operationId: getMusicMetrics
      parameters:
        - $ref: '#/components/parameters/MusicId'
      responses:
        '200':
          description: Metrics response.
  /artist/{slug}:
    get:
      tags: [Artist]
      summary: Get Artist
      description: Retrieve artist profile and aggregate statistics.
      operationId: getArtist
      parameters:
        - $ref: '#/components/parameters/ArtistSlug'
      responses:
        '200':
          description: Artist object.
  /artist/{slug}/uploads:
    get:
      tags: [Artist]
      summary: List Artist Uploads
      operationId: getArtistUploads
      parameters:
        - $ref: '#/components/parameters/ArtistSlug'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Uploads collection.
  /artist/{slug}/favorites:
    get:
      tags: [Artist]
      summary: List Artist Favorites
      operationId: getArtistFavorites
      parameters:
        - $ref: '#/components/parameters/ArtistSlug'
        - in: query
          name: show
          schema:
            type: string
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Favorites collection.
  /artist/{slug}/favorites/search:
    get:
      tags: [Artist]
      summary: Search Artist Favorites
      operationId: searchArtistFavorites
      parameters:
        - $ref: '#/components/parameters/ArtistSlug'
        - in: query
          name: q
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Favorites matching query.
  /artist/{slug}/playlists:
    get:
      tags: [Artist]
      summary: List Artist Playlists
      operationId: getArtistPlaylists
      parameters:
        - $ref: '#/components/parameters/ArtistSlug'
        - in: query
          name: genre
          schema:
            type: string
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Playlists collection.
  /artist/{slug}/follow:
    put:
      tags: [Artist]
      summary: Follow Artist
      operationId: followArtist
      parameters:
        - $ref: '#/components/parameters/ArtistSlug'
      responses:
        '200':
          description: Followed.
    delete:
      tags: [Artist]
      summary: Unfollow Artist
      operationId: unfollowArtist
      parameters:
        - $ref: '#/components/parameters/ArtistSlug'
      responses:
        '200':
          description: Unfollowed.
  /artist/{slug}/following:
    get:
      tags: [Artist]
      summary: List Artist Following
      operationId: getArtistFollowing
      parameters:
        - $ref: '#/components/parameters/ArtistSlug'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Artists this artist follows.
  /artist/{slug}/follows:
    get:
      tags: [Artist]
      summary: List Artist Followers
      operationId: getArtistFollowers
      parameters:
        - $ref: '#/components/parameters/ArtistSlug'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Followers collection.
  /artist/{slug}/feed:
    get:
      tags: [Artist]
      summary: Get Artist Feed
      operationId: getArtistFeed
      parameters:
        - $ref: '#/components/parameters/ArtistSlug'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Activity feed.
  /artist/{id}/metrics:
    get:
      tags: [Artist]
      summary: Get Artist Metrics
      description: Retrieve artist-level metrics plus top 10 tracks metrics.
      operationId: getArtistMetrics
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Metrics response.
  /artist/{slug}/pinned:
    get:
      tags: [Artist]
      summary: Get Artist Pinned
      operationId: getArtistPinned
      parameters:
        - $ref: '#/components/parameters/ArtistSlug'
      responses:
        '200':
          description: Pinned items.
    post:
      tags: [Artist]
      summary: Add Artist Pinned
      operationId: addArtistPinned
      parameters:
        - $ref: '#/components/parameters/ArtistSlug'
      responses:
        '200':
          description: Pinned items added.
    put:
      tags: [Artist]
      summary: Update Artist Pinned
      operationId: updateArtistPinned
      parameters:
        - $ref: '#/components/parameters/ArtistSlug'
      responses:
        '200':
          description: Pinned items updated.
    delete:
      tags: [Artist]
      summary: Remove Artist Pinned
      operationId: removeArtistPinned
      parameters:
        - $ref: '#/components/parameters/ArtistSlug'
      responses:
        '200':
          description: Pinned items removed.
  /chart/{kind}/{type}:
    get:
      tags: [Chart]
      summary: Get Chart
      description: Retrieve songs, albums, or playlists chart for a given timeframe (total, daily, weekly, monthly, yearly).
      operationId: getChart
      parameters:
        - in: path
          name: kind
          required: true
          schema:
            type: string
            enum: [songs, albums, playlists]
        - in: path
          name: type
          required: true
          schema:
            type: string
            enum: [total, daily, weekly, monthly, yearly]
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Chart entries.
  /{genre}/chart/{kind}/{type}:
    get:
      tags: [Chart]
      summary: Get Chart By Genre
      description: Retrieve a chart restricted to a genre such as `hip-hop-rap` or `afrobeats`.
      operationId: getChartByGenre
      parameters:
        - $ref: '#/components/parameters/Genre'
        - in: path
          name: kind
          required: true
          schema:
            type: string
            enum: [songs, albums, playlists]
        - in: path
          name: type
          required: true
          schema:
            type: string
            enum: [total, daily, weekly, monthly, yearly]
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Chart entries.
  /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.
  /search:
    get:
      tags: [Search]
      summary: Search Audiomack
      description: Search across music, albums, and artists with optional genre and verified filters.
      operationId: search
      parameters:
        - in: query
          name: q
          required: true
          schema:
            type: string
        - in: query
          name: show
          schema:
            type: string
        - in: query
          name: sort
          schema:
            type: string
        - in: query
          name: page
          schema:
            type: integer
        - in: query
          name: limit
          schema:
            type: integer
        - in: query
          name: genre
          schema:
            type: string
        - in: query
          name: verified
          schema:
            type: boolean
      responses:
        '200':
          description: Search results.
  /search_autosuggest:
    get:
      tags: [Search]
      summary: Autosuggest Search
      operationId: searchAutosuggest
      parameters:
        - in: query
          name: q
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Autosuggest results.
  /music/stats/token:
    get:
      tags: [Stats]
      summary: Get Stats Token
      description: Request a one-shot token used to authorise a subsequent stats event.
      operationId: getStatsToken
      parameters:
        - in: query
          name: device
          schema:
            type: string
        - in: query
          name: music_id
          schema:
            type: string
      responses:
        '200':
          description: Stats token issued.
  /music/stats/{music_id}:
    post:
      tags: [Stats]
      summary: Record Stats Event
      description: Record a view or play event using a previously issued stats token.
      operationId: postStatsEvent
      parameters:
        - in: path
          name: music_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [token, type]
              properties:
                token:
                  type: string
                type:
                  type: string
                  enum: [view, play]
      responses:
        '200':
          description: Event recorded.
  /user:
    get:
      tags: [User]
      summary: Get Authenticated User
      operationId: getUser
      responses:
        '200':
          description: Current user.
  /user/register:
    post:
      tags: [User]
      summary: Register User
      operationId: registerUser
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [email, artist_name, password, password2]
              properties:
                email:
                  type: string
                  format: email
                artist_name:
                  type: string
                password:
                  type: string
                  format: password
                password2:
                  type: string
                  format: password
      responses:
        '201':
          description: User registered.
  /user/forgot-password:
    post:
      tags: [User]
      summary: Forgot Password
      operationId: forgotPassword
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
      responses:
        '200':
          description: Password reset email sent.
  /user/playlists:
    get:
      tags: [User]
      summary: List User Playlists
      description: List authenticated user's playlists including private ones.
      operationId: getUserPlaylists
      parameters:
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Playlists collection.
  /user/favorites:
    get:
      tags: [User]
      summary: List User Favorites
      operationId: getUserFavorites
      parameters:
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Favorites collection.
  /user/feed:
    get:
      tags: [User]
      summary: Get User Feed
      operationId: getUserFeed
      parameters:
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Activity feed.
  /user/uploads:
    get:
      tags: [User]
      summary: List User Uploads
      operationId: getUserUploads
      parameters:
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Uploads collection.
  /user/native-notifications:
    get:
      tags: [User]
      summary: List User Notifications
      operationId: getUserNotifications
      parameters:
        - in: query
          name: only_unseen
          schema:
            type: boolean
        - in: query
          name: limit
          schema:
            type: integer
        - in: query
          name: paging_token
          schema:
            type: string
      responses:
        '200':
          description: Notifications collection.
  /user/native-notifications/seen:
    post:
      tags: [User]
      summary: Mark Notifications Seen
      operationId: markNotificationsSeen
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                for_all:
                  type: boolean
      responses:
        '200':
          description: Notifications updated.
components:
  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.
  parameters:
    MusicId:
      in: path
      name: id
      required: true
      schema:
        type: string
      description: Audiomack music identifier.
    PlaylistId:
      in: path
      name: id
      required: true
      schema:
        type: string
      description: Audiomack playlist identifier.
    ArtistSlug:
      in: path
      name: slug
      required: true
      schema:
        type: string
      description: Artist slug (e.g. `drake`).
    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`.
    Limit:
      in: query
      name: limit
      schema:
        type: integer
        default: 20
      description: Maximum results to return. Pass `0` to return all results.
    Key:
      in: query
      name: key
      schema:
        type: string
      description: Optional consumer key for unauthenticated read access.