Constructor.io Display Ads API

openapi: 3.2.0
info:
  title: Retail Media Display Ads API
  contact:
    email: support@constructor.io
  version: 1.0.0
servers:
- url: https://display.media-cnstrc.com
tags:
- name: Display Ads
paths:
  /v1/display-ads:
    servers:
    - url: https://display.media-cnstrc.com
    get:
      tags:
      - Display Ads
      summary: Retrieve Display Ads (Deprecated)
      description: Retrieves an ad for each of the given placement IDs. If no ad is available for a placement ID, the placement ID will be missing from the response.
      operationId: v1-display-ads-retrieve-display-ads
      deprecated: true
      parameters:
      - name: key
        in: query
        required: true
        schema:
          type: string
          description: The key of the index to use.
          title: Key
        description: The key of the index to use.
      - name: placement_ids
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
          maxItems: 20
          title: Placement IDs
          description: List of placement IDs.
          examples:
          - - home_page
            - mobile_search_results
        description: List of placement IDs.
      - name: query
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search query for keyword targeting.
          examples:
          - apple
          title: Query
        description: Search query for keyword targeting.
      - name: filter_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The name of the related browse filter.
          examples:
          - group_id
          - collection_id
          - color
          title: Filter Name
        description: The name of the related browse filter.
      - name: filter_value
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The value of the related browse filter.
          examples:
          - '123'
          title: Filter Value
        description: The value of the related browse filter.
      responses:
        '200':
          description: Successful Response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisplayAdsResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponse'
      security: []
  /v2/display-ads:
    servers:
    - url: https://display.media-cnstrc.com
    get:
      tags:
      - Display Ads
      summary: Retrieve Display Ads
      description: Retrieves ads for each of the given placements. Each placement maps to a typed response object. Banner placements return a single flattened ad; multi-banner placements return an array of ads ordered by auction rank. If no ad is available for a placement, the placement will be missing from the response. Placements are specified as repeated `placements` query parameters. Optionally, `num_results[{id}]=N` can be used to request a specific number of ads for a placement. When omitted, the placement's configured maximum is used.
      operationId: v2-display-ads-retrieve-display-ads
      parameters:
      - name: key
        in: query
        required: true
        schema:
          type: string
          description: The key of the index to use.
          title: Key
        description: The key of the index to use.
      - name: query
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search query for keyword targeting.
          examples:
          - apple
          title: Query
        description: Search query for keyword targeting.
      - name: filter_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The name of the related browse filter.
          examples:
          - group_id
          - collection_id
          - color
          title: Filter Name
        description: The name of the related browse filter.
      - name: filter_value
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The value of the related browse filter.
          examples:
          - '123'
          title: Filter Value
        description: The value of the related browse filter.
      - name: num_results
        in: query
        description: 'Optional deepObject parameter to request a specific number of ads for each placement. Example: num_results[home_page]=3&num_results[carousel]=1. When omitted, the placement''s configured maximum is used.'
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties:
            type: integer
            minimum: 1
            maximum: 20
      - name: placements
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 20
          description: Placement customer IDs to fetch ads for.
          examples:
          - - home_page
            - carousel
          title: Placements
        description: Placement customer IDs to fetch ads for.
      responses:
        '200':
          description: Successful Response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisplayAdsV2Response'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponse'
      security: []
