Dolby OptiView Ads

openapi: 3.0.3
info:
  title: OptiView Ads API
  version: v1
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: API key (username) and secret (password).
    orgId:
      type: apiKey
      in: header
      name: x-org-id
      description: Organization identifier.
  schemas: {}
paths:
  /api/v1/channels:
    get:
      description: List all channels with pagination, filtering, and sorting.
      parameters:
      - schema:
          default: 1
          type: integer
          minimum: 1
          maximum: 9007199254740991
        in: query
        name: page
        required: false
        description: Page number to return. The first page is 1.
      - schema:
          default: 20
          type: integer
          minimum: 1
          maximum: 100
        in: query
        name: pageSize
        required: false
        description: Number of items to return per page, between 1 and 100.
      - schema:
          type: string
        in: query
        name: filter
        required: false
        description: Optional RSQL filter expression (for example `status==READY;duration=gt=30`). Each resource exposes its
          own allow-list of filterable fields and operators.
      - schema:
          type: string
        in: query
        name: sort
        required: false
        description: Optional comma-separated list of fields to sort by; prefix a field with `-` for descending order. Defaults
          to newest first (createdAt descending).
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique channel identifier.
                        name:
                          description: Human-readable display name for the channel.
                          type: string
                        timebase:
                          type: string
                          enum:
                          - wallclock
                          - pts
                          - mediatime
                          description: 'Time reference used for scheduling breaks on a channel: `wallclock` (ISO 8601 datetime),
                            `pts` (numeric presentation timestamp) or `mediatime` (seconds from the start of the asset; VOD
                            channels only).'
                        dvrWindowMs:
                          description: DVR (rewind) window in milliseconds, controlling how far back the platform looks for
                            breaks to deliver to players. Defaults to 300000 (5 minutes) when not set.
                          type: integer
                          exclusiveMinimum: true
                          maximum: 9007199254740991
                        adPrefetchMs:
                          description: Ad prefetch window in milliseconds, controlling how far ahead of a break start time
                            the break is delivered to the player. Defaults to 10000 (10 seconds) when not set.
                          type: integer
                          exclusiveMinimum: true
                          maximum: 9007199254740991
                        liveOffsetMs:
                          description: 'Live latency offset in milliseconds: how far the player live playhead trails real
                            time on this channel. Break start times are evaluated against now minus this offset. Defaults
                            to 0 (no offset).'
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        customAssetKey:
                          description: Google Ad Manager (GAM) custom asset key used for the server-guided (SGAI) path. Required
                            for vendor pod breaks. Non-empty when provided; to remove it, delete the SGAI channel integration
                            instead.
                          type: string
                          minLength: 1
                        pollingIdleSeconds:
                          description: Break manifest polling interval in seconds advertised to players when no break is active.
                            Defaults to 10 when not set.
                          type: integer
                          exclusiveMinimum: true
                          maximum: 9007199254740991
                        pollingActiveSeconds:
                          description: Break manifest polling interval in seconds advertised to players during an active break.
                            Defaults to 1 when not set.
                          type: integer
                          exclusiveMinimum: true
                          maximum: 9007199254740991
                        adStartDelay:
                          description: Delay in seconds of played media time before any break may start, emitted at the top
                            level of the break manifest. Enforced player-side. Omitted means 0 (no delay).
                          type: number
                          minimum: 0
                        delivery:
                          minItems: 1
                          type: array
                          items:
                            type: object
                            properties:
                              mode:
                                type: string
                                enum:
                                - sgai
                                - ssai
                                description: 'Ad insertion architecture the player should use: `sgai` or `ssai`.'
                              targeting:
                                description: Player-side match criteria for this rule. The player uses the mode of the first
                                  rule whose targeting matches the current platform; a rule without targeting acts as the
                                  default.
                                type: object
                                properties:
                                  deviceType:
                                    description: Device type this entry targets. When a break provides several variants, the
                                      player selects the one matching the viewer device.
                                    type: string
                                    enum:
                                    - desktop
                                    - tablet
                                    - mobile
                                    - tv
                                additionalProperties: false
                            required:
                            - mode
                            additionalProperties: false
                          description: Ordered delivery steering rules emitted in the break manifest. The player uses the
                            mode (`sgai` or `ssai`) of the first rule whose targeting matches its device type; a rule without
                            targeting acts as the default. Non-empty when provided; when omitted the player defaults to `sgai`.
                        detectionEnabled:
                          type: boolean
                          description: Whether automatic break detection runs for this channel. Read-only on create and update;
                            toggle it via the detection enable/disable endpoints. Defaults to false.
                        createdAt:
                          type: string
                          description: Timestamp when the channel was created, as an ISO 8601 datetime string.
                      required:
                      - id
                      - timebase
                      - detectionEnabled
                      - createdAt
                      additionalProperties: false
                    description: The page of results.
                  pagination:
                    type: object
                    properties:
                      page:
                        type: number
                        description: Page number of this result set. The first page is 1.
                      pageSize:
                        type: number
                        description: Number of items requested per page.
                      total:
                        type: number
                        description: Total number of items matching the query across all pages.
                      totalPages:
                        type: number
                        description: Total number of pages available for the query.
                    required:
                    - page
                    - pageSize
                    - total
                    - totalPages
                    additionalProperties: false
                    description: Pagination metadata for the result set.
                required:
                - data
                - pagination
                additionalProperties: false
    post:
      description: Create a new channel.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  description: Unique channel identifier. Provided by the customer or auto-generated when omitted.
                  type: string
                  minLength: 1
                name:
                  description: Human-readable display name for the channel.
                  type: string
                timebase:
                  type: string
                  enum:
                  - wallclock
                  - pts
                  description: 'Time reference used for scheduling breaks on the channel: `wallclock` (ISO 8601 datetime)
                    or `pts` (numeric presentation timestamp). `mediatime` is only valid for VOD channels.'
                dvrWindowMs:
                  description: DVR (rewind) window in milliseconds, controlling how far back the platform looks for breaks
                    to deliver to players. Defaults to 300000 (5 minutes) when not set.
                  type: integer
                  exclusiveMinimum: true
                  maximum: 9007199254740991
                adPrefetchMs:
                  description: Ad prefetch window in milliseconds, controlling how far ahead of a break start time the break
                    is delivered to the player. Defaults to 10000 (10 seconds) when not set.
                  type: integer
                  exclusiveMinimum: true
                  maximum: 9007199254740991
                liveOffsetMs:
                  description: 'Live latency offset in milliseconds: how far the player live playhead trails real time on
                    this channel. Break start times are evaluated against now minus this offset. Defaults to 0 (no offset).'
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                customAssetKey:
                  description: Google Ad Manager (GAM) custom asset key used for the server-guided (SGAI) path. Required for
                    vendor pod breaks. Non-empty when provided; to remove it, delete the SGAI channel integration instead.
                  type: string
                  minLength: 1
                pollingIdleSeconds:
                  description: Break manifest polling interval in seconds advertised to players when no break is active. Defaults
                    to 10 when not set.
                  type: integer
                  exclusiveMinimum: true
                  maximum: 9007199254740991
                pollingActiveSeconds:
                  description: Break manifest polling interval in seconds advertised to players during an active break. Defaults
                    to 1 when not set.
                  type: integer
                  exclusiveMinimum: true
                  maximum: 9007199254740991
                adStartDelay:
                  description: Delay in seconds of played media time before any break may start, emitted at the top level
                    of the break manifest. Enforced player-side. Omitted means 0 (no delay).
                  type: number
                  minimum: 0
                delivery:
                  minItems: 1
                  type: array
                  items:
                    type: object
                    properties:
                      mode:
                        type: string
                        enum:
                        - sgai
                        - ssai
                        description: 'Ad insertion architecture the player should use: `sgai` or `ssai`.'
                      targeting:
                        description: Player-side match criteria for this rule. The player uses the mode of the first rule
                          whose targeting matches the current platform; a rule without targeting acts as the default.
                        type: object
                        properties:
                          deviceType:
                            description: Device type this entry targets. When a break provides several variants, the player
                              selects the one matching the viewer device.
                            type: string
                            enum:
                            - desktop
                            - tablet
                            - mobile
                            - tv
                    required:
                    - mode
                  description: Ordered delivery steering rules emitted in the break manifest. The player uses the mode (`sgai`
                    or `ssai`) of the first rule whose targeting matches its device type; a rule without targeting acts as
                    the default. Non-empty when provided; when omitted the player defaults to `sgai`.
              required:
              - timebase
      responses:
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique channel identifier.
                  name:
                    description: Human-readable display name for the channel.
                    type: string
                  timebase:
                    type: string
                    enum:
                    - wallclock
                    - pts
                    - mediatime
                    description: 'Time reference used for scheduling breaks on a channel: `wallclock` (ISO 8601 datetime),
                      `pts` (numeric presentation timestamp) or `mediatime` (seconds from the start of the asset; VOD channels
                      only).'
                  dvrWindowMs:
                    description: DVR (rewind) window in milliseconds, controlling how far back the platform looks for breaks
                      to deliver to players. Defaults to 300000 (5 minutes) when not set.
                    type: integer
                    exclusiveMinimum: true
                    maximum: 9007199254740991
                  adPrefetchMs:
                    description: Ad prefetch window in milliseconds, controlling how far ahead of a break start time the break
                      is delivered to the player. Defaults to 10000 (10 seconds) when not set.
                    type: integer
                    exclusiveMinimum: true
                    maximum: 9007199254740991
                  liveOffsetMs:
                    description: 'Live latency offset in milliseconds: how far the player live playhead trails real time on
                      this channel. Break start times are evaluated against now minus this offset. Defaults to 0 (no offset).'
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  customAssetKey:
                    description: Google Ad Manager (GAM) custom asset key used for the server-guided (SGAI) path. Required
                      for vendor pod breaks. Non-empty when provided; to remove it, delete the SGAI channel integration instead.
                    type: string
                    minLength: 1
                  pollingIdleSeconds:
                    description: Break manifest polling interval in seconds advertised to players when no break is active.
                      Defaults to 10 when not set.
                    type: integer
                    exclusiveMinimum: true
                    maximum: 9007199254740991
                  pollingActiveSeconds:
                    description: Break manifest polling interval in seconds advertised to players during an active break.
                      Defaults to 1 when not set.
                    type: integer
                    exclusiveMinimum: true
                    maximum: 9007199254740991
                  adStartDelay:
                    description: Delay in seconds of played media time before any break may start, emitted at the top level
                      of the break manifest. Enforced player-side. Omitted means 0 (no delay).
                    type: number
                    minimum: 0
                  delivery:
                    minItems: 1
                    type: array
                    items:
                      type: object
                      properties:
                        mode:
                          type: string
                          enum:
                          - sgai
                          - ssai
                          description: 'Ad insertion architecture the player should use: `sgai` or `ssai`.'
                        targeting:
                          description: Player-side match criteria for this rule. The player uses the mode of the first rule
                            whose targeting matches the current platform; a rule without targeting acts as the default.
                          type: object
                          properties:
                            deviceType:
                              description: Device type this entry targets. When a break provides several variants, the player
                                selects the one matching the viewer device.
                              type: string
                              enum:
                              - desktop
                              - tablet
                              - mobile
                              - tv
                          additionalProperties: false
                      required:
                      - mode
                      additionalProperties: false
                    description: Ordered delivery steering rules emitted in the break manifest. The player uses the mode (`sgai`
                      or `ssai`) of the first rule whose targeting matches its device type; a rule without targeting acts
                      as the default. Non-empty when provided; when omitted the player defaults to `sgai`.
                  detectionEnabled:
                    type: boolean
                    description: Whether automatic break detection runs for this channel. Read-only on create and update;
                      toggle it via the detection enable/disable endpoints. Defaults to false.
                  createdAt:
                    type: string
                    description: Timestamp when the channel was created, as an ISO 8601 datetime string.
                required:
                - id
                - timebase
                - detectionEnabled
                - createdAt
                additionalProperties: false
  /api/v1/channels/{channelId}:
    get:
      description: Get a channel by ID.
      parameters:
      - schema:
          type: string
        in: path
        name: channelId
        required: true
        description: Identifier of the channel.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique channel identifier.
                  name:
                    description: Human-readable display name for the channel.
                    type: string
                  timebase:
                    type: string
                    enum:
                    - wallclock
                    - pts
                    - mediatime
                    description: 'Time reference used for scheduling breaks on a channel: `wallclock` (ISO 8601 datetime),
                      `pts` (numeric presentation timestamp) or `mediatime` (seconds from the start of the asset; VOD channels
                      only).'
                  dvrWindowMs:
                    description: DVR (rewind) window in milliseconds, controlling how far back the platform looks for breaks
                      to deliver to players. Defaults to 300000 (5 minutes) when not set.
                    type: integer
                    exclusiveMinimum: true
                    maximum: 9007199254740991
                  adPrefetchMs:
                    description: Ad prefetch window in milliseconds, controlling how far ahead of a break start time the break
                      is delivered to the player. Defaults to 10000 (10 seconds) when not set.
                    type: integer
                    exclusiveMinimum: true
                    maximum: 9007199254740991
                  liveOffsetMs:
                    description: 'Live latency offset in milliseconds: how far the player live playhead trails real time on
                      this channel. Break start times are evaluated against now minus this offset. Defaults to 0 (no offset).'
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  customAssetKey:
                    description: Google Ad Manager (GAM) custom asset key used for the server-guided (SGAI) path. Required
                      for vendor pod breaks. Non-empty when provided; to remove it, delete the SGAI channel integration instead.
                    type: string
                    minLength: 1
                  pollingIdleSeconds:
                    description: Break manifest polling interval in seconds advertised to players when no break is active.
                      Defaults to 10 when not set.
                    type: integer
                    exclusiveMinimum: true
                    maximum: 9007199254740991
                  pollingActiveSeconds:
                    description: Break manifest polling interval in seconds advertised to players during an active break.
                      Defaults to 1 when not set.
                    type: integer
                    exclusiveMinimum: true
                    maximum: 9007199254740991
                  adStartDelay:
                    description: Delay in seconds of played media time before any break may start, emitted at the top level
                      of the break manifest. Enforced player-side. Omitted means 0 (no delay).
                    type: number
                    minimum: 0
                  delivery:
                    minItems: 1
                    type: array
                    items:
                      type: object
                      properties:
                        mode:
                          type: string
                          enum:
                          - sgai
                          - ssai
                          description: 'Ad insertion architecture the player should use: `sgai` or `ssai`.'
                        targeting:
                          description: Player-side match criteria for this rule. The player uses the mode of the first rule
                            whose targeting matches the current platform; a rule without targeting acts as the default.
                          type: object
                          properties:
                            deviceType:
                              description: Device type this entry targets. When a break provides several variants, the player
                                selects the one matching the viewer device.
                              type: string
                              enum:
                              - desktop
                              - tablet
                              - mobile
                              - tv
                          additionalProperties: false
                      required:
                      - mode
                      additionalProperties: false
                    description: Ordered delivery steering rules emitted in the break manifest. The player uses the mode (`sgai`
                      or `ssai`) of the first rule whose targeting matches its device type; a rule without targeting acts
                      as the default. Non-empty when provided; when omitted the player defaults to `sgai`.
                  detectionEnabled:
                    type: boolean
                    description: Whether automatic break detection runs for this channel. Read-only on create and update;
                      toggle it via the detection enable/disable endpoints. Defaults to false.
                  createdAt:
                    type: string
                    description: Timestamp when the channel was created, as an ISO 8601 datetime string.
                required:
                - id
                - timebase
                - detectionEnabled
                - createdAt
                additionalProperties: false
    patch:
      description: Update a channel.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Human-readable display name for the channel.
                  type: string
                timebase:
                  type: string
                  enum:
                  - wallclock
                  - pts
                  description: 'Time reference used for scheduling breaks on the channel: `wallclock` (ISO 8601 datetime)
                    or `pts` (numeric presentation timestamp). `mediatime` is only valid for VOD channels.'
                dvrWindowMs:
                  description: DVR (rewind) window in milliseconds, controlling how far back the platform looks for breaks
                    to deliver to players. Defaults to 300000 (5 minutes) when not set.
                  type: integer
                  exclusiveMinimum: true
                  maximum: 9007199254740991
                adPrefetchMs:
                  description: Ad prefetch window in milliseconds, controlling how far ahead of a break start time the break
                    is delivered to the player. Defaults to 10000 (10 seconds) when not set.
                  type: integer
                  exclusiveMinimum: true
                  maximum: 9007199254740991
                liveOffsetMs:
                  description: 'Live latency offset in milliseconds: how far the player live playhead trails real time on
                    this channel. Break start times are evaluated against now minus this offset. Defaults to 0 (no offset).'
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                customAssetKey:
                  description: Google Ad Manager (GAM) custom asset key used for the server-guided (SGAI) path. Required for
                    vendor pod breaks. Non-empty when provided; to remove it, delete the SGAI channel integration instead.
                  type: string
                  minLength: 1
                pollingIdleSeconds:
                  description: Break manifest polling interval in seconds advertised to players when no break is active. Defaults
                    to 10 when not set.
                  type: integer
                  exclusiveMinimum: true
                  maximum: 9007199254740991
                pollingActiveSeconds:
                  description: Break manifest polling interval in seconds advertised to players during an active break. Defaults
                    to 1 when not set.
                  type: integer
                  exclusiveMinimum: true
                  maximum: 9007199254740991
                adStartDelay:
                  description: Delay in seconds of played media time before any break may start, emitted at the top level
                    of the break manifest. Enforced player-side. Omitted means 0 (no delay).
                  type: number
                  minimum: 0
                delivery:
                  nullable: true
                  minItems: 1
                  type: array
                  items:
                    type: object
                    properties:
                      mode:
                        type: string
                        enum:
                        - sgai
                        - ssai
                        description: 'Ad insertion architecture the player should use: `sgai` or `ssai`.'
                      targeting:
                        description: Player-side match criteria for this rule. The player uses the mode of the first rule
                          whose targeting matches the current platform; a rule without targeting acts as the default.
                        type: object
                        properties:
                          deviceType:
                            description: Device type this entry targets. When a break provides several variants, the player
                              selects the one matching the viewer device.
                            type: string
                            enum:
                            - desktop
                            - tablet
                            - mobile
                            - tv
                    required:
                    - mode
                  description: Ordered delivery steering rules emitted in the break manifest. The player uses the mode (`sgai`
                    or `ssai`) of the first rule whose targeting matches its device type; a rule without targeting acts as
                    the default. Non-empty when provided; when omitted the player defaults to `sgai`.
      parameters:
      - schema:
          type: string
        in: path
        name: channelId
        required: true
        description: Identifier of the channel.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique channel identifier.
                  name:
                    description: Human-readable display name for the channel.
                    type: string
                  timebase:
                    type: string
                    enum:
                    - wallclock
                    - pts
                    - mediatime
                    description: 'Time reference used for scheduling breaks on a channel: `wallclock` (ISO 8601 datetime),
                      `pts` (numeric presentation timestamp) or `mediatime` (seconds from the start of the asset; VOD channels
                      only).'
                  dvrWindowMs:
                    description: DVR (rewind) window in milliseconds, controlling how far back the platform looks for breaks
                      to deliver to players. Defaults to 300000 (5 minutes) when not set.
                    type: integer
                    exclusiveMinimum: true
                    maximum: 9007199254740991
                  adPrefetchMs:
                    description: Ad prefetch window in milliseconds, controlling how far ahead of a break start time the break
                      is delivered to the player. Defaults to 10000 (10 seconds) when not set.
           

# --- truncated at 32 KB (4112 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dolby/refs/heads/main/openapi/dolby-optiview-ads-openapi.yml