Gracenote Entitlements API

openapi: 3.2.0
info:
  version: 3.0 Beta
  title: GMD API v3.0 Beta Entitlements API
  description: Gracenote Global Music Data (GMD) API V3.0 **Beta** Specification. Interfaces are subject to change.
servers:
- url: https://api.gmd.music.gracenote.com/v3
security:
- ApiKeyAuth: []
tags:
- name: Entitlements
  description: 'Entitlements represent authorization levels, determining the specific data access granted

    to a user based on their API key. All valid API keys are provisioned with the ''base'' package at least.

    API keys may have additional packages and addOns assigned to them, granting extended functionality.'
paths:
  /entitlements/lookup:
    get:
      tags:
      - Entitlements
      summary: Lookup Entitlements
      description: Lookup Entitlements licensed to the user's API Key. The API Key mentioned in the Request Header will be used to fetch its related entitlements.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                  data:
                    type: array
                    nullable: false
                    items:
                      $ref: '#/components/schemas/EntitlementsObject'
                required:
                - meta
                - data
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '429':
          $ref: '#/components/responses/ErrorResponse429'
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
      operationId: getEntitlementsLookup
      x-operation-id-source: derived
components:
  responses:
    ErrorResponse401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              value:
                status: 401
                error: unauthorized_missing_apikey
                description: API key is required.
    ErrorResponse429:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              value:
                status: 429
                error: rate_limit_exceeded
                description: Number of queries per minute exceeds limit.
  schemas:
    EntitlementsObject:
      title: entitlements object
      nullable: false
      type: object
      additionalProperties: false
      properties:
        addOns:
          type: array
          description: Add Ons licensed to the user's API Key.
          items:
            type: string
        packages:
          nullable: false
          type: array
          description: Packages licensed to the user's API Key.
          items:
            type: string
      required:
      - addOns
      - packages
      examples:
      - "{\n  \"addOns\": [\n    \"coverArt\",\n    \"apple-track-id\",\n    \"spotify-track-id\",\n    \"apple-album-id\",\n    \"spotify-album-id\",\n    \"tms-id\",\n    \"ISRC\",\n    \"UPC\",\n    \"styles\",\n    \"artist-image\",\n    \"cover-art\"\n],\n  \"packages\": [\n    \"base\",\n    \"search\",\n    \"advancedDiscovery\"\n]\n}\n"
    ResponseMeta:
      title: meta object
      type: object
      additionalProperties: false
      nullable: false
      properties:
        total:
          type: integer
          nullable: false
          description: Total data objects for the query criteria
        count:
          type: integer
          nullable: false
          description: Count of objects in the returned result set
        offset:
          type: integer
          nullable: false
          description: Current offset for result set
        references:
          type: object
          additionalProperties: false
          properties:
            genreList:
              type: string
              description: Hierarchical Genre List used for response.
            displayLanguage:
              type: string
              description: Display language used for descriptor strings.
      required:
      - total
      - count
      - offset
      examples:
      - total: 1
        count: 1
        offset: 0
        references:
          genreList: GENRES-US-DETAILED
          displayLanguage: en
    ErrorResponse:
      title: error response
      type: object
      additionalProperties: false
      nullable: false
      properties:
        status:
          type: integer
          nullable: false
        error:
          type: string
          nullable: false
          enum:
          - page_not_found
          - resource_not_found
          - invalid_query_parameter_key
          - invalid_query_parameter_value
          - missing_query_parameter_key
          - resource_type_error
          - internal_server_error
          - unauthorized_invalid_api_key
          - unauthorized_missing_api_key
          - missing_api_key
          - rate_limit_exceeded
          - missing_entitlement
        description:
          type: string
          nullable: false
      required:
      - status
      - error
      - description
  parameters:
    apiKeyParam:
      name: GN-APIKEY
      in: header
      description: API key to authorize the request.
      required: true
      schema:
        type: string
        examples:
        - your-api-key
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      description: API key provided during registration
      name: GN-APIKEY