openapi: 3.0.3
info:
  title: 7digital Artists API
  description: The classic 7digital REST API (v1.2) provides access to the 7digital music catalogue (artists, releases, tracks, tags), user lockers, basket/checkout, payment, editorial, territories and IP-lookup. All operations are signed with OAuth 1.0 and scoped by a consumer key issued under a commercial agreement.
  version: '1.2'
  contact:
    name: 7digital / MassiveMusic Client Success
    url: https://docs.massivemusic.com/docs/support
  license:
    name: Commercial — 7digital / MassiveMusic
    url: https://docs.massivemusic.com/docs/sla
  x-last-validated: '2026-05-28'
  x-generated-from: documentation
  x-source-url: https://github.com/7digital/7digital-api/blob/master/assets/7digital-api-schema.json
servers:
- url: https://api.7digital.com/1.2
  description: 7digital Public API v1.2 (production)
security:
- oauth1: []
tags:
- name: Artists
  description: Browse, search, chart, and resolve 7digital artists and their releases.
paths:
  /artist/browse:
    get:
      operationId: browseArtists
      summary: 7digital Browse Artists
      description: Browse artists in the 7digital catalogue whose names start with the given letter(s).
      tags:
      - Artists
      parameters:
      - name: letter
        in: query
        required: true
        description: The starting letter or letters to browse by (e.g. `A`, `Be`).
        schema:
          type: string
        example: B
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paged list of artists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/chart:
    get:
      operationId: getArtistChart
      summary: 7digital Get Artist Chart
      description: Get the current artist chart for a given period and territory.
      tags:
      - Artists
      parameters:
      - $ref: '#/components/parameters/Country'
      - $ref: '#/components/parameters/Period'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A chart of artists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/details:
    get:
      operationId: getArtistDetails
      summary: 7digital Get Artist Details
      description: Get all available metadata for an artist by 7digital artist id.
      tags:
      - Artists
      parameters:
      - $ref: '#/components/parameters/ArtistId'
      responses:
        '200':
          description: Artist metadata payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistDetailsResponse'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/releases:
    get:
      operationId: getArtistReleases
      summary: 7digital Get Artist Releases
      description: List releases by a given artist, optionally filtered by release type (album, single, etc.).
      tags:
      - Artists
      parameters:
      - $ref: '#/components/parameters/ArtistId'
      - $ref: '#/components/parameters/ReleaseType'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of releases by the artist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/similar:
    get:
      operationId: getSimilarArtists
      summary: 7digital Get Similar Artists
      description: List artists similar to the seed artist.
      tags:
      - Artists
      parameters:
      - $ref: '#/components/parameters/ArtistId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of similar artists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/search:
    get:
      operationId: searchArtists
      summary: 7digital Search Artists
      description: Free-text search the 7digital catalogue for artists matching a query.
      tags:
      - Artists
      parameters:
      - $ref: '#/components/parameters/Query'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paged list of matching artists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/topTracks:
    get:
      operationId: getArtistTopTracks
      summary: 7digital Get Artist Top Tracks
      description: List the top-streamed tracks by an artist.
      tags:
      - Artists
      parameters:
      - $ref: '#/components/parameters/ArtistId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of top tracks by the artist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/tags:
    get:
      operationId: getArtistTags
      summary: 7digital Get Artist Tags
      description: Get the tags / genre labels applied to an artist.
      tags:
      - Artists
      parameters:
      - $ref: '#/components/parameters/ArtistId'
      responses:
        '200':
          description: A list of tags for the artist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/match/byId:
    get:
      operationId: matchArtistById
      summary: 7digital Match Artist By Id
      description: Match an artist in a partner system to the 7digital artist using an external identifier (e.g. MusicBrainz id).
      tags:
      - Artists
      security:
      - oauth1_two_legged: []
      parameters:
      - name: id
        in: query
        required: true
        description: External artist identifier to match.
        schema:
          type: string
        example: mbid:5b11f4ce-a62d-471e-81fc-a69a8278c7da
      responses:
        '200':
          description: A matched artist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistDetailsResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/bytag/top:
    get:
      operationId: getTopArtistsByTags
      summary: 7digital Get Top Artists By Tags
      description: List top-performing artists for a given tag or set of tags.
      tags:
      - Artists
      parameters:
      - $ref: '#/components/parameters/Tags'
      - $ref: '#/components/parameters/Country'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of top artists for the tag(s).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    Tags:
      name: tags
      in: query
      required: true
      description: One or more tag identifiers, comma-separated.
      schema:
        type: string
      example: rock,indie
    ReleaseType:
      name: type
      in: query
      description: Release type filter.
      schema:
        type: string
        enum:
        - album
        - single
        - ep
        - compilation
      example: album
    Page:
      name: page
      in: query
      description: 1-based page number for paged endpoints.
      schema:
        type: integer
        minimum: 1
        default: 1
      example: 1
    ArtistId:
      name: artistId
      in: query
      required: true
      description: 7digital artist id.
      schema:
        type: string
      example: '12345'
    Country:
      name: country
      in: query
      description: ISO 3166-1 alpha-2 country code for the sales territory.
      schema:
        type: string
        minLength: 2
        maxLength: 2
      example: GB
    Query:
      name: q
      in: query
      required: true
      description: Free-text search query.
      schema:
        type: string
      example: beatles
    Period:
      name: period
      in: query
      description: Chart period — typically `day`, `week`, `month`, `year`.
      schema:
        type: string
        enum:
        - day
        - week
        - month
        - year
      example: week
    PageSize:
      name: pageSize
      in: query
      description: Number of items per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      example: 20
  schemas:
    Tag:
      type: object
      description: A genre/tag label.
      properties:
        id:
          type: string
          example: rock
        name:
          type: string
          example: Rock
        parentId:
          type: string
          nullable: true
          example: null
    Release:
      type: object
      description: A 7digital release (album, single, EP, compilation).
      properties:
        id:
          type: string
          description: 7digital release id.
          example: '11700062'
        title:
          type: string
          description: Release title.
          example: Abbey Road
        version:
          type: string
          description: Release version (e.g. `Remastered`).
          example: Remastered
        type:
          type: string
          enum:
          - album
          - single
          - ep
          - compilation
          example: album
        artist:
          $ref: '#/components/schemas/Artist'
        url:
          type: string
          format: uri
          example: https://uk.7digital.com/artist/the-beatles/release/abbey-road-11700062
        image:
          type: string
          format: uri
          example: https://artwork-cdn.7static.com/static/img/sleeveart/00/117/000/0011700062_350.jpg
        releaseDate:
          type: string
          format: date
          example: '1969-09-26'
        label:
          type: string
          example: Apple Records
        explicit:
          type: boolean
          example: false
        upc:
          type: string
          description: Universal Product Code (UPC/EAN).
          example: 00602445912025
        price:
          $ref: '#/components/schemas/Price'
    Track:
      type: object
      description: A 7digital track.
      properties:
        id:
          type: string
          description: 7digital track id.
          example: '123456'
        title:
          type: string
          description: Track title.
          example: Come Together
        version:
          type: string
          description: Track version (e.g. `Remastered 2019`).
          example: Remastered 2019
        artist:
          $ref: '#/components/schemas/Artist'
        release:
          $ref: '#/components/schemas/Release'
        trackNumber:
          type: integer
          description: Track number on the release.
          example: 1
        duration:
          type: integer
          description: Duration in seconds.
          example: 259
        explicit:
          type: boolean
          example: false
        isrc:
          type: string
          description: International Standard Recording Code.
          example: GBAYE6900477
        previewUrl:
          type: string
          format: uri
          description: URL for the 30-second preview clip.
          example: https://previews.7digital.com/clip/123456
        price:
          $ref: '#/components/schemas/Price'
    ArtistDetailsResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        artist:
          $ref: '#/components/schemas/Artist'
    TagListResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    ErrorResponse:
      type: object
      description: Standard 7digital error envelope.
      properties:
        status:
          type: string
          description: Always `error` on a failure.
          example: error
        error:
          type: object
          properties:
            code:
              type: integer
              description: 7digital error code (1xxx input, 2xxx resource, 3xxx user, 7xxx app, 9xxx server).
              example: 2001
            message:
              type: string
              description: Human-readable error message.
              example: Resource not found
            errors:
              type: array
              description: Per-item errors for batch requests (code 1008).
              items:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
                  index:
                    type: integer
    ReleaseListResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        page:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 20
        totalItems:
          type: integer
          example: 42
        releases:
          type: array
          items:
            $ref: '#/components/schemas/Release'
    Artist:
      type: object
      description: A 7digital artist.
      properties:
        id:
          type: string
          description: 7digital artist id.
          example: '12345'
        name:
          type: string
          description: Artist name.
          example: The Beatles
        url:
          type: string
          format: uri
          description: Artist page URL on 7digital.
          example: https://uk.7digital.com/artist/the-beatles
        image:
          type: string
          format: uri
          description: Artist image URL.
          example: https://artwork-cdn.7static.com/static/img/artistimages/00/000/012/0000001234_350.jpg
        sortName:
          type: string
          description: Sort form of the artist name.
          example: Beatles, The
        appearsAs:
          type: string
          description: Alternative spellings under which the artist appears.
          example: Beatles, The
    Price:
      type: object
      description: A price quoted in the requested territory's currency.
      properties:
        formattedPrice:
          type: string
          example: £9.99
        amount:
          type: number
          description: Numeric price value.
          example: 9.99
        currency:
          type: string
          description: ISO 4217 currency code.
          example: GBP
    TrackListResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        page:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 20
        totalItems:
          type: integer
          example: 13
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/Track'
    ArtistListResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        page:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 20
        totalItems:
          type: integer
          example: 42
        artists:
          type: array
          items:
            $ref: '#/components/schemas/Artist'
  responses:
    NotFoundError:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    oauth1:
      type: apiKey
      in: query
      name: oauth_consumer_key
      description: 7digital uses OAuth 1.0 signing. Every request MUST include `oauth_consumer_key` as either a query parameter or in the Authorization header. Sensitive operations require a 2-legged or 3-legged signature with a user access token.
    oauth1_two_legged:
      type: apiKey
      in: query
      name: oauth_consumer_key
      description: 2-legged OAuth 1.0 (partner-scoped — consumer key + secret only).
    oauth1_three_legged:
      type: apiKey
      in: query
      name: oauth_consumer_key
      description: 3-legged OAuth 1.0 (consumer key + secret plus a user access token + secret).