components:
  schemas:
    PublicErrorResponse:
      properties:
        message:
          type: string
          title: Message
        errors:
          items:
            $ref: '#/components/schemas/PublicErrorDetails'
          type: array
          title: Errors
        trace_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Trace ID
      type: object
      required:
      - message
      - errors
      - trace_id
      title: PublicErrorResponse
    SrcWithPixelDensity:
      properties:
        src:
          type: string
          title: Src
          description: URL of the image.
        pixel_density:
          type: number
          title: Pixel Density
          description: Pixel density at which this image should be used.
        alt_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Alt text
          description: Optional alt text for the image.
      type: object
      required:
      - src
      - pixel_density
      title: SrcWithPixelDensity
    DisplayAdsResponse:
      properties:
        display_ads:
          additionalProperties:
            $ref: '#/components/schemas/DisplayAd'
          type: object
          title: Display Ads
          description: Map of placement IDs to Display Ads. If a placement ID is missing it means that there are no available ads for that placement.
          examples:
          - home_page:
              advertiser: Advertiser Name
              banner_ad_id: AD_ID
              image_banner:
                cta: Ad CTA
                cta_label: Call to action label
                description: Ad Description
                images:
                - media: '(min-width: 1024px)'
                  srcset:
                  - alt_text: An example image
                    pixel_density: 1
                    src: https://example.com/image.jpg
                srcset:
                - pixel_density: 1
                  src: https://example.com/image.jpg
                target_url: https://example.com
                title: Ad Title
      type: object
      required:
      - display_ads
      title: DisplayAdsResponse
    ImageOverride:
      properties:
        media:
          type: string
          title: Media
          description: A media query that must match for this image to be shown.
        srcset:
          items:
            $ref: '#/components/schemas/SrcWithPixelDensity'
          type: array
          title: Srcset
          description: Set of images with their corresponding pixel densities.
      type: object
      required:
      - media
      - srcset
      title: ImageOverride
    ImageBanner:
      properties:
        target_url:
          type: string
          title: Target URL
          description: Target URL of the ad.
        srcset:
          items:
            $ref: '#/components/schemas/SrcWithPixelDensity'
          type: array
          title: Srcset
          description: Main set of images for the ad with their corresponding pixel densities.
        title:
          type: string
          title: Title
          description: Plain text title of the ad.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Optional plain text description of the ad.
        cta:
          anyOf:
          - type: string
          - type: 'null'
          title: CTA
          description: Optional call-to-action for the ad.
        cta_label:
          anyOf:
          - type: string
          - type: 'null'
          title: CTA Label
          description: Optional aria-label for the call-to-action button.
        images:
          items:
            $ref: '#/components/schemas/ImageOverride'
          type: array
          title: Images
          description: Optional list of alternative images for different media conditions.
      type: object
      required:
      - target_url
      - srcset
      - title
      - description
      - cta
      - images
      title: ImageBanner
    MultiPlacementResponse:
      properties:
        type:
          type: string
          const: multi
          title: Type
          description: Ad type discriminator.
        ads:
          items:
            $ref: '#/components/schemas/FlatDisplayAd'
          type: array
          title: Ads
          description: List of ads ordered by auction rank.
      type: object
      required:
      - type
      - ads
      title: MultiPlacementResponse
    PublicErrorDetails:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
      type: object
      required:
      - code
      - message
      - source
      title: PublicErrorDetails
    DisplayAd:
      properties:
        banner_ad_id:
          type: string
          title: Banner Ad ID
          description: Unique identifier of this ad instance for tracking purposes.
        advertiser:
          type: string
          title: Advertiser
          description: Name of the advertiser for compliance and disclosure purposes.
        image_banner:
          anyOf:
          - $ref: '#/components/schemas/ImageBanner'
          - type: 'null'
          description: Image banner to show on the ad - must be checked if it's present before rendering it.
        custom_fields:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Custom Fields
          description: Custom key-value fields associated with the creative.
      type: object
      required:
      - banner_ad_id
      - advertiser
      - image_banner
      title: DisplayAd
    DisplayAdsV2Response:
      properties:
        display_ads:
          additionalProperties:
            oneOf:
            - $ref: '#/components/schemas/BannerPlacementResponse'
            - $ref: '#/components/schemas/MultiPlacementResponse'
            discriminator:
              propertyName: type
              mapping:
                image_banner: '#/components/schemas/BannerPlacementResponse'
                multi: '#/components/schemas/MultiPlacementResponse'
          type: object
          title: Display Ads
          description: Map of placement IDs to placement response objects. Banner placements return a single flattened ad object with type 'image_banner'. Multi-banner placements return an object with type 'multi' and an 'ads' array. If a placement ID is missing it means that there are no available ads for that placement.
          examples:
          - carousel:
              ads:
              - advertiser: Brand B
                banner_ad_id: AD_ID_2
                images: []
                srcset:
                - pixel_density: 1
                  src: https://example.com/image-b.jpg
                target_url: https://example.com/brand-b
                title: Ad Title B
                type: image_banner
              type: multi
            home_page:
              advertiser: Brand A
              banner_ad_id: AD_ID_1
              cta: Shop Now
              cta_label: Shop the sale
              description: Ad Description A
              images: []
              srcset:
              - pixel_density: 1
                src: https://example.com/image-a.jpg
              target_url: https://example.com/brand-a
              title: Ad Title A
              type: image_banner
      type: object
      required:
      - display_ads
      title: DisplayAdsV2Response
    BannerPlacementResponse:
      properties:
        type:
          type: string
          const: image_banner
          title: Type
          description: Ad type discriminator.
        banner_ad_id:
          type: string
          title: Banner Ad ID
          description: Unique identifier of this ad instance for tracking purposes.
        advertiser:
          type: string
          title: Advertiser
          description: Name of the advertiser for compliance and disclosure purposes.
        target_url:
          type: string
          title: Target URL
          description: Target URL of the ad.
        title:
          type: string
          title: Title
          description: Plain text title of the ad.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Optional plain text description of the ad.
        cta:
          anyOf:
          - type: string
          - type: 'null'
          title: CTA
          description: Optional call-to-action for the ad.
        cta_label:
          anyOf:
          - type: string
          - type: 'null'
          title: CTA Label
          description: Optional aria-label for the call-to-action button.
        srcset:
          items:
            $ref: '#/components/schemas/SrcWithPixelDensity'
          type: array
          title: Srcset
          description: Main set of images for the ad with their corresponding pixel densities.
        images:
          items:
            $ref: '#/components/schemas/ImageOverride'
          type: array
          title: Images
          description: Optional list of alternative images for different media conditions.
        custom_fields:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Custom Fields
          description: Custom key-value fields associated with the creative.
      type: object
      required:
      - type
      - banner_ad_id
      - advertiser
      - target_url
      - title
      - description
      - cta
      - srcset
      - images
      title: BannerPlacementResponse
    FlatDisplayAd:
      properties:
        type:
          type: string
          const: image_banner
          title: Type
          description: Ad type discriminator.
        banner_ad_id:
          type: string
          title: Banner Ad ID
          description: Unique identifier of this ad instance for tracking purposes.
        advertiser:
          type: string
          title: Advertiser
          description: Name of the advertiser for compliance and disclosure purposes.
        target_url:
          type: string
          title: Target URL
          description: Target URL of the ad.
        title:
          type: string
          title: Title
          description: Plain text title of the ad.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Optional plain text description of the ad.
        cta:
          anyOf:
          - type: string
          - type: 'null'
          title: CTA
          description: Optional call-to-action for the ad.
        cta_label:
          anyOf:
          - type: string
          - type: 'null'
          title: CTA Label
          description: Optional aria-label for the call-to-action button.
        srcset:
          items:
            $ref: '#/components/schemas/SrcWithPixelDensity'
          type: array
          title: Srcset
          description: Main set of images for the ad with their corresponding pixel densities.
        images:
          items:
            $ref: '#/components/schemas/ImageOverride'
          type: array
          title: Images
          description: Optional list of alternative images for different media conditions.
        custom_fields:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Custom Fields
          description: Custom key-value fields associated with the creative.
      type: object
      required:
      - type
      - banner_ad_id
      - advertiser
      - target_url
      - title
      - description
      - cta
      - srcset
      - images
      title: FlatDisplayAd
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
x-readme:
  explorer-enabled: false