openapi: 3.0.3
info:
  title: Audiomack Data Artist 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: Artist
  description: Artist profiles, uploads, favorites, followers, and pinned items.
paths:
  /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.
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`.
    ArtistSlug:
      in: path
      name: slug
      required: true
      schema:
        type: string
      description: Artist slug (e.g. `drake`).
    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.