Gracenote Export API

openapi: 3.2.0
info:
  title: GN IDS API v1.9.3 Export API
  description: 'The purpose of this application is to provide an API to create, retrieve, update, delete,

    and publish client programs.'
  version: 1.9.3
servers:
- url: /proxy/gnids/api/v1
tags:
- name: Export
paths:
  /bulk/programs/exports:
    get:
      tags:
      - Export
      summary: Returns a paginated collection of exports in a source's catalog
      description: it provides information for all exports to a source with current export statuses
      operationId: getExports
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
      - name: limit
        in: query
        required: true
        schema:
          maximum: 1000
          minimum: 1
          type: integer
          format: int64
      - name: page
        in: query
        required: true
        schema:
          minimum: 1
          type: integer
          format: int64
      - name: sortField
        in: query
        description: Field by which to sort batches by.
        schema:
          type: string
          default: updated
          enum:
          - created
          - updated
      - name: sortDirection
        in: query
        description: Direction by which to sort the search results.
        schema:
          type: string
          default: DESC
          enum:
          - ASC
          - asc
          - DESC
          - desc
      responses:
        '200':
          description: ExportsResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportsResponse'
        '400':
          description: BadRequestError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - request body must not be empty
                  error:
                    type: string
                    examples:
                    - bad_request
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 400
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - authentication failed
                  error:
                    type: string
                    examples:
                    - unauthorized
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 401
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - 'cannot use title language "cs": not entitled'
                  error:
                    type: string
                    examples:
                    - forbidden
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 403
        '500':
          description: InternalServerError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - internal server error
                  error:
                    type: string
                    examples:
                    - internal_server_error
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 500
      security:
      - api_key: []
    post:
      tags:
      - Export
      summary: creates a new export with user provided filters
      description: An Export is a user provided filter and context information that will be used by batch to fetch programs based on provided criteria
      operationId: createExport
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewExport'
        required: false
      responses:
        '200':
          description: ExportResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportResponse'
        '400':
          description: BadRequestValidationError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - see fields for details.
                  error:
                    type: string
                    examples:
                    - bad_request
                  fields:
                    type: object
                    additionalProperties:
                      type: object
                      additionalProperties:
                        type: string
                    examples:
                    - subType:
                        error: subType is a required field
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 400
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - authentication failed
                  error:
                    type: string
                    examples:
                    - unauthorized
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 401
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - 'cannot use title language "cs": not entitled'
                  error:
                    type: string
                    examples:
                    - forbidden
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 403
        '413':
          description: RequestEntityTooLargeError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - request size exceeds 25MB limit
                  error:
                    type: string
                    examples:
                    - request_entity_too_large
                  instance:
                    type: string
                    examples:
                    - /api/v1/bulk/movies/batches
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 413
        '415':
          description: UnsupportedMediaError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - request body contains badly-formed JSON
                  error:
                    type: string
                    examples:
                    - unsupported_media_type
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 415
        '500':
          description: InternalServerError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - internal server error
                  error:
                    type: string
                    examples:
                    - internal_server_error
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 500
        '598':
          description: RequestReadTimeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - request read timed out
                  error:
                    type: string
                    examples:
                    - request_read_timeout
                  instance:
                    type: string
                    examples:
                    - /api/v1/bulk/movies/batches
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 598
      security:
      - api_key: []
      x-codegen-request-body-name: newExport
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
  /bulk/programs/exports/{gnID}:
    get:
      tags:
      - Export
      description: Fetches an export by its GNID
      operationId: getExportByGnID
      responses:
        '200':
          description: ExportResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportResponse'
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - authentication failed
                  error:
                    type: string
                    examples:
                    - unauthorized
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 401
        '404':
          description: NotFoundError
          content:
            application/json:
              schema:
                type: object
                properties:
                  Meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - '"foo-bar"'
                  code:
                    type: integer
                    format: int64
                  description:
                    type: string
                  error:
                    type: string
        '500':
          description: InternalServerError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - internal server error
                  error:
                    type: string
                    examples:
                    - internal_server_error
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 500
      security:
      - api_key: []
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
      summary: Get export by gn ID
      x-summary-source: derived
  /bulk/programs/exports/{gnID}/results:
    get:
      tags:
      - Export
      summary: Fetches the results for an export by its GNID
      description: Page and limit are required parameters to fetch the results
      operationId: getExportByGnID
      responses:
        '200':
          description: ExportResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportResponse'
        '400':
          description: BadRequestError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - request body must not be empty
                  error:
                    type: string
                    examples:
                    - bad_request
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 400
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - authentication failed
                  error:
                    type: string
                    examples:
                    - unauthorized
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 401
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - 'cannot use title language "cs": not entitled'
                  error:
                    type: string
                    examples:
                    - forbidden
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 403
        '404':
          description: NotFoundError
          content:
            application/json:
              schema:
                type: object
                properties:
                  Meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - '"foo-bar"'
                  code:
                    type: integer
                    format: int64
                  description:
                    type: string
                  error:
                    type: string
        '500':
          description: InternalServerError
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    examples:
                    - internal server error
                  error:
                    type: string
                    examples:
                    - internal_server_error
                  instance:
                    type: string
                    examples:
                    - /api/v1/shows
                  meta:
                    type: object
                    properties:
                      rayID:
                        type: string
                        examples:
                        - 52fdfc07-2182-454f-963f-5f0f9a621d72
                  status:
                    type: integer
                    format: int64
                    examples:
                    - 500
      security:
      - api_key: []
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
components:
  schemas:
    Export:
      title: Export represents an export request.
      type: object
      properties:
        context:
          $ref: '#/components/schemas/Context'
        filter:
          $ref: '#/components/schemas/Filter'
        created:
          type: string
          description: Export creation timestamp.
          readOnly: true
        gnID:
          type: string
          description: The Gracenote ID of the export.
          readOnly: true
        status:
          type: string
          description: 'The status for the export. Possible values: waiting, inProgress, succeeded, failed.

            Note: If an export fails but has not reached the maximum retry limit (3 attempts),

            the status will be returned as ''inProgress'' to indicate it will be retried automatically.

            Only when retry_count >= 3 will the status be returned as ''failed''.'
          readOnly: true
          enum:
          - waiting
          - inProgress
          - succeeded
          - failed
        updated:
          type: string
          description: The timestamp when Export was last updated.
          readOnly: true
    Context:
      title: Context contains the user defined context to store/return alongside the export.
      type: object
      additionalProperties:
        type: string
    Filter:
      title: Filter contains the fields which can be used to filter programs,
      type: object
      properties:
        catalogGnIDs:
          type: array
          description: 'CatalogGnIDs to filter programs by


            in: query'
          items:
            type: string
          examples:
          - - GN1
            - GN2
        externalIDs:
          type: array
          description: 'ExternalIDs to filter programs by.


            in: query'
          items:
            type: string
          examples:
          - - EP123
            - SH123
            - MV123
        genres:
          type: array
          description: 'Genres to filter programs by.


            in: query'
          items:
            type: string
          examples:
          - - Adventure
            - Fantasy
        publishStatus:
          type: array
          description: 'PublishingStatuses to filter programs by. Valid values may be

            found in the Gracenote Vocabulary.


            in: query'
          items:
            type: string
          examples:
          - - registered
            - published
        subTypes:
          type: array
          description: 'SubTypes to filter programs by.


            in: query'
          items:
            type: string
          examples:
          - - episode
        title:
          type: string
          description: 'The raw string value of a title to filter programs by.


            in: query'
          examples:
          - '"Rings of Power: Speculative Episode Title"'
        tmsIDs:
          type: array
          description: 'TMSIDs to filter programs by.


            in: query'
          items:
            type: string
          examples:
          - - EP123
            - SH123
            - MV123
        types:
          type: array
          description: 'Program types to filter programs by.


            in: query'
          items:
            type: string
          examples:
          - - episode
      description: while generating the export results.
    NewExport:
      title: NewExport contains the required fields for creating a new export.
      type: object
      properties:
        context:
          $ref: '#/components/schemas/Context'
        filter:
          $ref: '#/components/schemas/Filter'
    ExportResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Export'
        meta:
          $ref: '#/components/schemas/MetaResponse'
    ExportsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Export'
        meta:
          $ref: '#/components/schemas/MetaResponse'
    MetaResponse:
      required:
      - rayID
      type: object
      properties:
        count:
          type: integer
          description: Count is the number of records included a Data field.
          format: int64
        limit:
          type: integer
          description: Limit is the maximum requested number of objects returned by the request.
          format: int64
        page:
          type: integer
          description: Page is the page number containing the objects in the response.
          format: int64
        rayID:
          type: string
          description: 'RayID is the backend id of the request, generated at invocation time.

            Any questions or bug reports about a particular invocation should include the returned RequestID.'
        total:
          type: integer
          description: Total is the total number of hits on a query before pagination.
          format: int64
      description: MetaResponse describes response data
  parameters:
    apiKeyParam:
      name: GN-APIKEY
      in: header
      description: API key to authorize the request.
      required: true
      schema:
        type: string
        examples:
        - your-api-key
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: GN-APIKEY
      description: API key to authorize the request. Click Authorize and paste the key created for your application.
x-original-swagger-version: '2.0'