openapi: 3.0.3
info:
  title: Audiomack Data Artist Music 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.
paths:
  /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.
components:
  parameters:
    Fields:
      in: query
      name: fields
      schema:
        type: string
      description: Comma-separated list of fields to include (sparse fieldsets), e.g. `id,title,artist:name`.
    Key:
      in: query
      name: key
      schema:
        type: string
      description: Optional consumer key for unauthenticated read access.
    Genre:
      in: path
      name: genre
      required: true
      schema:
        type: string
      description: Audiomack genre slug (e.g. `hip-hop-rap`, `afrobeats`, `reggae`, `electronic`).
    Limit:
      in: query
      name: limit
      schema:
        type: integer
        default: 20
      description: Maximum results to return. Pass `0` to return all results.
    MusicId:
      in: path
      name: id
      required: true
      schema:
        type: string
      description: Audiomack music identifier.
    ArtistSlug:
      in: path
      name: slug
      required: true
      schema:
        type: string
      description: Artist slug (e.g. `drake`).
  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.