openapi: 3.0.3
info:
  title: Songstats Enterprise Artists API
  description: The Songstats Enterprise API provides music data analytics for artists, tracks, labels, and collaborators across all major streaming platforms. Endpoints return JSON data including current stats, historic stats, audience details, catalog, activities, and playlist data. Used by music industry professionals to build dashboards, reports, and data-driven tools.
  version: 1.0.0
  contact:
    name: Songstats API Support
    email: api@songstats.com
    url: https://songstats.com/for/developers
  termsOfService: https://songstats.com/terms
servers:
- url: https://api.songstats.com/enterprise/v1
  description: Songstats Enterprise API
security:
- ApiKeyAuth: []
tags:
- name: Artists
paths:
  /artists/info:
    get:
      operationId: getArtistInfo
      summary: Get Artist Info
      description: Returns basic information about an artist
      tags:
      - Artists
      parameters:
      - name: songstats_artist_id
        in: query
        required: false
        schema:
          type: string
        description: Songstats artist ID
      - name: spotify_artist_id
        in: query
        required: false
        schema:
          type: string
        description: Spotify artist ID
      - name: apple_music_artist_id
        in: query
        required: false
        schema:
          type: string
        description: Apple Music artist ID
      responses:
        '200':
          description: Artist information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistInfo'
        '401':
          description: Unauthorized
  /artists/stats:
    get:
      operationId: getArtistCurrentStats
      summary: Get Artist Current Stats
      description: Returns current statistics for an artist filtered by source
      tags:
      - Artists
      parameters:
      - name: songstats_artist_id
        in: query
        required: true
        schema:
          type: string
        description: Songstats artist ID
      - name: source
        in: query
        required: false
        schema:
          type: string
        description: Streaming platform source filter
      responses:
        '200':
          description: Artist current stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistStats'
        '401':
          description: Unauthorized
  /artists/historic_stats:
    get:
      operationId: getArtistHistoricStats
      summary: Get Artist Historic Stats
      description: Returns historical statistics for an artist filtered by source
      tags:
      - Artists
      parameters:
      - name: songstats_artist_id
        in: query
        required: true
        schema:
          type: string
        description: Songstats artist ID
      - name: source
        in: query
        required: false
        schema:
          type: string
        description: Streaming platform source filter
      - name: start_date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Start date for historical data
      - name: end_date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: End date for historical data
      responses:
        '200':
          description: Artist historic stats
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArtistStats'
        '401':
          description: Unauthorized
  /artists/audience:
    get:
      operationId: getArtistAudience
      summary: Get Artist Audience
      description: Returns audience data for an artist
      tags:
      - Artists
      parameters:
      - name: songstats_artist_id
        in: query
        required: true
        schema:
          type: string
        description: Songstats artist ID
      - name: source
        in: query
        required: false
        schema:
          type: string
        description: Streaming platform source filter
      responses:
        '200':
          description: Artist audience data
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
  /artists/audience/details:
    get:
      operationId: getArtistAudienceDetails
      summary: Get Artist Audience Details
      description: Returns detailed audience insights for an artist in a specific country
      tags:
      - Artists
      parameters:
      - name: songstats_artist_id
        in: query
        required: true
        schema:
          type: string
        description: Songstats artist ID
      - name: source
        in: query
        required: false
        schema:
          type: string
        description: Streaming platform source filter
      - name: country_code
        in: query
        required: true
        schema:
          type: string
        description: ISO 3166-1 alpha-2 country code
      responses:
        '200':
          description: Artist audience details
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
  /artists/catalog:
    get:
      operationId: getArtistCatalog
      summary: Get Artist Catalog
      description: Returns the track catalog of an artist ordered by release date
      tags:
      - Artists
      parameters:
      - name: songstats_artist_id
        in: query
        required: true
        schema:
          type: string
        description: Songstats artist ID
      responses:
        '200':
          description: Artist catalog
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
  /artists/search:
    get:
      operationId: searchArtists
      summary: Search Artists
      description: Search for artists by name
      tags:
      - Artists
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Search query
      responses:
        '200':
          description: Artist search results
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
  /artists/top_tracks:
    get:
      operationId: getArtistTopTracks
      summary: Get Artist Top Tracks
      description: Returns the top tracks of an artist sorted by rank type
      tags:
      - Artists
      parameters:
      - name: songstats_artist_id
        in: query
        required: true
        schema:
          type: string
        description: Songstats artist ID
      - name: source
        in: query
        required: false
        schema:
          type: string
        description: Streaming platform source filter
      responses:
        '200':
          description: Artist top tracks
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
  /artists/top_playlists:
    get:
      operationId: getArtistTopPlaylists
      summary: Get Artist Top Playlists
      description: Returns top playlists featuring the artist
      tags:
      - Artists
      parameters:
      - name: songstats_artist_id
        in: query
        required: true
        schema:
          type: string
        description: Songstats artist ID
      - name: source
        in: query
        required: false
        schema:
          type: string
        description: Streaming platform source filter
      responses:
        '200':
          description: Artist top playlists
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
  /artists/activities:
    get:
      operationId: getArtistActivities
      summary: Get Artist Activities
      description: Returns recent activities for an artist
      tags:
      - Artists
      parameters:
      - name: songstats_artist_id
        in: query
        required: true
        schema:
          type: string
        description: Songstats artist ID
      responses:
        '200':
          description: Artist activities
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
  /artists/link_request:
    post:
      operationId: addArtistLinkRequest
      summary: Add Artist Link Request
      description: Request a link to be added to an artist
      tags:
      - Artists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                songstats_artist_id:
                  type: string
                link:
                  type: string
      responses:
        '200':
          description: Link request submitted
        '401':
          description: Unauthorized
    delete:
      operationId: removeArtistLinkRequest
      summary: Remove Artist Link Request
      description: Request a link to be removed from an artist
      tags:
      - Artists
      parameters:
      - name: songstats_artist_id
        in: query
        required: true
        schema:
          type: string
      - name: link
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Link removal request submitted
        '401':
          description: Unauthorized
  /artists/track_request:
    post:
      operationId: addArtistTrackRequest
      summary: Add Artist Track Request
      description: Request for a track to be added to an artist catalog
      tags:
      - Artists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                songstats_artist_id:
                  type: string
                songstats_track_id:
                  type: string
      responses:
        '200':
          description: Track request submitted
        '401':
          description: Unauthorized
    delete:
      operationId: removeArtistTrackRequest
      summary: Remove Artist Track Request
      description: Request for a track to be removed from an artist catalog
      tags:
      - Artists
      parameters:
      - name: songstats_artist_id
        in: query
        required: true
        schema:
          type: string
      - name: songstats_track_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Track removal request submitted
        '401':
          description: Unauthorized
components:
  schemas:
    ArtistInfo:
      type: object
      description: Basic information about a music artist
      properties:
        songstats_artist_id:
          type: string
          description: Songstats internal artist ID
        name:
          type: string
          description: Artist name
        genres:
          type: array
          items:
            type: string
          description: Associated genres
        links:
          type: object
          description: Platform links for the artist
        image_url:
          type: string
          description: Artist image URL
    ArtistStats:
      type: object
      description: Current statistics for an artist across streaming platforms
      properties:
        songstats_artist_id:
          type: string
        source:
          type: string
          description: Streaming platform source (spotify, apple_music, deezer, etc.)
        followers:
          type: integer
          description: Follower count
        monthly_listeners:
          type: integer
          description: Monthly listener count
        playlists_editorial_current:
          type: integer
          description: Current editorial playlist count
        playlists_editorial_total:
          type: integer
          description: Total editorial playlist placements ever
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: API key from the Songstats Enterprise dashboard. Contact api@songstats.com for access.