openapi: 3.1.0
info:
  title: GumGum Contextual API
  version: '1.0'
  x-generated: '2026-08-01'
  x-method: generated
  x-source: >-
    Generated faithfully from the published GumGum Contextual Documentation Center
    (https://gumgum.jira.com/wiki/spaces/VDC) — specifically the Get Started - Page API
    (pages/1712095256), Get Started - Video API (pages/1712029924), API Reference
    (pages/1712030855), Page API Reference (pages/1780285512), Image API Reference
    (pages/1780187188), Text API Reference (pages/1780187198) and JSON Response Reference
    (pages/1724743813) pages. GumGum does not publish an OpenAPI description. Every path,
    method, parameter, response field, and status code below is transcribed from those pages.
    The host was verified by probing it on 2026-08-01 (GET https://verity-api.gumgum.com/page/classify
    with no API key returns HTTP 403 with the JSON body {"message":"Forbidden"}; unmatched
    paths return HTTP 403 {"message":"Missing Authentication Token"} — the AWS API Gateway
    signature). No operation, field, or value was invented; where the documentation does not
    enumerate a request body's fields, the schema is left open and annotated rather than guessed.
  description: >-
    The GumGum Contextual API (formerly Verity) returns content-level contextual classification,
    brand safety/suitability and sentiment analysis for web pages, video (including audio),
    individual video frames (intravideo), images and raw text. Analysis is asynchronous: a
    request is submitted, the service returns a UUID, and results are retrieved either by
    polling or by supplying a callback URL that GumGum POSTs the finished analysis to. Results
    include IAB Content Taxonomy categories (v1, v2 and v3), extracted keywords, named entities,
    a brand-safety boolean, detected threats and sentiment scores.
  contact:
    name: GumGum Partner Support
    url: https://gumgum.jira.com/wiki/spaces/VDC/pages/1728217585
    email: support@gumgum.com
  termsOfService: https://gumgum.com/terms-and-policies
  x-documentation: https://gumgum.jira.com/wiki/spaces/VDC
servers:
  - url: https://verity-api.gumgum.com
    description: Production GumGum Contextual API host
security:
  - apiKeyHeader: []
tags:
  - name: Page
    description: Contextual classification and brand-safety analysis of a web page URL.
  - name: Video
    description: Contextual classification and brand-safety analysis of a video asset, including its audio track.
  - name: Intravideo
    description: Frame-level (intravideo) classification of a video asset. Version 2 of the video classification surface.
  - name: Image
    description: Contextual classification, keyword and threat analysis of a single image.
  - name: Text
    description: Contextual classification, keyword and brand-safety analysis of a raw block of text.
paths:
  /page/classify:
    get:
      operationId: classifyPage
      summary: Classify a web page
      description: >-
        Submit a properly formed web page URL for contextual and brand-safety analysis. GumGum
        Contextual first checks whether results for the URL are already in its database and, if so,
        returns them. Otherwise the request is accepted with status INITIATED and the caller either
        polls this endpoint until status becomes PROCESSED, or supplies callBackUrl to have the
        finished analysis delivered to a webhook endpoint.
      tags:
        - Page
      parameters:
        - name: pageUrl
          in: query
          required: true
          description: The properly formed URL of the web page to classify.
          schema:
            type: string
            format: uri
        - name: callBackUrl
          in: query
          required: false
          description: >-
            Webhook endpoint GumGum Contextual POSTs the completed analysis to, as an alternative
            to polling this endpoint.
          schema:
            type: string
            format: uri
        - name: ignoreCache
          in: query
          required: false
          description: >-
            Bypass stored response data and reprocess the page analysis request rather than
            returning the cached result from the GumGum Contextual database.
          schema:
            type: boolean
      responses:
        '200':
          description: Analysis result, or an acknowledgement that analysis has been initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageClassification'
        '403':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /video/classification:
    post:
      operationId: submitVideoClassification
      summary: Submit a video for classification
      description: >-
        Submit a video asset for contextual, brand-safety and sentiment analysis. The service
        responds 202 with a UUID that identifies the classification job.
      tags:
        - Video
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoClassificationRequest'
      responses:
        '202':
          description: Video accepted for classification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassificationAccepted'
        '403':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /video/classification/{uuid}:
    get:
      operationId: getVideoClassification
      summary: Retrieve video classification results
      description: Retrieve the completed contextual analysis for a previously submitted video.
      tags:
        - Video
      parameters:
        - $ref: '#/components/parameters/uuid'
      responses:
        '200':
          description: Completed video classification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Classification'
        '404':
          description: Results are not yet available, or the UUID is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /video/classification/{uuid}/status:
    get:
      operationId: getVideoClassificationStatus
      summary: Check video classification status
      description: Check the processing status of a submitted video classification job.
      tags:
        - Video
      parameters:
        - $ref: '#/components/parameters/uuid'
      responses:
        '200':
          description: Current processing status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassificationStatus'
        '404':
          description: Status not available, or the UUID is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/video/classification:
    post:
      operationId: submitIntravideoClassification
      summary: Submit a video for intravideo (frame-level) classification
      description: >-
        Version 2 of the video classification surface, documented as the Intravideo API. Submits a
        video asset for frame-level contextual and brand-safety analysis.
      tags:
        - Intravideo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoClassificationRequest'
      responses:
        '202':
          description: Video accepted for intravideo classification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassificationAccepted'
        '403':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/video/classification/{uuid}:
    get:
      operationId: getIntravideoClassification
      summary: Retrieve intravideo classification results
      description: Retrieve the completed frame-level analysis for a previously submitted video.
      tags:
        - Intravideo
      parameters:
        - $ref: '#/components/parameters/uuid'
      responses:
        '200':
          description: Completed intravideo classification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Classification'
        '404':
          description: Results are not yet available, or the UUID is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/video/classification/{uuid}/status:
    get:
      operationId: getIntravideoClassificationStatus
      summary: Check intravideo classification status
      description: Check the processing status of a submitted intravideo classification job.
      tags:
        - Intravideo
      parameters:
        - $ref: '#/components/parameters/uuid'
      responses:
        '200':
          description: Current processing status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassificationStatus'
        '404':
          description: Status not available, or the UUID is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /image/classification:
    post:
      operationId: submitImageClassification
      summary: Submit an image for classification
      description: >-
        Initiate a new image analysis. The documentation states the request specifies the URL of
        the image to be analyzed; the response carries brand-safety, keyword and threat
        categorization data.
      tags:
        - Image
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageClassificationRequest'
      responses:
        '202':
          description: Image accepted for classification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassificationAccepted'
        '403':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /image/classification/{uuid}:
    get:
      operationId: getImageClassification
      summary: Retrieve image classification results
      description: Retrieve the completed image analysis for a previously submitted image.
      tags:
        - Image
      parameters:
        - $ref: '#/components/parameters/uuid'
      responses:
        '200':
          description: Completed image classification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Classification'
        '404':
          description: Results are not yet available, or the UUID is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /image/classification/{uuid}/status:
    get:
      operationId: getImageClassificationStatus
      summary: Check image classification status
      description: Retrieve the processing status of a submitted image analysis request.
      tags:
        - Image
      parameters:
        - $ref: '#/components/parameters/uuid'
      responses:
        '200':
          description: Current processing status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassificationStatus'
        '404':
          description: Status not available, or the UUID is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /text/classification:
    post:
      operationId: submitTextClassification
      summary: Submit text for classification
      description: >-
        Initiate a new text analysis request. The response carries complete brand-safety, keyword
        and categorization analysis data for the analyzed text.
      tags:
        - Text
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextClassificationRequest'
      responses:
        '202':
          description: Text accepted for classification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassificationAccepted'
        '403':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /text/classification/{uuid}:
    get:
      operationId: getTextClassification
      summary: Retrieve text classification results
      description: Return the analyzed text results for a previously submitted request.
      tags:
        - Text
      parameters:
        - $ref: '#/components/parameters/uuid'
      responses:
        '200':
          description: Completed text classification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Classification'
        '404':
          description: Results are not yet available, or the UUID is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /text/classification/{uuid}/status:
    get:
      operationId: getTextClassificationStatus
      summary: Check text classification status
      description: Return the status of the text analysis.
      tags:
        - Text
      parameters:
        - $ref: '#/components/parameters/uuid'
      responses:
        '200':
          description: Current processing status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassificationStatus'
        '404':
          description: Status not available, or the UUID is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-api-key
      description: >-
        API key issued by GumGum, sent on every request as the X-api-key request header.
        Documented at https://gumgum.jira.com/wiki/spaces/VDC/pages/1712095256.
  parameters:
    uuid:
      name: uuid
      in: path
      required: true
      description: The unique identifier the classification service generated for the submitted asset.
      schema:
        type: string
  schemas:
    Error:
      type: object
      description: >-
        Error envelope observed on the production host on 2026-08-01 — for example
        {"message":"Forbidden"} for an unauthenticated call to a real path and
        {"message":"Missing Authentication Token"} for an unmatched path.
      properties:
        message:
          type: string
          description: Human-readable error message.
      required:
        - message
    ClassificationAccepted:
      type: object
      description: Acknowledgement that an asset has been accepted for classification.
      properties:
        uuid:
          type: string
          description: Unique identifier generated by the service for this classification job.
        url:
          type: string
          format: uri
          description: The asset URL supplied on the request.
        acceptedAt:
          type: string
          format: date-time
          description: ISO-8601 formatted timestamp representing when the asset was first accepted.
    ClassificationStatus:
      type: object
      description: >-
        Processing status of a classification job. GumGum documents the application status
        messages for each content type on dedicated Application Status Messages pages
        (Page, Video, Intravideo, Image, Text) rather than enumerating one shared list.
      properties:
        uuid:
          type: string
        status:
          type: string
          description: Application status message, for example INITIATED or PROCESSED.
        dataAvailable:
          type: boolean
          description: Whether the analysis has completed and result data is available.
    VerityData:
      type: object
      description: The contextual analysis payload returned by every GumGum Contextual surface.
      properties:
        iab:
          type: object
          description: IAB Content Taxonomy classifications.
          properties:
            v1:
              type: array
              description: IAB Content Taxonomy v1 categories with scores.
              items:
                type: object
            v2:
              type: array
              description: IAB Content Taxonomy v2 categories with scores.
              items:
                type: object
            v3:
              type: array
              description: IAB Content Taxonomy v3 categories with scores.
              items:
                type: object
        ner:
          type: array
          description: Named entity recognition results.
          items:
            type: object
        keywords:
          type: array
          description: Keywords extracted from the analyzed content.
          items:
            type: object
        safe:
          type: boolean
          description: Brand safety assessment for the analyzed content.
        threats:
          type: array
          description: Detected brand-safety threats with confidence levels.
          items:
            type: object
        sentiments:
          type: array
          description: Emotional tone analysis of the analyzed content.
          items:
            type: object
    Classification:
      type: object
      description: >-
        Completed classification result. The response body format is
        Content-Type application/json; charset=UTF-8.
      properties:
        dataAvailable:
          type: boolean
          description: Whether the analysis is complete and verityData is populated.
        status:
          type: string
          description: Request status, for example INITIATED or PROCESSED.
        uuid:
          type: string
          description: Unique identifier for this classification.
        processedAt:
          type: string
          format: date-time
          description: Timestamp of processing completion.
        expiresAt:
          type: string
          format: date-time
          description: Timestamp at which the stored result expires.
        languageCode:
          type: string
          description: Detected language identifier.
        verityData:
          $ref: '#/components/schemas/VerityData'
    PageClassification:
      allOf:
        - $ref: '#/components/schemas/Classification'
        - type: object
          properties:
            pageUrl:
              type: string
              format: uri
              description: The analyzed page URL.
    VideoClassificationRequest:
      type: object
      description: Video classification submission body.
      properties:
        url:
          type: string
          format: uri
          description: Video url for the asset to process.
        description:
          type: string
          description: Video description from client.
        title:
          type: string
          description: Video title from client.
        languageCode:
          type: string
          description: Video language. Inferred automatically when omitted.
        partnerVideoId:
          type: string
          description: Client's unique video identifier.
        publisherId:
          type: string
          description: Publisher's unique identifier.
        callbackUrl:
          type: string
          format: uri
          description: Webhook endpoint results are delivered to once processing completes.
      required:
        - url
    ImageClassificationRequest:
      type: object
      description: >-
        Image classification submission body. The Image API Reference documents that the request
        specifies the URL of the image to be analyzed; it does not enumerate further fields, so
        none are asserted here.
      properties:
        url:
          type: string
          format: uri
          description: URL of the image to be analyzed.
      required:
        - url
      additionalProperties: true
    TextClassificationRequest:
      type: object
      description: >-
        Text classification submission body. The published Text API Reference does not enumerate
        the request field names, so this schema is deliberately left open rather than guessed —
        see https://gumgum.jira.com/wiki/spaces/VDC/pages/1780187198.
      additionalProperties: true