# This OpenAPI specification is auto-generated
# DO NOT EDIT THIS FILE MANUALLY
# API Type: BUYER
# API Version: V2

openapi: 3.0.0
info:
  title: Scope3 Buyer API
  version: 2.0.0
  description: |-
    REST API for advertisers to manage advertisers, campaigns, and reporting.

    ## Authentication

    All endpoints require a Bearer token in the Authorization header:
    ```
    Authorization: Bearer your-api-key
    ```

    ## Base URL

    `https://api.interchange.io/api/v2/buyer`

    ## For AI Agents

    AI agents can use the MCP endpoint at `/mcp/v2/buyer` with three tools:
    - `initialize`: Start an MCP session
    - `api_call`: Make REST API calls
    - `ask_about_capability`: Learn about API features
servers:
  - url: https://api.interchange.io/api/v2/buyer
    description: Production server
  - url: https://api.staging.interchange.io/api/v2/buyer
    description: Staging server
tags:
  - name: Account
    description: Account management, service tokens, and preferences
  - name: Advertisers
    description: Manage advertisers
  - name: Product Discovery
    description: Discover and select products
  - name: Campaigns
    description: Manage advertising campaigns
  - name: Creatives
    description: Build, manage, and sync campaign creatives via AdCP Creative Protocol
  - name: Reporting
    description: Access performance metrics
  - name: Property Lists
    description: Validate property lists against AAO registry
  - name: Sales Agents
    description: View and connect sales agents
  - name: Measurement
    description: Measurement sources, records, context, and freshness
  - name: Syndication
    description: Syndicate resources to ADCP agents
  - name: Tasks
    description: Track async operation status
  - name: Buyer Billing
    description: Consolidated invoicing for buyers — invoices and pending invoice items issued by Scope3 across the buyer customer.
  - name: MCP
    description: Model Context Protocol endpoints for AI agents
paths:
  /advertisers:
    get:
      operationId: listAdvertisers
      summary: List advertisers
      description: List all advertisers with optional filtering and pagination.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: status
          schema:
            description: Filter by advertiser status. Use ALL to include both active and archived. Defaults to ACTIVE.
            default: ACTIVE
            type: string
            enum:
              - ACTIVE
              - ARCHIVED
              - ALL
          description: Filter by advertiser status. Use ALL to include both active and archived. Defaults to ACTIVE.
        - in: query
          name: name
          schema:
            description: Filter by advertiser name (case-insensitive, partial match)
            example: Acme
            type: string
          description: Filter by advertiser name (case-insensitive, partial match)
        - in: query
          name: sandbox
          schema:
            description: >-
              Filter by sandbox mode. true returns only sandbox advertisers, false returns only production advertisers.
              Omit to return all.
            type: boolean
          description: >-
            Filter by sandbox mode. true returns only sandbox advertisers, false returns only production advertisers.
            Omit to return all.
        - in: query
          name: limit
          schema:
            description: 'Maximum number of advertisers to return per page (default: 100, max: 100)'
            example: 100
            default: 100
            type: integer
            exclusiveMinimum: true
            maximum: 100
          description: 'Maximum number of advertisers to return per page (default: 100, max: 100)'
        - in: query
          name: offset
          schema:
            description: 'Number of advertisers to skip for pagination (default: 0)'
            example: 0
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: 'Number of advertisers to skip for pagination (default: 0)'
      responses:
        '200':
          description: List advertisers
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createAdvertiser
      summary: Create advertiser
      description: Create a new advertiser. Advertisers are the top-level entity for campaigns.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAdvertiserBody'
      responses:
        '201':
          description: Create advertiser
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}:
    get:
      operationId: getAdvertiser
      summary: Get advertiser
      description: Get a single advertiser by ID. Always returns full brand details including the ADCP manifest.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: Get advertiser
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateAdvertiser
      summary: Update advertiser
      description: Update an existing advertiser.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAdvertiserBody'
      responses:
        '200':
          description: Update advertiser
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteAdvertiser
      summary: Delete advertiser
      description: Delete (archive) an advertiser.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '204':
          description: No content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /discovery/discover-products:
    post:
      operationId: discoverProducts
      summary: Discover products
      description: >-
        Discover products with automatic session creation. If discoveryId is not provided, a new session is created
        automatically. Returns discoveryId and discovered products.
      tags:
        - Product Discovery
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/DiscoverProductsBody'
      responses:
        '200':
          description: Discover products
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoverProductsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /discovery/{discoveryId}/discover-products:
    get:
      operationId: browseProducts
      summary: Browse products for discovery session
      description: >-
        Browse available products for an existing discovery session. Returns product suggestions grouped by publisher
        with pagination support.
      tags:
        - Product Discovery
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: groupLimit
          schema:
            description: 'Maximum number of product groups to return (default: 10, max: 10)'
            example: 10
            default: 10
            type: integer
            exclusiveMinimum: true
            maximum: 10
          description: 'Maximum number of product groups to return (default: 10, max: 10)'
        - in: query
          name: groupOffset
          schema:
            description: Number of groups to skip for pagination
            example: 0
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: Number of groups to skip for pagination
        - in: query
          name: productsPerGroup
          schema:
            description: 'Maximum products to return per group (default: 10, max: 15)'
            example: 10
            default: 10
            type: integer
            exclusiveMinimum: true
            maximum: 15
          description: 'Maximum products to return per group (default: 10, max: 15)'
        - in: query
          name: productOffset
          schema:
            description: 'Number of products to skip within each group (default: 0, max: 1000)'
            example: 5
            default: 0
            type: integer
            minimum: 0
            maximum: 1000
          description: 'Number of products to skip within each group (default: 0, max: 1000)'
        - in: query
          name: publisherDomain
          schema:
            description: Filter products by publisher domain (exact domain component match)
            example: hulu
            type: string
            minLength: 1
          description: Filter products by publisher domain (exact domain component match)
        - in: query
          name: pricingModel
          schema:
            description: Filter products by pricing model
            example: cpm
            type: string
            enum:
              - cpm
              - vcpm
              - cpc
              - cpcv
              - cpv
              - cpp
              - flat_rate
          description: Filter products by pricing model
        - in: query
          name: storefrontIds
          schema:
            description: Filter products by storefront ID(s) (from `list_storefronts`).
            example:
              - 42
              - 57
            anyOf:
              - maxItems: 50
                type: array
                items:
                  type: integer
                  exclusiveMinimum: true
                  maximum: 9007199254740991
              - type: string
          description: Filter products by storefront ID(s) (from `list_storefronts`).
        - in: query
          name: storefrontNames
          schema:
            description: Filter products by storefront name (case-insensitive substring match).
            example:
              - Acme
              - Acme Exchange
            anyOf:
              - maxItems: 50
                type: array
                items:
                  type: string
                  maxLength: 255
              - type: string
          description: Filter products by storefront name (case-insensitive substring match).
        - in: query
          name: debug
          schema:
            description: When true, includes detailed ADCP agent request/response debug logs in the response for troubleshooting
            anyOf:
              - type: boolean
              - type: string
          description: When true, includes detailed ADCP agent request/response debug logs in the response for troubleshooting
        - in: path
          name: discoveryId
          schema:
            description: Discovery ID
            example: abc123-def456-ghi789
            type: string
            minLength: 1
          required: true
          description: Discovery ID
      responses:
        '200':
          description: Browse products for discovery session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoverProductsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /discovery/{discoveryId}/products:
    get:
      operationId: getProducts
      summary: Get selected products
      description: Get the list of products that have been selected in this discovery session.
      tags:
        - Product Discovery
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: discoveryId
          schema:
            description: Discovery ID
            example: abc123-def456-ghi789
            type: string
            minLength: 1
          required: true
          description: Discovery ID
      responses:
        '200':
          description: Get selected products
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionProductsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: addProducts
      summary: Add products to selection
      description: >-
        Add products to the selection. Products must have been discovered via GET
        /discovery/{discoveryId}/discover-products first.
      tags:
        - Product Discovery
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: discoveryId
          schema:
            description: Discovery ID
            example: abc123-def456-ghi789
            type: string
            minLength: 1
          required: true
          description: Discovery ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddProductsRequest'
      responses:
        '200':
          description: Add products to selection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionProductsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: removeProducts
      summary: Remove products from selection
      description: Remove products from the selection.
      tags:
        - Product Discovery
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: discoveryId
          schema:
            description: Discovery ID
            example: abc123-def456-ghi789
            type: string
            minLength: 1
          required: true
          description: Discovery ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveProductsRequest'
      responses:
        '200':
          description: Remove products from selection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionProductsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /discovery/{discoveryId}/apply-proposal:
    post:
      operationId: applyProposal
      summary: Apply a proposal
      description: >-
        Apply a sales agent proposal to auto-add products with recommended budget allocations. Requires
        discover-products to have been called first.
      tags:
        - Product Discovery
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: discoveryId
          schema:
            description: Discovery ID
            example: abc123-def456-ghi789
            type: string
            minLength: 1
          required: true
          description: Discovery ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyProposalRequest'
      responses:
        '200':
          description: Apply a proposal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplyProposalResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /campaigns:
    get:
      operationId: listCampaigns
      summary: List campaigns
      description: List campaigns with optional filtering by advertiser and status.
      tags:
        - Campaigns
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: advertiserId
          schema:
            description: Filter by advertiser ID
            example: '12345'
            type: string
          description: Filter by advertiser ID
        - in: query
          name: name
          schema:
            description: Filter by campaign name (case-insensitive, partial match)
            example: Summer
            type: string
          description: Filter by campaign name (case-insensitive, partial match)
        - in: query
          name: status
          schema:
            description: Filter by campaign status
            anyOf:
              - type: string
                enum:
                  - DRAFT
                  - ACTIVE
                  - PAUSED
                  - COMPLETED
                  - ARCHIVED
              - type: array
                items:
                  type: string
                  enum:
                    - DRAFT
                    - ACTIVE
                    - PAUSED
                    - COMPLETED
                    - ARCHIVED
          description: Filter by campaign status
        - in: query
          name: mediaBuyStatus
          schema:
            description: Filter to only campaigns that have at least one media buy matching any of the given statuses
            anyOf:
              - type: array
                items:
                  type: string
                  enum:
                    - DRAFT
                    - PENDING_APPROVAL
                    - INPUT_REQUIRED
                    - ACTIVE
                    - PAUSED
                    - COMPLETED
                    - CANCELED
                    - FAILED
                    - REJECTED
                    - ARCHIVED
              - type: string
                enum:
                  - DRAFT
                  - PENDING_APPROVAL
                  - INPUT_REQUIRED
                  - ACTIVE
                  - PAUSED
                  - COMPLETED
                  - CANCELED
                  - FAILED
                  - REJECTED
                  - ARCHIVED
          description: Filter to only campaigns that have at least one media buy matching any of the given statuses
        - in: query
          name: includeArchived
          schema:
            description: >-
              Include archived (soft-deleted) campaigns in the response (default: false). Implicitly treated as true
              when the status filter contains 'ARCHIVED'.
            type: string
            enum:
              - 'true'
              - 'false'
          description: >-
            Include archived (soft-deleted) campaigns in the response (default: false). Implicitly treated as true when
            the status filter contains 'ARCHIVED'.
        - in: query
          name: take
          schema:
            description: Number of results to return (max 250)
            example: 50
            default: 50
            type: integer
            exclusiveMinimum: true
            maximum: 250
          description: Number of results to return (max 250)
        - in: query
          name: skip
          schema:
            description: Number of results to skip for pagination
            example: 0
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: Number of results to skip for pagination
      responses:
        '200':
          description: List campaigns
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createCampaign
      summary: Create campaign
      description: >-
        Create a new campaign. Optional fields like discoveryId and performanceConfig can be provided at creation or set
        later via update. The `brief` and `name` fields are screened by the content-moderation engine and rejected with
        422 `CONTENT_MODERATION_BLOCKED` on policy violation.
      tags:
        - Campaigns
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCampaignBody'
      responses:
        '201':
          description: Create campaign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Content rejected by moderation policy. The `brief` or `name` matched a prompt-injection / jailbreak /
            hate-speech / CSAM / violence / misinformation pattern, or failed the business-context gate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /campaigns/{campaignId}:
    put:
      operationId: updateCampaign
      summary: Update campaign
      description: >-
        Update an existing campaign. All fields are optional. The `brief` and `name` fields are screened by the
        content-moderation engine and rejected with 422 `CONTENT_MODERATION_BLOCKED` on policy violation.
      tags:
        - Campaigns
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            description: Unique identifier for the campaign
            example: cmp_987654321
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the campaign
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCampaignBody'
      responses:
        '200':
          description: Update campaign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Content rejected by moderation policy. See `POST /campaigns` for full criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: getCampaign
      summary: Get campaign
      description: Get detailed information about a specific campaign.
      tags:
        - Campaigns
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: mediaBuyId
          schema:
            description: >-
              Filter the embedded `mediaBuys[]` array to only the media buys with these IDs. Accepts a single ID
              (`?mediaBuyId=mb_X`) or repeated values (`?mediaBuyId=mb_X&mediaBuyId=mb_Y`). The campaign object itself
              is unchanged; only the nested media buys are narrowed. Use to drill into specific buys without loading
              every buy on the campaign (helps when the full tree exceeds an LLM context window). `mediaBuyRefs` still
              lists every buy on the campaign so callers can discover IDs.
            example: mb_ETBn4gJ9Wu
            anyOf:
              - type: array
                items:
                  type: string
              - type: string
          description: >-
            Filter the embedded `mediaBuys[]` array to only the media buys with these IDs. Accepts a single ID
            (`?mediaBuyId=mb_X`) or repeated values (`?mediaBuyId=mb_X&mediaBuyId=mb_Y`). The campaign object itself is
            unchanged; only the nested media buys are narrowed. Use to drill into specific buys without loading every
            buy on the campaign (helps when the full tree exceeds an LLM context window). `mediaBuyRefs` still lists
            every buy on the campaign so callers can discover IDs.
        - in: path
          name: id
          schema:
            description: Unique identifier for the campaign
            example: cmp_987654321
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the campaign
      responses:
        '200':
          description: Get campaign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteCampaign
      summary: Delete campaign
      description: Delete a campaign.
      tags:
        - Campaigns
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            description: Unique identifier for the campaign
            example: cmp_987654321
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the campaign
      responses:
        '204':
          description: No content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /campaigns/{campaignId}/execute:
    post:
      operationId: executeCampaign
      summary: Execute campaign
      description: >-
        Launch/execute a campaign to start delivering ads. Pass `debug: true` in the request body to include detailed
        debug information in error responses.
      tags:
        - Campaigns
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            description: Unique identifier for the campaign
            example: cmp_987654321
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the campaign
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteCampaignBody'
      responses:
        '200':
          description: Execute campaign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignStatusChangeResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /campaigns/{campaignId}/pause:
    post:
      operationId: pauseCampaign
      summary: Pause campaign
      description: Pause a running campaign.
      tags:
        - Campaigns
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            description: Unique identifier for the campaign
            example: cmp_987654321
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the campaign
      responses:
        '200':
          description: Pause campaign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignStatusChangeResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /campaigns/{campaignId}/auto-select-products:
    post:
      operationId: autoSelectProducts
      summary: Auto-select products
      description: >-
        Automatically select products for a performance campaign using a 3-tier strategy (scoring → measurability → CPM
        heuristic). Campaign must be in DRAFT status. Supports iterative refinement via ADCP-style refine directives —
        review results then re-call with include/omit/more_like_this to adjust selections. Replaces all previously
        selected products.
      tags:
        - Campaigns
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            description: Unique identifier for the campaign
            example: cmp_987654321
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the campaign
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoSelectProductsRequest'
      responses:
        '200':
          description: Auto-select products
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoSelectProductsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /campaigns/{campaignId}/media-buy-status:
    get:
      operationId: getMediaBuyAdcpStatus
      summary: Get media buy ADCP status
      description: >-
        Poll ADCP sales agents for the live status of all media buys in a campaign. Returns current ADCP status for each
        media buy and updates local status when changes are detected.
      tags:
        - Campaigns
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            description: Unique identifier for the campaign
            example: cmp_987654321
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the campaign
      responses:
        '200':
          description: Get media buy ADCP status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAdcpStatusOutput'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /campaigns/{campaignId}/products:
    get:
      operationId: getCampaignProducts
      summary: Get campaign products
      description: >-
        List all products staged on a campaign together with the discovery run that found each one and any media buys it
        has been executed into. Use to inspect what products are queued for execution before launching a campaign.
      tags:
        - Campaigns
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            description: Unique identifier for the campaign
            example: cmp_987654321
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the campaign
      responses:
        '200':
          description: Get campaign products
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignProductsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /audit-logs:
    get:
      operationId: listBuyerAuditLogs
      summary: List buyer audit logs
      description: Paginated audit log feed for buyer activity. Filters by time window, advertiser, campaign, and resource type.
      tags:
        - Audit Logs
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: startDate
          schema:
            description: ISO timestamp; only include audit logs at or after this time
            example: '2026-03-01T00:00:00Z'
            type: string
          description: ISO timestamp; only include audit logs at or after this time
        - in: query
          name: endDate
          schema:
            description: ISO timestamp; only include audit logs at or before this time
            example: '2026-04-01T00:00:00Z'
            type: string
          description: ISO timestamp; only include audit logs at or before this time
        - in: query
          name: advertiserId
          schema:
            description: Filter to audit logs scoped to a single advertiser
            example: 42
            type: integer
            exclusiveMinimum: true
            maximum: 9007199254740991
          description: Filter to audit logs scoped to a single advertiser
        - in: query
          name: campaignId
          schema:
            description: Filter to a campaign and all of its activity (media buys, creatives, etc.)
            example: camp_abc123
            type: string
          description: Filter to a campaign and all of its activity (media buys, creatives, etc.)
        - in: query
          name: resourceTypes
          schema:
            description: Filter to a subset of buyer resource types. Defaults to all buyer resource types.
            anyOf:
              - type: array
                items:
                  type: string
                  enum:
                    - CAMPAIGN
                    - CREATIVE
                    - MEDIA_BUY
                    - PRODUCT
                    - PACKAGE
              - type: string
          description: Filter to a subset of buyer resource types. Defaults to all buyer resource types.
        - in: query
          name: take
          schema:
            description: Number of results to return (max 500)
            example: 50
            default: 50
            type: integer
            exclusiveMinimum: true
            maximum: 500
          description: Number of results to return (max 500)
        - in: query
          name: skip
          schema:
            description: Number of results to skip for pagination
            example: 0
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: Number of results to skip for pagination
      responses:
        '200':
          description: List buyer audit logs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBuyerActivityResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /campaigns/{campaignId}/creatives/create:
    post:
      operationId: createCreativeManifest
      summary: Create creative manifest
      description: >-
        Create a creative manifest with uploaded file assets and optional brief/tag metadata. Multipart form-data
        request with files and JSON metadata.
      tags:
        - Creatives
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: campaignId
          schema:
            description: Campaign ID
            type: string
            minLength: 1
          required: true
          description: Campaign ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCreativeManifestMetadata'
      responses:
        '201':
          description: Create creative manifest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreativeManifestResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /campaigns/{campaignId}/creativeManifest:
    get:
      operationId: listCreativeManifests
      summary: List creative manifests
      description: List creative manifests for a campaign with optional filtering by status, quality, or search term.
      tags:
        - Creatives
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: search
          schema:
            description: Search by name
            type: string
            maxLength: 200
          description: Search by name
        - in: query
          name: take
          schema:
            description: Number of results to return (max 250)
            example: 50
            default: 50
            type: integer
            exclusiveMinimum: true
            maximum: 250
          description: Number of results to return (max 250)
        - in: query
          name: skip
          schema:
            description: Number of results to skip for pagination
            example: 0
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: Number of results to skip for pagination
        - in: path
          name: campaignId
          schema:
            description: Campaign ID
            type: string
            minLength: 1
          required: true
          description: Campaign ID
      responses:
        '200':
          description: List creative manifests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreativeManifestListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /campaigns/{campaignId}/creatives/{creativeId}:
    get:
      operationId: getCreativeManifest
      summary: Get creative manifest
      description: >-
        Get a single creative manifest by ID within a campaign. Supports optional ?preview=true to include preview
        render.
      tags:
        - Creatives
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: preview
          schema:
            description: Include preview render in response (preview=true)
            type: string
            enum:
              - 'true'
              - 'false'
          description: Include preview render in response (preview=true)
        - in: path
          name: campaignId
          schema:
            description: Campaign ID
            type: string
            minLength: 1
          required: true
          description: Campaign ID
        - in: path
          name: creativeId
          schema:
            description: Creative manifest ID
            type: string
            minLength: 1
          required: true
          description: Creative manifest ID
      responses:
        '200':
          description: Get creative manifest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreativeManifestResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateCreativeManifest
      summary: Update creative manifest
      description: >-
        Update creative manifest fields such as name, brief message, tag, quality, status, or manage assets (add,
        delete, reclassify). Multipart form-data request.
      tags:
        - Creatives
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: campaignId
          schema:
            description: Campaign ID
            type: string
            minLength: 1
          required: true
          description: Campaign ID
        - in: path
          name: creativeId
          schema:
            description: Creative manifest ID
            type: string
            minLength: 1
          required: true
          description: Creative manifest ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCreativeManifestMetadata'
      responses:
        '200':
          description: Update creative manifest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreativeManifestResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteCreativeManifest
      summary: Delete creative manifest
      description: Delete a creative manifest and all its assets from a campaign.
      tags:
        - Creatives
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: campaignId
          schema:
            description: Campaign ID
            type: string
            minLength: 1
          required: true
          description: Campaign ID
        - in: path
          name: creativeId
          schema:
            description: Creative manifest ID
            type: string
            minLength: 1
          required: true
          description: Creative manifest ID
      responses:
        '204':
          description: No content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/event-sources:
    get:
      operationId: listEventSources
      summary: List event sources
      description: >-
        List event sources for an advertiser. Event sources represent conversion data pipelines referenced by
        optimization goals.
      tags:
        - Event Sources
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: take
          schema:
            description: Number of results to return (max 250)
            example: 50
            default: 50
            type: integer
            exclusiveMinimum: true
            maximum: 250
          description: Number of results to return (max 250)
        - in: query
          name: skip
          schema:
            description: Number of results to skip for pagination
            example: 0
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: Number of results to skip for pagination
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: List event sources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSourceListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/event-sources/sync:
    post:
      operationId: syncEventSources
      summary: Sync event sources
      description: >-
        Inbound ADCP sync_event_sources endpoint. Buyers call this to sync their event source configurations to the
        advertiser.
      tags:
        - Event Sources
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncEventSourcesRequest'
      responses:
        '200':
          description: Sync event sources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncEventSourcesResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/events/summary:
    get:
      operationId: getEventSummary
      summary: Get event summary
      description: Get hourly-aggregated event counts for an advertiser. Returns event counts broken down by type and hour.
      tags:
        - Reporting
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: eventType
          schema:
            description: Filter by event type. When omitted, returns all event types.
            example: impression
            allOf:
              - $ref: '#/components/schemas/EventSummaryType'
          description: Filter by event type. When omitted, returns all event types.
        - in: query
          name: startHour
          schema:
            description: >-
              Start of the query range (inclusive). Must be hour-aligned. Defaults to the start of the last completed
              UTC hour.
            example: '2026-03-27T14:00:00Z'
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:00:00(Z|[+-]\d{2}:\d{2})$
          description: >-
            Start of the query range (inclusive). Must be hour-aligned. Defaults to the start of the last completed UTC
            hour.
        - in: query
          name: endHour
          schema:
            description: >-
              End of the query range (exclusive). Must be hour-aligned. Defaults to the end of the last completed UTC
              hour.
            example: '2026-03-27T15:00:00Z'
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:00:00(Z|[+-]\d{2}:\d{2})$
          description: >-
            End of the query range (exclusive). Must be hour-aligned. Defaults to the end of the last completed UTC
            hour.
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: Get event summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSummaryResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/measurement-data/sync:
    post:
      operationId: syncMeasurementData
      summary: Sync measurement data
      description: >-
        Inbound sync_measurement_data endpoint. Advertisers or MMPs call this to provide performance data as an
        alternative to CAPI. Accepts time-series measurement data keyed by campaign, media buy, package, and/or
        creative.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncMeasurementDataRequest'
      responses:
        '200':
          description: Sync measurement data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncMeasurementDataResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/test-cohorts:
    get:
      operationId: listTestCohorts
      summary: List test cohorts
      description: List test cohorts for an advertiser.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: advertiserId
          schema:
            description: Filter by advertiser ID
            example: '12345'
            type: string
          description: Filter by advertiser ID
        - in: query
          name: role
          schema:
            description: Filter by cohort role
            type: string
            enum:
              - TREATMENT
              - CONTROL
              - OBSERVATION
          description: Filter by cohort role
        - in: query
          name: isActive
          schema:
            description: Filter by active status
            type: boolean
          description: Filter by active status
        - in: query
          name: take
          schema:
            description: Number of results to return (max 250)
            example: 50
            default: 50
            type: integer
            exclusiveMinimum: true
            maximum: 250
          description: Number of results to return (max 250)
        - in: query
          name: skip
          schema:
            description: Number of results to skip for pagination
            example: 0
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: Number of results to skip for pagination
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: List test cohorts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestCohortListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createTestCohort
      summary: Create test cohort
      description: Create a new test cohort for measurement.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTestCohortInput'
      responses:
        '201':
          description: Create test cohort
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestCohortResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/test-cohorts/{cohortId}:
    get:
      operationId: getTestCohort
      summary: Get test cohort
      description: Get a specific test cohort by ID.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: cohortId
          schema:
            description: Unique identifier for the test cohort
            example: cohort_abc123
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the test cohort
      responses:
        '200':
          description: Get test cohort
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestCohortResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateTestCohort
      summary: Update test cohort
      description: Update an existing test cohort.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: cohortId
          schema:
            description: Unique identifier for the test cohort
            example: cohort_abc123
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the test cohort
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTestCohortInput'
      responses:
        '200':
          description: Update test cohort
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestCohortResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteTestCohort
      summary: Delete test cohort
      description: Delete a test cohort.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: cohortId
          schema:
            description: Unique identifier for the test cohort
            example: cohort_abc123
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the test cohort
      responses:
        '204':
          description: No content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/measurement-config:
    get:
      operationId: getMeasurementConfig
      summary: Get measurement configuration
      description: Get the measurement configuration for an advertiser.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: Get measurement configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasurementConfigResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateMeasurementConfig
      summary: Update measurement configuration
      description: Update the measurement configuration for an advertiser.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMeasurementConfigInput'
      responses:
        '200':
          description: Update measurement configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasurementConfigResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/measurement-sources:
    get:
      operationId: listMeasurementSources
      summary: List measurement sources
      description: List measurement sources for an advertiser.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: take
          schema:
            description: Number of results to return (max 250)
            example: 50
            default: 50
            type: integer
            exclusiveMinimum: true
            maximum: 250
          description: Number of results to return (max 250)
        - in: query
          name: skip
          schema:
            description: Number of results to skip for pagination
            example: 0
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: Number of results to skip for pagination
        - in: query
          name: outcomeType
          schema:
            type: string
        - in: query
          name: status
          schema:
            type: string
            enum:
              - pending
              - active
              - paused
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: List measurement sources
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createMeasurementSource
      summary: Create measurement source
      description: Register a measurement data source (e.g. MMM, brand lift study) for an advertiser.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sourceKey:
                  type: string
                  minLength: 1
                name:
                  type: string
                  minLength: 1
                outcomeType:
                  type: string
                  minLength: 1
                granularity:
                  type: string
                  minLength: 1
                lagWeeks:
                  default: 1
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                cadence:
                  type: string
                  enum:
                    - continuous
                    - daily
                    - weekly
                    - biweekly
                    - monthly
                    - quarterly
                provider:
                  type: string
                  minLength: 1
                ingestionMethod:
                  type: string
                attributionConfig:
                  type: object
                  additionalProperties: {}
                signalWeight:
                  default: 1
                  type: number
                  minimum: 0
                  maximum: 1
                status:
                  default: pending
                  type: string
                  enum:
                    - pending
                    - active
                    - paused
                notes:
                  type: string
              required:
                - sourceKey
                - name
                - outcomeType
                - granularity
                - cadence
                - provider
      responses:
        '201':
          description: Create measurement source
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/measurement-sources/{sourceId}:
    get:
      operationId: getMeasurementSource
      summary: Get measurement source
      description: Get a specific measurement source by ID.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
        - in: path
          name: sourceId
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Get measurement source
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: updateMeasurementSource
      summary: Update measurement source
      description: Update a measurement source.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
        - in: path
          name: sourceId
          schema:
            type: string
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                outcomeType:
                  type: string
                  minLength: 1
                granularity:
                  type: string
                  minLength: 1
                lagWeeks:
                  default: 1
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                cadence:
                  type: string
                  enum:
                    - continuous
                    - daily
                    - weekly
                    - biweekly
                    - monthly
                    - quarterly
                provider:
                  type: string
                  minLength: 1
                ingestionMethod:
                  type: string
                attributionConfig:
                  type: object
                  additionalProperties: {}
                signalWeight:
                  default: 1
                  type: number
                  minimum: 0
                  maximum: 1
                status:
                  default: pending
                  type: string
                  enum:
                    - pending
                    - active
                    - paused
                notes:
                  type: string
      responses:
        '200':
          description: Update measurement source
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/measurement-records:
    post:
      operationId: uploadMeasurementRecords
      summary: Upload measurement records
      description: >-
        Upload outcome measurement records (sales, brand lift, etc). Upserts on (customer, seat, outcome_type, source,
        geo, time_window).
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                records:
                  minItems: 1
                  maxItems: 5000
                  type: array
                  items:
                    type: object
                    properties:
                      outcomeType:
                        type: string
                        minLength: 1
                      geo:
                        type: string
                        minLength: 1
                      timeWindowStart:
                        type: string
                        format: date
                        pattern: >-
                          ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                      timeWindowEnd:
                        type: string
                        format: date
                        pattern: >-
                          ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                      value:
                        type: number
                      baselineValue:
                        type: number
                      confidenceInterval:
                        type: number
                      source:
                        type: string
                        minLength: 1
                      lagDays:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                    required:
                      - outcomeType
                      - geo
                      - timeWindowStart
                      - timeWindowEnd
                      - value
                      - source
              required:
                - records
      responses:
        '201':
          description: Upload measurement records
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: listMeasurementRecords
      summary: List measurement records
      description: List uploaded measurement records with optional filtering by outcome type and geo.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: take
          schema:
            description: Number of results to return (max 250)
            example: 50
            default: 50
            type: integer
            exclusiveMinimum: true
            maximum: 250
          description: Number of results to return (max 250)
        - in: query
          name: skip
          schema:
            description: Number of results to skip for pagination
            example: 0
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: Number of results to skip for pagination
        - in: query
          name: outcomeType
          schema:
            type: string
        - in: query
          name: geo
          schema:
            type: string
        - in: query
          name: geos
          schema:
            type: string
        - in: query
          name: startDate
          schema:
            type: string
            format: date
            pattern: >-
              ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
        - in: query
          name: endDate
          schema:
            type: string
            format: date
            pattern: >-
              ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: List measurement records
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/context-records:
    post:
      operationId: uploadContextRecords
      summary: Upload context records
      description: Upload exogenous context data (promos, weather, competitor activity) for measurement analysis.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                records:
                  minItems: 1
                  maxItems: 5000
                  type: array
                  items:
                    type: object
                    properties:
                      geo:
                        type: string
                        minLength: 1
                      timeWindowStart:
                        type: string
                        format: date
                        pattern: >-
                          ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                      timeWindowEnd:
                        type: string
                        format: date
                        pattern: >-
                          ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                      promoActive:
                        default: false
                        type: boolean
                      promoType:
                        type: string
                      temperatureAvg:
                        type: number
                      competitorActivity:
                        type: object
                        additionalProperties: {}
                      seasonalityIndex:
                        type: number
                      flightStatus:
                        default: active
                        type: string
                        enum:
                          - active
                          - dark
                          - pre_flight
                          - post_flight
                    required:
                      - geo
                      - timeWindowStart
                      - timeWindowEnd
              required:
                - records
      responses:
        '201':
          description: Upload context records
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/measurement-freshness:
    get:
      operationId: getMeasurementFreshness
      summary: Check measurement freshness
      description: Check for gaps in measurement data coverage relative to flight schedule and measurement source cadence.
      tags:
        - Measurement
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: flightStart
          schema:
            type: string
            format: date
            pattern: >-
              ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
          required: true
        - in: query
          name: flightEnd
          schema:
            type: string
            format: date
            pattern: >-
              ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
        - in: query
          name: geos
          schema:
            type: string
          required: true
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: Check measurement freshness
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /reporting/metrics:
    get:
      operationId: getReportingMetrics
      summary: Get reporting
      description: Get reporting metrics across all advertisers and campaigns.
      tags:
        - Reporting
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: advertiserId
          schema:
            description: Filter to campaigns on this advertiser (seat ID)
            type: string
          description: Filter to campaigns on this advertiser (seat ID)
        - in: query
          name: campaignId
          schema:
            description: >-
              Filter to a specific campaign. If advertiserId is also provided, the campaign must belong to that
              advertiser
            type: string
          description: Filter to a specific campaign. If advertiserId is also provided, the campaign must belong to that advertiser
        - in: query
          name: startDate
          schema:
            description: Start date in ISO format (YYYY-MM-DD)
            example: '2025-01-01'
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          description: Start date in ISO format (YYYY-MM-DD)
        - in: query
          name: endDate
          schema:
            description: End date in ISO format (YYYY-MM-DD)
            example: '2025-01-31'
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          description: End date in ISO format (YYYY-MM-DD)
        - in: query
          name: days
          schema:
            description: 'Number of days to include (default: 7, max: 90). Use 0 for the full campaign timeframe.'
            example: 7
            default: 7
            type: integer
            minimum: 0
            maximum: 90
          description: 'Number of days to include (default: 7, max: 90). Use 0 for the full campaign timeframe.'
        - in: query
          name: view
          schema:
            description: >-
              Response format: "summary" for hierarchical advertiser/campaign/media-buy/package breakdown, "timeseries"
              for flat rows with one entry per (advertiser → campaign → media buy → package) × day
            default: summary
            type: string
            enum:
              - summary
              - timeseries
          description: >-
            Response format: "summary" for hierarchical advertiser/campaign/media-buy/package breakdown, "timeseries"
            for flat rows with one entry per (advertiser → campaign → media buy → package) × day
        - in: query
          name: download
          schema:
            description: When true, generates a CSV file and returns a signed download URL instead of JSON data
            default: false
            type: boolean
          description: When true, generates a CSV file and returns a signed download URL instead of JSON data
        - in: query
          name: demo
          schema:
            description: When true, returns auto-generated demo data instead of querying real data sources
            default: false
            type: boolean
          required: true
          description: When true, returns auto-generated demo data instead of querying real data sources
      responses:
        '200':
          description: Get reporting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportingMetricsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /accounts/current:
    servers: &ref_0
      - url: https://api.interchange.io/api/v2
        description: Production server
      - url: https://api.staging.interchange.io/api/v2
        description: Staging server
    get:
      operationId: getCurrentAccount
      summary: Get current account
      description: Get the authenticated user's current customer account context.
      tags:
        - Account
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Get current account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrentAccountResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /accounts:
    servers: *ref_0
    get:
      operationId: listCustomerAccounts
      summary: List customer accounts
      description: List all customer accounts the authenticated user has active membership on.
      tags:
        - Account
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List customer accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomerAccountsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /accounts/create-child:
    servers: *ref_0
    post:
      operationId: createChildAccount
      summary: Create child account
      description: >-
        Create a new child customer account. For standalone customers, creates a parent/child hierarchy first. Requires
        ADMIN role.
      tags:
        - Account
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChildAccountBody'
      responses:
        '201':
          description: Create child account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChildAccountResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /accounts/{customerId}/domain:
    servers: *ref_0
    patch:
      operationId: updateCustomerDomain
      summary: Update customer domain
      description: >-
        Update a customer's registered organization domain. Requires ADMIN role on the target customer (direct
        membership, parent admin via the customer hierarchy, or SuperAdmin).
      tags:
        - Account
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          schema:
            description: Customer ID
            example: '200'
            type: string
            minLength: 1
          required: true
          description: Customer ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerDomainBody'
      responses:
        '200':
          description: Update customer domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCustomerDomainResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /notification-preferences:
    servers: *ref_0
    get:
      operationId: getNotificationPreferences
      summary: Get notification preferences
      description: Get notification opt-in preferences for the authenticated user.
      tags:
        - Account
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Get notification preferences
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateNotificationPreferences
      summary: Update notification preferences
      description: Set notification opt-in preferences for the authenticated user. Replaces all existing opt-ins.
      tags:
        - Account
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                optIns:
                  maxItems: 200
                  type: array
                  items:
                    type: object
                    properties:
                      notificationType:
                        type: string
                        enum:
                          - brand_agent.created
                          - brand_agent.updated
                          - brand_agent.deleted
                          - campaign.healthy
                          - campaign.unhealthy
                          - campaign.created
                          - campaign.updated
                          - campaign.deleted
                          - campaign.completed
                          - creative.approved
                          - creative.rejected
                          - creative.changes_requested
                          - creative.sync_started
                          - creative.sync_completed
                          - creative.sync_failed
                          - creative.created
                          - creative.updated
                          - creative.deleted
                          - strategy.created
                          - strategy.updated
                          - strategy.deleted
                          - media_buy.created
                          - media_buy.updated
                          - media_buy.deleted
                          - salesagent.available
                          - salesagent.unavailable
                          - salesagent.registered
                          - salesagent.unregistered
                          - salesagent.updated
                          - signalsagent.registered
                          - signalsagent.unregistered
                          - signalsagent.updated
                          - signalsagent.signal_activated
                          - signalsagent.signals_fetched
                          - outcomesagent.registered
                          - outcomesagent.unregistered
                          - outcomesagent.updated
                          - syndication.completed
                          - syndication.failed
                          - audience.synced
                          - audience.sync_failed
                          - optimization.suggestion_received
                          - optimization.suggestion_approved
                          - optimization.suggestion_rejected
                          - optimization.suggestion_applied
                          - optimization.suggestion_failed
                          - system.warning
                          - system.error
                          - learning_cycle.completed
                          - learning_cycle.failed
                          - hypothesis.status_changed
                          - hypothesis.review_requested
                          - hypothesis.proven
                          - hypothesis.disproven
                          - measurement.received
                          - measurement.stale
                          - opportunity.evaluated
                          - opportunity.recommended
                          - opportunity.flagged
                          - opportunity.explore
                      channel:
                        type: string
                        enum:
                          - email
                          - in_app
                    required:
                      - notificationType
                      - channel
              required:
                - optIns
      responses:
        '200':
          description: Update notification preferences
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /moderation/check:
    servers: *ref_0
    post:
      operationId: checkModeration
      summary: Pre-check content against moderation policy
      description: >-
        Runs the content-moderation engine against the supplied text WITHOUT blocking. Returns structured findings
        (category, severity, suggestion) so buyer agents can validate input before submitting it to a campaign create or
        other blocking surface. Mirrors the engine that powers `POST /v2/campaigns` brief screening.
      tags:
        - Moderation
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  description: The text to evaluate. Up to 10,000 characters; longer text is truncated server-side.
                  type: string
                  minLength: 1
                  maxLength: 10000
                direction:
                  description: >-
                    Which pattern set to apply. "input" runs the brief/jailbreak/policy patterns; "output" runs the
                    LLM-output (refusal/identity/PII) patterns.
                  default: input
                  type: string
                  enum:
                    - input
                    - output
                surface:
                  description: Optional surface label for metric attribution. Defaults to "moderation.check".
                  default: moderation.check
                  type: string
                  minLength: 1
                  maxLength: 100
              required:
                - text
      responses:
        '200':
          description: Pre-check content against moderation policy
          content:
            application/json:
              schema:
                type: object
                properties:
                  passed:
                    description: True when no moderation patterns matched.
                    type: boolean
                  wouldBlock:
                    description: >-
                      True when at least one finding would trigger a 422 if this content were submitted to a blocking
                      surface.
                    type: boolean
                  findings:
                    description: >-
                      All matching findings. Empty when `passed` is true. Both blocking and non-blocking findings are
                      reported so callers can observe medium-severity signals.
                    type: array
                    items:
                      type: object
                      properties:
                        category:
                          description: Moderation category (e.g. "jailbreak_attempt", "pii_leak").
                          type: string
                        severity:
                          description: Severity tier. "high" and above is what blocks at default thresholds.
                          type: string
                          enum:
                            - low
                            - medium
                            - high
                            - critical
                        suggestion:
                          description: Human-readable remediation guidance for the buyer agent to self-correct.
                          type: string
                      required:
                        - category
                        - severity
                        - suggestion
                      additionalProperties: false
                required:
                  - passed
                  - wouldBlock
                  - findings
                additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/accounts/available:
    get:
      operationId: listAvailableAccounts
      summary: List available accounts
      description: Discover accounts available to link to an advertiser from a specific sales agent.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: storefrontId
          schema:
            description: Storefront the source lives on. Pair with `sourceId` to identify the source whose accounts to list.
            example: 42
            type: integer
            exclusiveMinimum: true
            maximum: 9007199254740991
          required: true
          description: Storefront the source lives on. Pair with `sourceId` to identify the source whose accounts to list.
        - in: query
          name: sourceId
          schema:
            description: Inventory source within `storefrontId` whose accounts to list.
            example: src_main
            type: string
            minLength: 1
          required: true
          description: Inventory source within `storefrontId` whose accounts to list.
        - in: query
          name: refresh
          schema:
            description: >-
              When true, re-fetches accounts from the source before returning results. Defaults to false (returns cached
              accounts).
            example: 'false'
            type: string
            enum:
              - 'true'
              - 'false'
          description: >-
            When true, re-fetches accounts from the source before returning results. Defaults to false (returns cached
            accounts).
        - in: query
          name: billingType
          schema:
            description: >-
              Billing arrangement type to filter accounts by (e.g. "advertiser", "operator", "agent"). Must be one of
              the values supported by this source. Defaults to the source's default billing type if omitted.
            example: advertiser
            type: string
          description: >-
            Billing arrangement type to filter accounts by (e.g. "advertiser", "operator", "agent"). Must be one of the
            values supported by this source. Defaults to the source's default billing type if omitted.
        - in: query
          name: credentialId
          schema:
            description: >-
              ID of a specific registered credential to use for account discovery. Required when the customer has
              multiple credentials registered for this source. Use GET /storefronts/credentials to list registered
              credentials and their IDs.
            example: '42'
            type: string
          description: >-
            ID of a specific registered credential to use for account discovery. Required when the customer has multiple
            credentials registered for this source. Use GET /storefronts/credentials to list registered credentials and
            their IDs.
        - in: query
          name: take
          schema:
            description: Number of results to return (max 250)
            example: 50
            default: 50
            type: integer
            exclusiveMinimum: true
            maximum: 250
          description: Number of results to return (max 250)
        - in: query
          name: skip
          schema:
            description: Number of results to skip for pagination
            example: 0
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: Number of results to skip for pagination
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: List available accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableAccountListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/accounts/{linkId}/reporting-bucket:
    put:
      operationId: updateAccountReportingBucket
      summary: Update account reporting bucket
      description: >-
        Set or clear the offline `reporting_bucket` configuration on a linked partner account, then notify the seller
        via `sync_accounts`. Pass `reporting_bucket: null` to clear the bucket.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
        - in: path
          name: linkId
          schema:
            description: Identifier of the advertiser-account link row (numeric primary key)
            example: '42'
            type: string
            pattern: ^\d+$
          required: true
          description: Identifier of the advertiser-account link row (numeric primary key)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateReportingBucketBody'
      responses:
        '200':
          description: Update account reporting bucket
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/catalogs:
    get:
      operationId: listCatalogs
      summary: List catalogs
      description: List catalogs that have been synced for an advertiser.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: type
          schema:
            type: string
            enum:
              - offering
              - product
              - inventory
              - store
              - promotion
              - hotel
              - flight
              - job
              - vehicle
              - real_estate
              - education
              - destination
        - in: query
          name: take
          schema:
            description: Number of results to return (max 250)
            example: 50
            default: 50
            type: integer
            exclusiveMinimum: true
            maximum: 250
          description: Number of results to return (max 250)
        - in: query
          name: skip
          schema:
            description: Number of results to skip for pagination
            example: 0
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: Number of results to skip for pagination
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: List catalogs
          content:
            application/json:
              schema:
                type: object
                properties:
                  catalogs:
                    type: array
                    items:
                      type: object
                      properties:
                        catalogId:
                          type: string
                        platformId:
                          type: string
                        type:
                          type: string
                          enum:
                            - offering
                            - product
                            - inventory
                            - store
                            - promotion
                            - hotel
                            - flight
                            - job
                            - vehicle
                            - real_estate
                            - education
                            - destination
                        name:
                          nullable: true
                          type: string
                        url:
                          nullable: true
                          type: string
                        feedFormat:
                          nullable: true
                          type: string
                          enum:
                            - google_merchant_center
                            - facebook_catalog
                            - shopify
                            - linkedin_jobs
                            - custom
                        updateFrequency:
                          nullable: true
                          type: string
                          enum:
                            - realtime
                            - hourly
                            - daily
                            - weekly
                        itemCount:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        lastSyncedAt:
                          nullable: true
                          type: string
                          format: date-time
                          pattern: >-
                            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        advertiserId:
                          type: string
                      required:
                        - catalogId
                        - platformId
                        - type
                        - name
                        - url
                        - feedFormat
                        - updateFrequency
                        - itemCount
                        - lastSyncedAt
                        - advertiserId
                      additionalProperties: false
                  total:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                required:
                  - catalogs
                  - total
                additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/catalogs/sync:
    post:
      operationId: syncCatalogs
      summary: Sync catalogs
      description: Inbound ADCP sync_catalogs endpoint. Buyers call this to sync their catalogs and items to the advertiser.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  description: Advertiser account to sync catalogs onto
                  type: object
                  properties:
                    account_id:
                      description: Advertiser ID (seat_id) to attach catalogs to
                      example: '12345'
                      type: string
                      minLength: 1
                  required:
                    - account_id
                catalogs:
                  description: Catalog feeds to sync (up to 50 per call)
                  minItems: 1
                  maxItems: 50
                  type: array
                  items:
                    type: object
                    properties:
                      catalog_id:
                        description: Buyer-assigned catalog identifier
                        example: my-summer-products
                        type: string
                        minLength: 1
                      type:
                        type: string
                        enum:
                          - offering
                          - product
                          - inventory
                          - store
                          - promotion
                          - hotel
                          - flight
                          - job
                          - vehicle
                          - real_estate
                          - education
                          - destination
                      name:
                        description: Display name for the catalog
                        example: Summer Sale 2026
                        type: string
                        minLength: 1
                        maxLength: 255
                      url:
                        description: Remote feed URL (provide this or items, not both)
                        example: https://feeds.example.com/products.xml
                        type: string
                        format: uri
                      feed_format:
                        type: string
                        enum:
                          - google_merchant_center
                          - facebook_catalog
                          - shopify
                          - linkedin_jobs
                          - custom
                      update_frequency:
                        type: string
                        enum:
                          - realtime
                          - hourly
                          - daily
                          - weekly
                      items:
                        description: Inline catalog items (provide this or url, not both)
                        maxItems: 10000
                        type: array
                        items:
                          description: An individual catalog item (product, offering, job, etc.)
                          type: object
                          additionalProperties: {}
                      conversion_events:
                        description: Conversion event IDs linked to this catalog
                        example:
                          - purchase
                          - add_to_cart
                        type: array
                        items:
                          type: string
                    required:
                      - catalog_id
                      - type
                catalog_ids:
                  description: 'Optional: only process these catalog_ids from the catalogs array'
                  type: array
                  items:
                    type: string
                delete_missing:
                  description: Archive buyer-managed catalogs not included in this request
                  default: false
                  type: boolean
                dry_run:
                  description: Preview changes without persisting to the database
                  default: false
                  type: boolean
                validation_mode:
                  description: Item validation strictness
                  default: strict
                  type: string
                  enum:
                    - strict
                    - lenient
              required:
                - account
                - catalogs
      responses:
        '200':
          description: Sync catalogs
          content:
            application/json:
              schema:
                type: object
                properties:
                  catalogs:
                    type: array
                    items:
                      type: object
                      properties:
                        catalog_id:
                          type: string
                        action:
                          type: string
                          enum:
                            - created
                            - updated
                            - unchanged
                            - failed
                            - deleted
                        platform_id:
                          type: string
                        item_count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        items_approved:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        items_pending:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        items_rejected:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        item_issues:
                          type: array
                          items:
                            type: object
                            properties:
                              item_id:
                                type: string
                              field:
                                type: string
                              issue:
                                type: string
                              severity:
                                type: string
                                enum:
                                  - error
                                  - warning
                            required:
                              - issue
                            additionalProperties: false
                        last_synced_at:
                          type: string
                          format: date-time
                          pattern: >-
                            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        next_fetch_at:
                          type: string
                          format: date-time
                          pattern: >-
                            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        error:
                          type: string
                      required:
                        - catalog_id
                        - action
                      additionalProperties: false
                  dry_run:
                    type: boolean
                required:
                  - catalogs
                additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefronts:
    get:
      operationId: listStorefronts
      summary: List storefronts
      description: List all enabled storefronts visible to the buyer. Each storefront contains inventory sources backed by agents.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: name
          schema:
            description: Filter by storefront name (partial match, case-insensitive)
            type: string
          description: Filter by storefront name (partial match, case-insensitive)
        - in: query
          name: visibility
          schema:
            description: >-
              Which storefronts to list. `public` (default) returns ACTIVE storefronts available to any buyer. `private`
              returns ALL storefronts (ACTIVE, PENDING, and DISABLED) owned by customers in the caller's parent
              organization.
            type: string
            enum:
              - public
              - private
        - in: query
          name: limit
          schema:
            description: 'Maximum storefronts per page (default: 20, max: 50)'
            type: integer
            exclusiveMinimum: true
            maximum: 50
          description: 'Maximum storefronts per page (default: 20, max: 50)'
        - in: query
          name: offset
          schema:
            description: 'Number of storefronts to skip for pagination (default: 0)'
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: 'Number of storefronts to skip for pagination (default: 0)'
      responses:
        '200':
          description: List storefronts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerStorefrontList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefronts/{storefrontId}:
    get:
      operationId: getStorefront
      summary: Get storefront
      description: Get a single storefront with inventory sources and buyer connection status.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: storefrontId
          schema:
            description: Storefront ID
            type: integer
            exclusiveMinimum: true
            maximum: 9007199254740991
          required: true
          description: Storefront ID
      responses:
        '200':
          description: Get storefront
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerStorefront'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefronts/credentials:
    get:
      operationId: listStorefrontCredentials
      summary: List credentials
      description: List all credentials the buyer has registered, scoped to the storefront sources each credential gives access to.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List credentials
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BuyerCredential'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefronts/{storefrontId}/sources/{sourceId}/credentials:
    post:
      operationId: registerSourceCredentials
      summary: Register source credentials
      description: Register credentials for an inventory source within a storefront.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: storefrontId
          schema:
            description: Storefront ID
            type: integer
            exclusiveMinimum: true
            maximum: 9007199254740991
          required: true
          description: Storefront ID
        - in: path
          name: sourceId
          schema:
            description: Inventory source ID
            type: string
            minLength: 1
          required: true
          description: Inventory source ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                accountIdentifier:
                  description: Unique account identifier for this agent
                  type: string
                  minLength: 1
                  maxLength: 255
                auth:
                  description: Authentication credentials. Required for API_KEY/JWT agents, not needed for OAUTH agents.
                  anyOf:
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - jwt
                        privateKey:
                          type: string
                          minLength: 1
                        issuer:
                          type: string
                          minLength: 1
                        subject:
                          type: string
                          minLength: 1
                        keyId:
                          type: string
                          minLength: 1
                        scope:
                          type: string
                          minLength: 1
                        tokenEndpointUrl:
                          type: string
                          format: uri
                        audienceUrl:
                          type: string
                          format: uri
                        algorithm:
                          type: string
                          enum:
                            - ES256
                            - RS256
                        environment:
                          type: string
                      required:
                        - type
                        - privateKey
                        - issuer
                        - subject
                        - keyId
                        - scope
                        - tokenEndpointUrl
                        - audienceUrl
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - bearer
                            - apikey
                            - api_key
                        token:
                          type: string
                          minLength: 1
                      required:
                        - type
                        - token
                    - type: object
                      properties: {}
                marketplaceAccount:
                  description: Admin-only flag. When true, creates a marketplace account instead of a client account.
                  type: boolean
              required:
                - accountIdentifier
      responses:
        '201':
          description: Register source credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerCredentialRegistrationResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/syndicate:
    post:
      operationId: syndicate
      summary: Toggle syndication for a resource
      description: >-
        Toggle syndication ON/OFF for an audience, event source, or catalog to a specific ADCP agent. Returns the
        syndication status record immediately.
      tags:
        - Syndication
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                resourceType:
                  type: string
                  enum:
                    - AUDIENCE
                    - EVENT_SOURCE
                    - CATALOG
                resourceId:
                  type: string
                  minLength: 1
                adcpAgentIds:
                  minItems: 1
                  type: array
                  items:
                    type: string
                    minLength: 1
                enabled:
                  type: boolean
              required:
                - resourceType
                - resourceId
                - adcpAgentIds
                - enabled
      responses:
        '201':
          description: Toggle syndication for a resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyndicateResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/syndication-status:
    get:
      operationId: getSyndicationStatus
      summary: Query syndication status
      description: >-
        Query syndication status records for an advertiser, with optional filtering by resource type, resource ID, ADCP
        agent, and enabled state.
      tags:
        - Syndication
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: resourceType
          schema:
            type: string
            enum:
              - AUDIENCE
              - EVENT_SOURCE
              - CATALOG
        - in: query
          name: resourceId
          schema:
            type: string
        - in: query
          name: adcpAgentId
          schema:
            type: string
        - in: query
          name: enabled
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - in: query
          name: status
          schema:
            type: string
            enum:
              - PENDING
              - SYNCING
              - COMPLETED
              - FAILED
              - DISABLED
        - in: query
          name: limit
          schema:
            default: 50
            type: integer
            minimum: 1
            maximum: 100
        - in: query
          name: offset
          schema:
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: Query syndication status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyndicationStatusListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{accountId}/audiences/sync:
    post:
      operationId: syncAudiences
      summary: Sync audiences
      description: Sync first-party CRM audiences for an account. Processing is asynchronous — returns 202 with an operation ID.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncAudiencesBody'
      responses:
        '202':
          description: Sync audiences
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncAudiencesResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{accountId}/audiences:
    get:
      operationId: listAudiences
      summary: List audiences
      description: List stored audience metadata for an account.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: take
          schema:
            description: Number of results to return (max 250)
            example: 50
            default: 50
            type: integer
            exclusiveMinimum: true
            maximum: 250
          description: Number of results to return (max 250)
        - in: query
          name: skip
          schema:
            description: Number of results to skip for pagination
            example: 0
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: Number of results to skip for pagination
      responses:
        '200':
          description: List audiences
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudienceListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /tasks/{taskId}:
    get:
      operationId: getTask
      summary: Get task status
      description: Get the current status of an async task. AdCP polling fallback for when webhooks are unavailable.
      tags:
        - Tasks
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: taskId
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          required: true
      responses:
        '200':
          description: Get task status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/property-lists:
    get:
      operationId: listPropertyLists
      summary: List property lists
      description: List property lists for an advertiser. Optionally filter by purpose (include/exclude).
      tags:
        - Property Lists
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: take
          schema:
            description: Number of results to return (max 250)
            example: 50
            default: 50
            type: integer
            exclusiveMinimum: true
            maximum: 250
          description: Number of results to return (max 250)
        - in: query
          name: skip
          schema:
            description: Number of results to skip for pagination
            example: 0
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: Number of results to skip for pagination
        - in: query
          name: purpose
          schema:
            description: Whether properties in this list should be included or excluded
            example: include
            type: string
            enum:
              - include
              - exclude
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: List property lists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyListListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createPropertyList
      summary: Create property list
      description: >-
        Create a named include or exclude list of publisher domains for an advertiser. Domains are resolved to internal
        property records. Unresolvable domains are returned in the response.
      tags:
        - Property Lists
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePropertyListInput'
      responses:
        '200':
          description: Create property list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/property-lists/{listId}:
    get:
      operationId: getPropertyList
      summary: Get property list
      description: Get a specific property list by ID with resolved domain identifiers.
      tags:
        - Property Lists
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
        - in: path
          name: listId
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Get property list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updatePropertyList
      summary: Update property list
      description: Update a property list name and/or replace domains entirely.
      tags:
        - Property Lists
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
        - in: path
          name: listId
          schema:
            type: string
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePropertyListInput'
      responses:
        '200':
          description: Update property list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deletePropertyList
      summary: Delete property list
      description: Archive a property list and unlink it from the advertiser targeting profile.
      tags:
        - Property Lists
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
        - in: path
          name: listId
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Delete property list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /property-lists/check:
    post:
      operationId: checkPropertyList
      summary: Check property list
      description: >-
        Check a list of domains against the AAO Community Registry. Returns domains categorized into remove, modify,
        assess, and ok buckets.
      tags:
        - Property Lists
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckPropertyListBody'
      responses:
        '200':
          description: Check property list
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary:
                    type: object
                    properties:
                      total:
                        type: number
                      remove:
                        type: number
                      modify:
                        type: number
                      assess:
                        type: number
                      ok:
                        type: number
                    required:
                      - total
                      - remove
                      - modify
                      - assess
                      - ok
                    additionalProperties: false
                  remove:
                    type: array
                    items:
                      type: object
                      properties:
                        input:
                          type: string
                        canonical:
                          type: string
                        reason:
                          type: string
                          enum:
                            - duplicate
                            - blocked
                        domain_type:
                          type: string
                        blocked_reason:
                          type: string
                        identifier:
                          type: object
                          properties:
                            type:
                              anyOf:
                                - type: string
                                  enum:
                                    - domain
                                - type: string
                                  enum:
                                    - subdomain
                                - type: string
                                  enum:
                                    - network_id
                                - type: string
                                  enum:
                                    - ios_bundle
                                - type: string
                                  enum:
                                    - android_package
                                - type: string
                                  enum:
                                    - apple_app_store_id
                                - type: string
                                  enum:
                                    - google_play_id
                                - type: string
                                  enum:
                                    - roku_store_id
                                - type: string
                                  enum:
                                    - fire_tv_asin
                                - type: string
                                  enum:
                                    - samsung_app_id
                                - type: string
                                  enum:
                                    - apple_tv_bundle
                                - type: string
                                  enum:
                                    - bundle_id
                                - type: string
                                  enum:
                                    - venue_id
                                - type: string
                                  enum:
                                    - screen_id
                                - type: string
                                  enum:
                                    - openooh_venue_type
                                - type: string
                                  enum:
                                    - rss_url
                                - type: string
                                  enum:
                                    - apple_podcast_id
                                - type: string
                                  enum:
                                    - spotify_collection_id
                                - type: string
                                  enum:
                                    - podcast_guid
                                - type: string
                                  enum:
                                    - station_id
                                - type: string
                                  enum:
                                    - facility_id
                            value:
                              type: string
                          required:
                            - type
                            - value
                          additionalProperties: {}
                      required:
                        - input
                        - canonical
                        - reason
                      additionalProperties: false
                  modify:
                    type: array
                    items:
                      type: object
                      properties:
                        input:
                          type: string
                        canonical:
                          type: string
                        reason:
                          type: string
                        identifier:
                          type: object
                          properties:
                            type:
                              anyOf:
                                - type: string
                                  enum:
                                    - domain
                                - type: string
                                  enum:
                                    - subdomain
                                - type: string
                                  enum:
                                    - network_id
                                - type: string
                                  enum:
                                    - ios_bundle
                                - type: string
                                  enum:
                                    - android_package
                                - type: string
                                  enum:
                                    - apple_app_store_id
                                - type: string
                                  enum:
                                    - google_play_id
                                - type: string
                                  enum:
                                    - roku_store_id
                                - type: string
                                  enum:
                                    - fire_tv_asin
                                - type: string
                                  enum:
                                    - samsung_app_id
                                - type: string
                                  enum:
                                    - apple_tv_bundle
                                - type: string
                                  enum:
                                    - bundle_id
                                - type: string
                                  enum:
                                    - venue_id
                                - type: string
                                  enum:
                                    - screen_id
                                - type: string
                                  enum:
                                    - openooh_venue_type
                                - type: string
                                  enum:
                                    - rss_url
                                - type: string
                                  enum:
                                    - apple_podcast_id
                                - type: string
                                  enum:
                                    - spotify_collection_id
                                - type: string
                                  enum:
                                    - podcast_guid
                                - type: string
                                  enum:
                                    - station_id
                                - type: string
                                  enum:
                                    - facility_id
                            value:
                              type: string
                          required:
                            - type
                            - value
                          additionalProperties: {}
                      required:
                        - input
                        - canonical
                        - reason
                      additionalProperties: false
                  assess:
                    type: array
                    items:
                      type: object
                      properties:
                        domain:
                          type: string
                        identifier:
                          type: object
                          properties:
                            type:
                              anyOf:
                                - type: string
                                  enum:
                                    - domain
                                - type: string
                                  enum:
                                    - subdomain
                                - type: string
                                  enum:
                                    - network_id
                                - type: string
                                  enum:
                                    - ios_bundle
                                - type: string
                                  enum:
                                    - android_package
                                - type: string
                                  enum:
                                    - apple_app_store_id
                                - type: string
                                  enum:
                                    - google_play_id
                                - type: string
                                  enum:
                                    - roku_store_id
                                - type: string
                                  enum:
                                    - fire_tv_asin
                                - type: string
                                  enum:
                                    - samsung_app_id
                                - type: string
                                  enum:
                                    - apple_tv_bundle
                                - type: string
                                  enum:
                                    - bundle_id
                                - type: string
                                  enum:
                                    - venue_id
                                - type: string
                                  enum:
                                    - screen_id
                                - type: string
                                  enum:
                                    - openooh_venue_type
                                - type: string
                                  enum:
                                    - rss_url
                                - type: string
                                  enum:
                                    - apple_podcast_id
                                - type: string
                                  enum:
                                    - spotify_collection_id
                                - type: string
                                  enum:
                                    - podcast_guid
                                - type: string
                                  enum:
                                    - station_id
                                - type: string
                                  enum:
                                    - facility_id
                            value:
                              type: string
                          required:
                            - type
                            - value
                          additionalProperties: {}
                      required:
                        - domain
                      additionalProperties: false
                  ok:
                    type: array
                    items:
                      type: object
                      properties:
                        domain:
                          type: string
                        source:
                          type: string
                        identifier:
                          type: object
                          properties:
                            type:
                              anyOf:
                                - type: string
                                  enum:
                                    - domain
                                - type: string
                                  enum:
                                    - subdomain
                                - type: string
                                  enum:
                                    - network_id
                                - type: string
                                  enum:
                                    - ios_bundle
                                - type: string
                                  enum:
                                    - android_package
                                - type: string
                                  enum:
                                    - apple_app_store_id
                                - type: string
                                  enum:
                                    - google_play_id
                                - type: string
                                  enum:
                                    - roku_store_id
                                - type: string
                                  enum:
                                    - fire_tv_asin
                                - type: string
                                  enum:
                                    - samsung_app_id
                                - type: string
                                  enum:
                                    - apple_tv_bundle
                                - type: string
                                  enum:
                                    - bundle_id
                                - type: string
                                  enum:
                                    - venue_id
                                - type: string
                                  enum:
                                    - screen_id
                                - type: string
                                  enum:
                                    - openooh_venue_type
                                - type: string
                                  enum:
                                    - rss_url
                                - type: string
                                  enum:
                                    - apple_podcast_id
                                - type: string
                                  enum:
                                    - spotify_collection_id
                                - type: string
                                  enum:
                                    - podcast_guid
                                - type: string
                                  enum:
                                    - station_id
                                - type: string
                                  enum:
                                    - facility_id
                            value:
                              type: string
                          required:
                            - type
                            - value
                          additionalProperties: {}
                      required:
                        - domain
                        - source
                      additionalProperties: false
                  reportId:
                    description: >-
                      Primary AAO registry report ID (equals `reportIds[0]` when domains were checked). Omitted when the
                      request contained only bundle identifiers (AAO does not currently check bundles).
                    type: string
                  reportIds:
                    description: >-
                      All registry report IDs for this check. Contains one ID when the input fits in a single registry
                      call, and multiple IDs when the domain input was chunked. Omitted when the request contained only
                      bundle identifiers.
                    type: array
                    items:
                      type: string
                required:
                  - summary
                  - remove
                  - modify
                  - assess
                  - ok
                additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /property-lists/reports/{reportId}:
    get:
      operationId: getPropertyListCheckReport
      summary: Get property list check report
      description: Retrieve a stored property list check report by ID. Reports expire after 7 days.
      tags:
        - Property Lists
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: reportId
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Get property list check report
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary:
                    type: object
                    properties:
                      total:
                        type: number
                      remove:
                        type: number
                      modify:
                        type: number
                      assess:
                        type: number
                      ok:
                        type: number
                    required:
                      - total
                      - remove
                      - modify
                      - assess
                      - ok
                    additionalProperties: false
                required:
                  - summary
                additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /billing/invoices:
    get:
      operationId: listBuyerInvoices
      summary: List invoices
      description: List consolidated invoices issued to the authenticated buyer customer.
      tags:
        - Buyer Billing
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            description: Maximum number of results (1–100, default 25)
            type: integer
            minimum: 1
            maximum: 100
          description: Maximum number of results (1–100, default 25)
        - in: query
          name: starting_after
          schema:
            description: Cursor for pagination (ID of last item from previous page)
            type: string
          description: Cursor for pagination (ID of last item from previous page)
      responses:
        '200':
          description: List invoices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerInvoicesResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /billing/pending-invoice-items:
    get:
      operationId: listBuyerPendingInvoiceItems
      summary: List pending invoice items
      description: >-
        List pending line items that will appear on the next consolidated invoice issued to the authenticated buyer
        customer.
      tags:
        - Buyer Billing
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            description: Maximum number of results (1–100, default 25)
            type: integer
            minimum: 1
            maximum: 100
          description: Maximum number of results (1–100, default 25)
        - in: query
          name: starting_after
          schema:
            description: Cursor for pagination (ID of last item from previous page)
            type: string
          description: Cursor for pagination (ID of last item from previous page)
      responses:
        '200':
          description: List pending invoice items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerPendingInvoiceItemsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /:
    servers: &ref_1
      - url: https://api.interchange.io/mcp/v2/buyer
        description: Production MCP server
      - url: https://api.staging.interchange.io/mcp/v2/buyer
        description: Staging MCP server
    post:
      operationId: mcpInitialize
      summary: Initialize MCP session
      description: |-
        Start a new MCP (Model Context Protocol) session. This must be called before using any other MCP tools.

        ## Request Format

        Send a JSON-RPC 2.0 request with:
        - `method`: "initialize"
        - `params.protocolVersion`: "2024-11-05"
        - `params.capabilities`: {} (empty object)
        - `params.clientInfo`: Your agent info

        ## Example Request

        ```json
        {
          "jsonrpc": "2.0",
          "id": 1,
          "method": "initialize",
          "params": {
            "protocolVersion": "2024-11-05",
            "capabilities": {},
            "clientInfo": { "name": "your-agent", "version": "1.0" }
          }
        }
        ```

        ## Example Response

        ```json
        {
          "jsonrpc": "2.0",
          "id": 1,
          "result": {
            "protocolVersion": "2024-11-05",
            "capabilities": { "tools": {} },
            "serverInfo": { "name": "scope3-buyer-api", "version": "2.0.0" }
          }
        }
        ```
      tags:
        - MCP
      parameters:
        - name: mcp-session-id
          in: header
          required: true
          schema:
            type: string
            format: uuid
          description: MCP session identifier. Generate a new UUID for this request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpInitializeRequest'
            example:
              jsonrpc: '2.0'
              id: 1
              method: initialize
              params:
                protocolVersion: '2024-11-05'
                capabilities: {}
                clientInfo:
                  name: your-agent
                  version: '1.0'
      responses:
        '200':
          description: Session initialized successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpInitializeResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
  /api-call:
    servers: *ref_1
    post:
      operationId: mcpApiCall
      summary: Make API call via MCP
      description: |-
        Make REST API calls to any Buyer API endpoint through MCP.

        ## Parameters

        - `method`: HTTP method (GET, POST, PUT, DELETE)
        - `path`: API path (e.g., "/advertisers", "/campaigns/{id}")
        - `body`: Request body for POST/PUT requests (optional)
        - `query`: Query parameters (optional)

        ## Example: List Advertisers

        ```json
        {
          "jsonrpc": "2.0",
          "id": 2,
          "method": "tools/call",
          "params": {
            "name": "api_call",
            "arguments": {
              "method": "GET",
              "path": "/advertisers",
              "query": { "take": 10 }
            }
          }
        }
        ```

        ## Example Response

        ```json
        {
          "jsonrpc": "2.0",
          "id": 2,
          "result": {
            "content": [
              {
                "type": "text",
                "text": "{ \"advertisers\": [...], \"total\": 5 }"
              }
            ]
          }
        }
        ```
      tags:
        - MCP
      parameters:
        - name: mcp-session-id
          in: header
          required: true
          schema:
            type: string
            format: uuid
          description: MCP session identifier from the initialize call.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpApiCallRequest'
            example:
              jsonrpc: '2.0'
              id: 2
              method: tools/call
              params:
                name: api_call
                arguments:
                  method: GET
                  path: /advertisers
                  query:
                    take: 10
      responses:
        '200':
          description: API call executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpToolResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
  /ask-about-capability:
    servers: *ref_1
    post:
      operationId: mcpAskAboutCapability
      summary: Ask about API capabilities
      description: |-
        Learn about Buyer API features and capabilities using natural language questions.

        This tool helps AI agents understand what the API can do without needing to read documentation.

        ## Parameters

        - `question`: A natural language question about API capabilities

        ## Example Questions

        - "How do I create a campaign?"
        - "What can I configure on a campaign?"
        - "What authentication is required?"

        ## Example Request

        ```json
        {
          "jsonrpc": "2.0",
          "id": 4,
          "method": "tools/call",
          "params": {
            "name": "ask_about_capability",
            "arguments": {
              "question": "How do I create a campaign?"
            }
          }
        }
        ```

        ## Example Response

        ```json
        {
          "jsonrpc": "2.0",
          "id": 4,
          "result": {
            "content": [
              {
                "type": "text",
                "text": "To create a campaign, use POST /campaigns with..."
              }
            ]
          }
        }
        ```
      tags:
        - MCP
      parameters:
        - name: mcp-session-id
          in: header
          required: true
          schema:
            type: string
            format: uuid
          description: MCP session identifier from the initialize call.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpAskCapabilityRequest'
            example:
              jsonrpc: '2.0'
              id: 4
              method: tools/call
              params:
                name: ask_about_capability
                arguments:
                  question: How do I create a campaign?
      responses:
        '200':
          description: Capability information returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpToolResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateAdvertiserBody:
      description: Request body for creating a new advertiser
      type: object
      properties:
        name:
          description: Name of the advertiser
          example: Acme Corp
          type: string
          minLength: 1
          maxLength: 255
        description:
          description: Optional description of the advertiser
          example: Global advertising account for Acme Corporation
          type: string
          maxLength: 1000
        brand:
          description: >-
            Brand domain (e.g., "nike.com") or full URL to brand manifest. Brand identity is resolved from
            /.well-known/brand.json or the AdCP registry.
          example: nike.com
          type: string
          minLength: 1
        saveBrand:
          description: >-
            When true, auto-saves an enriched brand to the AdCP registry if the brand is not yet registered. Set this
            after reviewing the enriched brand preview returned from a previous attempt.
          default: false
          type: boolean
        linkedAccounts:
          description: >-
            Accounts to link to this advertiser at creation time. Each entry references a discovered account from a
            partner.
          type: array
          items:
            $ref: '#/components/schemas/LinkedAccountInput'
        optimizationApplyMode:
          description: >-
            Default mode for applying Scope3 AI model optimizations to media buys for campaigns under this advertiser.
            When set to "AUTO", optimizations are applied automatically; when "MANUAL", they require approval. Defaults
            to "MANUAL".
          allOf:
            - $ref: '#/components/schemas/OptimizationApplyMode'
        campaignBudgetType:
          description: >-
            How budget is allocated by campaign. "total_budget" means the campaign budget covers both media spend and
            fees. Defaults to "total_budget".
          allOf:
            - $ref: '#/components/schemas/CampaignBudgetType'
        sandbox:
          description: >-
            When true, this advertiser operates in sandbox mode. All ADCP operations will use sandbox-flagged accounts —
            no real platform calls, no real spend. Cannot be changed after creation.
          default: false
          type: boolean
        utmConfig:
          description: >-
            Default UTM (Urchin Tracking Module) parameters for this advertiser. These are appended to landing page URLs
            during clickthrough redirection. Campaign-level UTM config can override these per param key.
          maxItems: 20
          type: array
          items:
            type: object
            properties:
              paramKey:
                description: Output query parameter key appended to landing URL (e.g., "utm_source", "bg_campaign")
                example: utm_campaign
                type: string
                pattern: ^[a-zA-Z0-9_-]{1,100}$
              paramValue:
                description: Macro name (e.g., "{CAMPAIGN_ID}") or static string (e.g., "scope3") to resolve as the value
                example: '{CAMPAIGN_ID}'
                type: string
                minLength: 1
                maxLength: 200
            required:
              - paramKey
              - paramValue
        dataDelivery:
          $ref: '#/components/schemas/AdvertiserDataDeliveryInput'
        frequencyCaps:
          description: >-
            Buyer-side frequency cap configs to apply to this advertiser. Enforced by Scope3 across all publishers;
            distinct from publisher-side caps in package target_overlay.
          type: array
          items:
            type: object
            properties:
              max_impressions:
                description: Maximum number of impressions allowed within the window
                example: 3
                type: integer
                exclusiveMinimum: true
                maximum: 9007199254740991
              window:
                type: object
                properties:
                  interval:
                    type: number
                  unit:
                    anyOf:
                      - type: string
                        enum:
                          - seconds
                      - type: string
                        enum:
                          - minutes
                      - type: string
                        enum:
                          - hours
                      - type: string
                        enum:
                          - days
                      - type: string
                        enum:
                          - campaign
                required:
                  - interval
                  - unit
                additionalProperties: {}
            required:
              - max_impressions
              - window
            additionalProperties: {}
      required:
        - name
        - brand
    LinkedAccountInput:
      description: An account to link to the advertiser
      type: object
      properties:
        storefrontId:
          description: Storefront the source lives on. Pair with `sourceId` to identify the source whose account is being linked.
          example: 42
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
        sourceId:
          description: Inventory source within `storefrontId` whose account is being linked.
          example: src_main
          type: string
          minLength: 1
        accountId:
          description: Account ID at the source to link to this advertiser. Must come from `list_available_accounts`.
          example: acc_123
          type: string
          minLength: 1
        billingType:
          description: Billing arrangement type (e.g. "advertiser", "operator", "agent")
          example: advertiser
          type: string
      required:
        - storefrontId
        - sourceId
        - accountId
    OptimizationApplyMode:
      description: Whether optimization suggestions are automatically applied or require human approval.
      type: string
      enum:
        - AUTO
        - MANUAL
    CampaignBudgetType:
      description: How budget is allocated by campaign. "total_budget" means the campaign budget covers both media spend and fees.
      type: string
      enum:
        - total_budget
    AdvertiserDataDeliveryInput:
      description: >-
        Data-delivery configuration for this advertiser. Groups standing Data Delivery Outputs (and, in a follow-up, the
        destination credentials they reference). Distinct from media-buy reporting fields elsewhere in the API.
      type: object
      properties:
        outputs:
          description: >-
            Standing log-level data subscriptions to ship from Scope3 to a buyer-owned destination. Replaces all
            existing advertiser-scoped Data Delivery Outputs when provided. Pass an empty array to clear.
          allOf:
            - $ref: '#/components/schemas/DataDeliveryOutputArrayInput'
    DataDeliveryOutputArrayInput:
      description: >-
        Array of Data Delivery Outputs for one scope (advertiser or campaign). At most one Output per dataDeliveryType
        per scope in v1 (per (dataDeliveryType, credential) once destination credentials land).
      maxItems: 20
      type: array
      items:
        $ref: '#/components/schemas/DataDeliveryOutputInput'
    DataDeliveryOutputInput:
      description: A single Data Delivery Output entry. Used inline on advertiser/campaign create+update.
      type: object
      properties:
        dataDeliveryType:
          description: The kind of LLD shipped by this Output.
          type: string
          enum:
            - MB_DELIVERY
            - IMPRESSIONS
            - CLICKS
            - VAST_EVENTS
            - CAPI_ATTRIBUTION
            - MMP_POSTBACKS
            - MEASUREMENT
        cadence:
          description: Firing rate. HOURLY fires at minute 0 every hour, DAILY at 00:00 UTC, WEEKLY at 00:00 UTC on syncWeeklyDay.
          type: string
          enum:
            - HOURLY
            - DAILY
            - WEEKLY
        syncWeeklyDay:
          description: Day of week for WEEKLY cadence (0=Sunday..6=Saturday). Required when cadence=WEEKLY, ignored otherwise.
          type: integer
          minimum: 0
          maximum: 6
        enabled:
          description: When false, the Temporal schedule is paused — no new runs fire, in-flight runs continue. Defaults to true.
          default: true
          type: boolean
        deliveryConfig:
          $ref: '#/components/schemas/DeliveryConfig'
      required:
        - dataDeliveryType
        - cadence
        - deliveryConfig
    DeliveryConfig:
      description: >-
        Per-Output destination shape (non-secret). v1 supports GCS only; additional destination types are added as new
        variants in this discriminated union.
      oneOf:
        - $ref: '#/components/schemas/GcsDeliveryConfig'
      type: object
      discriminator:
        propertyName: type
        mapping:
          GCS: '#/components/schemas/GcsDeliveryConfig'
    GcsDeliveryConfig:
      type: object
      properties:
        type:
          type: string
          enum:
            - GCS
        bucket:
          description: Target GCS bucket name (no gs:// prefix)
          type: string
          minLength: 1
          maxLength: 222
          pattern: ^[a-z0-9][a-z0-9._-]*[a-z0-9]$
        pathPrefix:
          description: >-
            Object key prefix within the bucket. Leading slashes are stripped. May contain {YYYY}, {MM}, {DD}, {HH},
            {DATA_DELIVERY_TYPE} placeholders.
          default: ''
          type: string
          maxLength: 1024
        format:
          default: JSONL
          type: string
          enum:
            - JSONL
            - PARQUET
            - CSV
      required:
        - type
        - bucket
    UpdateAdvertiserBody:
      description: Request body for updating an advertiser
      type: object
      properties:
        name:
          description: Updated name of the advertiser
          example: Acme Corporation
          type: string
          minLength: 1
          maxLength: 255
        description:
          description: Updated description of the advertiser
          example: Updated description for Acme Corporation
          type: string
          maxLength: 1000
        brand:
          description: >-
            Updated brand domain (e.g., "nike.com"). Re-resolves brand identity from /.well-known/brand.json or the AdCP
            registry.
          example: nike.com
          type: string
          minLength: 1
        linkedAccounts:
          description: Accounts to add to this advertiser. Existing linked accounts are not removed.
          type: array
          items:
            $ref: '#/components/schemas/LinkedAccountInput'
        optimizationApplyMode:
          description: >-
            Default mode for applying Scope3 AI model optimizations to media buys for campaigns under this advertiser.
            When set to "AUTO", optimizations are applied automatically; when "MANUAL", they require approval.
          allOf:
            - $ref: '#/components/schemas/OptimizationApplyMode'
        campaignBudgetType:
          description: >-
            How budget is allocated by campaign. "total_budget" means the campaign budget covers both media spend and
            fees.
          allOf:
            - $ref: '#/components/schemas/CampaignBudgetType'
        utmConfig:
          description: >-
            Default UTM (Urchin Tracking Module) parameters for this advertiser. Replaces all existing seat-level UTM
            params. Pass an empty array to clear.
          maxItems: 20
          type: array
          items:
            type: object
            properties:
              paramKey:
                description: Output query parameter key appended to landing URL (e.g., "utm_source", "bg_campaign")
                example: utm_campaign
                type: string
                pattern: ^[a-zA-Z0-9_-]{1,100}$
              paramValue:
                description: Macro name (e.g., "{CAMPAIGN_ID}") or static string (e.g., "scope3") to resolve as the value
                example: '{CAMPAIGN_ID}'
                type: string
                minLength: 1
                maxLength: 200
            required:
              - paramKey
              - paramValue
        dataDelivery:
          description: >-
            Data-delivery configuration for this advertiser. Groups standing Data Delivery Outputs (and, in a follow-up,
            the destination credentials they reference). Omit to leave existing config untouched.
          type: object
          properties:
            outputs:
              description: >-
                Standing log-level data subscriptions to ship from Scope3 to a buyer-owned destination. Replaces all
                existing advertiser-scoped Data Delivery Outputs when provided. Pass an empty array to clear. Omit to
                leave existing Outputs untouched.
              allOf:
                - $ref: '#/components/schemas/DataDeliveryOutputArrayInput'
        frequencyCaps:
          description: >-
            Buyer-side frequency cap configs to apply to this advertiser. When provided, replaces all existing
            non-archived caps for this advertiser (pass an empty array to clear). Omit to leave existing caps untouched.
          type: array
          items:
            type: object
            properties:
              max_impressions:
                description: Maximum number of impressions allowed within the window
                example: 3
                type: integer
                exclusiveMinimum: true
                maximum: 9007199254740991
              window:
                type: object
                properties:
                  interval:
                    type: number
                  unit:
                    anyOf:
                      - type: string
                        enum:
                          - seconds
                      - type: string
                        enum:
                          - minutes
                      - type: string
                        enum:
                          - hours
                      - type: string
                        enum:
                          - days
                      - type: string
                        enum:
                          - campaign
                required:
                  - interval
                  - unit
                additionalProperties: {}
            required:
              - max_impressions
              - window
            additionalProperties: {}
    DiscoverProductsBody:
      description: Request body for discovering products with optional auto-session creation
      type: object
      properties:
        advertiserId:
          description: Advertiser ID to resolve brand manifest
          example: 12345
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
        discoveryId:
          description: Existing discovery ID. If not provided, a new discovery session is created.
          example: abc123-def456-ghi789
          type: string
        campaignId:
          description: >-
            Campaign ID to seed discovery from. The campaign brief, flight dates, and budget are used as defaults
            (explicit request values take precedence).
          example: campaign_ea5e33dd-d65b-44c7-a3e8-8e1db1d137b4
          type: string
        channels:
          description: >-
            Channels to search (defaults to ["display", "olv", "ctv", "social"]). "video" is accepted as an alias for
            "olv".
          example:
            - ctv
            - display
          type: array
          items:
            type: string
            enum:
              - display
              - olv
              - ctv
              - social
              - video
        countries:
          description: Countries to target (defaults to brand agent countries if not specified)
          example:
            - US
            - CA
          maxItems: 250
          type: array
          items:
            type: string
            pattern: ^[A-Z]{2}$
        brief:
          description: Natural language context for product search
          example: Looking for premium video inventory targeting tech enthusiasts
          type: string
          maxLength: 5000
        budget:
          description: Budget for the discovery
          example: 50000
          type: number
          minimum: 0
          exclusiveMinimum: true
        flightDates:
          description: Optional flight dates for availability filtering
          type: object
          properties:
            startDate:
              description: Campaign start date (ISO 8601)
              example: '2025-01-15T00:00:00Z'
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
            endDate:
              description: Campaign end date (ISO 8601)
              example: '2025-03-31T23:59:59Z'
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
          required:
            - startDate
            - endDate
        publisherDomain:
          description: Filter products by publisher domain (exact domain component match)
          example: hulu
          type: string
          minLength: 1
        pricingModel:
          description: Filter products by pricing model
          example: cpm
          type: string
          enum:
            - cpm
            - vcpm
            - cpc
            - cpcv
            - cpv
            - cpp
            - flat_rate
        storefrontIds:
          description: >-
            Filter discovery to these storefronts. Highly encouraged when the buyer wants results scoped to specific
            sellers — pass the IDs returned by `list_storefronts`. Combined with `storefrontNames` using OR logic. An
            empty array or omitted field both mean "no request-level filter" — if a `campaignId` is also provided and
            the campaign was created with `storefrontIds`, the campaign-level value is used in that case.
          example:
            - 42
            - 57
          maxItems: 50
          type: array
          items:
            type: integer
            exclusiveMinimum: true
            maximum: 9007199254740991
        storefrontNames:
          description: >-
            Filter discovery to storefronts whose name matches one of these values (case-insensitive substring match).
            Use when the buyer mentions a seller by name. Combined with `storefrontIds` using OR logic. An empty array
            or omitted field both mean "no request-level filter" — campaign-level pinning is used in that case if
            available.
          example:
            - Acme
            - Acme Exchange
          maxItems: 50
          type: array
          items:
            type: string
            maxLength: 255
        groupLimit:
          description: 'Maximum number of product groups to return (default: 10, max: 10)'
          example: 10
          default: 10
          type: integer
          exclusiveMinimum: true
          maximum: 10
        groupOffset:
          description: Number of groups to skip for pagination
          example: 0
          default: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        productsPerGroup:
          description: 'Maximum products to return per group (default: 10, max: 15)'
          example: 10
          default: 10
          type: integer
          exclusiveMinimum: true
          maximum: 15
        productOffset:
          description: 'Number of products to skip within each group (default: 0, max: 1000)'
          example: 5
          default: 0
          type: integer
          minimum: 0
          maximum: 1000
        debug:
          description: When true, includes detailed ADCP agent request/response debug logs in the response for troubleshooting
          type: boolean
        refine:
          description: Refinement instructions for iterating on previous discovery results. When provided, discoveryId is required.
          minItems: 1
          maxItems: 100
          type: array
          items:
            $ref: '#/components/schemas/DiscoveryRefinementItem'
      required:
        - advertiserId
    DiscoveryRefinementItem:
      description: >-
        A refinement instruction for iterating on discovery results. Scoped to the overall request, a specific product,
        or a specific proposal.
      oneOf:
        - type: object
          properties:
            scope:
              type: string
              enum:
                - request
            ask:
              description: Direction for the overall selection (e.g., "more video options and less display")
              example: more video options and less display
              type: string
              minLength: 1
              maxLength: 2000
          required:
            - scope
            - ask
        - type: object
          properties:
            scope:
              type: string
              enum:
                - product
            id:
              description: Product ID from a previous discovery response
              example: product_123
              type: string
              minLength: 1
            action:
              description: >-
                'include': return with updated pricing. 'omit': exclude from response. 'more_like_this': find similar
                products.
              type: string
              enum:
                - include
                - omit
                - more_like_this
            ask:
              description: Specific changes for this product (e.g., 'add 16:9 format'). Ignored when action is 'omit'.
              example: same audience but video format
              type: string
              maxLength: 2000
          required:
            - scope
            - id
            - action
        - type: object
          properties:
            scope:
              type: string
              enum:
                - proposal
            id:
              description: Proposal ID from a previous discovery response
              example: proposal_abc123
              type: string
              minLength: 1
            action:
              description: >-
                'include': return with updated allocations. 'omit': exclude from response. 'finalize': request firm
                pricing and inventory hold.
              type: string
              enum:
                - include
                - omit
                - finalize
            ask:
              description: Changes for this proposal (e.g., 'shift more budget toward video'). Ignored when action is 'omit'.
              example: reduce total by 10%
              type: string
              maxLength: 2000
          required:
            - scope
            - id
            - action
      type: object
    AddProductsRequest:
      description: Request to add products to a discovery session
      type: object
      properties:
        products:
          description: Products to add to the selection
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/ProductSelection'
        replace:
          description: When true, replaces all existing products instead of merging
          type: boolean
      required:
        - products
    ProductSelection:
      description: Product selection for adding to a discovery session
      type: object
      properties:
        productId:
          description: Product ID to add
          example: product_123
          type: string
        salesAgentId:
          description: Sales agent ID for this product
          example: agent_456
          type: string
        groupId:
          description: Group ID where the product was discovered
          example: ctx_123-group-0
          type: string
        groupName:
          description: Name of the group where the product was discovered
          example: Publisher Name
          type: string
        bidPrice:
          description: >-
            Bid price for non-fixed pricing options (isFixed: false). Read from the product's pricingOptions (rate or
            floorPrice) in the discovery response.
          example: 12.5
          type: number
        budget:
          description: Budget allocation for this product
          example: 5000
          type: number
        pricingOptionId:
          description: Pricing option ID from the sales agent
          example: po_abc123
          type: string
      required:
        - productId
        - salesAgentId
        - groupId
        - groupName
    RemoveProductsRequest:
      description: Request to remove products from a discovery session
      type: object
      properties:
        productIds:
          description: Product IDs to remove from the selection
          minItems: 1
          type: array
          items:
            type: string
      required:
        - productIds
    ApplyProposalRequest:
      description: Apply a sales agent proposal to auto-add products with recommended budget allocations
      type: object
      properties:
        proposalId:
          description: Proposal ID from the discover-products response to apply
          example: proposal_abc123
          type: string
        totalBudget:
          description: Total budget to distribute across products. Defaults to the proposal totalBudgetGuidance.recommended.
          example: 50000
          type: number
          minimum: 0
          exclusiveMinimum: true
        replace:
          description: When true, replaces all existing products instead of merging
          type: boolean
      required:
        - proposalId
    CreateCampaignBody:
      description: Request body for creating a campaign
      type: object
      properties:
        advertiserId:
          description: Advertiser ID that will own this campaign
          example: 12345
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
        name:
          description: Name of the campaign
          example: Q1 2025 Campaign
          type: string
          minLength: 1
          maxLength: 255
        flightDates:
          description: Campaign flight dates
          type: object
          properties:
            startDate:
              description: Campaign start date (ISO 8601)
              example: '2025-01-15T00:00:00Z'
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
            endDate:
              description: Campaign end date (ISO 8601)
              example: '2025-03-31T23:59:59Z'
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
          required:
            - startDate
            - endDate
        budget:
          description: Campaign budget configuration
          type: object
          properties:
            total:
              type: number
              minimum: 0
              exclusiveMinimum: true
            currency:
              default: USD
              type: string
              minLength: 3
              maxLength: 3
            dailyCap:
              type: number
              minimum: 0
              exclusiveMinimum: true
            pacing:
              type: string
              enum:
                - EVEN
                - ASAP
                - FRONTLOADED
          required:
            - total
        campaignType:
          description: >-
            Determines Scope3's role in the campaign. DECISIONED campaigns use Scope3 optimization; ROUTED campaigns
            pass through to the sales agent using customer credentials. Immutable after creation.
          allOf:
            - $ref: '#/components/schemas/CampaignType'
        brief:
          description: Natural language brief for product search context
          example: Looking for premium video inventory targeting tech enthusiasts
          type: string
          maxLength: 5000
        constraints:
          description: Campaign targeting constraints
          type: object
          properties:
            channels:
              description: Channels to target (e.g., ["ctv", "display"])
              type: array
              items:
                type: string
            countries:
              description: Countries to target (ISO 3166-1 alpha-2 codes)
              maxItems: 250
              type: array
              items:
                type: string
                pattern: ^[A-Z]{2}$
        storefrontIds:
          description: >-
            Storefront IDs the campaign is limited to. When set, every `discover_products` run for this campaign
            auto-applies this filter — buyers do not need to resend it. Pass the IDs returned by `list_storefronts`.
            Highly encouraged so the campaign only sources inventory from sellers the buyer has chosen.
          example:
            - 42
            - 57
          maxItems: 50
          type: array
          items:
            type: integer
            exclusiveMinimum: true
            maximum: 9007199254740991
        discoveryId:
          description: Attach an existing discovery session to the campaign
          example: abc123-def456-ghi789
          type: string
          minLength: 1
        productIds:
          description: Product IDs to pre-select from the discovery session (requires discoveryId)
          example:
            - prod_123
            - prod_456
          type: array
          items:
            type: string
        audienceConfig:
          description: Audience targeting and suppression configuration. On create, listed audiences are attached to the campaign.
          type: object
          properties:
            targetAudienceIds:
              description: Audience IDs to target with this campaign
              example:
                - aud_123
                - aud_456
              maxItems: 100
              type: array
              items:
                type: string
                minLength: 1
            suppressAudienceIds:
              description: Audience IDs to suppress (exclude) from this campaign
              example:
                - aud_789
              maxItems: 100
              type: array
              items:
                type: string
                minLength: 1
        performanceConfig:
          description: Performance optimization configuration
          allOf:
            - $ref: '#/components/schemas/PerformanceConfig'
        optimizationApplyMode:
          description: >-
            Controls whether Scope3 AI model optimizations to media buys are applied automatically or require manual
            approval. If omitted, inherits the advertiser-level setting.
          allOf:
            - $ref: '#/components/schemas/OptimizationApplyMode'
        catalogId:
          description: >-
            ID of a catalog (from the advertiser catalogs list) to attach to this campaign. Only one catalog may be
            attached per campaign.
          example: 42
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
        pacingPeriods:
          description: >-
            Pacing schedule for the campaign. Defines time-based spend periods with varying intensity. In weight mode,
            budget is distributed proportionally by weighted days. In budget mode, explicit dollar amounts are set per
            period. Gaps between periods are treated as pauses (no spend). On execution, each product is split into one
            package per period with proportional budget.
          allOf:
            - $ref: '#/components/schemas/PacingPeriods'
        utmConfig:
          description: >-
            UTM (Urchin Tracking Module) parameter configuration for this campaign. Overrides seat-level defaults for
            matching param keys.
          allOf:
            - $ref: '#/components/schemas/CampaignUtmConfig'
        dataDelivery:
          $ref: '#/components/schemas/CampaignDataDeliveryInput'
        frequencyCaps:
          description: Buyer-side frequency cap configs to apply to this campaign. Enforced by Scope3 across all publishers.
          type: array
          items:
            type: object
            properties:
              max_impressions:
                description: Maximum number of impressions allowed within the window
                example: 3
                type: integer
                exclusiveMinimum: true
                maximum: 9007199254740991
              window:
                type: object
                properties:
                  interval:
                    type: number
                  unit:
                    anyOf:
                      - type: string
                        enum:
                          - seconds
                      - type: string
                        enum:
                          - minutes
                      - type: string
                        enum:
                          - hours
                      - type: string
                        enum:
                          - days
                      - type: string
                        enum:
                          - campaign
                required:
                  - interval
                  - unit
                additionalProperties: {}
            required:
              - max_impressions
              - window
            additionalProperties: {}
      required:
        - advertiserId
        - name
        - flightDates
        - budget
        - campaignType
    CampaignType:
      description: >-
        Determines Scope3's role: DECISIONED campaigns use Scope3 optimization; ROUTED campaigns pass through to the
        sales agent using customer credentials. Immutable after creation.
      type: string
      enum:
        - DECISIONED
        - ROUTED
    PerformanceConfig:
      description: Configuration for performance campaign optimization
      type: object
      properties:
        optimizationGoals:
          description: Optimization goals for the campaign. Each goal targets either conversion events or seller-native metrics.
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/OptimizationGoal'
      required:
        - optimizationGoals
    OptimizationGoal:
      description: >-
        A single optimization target. Either kind "event" (conversion events) or kind "metric" (seller-native delivery
        metric).
      oneOf:
        - $ref: '#/components/schemas/EventGoal'
        - $ref: '#/components/schemas/MetricGoal'
      type: object
      discriminator:
        propertyName: kind
        mapping:
          event: '#/components/schemas/EventGoal'
          metric: '#/components/schemas/MetricGoal'
    EventGoal:
      description: Optimize for advertiser-tracked conversion events via event sources.
      type: object
      properties:
        kind:
          type: string
          enum:
            - event
        eventSources:
          description: Event source and type pairs feeding this goal. Seller deduplicates by event_id across entries.
          minItems: 1
          type: array
          items:
            type: object
            properties:
              eventSourceId:
                description: Event source to include (must be configured via sync_event_sources)
                example: website_pixel
                type: string
                minLength: 1
              eventType:
                description: IAB ECAPI event type to optimize for
                type: string
                enum:
                  - page_view
                  - view_content
                  - select_content
                  - select_item
                  - search
                  - share
                  - add_to_cart
                  - remove_from_cart
                  - viewed_cart
                  - add_to_wishlist
                  - initiate_checkout
                  - add_payment_info
                  - purchase
                  - refund
                  - lead
                  - qualify_lead
                  - close_convert_lead
                  - disqualify_lead
                  - complete_registration
                  - subscribe
                  - start_trial
                  - app_install
                  - app_launch
                  - contact
                  - schedule
                  - donate
                  - submit_application
                  - custom
              customEventName:
                description: Required when eventType is 'custom'. Platform-specific custom event name.
                type: string
              valueField:
                description: Field on custom_data carrying the monetary value. Required when target is 'per_ad_spend'.
                example: value
                type: string
              valueFactor:
                description: Multiplier for valueField (default 1). Use -1 for refunds, 0.01 for cents.
                example: 1
                type: number
            required:
              - eventSourceId
              - eventType
        target:
          description: Target cost or return. When omitted, the seller maximizes conversions within budget.
          oneOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - cost_per
                value:
                  description: Target cost per unit in buy currency
                  example: 25
                  type: number
                  minimum: 0
                  exclusiveMinimum: true
              required:
                - kind
                - value
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - per_ad_spend
                value:
                  description: Target return ratio (e.g. 4.0 = $4 of value per $1 spent)
                  example: 4
                  type: number
                  minimum: 0
                  exclusiveMinimum: true
              required:
                - kind
                - value
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - maximize_value
              required:
                - kind
          type: object
        attributionWindow:
          description: Attribution window for this goal. When omitted, the seller uses their default.
          allOf:
            - $ref: '#/components/schemas/OptimizationAttributionWindow'
        priority:
          description: Priority among goals on this package. 1 = highest. When omitted, sellers use array position.
          example: 1
          type: integer
          minimum: 1
          maximum: 9007199254740991
      required:
        - kind
        - eventSources
    OptimizationAttributionWindow:
      description: Attribution window for conversion optimization
      type: object
      properties:
        postClick:
          description: Click-through attribution window
          example:
            interval: 7
            unit: days
          allOf:
            - $ref: '#/components/schemas/Duration'
        postView:
          description: View-through attribution window
          example:
            interval: 1
            unit: days
          allOf:
            - $ref: '#/components/schemas/Duration'
      required:
        - postClick
    Duration:
      description: A duration expressed as an interval and unit
      type: object
      properties:
        interval:
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
        unit:
          type: string
          enum:
            - minutes
            - hours
            - days
            - campaign
      required:
        - interval
        - unit
    MetricGoal:
      description: Optimize for a seller-tracked delivery metric. No event source required.
      type: object
      properties:
        kind:
          type: string
          enum:
            - metric
        metric:
          description: >-
            Seller-native metric to optimize for. Delivery metrics: clicks, views (viewable impressions, per AdCP),
            completed_views (video/audio completions, qualified by viewDurationSeconds). Duration/score: viewed_seconds,
            attention_seconds, attention_score. Audience action: engagements, follows, saves, profile_visits. To target
            a viewability rate, use metric: 'views' with a threshold_rate target (proportion of impressions).
          type: string
          enum:
            - clicks
            - views
            - completed_views
            - viewed_seconds
            - attention_seconds
            - attention_score
            - engagements
            - follows
            - saves
            - profile_visits
        viewDurationSeconds:
          description: Minimum video view duration in seconds for completed_view. Only applicable when metric is 'completed_views'.
          type: number
          minimum: 0
          exclusiveMinimum: true
        target:
          description: Target for this metric. When omitted, the seller maximizes metric volume within budget.
          oneOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - cost_per
                value:
                  description: Target cost per unit in buy currency
                  example: 25
                  type: number
                  minimum: 0
                  exclusiveMinimum: true
              required:
                - kind
                - value
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - threshold_rate
                value:
                  description: >-
                    Minimum per-impression value. Units depend on metric: proportion (clicks, views), seconds
                    (viewed_seconds, attention_seconds), or score (attention_score).
                  example: 0.001
                  type: number
                  minimum: 0
                  exclusiveMinimum: true
              required:
                - kind
                - value
          type: object
        priority:
          description: Priority among goals on this package. 1 = highest. When omitted, sellers use array position.
          example: 2
          type: integer
          minimum: 1
          maximum: 9007199254740991
      required:
        - kind
        - metric
    PacingPeriods:
      description: >-
        Defines a pacing schedule for a campaign. Periods represent time windows with varying spend intensity. Gaps
        between periods are treated as pauses (no spend). Use weight mode for relative intensity (e.g., 2x during
        holidays) or budget mode for explicit dollar amounts per period.
      type: object
      properties:
        mode:
          description: >-
            How period budgets are determined. "weight" uses relative weights to distribute the campaign budget
            proportionally. "budget" uses explicit dollar amounts per period.
          type: string
          enum:
            - weight
            - budget
        periods:
          description: Ordered list of pacing periods with date ranges and spend intensity
          minItems: 1
          maxItems: 52
          type: array
          items:
            type: object
            properties:
              label:
                description: Human-readable label for this period (e.g. "Memorial Day Heavy-Up")
                type: string
                minLength: 1
                maxLength: 100
              start:
                description: Period start date (YYYY-MM-DD, inclusive)
                type: string
                pattern: ^\d{4}-\d{2}-\d{2}$
              end:
                description: Period end date (YYYY-MM-DD, inclusive)
                type: string
                pattern: ^\d{4}-\d{2}-\d{2}$
              weight:
                description: Relative spend weight (1.0 = normal, 2.5 = 150% more). Required when mode is "weight".
                type: number
                minimum: 0
                exclusiveMinimum: true
                maximum: 10
              budget:
                description: Absolute budget for this period. Required when mode is "budget".
                type: number
                minimum: 0
                exclusiveMinimum: true
            required:
              - label
              - start
              - end
      required:
        - mode
        - periods
    CampaignUtmConfig:
      description: UTM configuration for a campaign. Overrides seat-level defaults for matching param keys.
      type: object
      properties:
        params:
          description: Array of UTM parameter mappings for this campaign
          maxItems: 20
          type: array
          items:
            type: object
            properties:
              paramKey:
                description: Output query parameter key appended to landing URL (e.g., "utm_source", "bg_campaign")
                example: utm_campaign
                type: string
                pattern: ^[a-zA-Z0-9_-]{1,100}$
              paramValue:
                description: Macro name (e.g., "{CAMPAIGN_ID}") or static string (e.g., "scope3") to resolve as the value
                example: '{CAMPAIGN_ID}'
                type: string
                minLength: 1
                maxLength: 200
            required:
              - paramKey
              - paramValue
        deleteMissing:
          description: >-
            If true, remove campaign-level UTM params not in this request (replace mode). If false/omitted, only
            add/update (additive mode).
          type: boolean
      required:
        - params
    CampaignDataDeliveryInput:
      description: >-
        Campaign-scoped data-delivery configuration. Groups Data Delivery Outputs that override advertiser-scoped
        delivery for the same `dataDeliveryType`. Distinct from media-buy reporting fields elsewhere in the API.
      type: object
      properties:
        outputs:
          description: >-
            Campaign-scoped Data Delivery Outputs. Override advertiser-scoped Outputs by `dataDeliveryType`. Replaces
            all existing campaign-scoped Outputs when provided. Pass an empty array to clear.
          allOf:
            - $ref: '#/components/schemas/DataDeliveryOutputArrayInput'
    UpdateCampaignBody:
      description: Request body for updating a campaign
      type: object
      properties:
        name:
          description: Updated campaign name
          type: string
          minLength: 1
          maxLength: 255
        flightDates:
          description: Updated campaign flight dates
          type: object
          properties:
            startDate:
              description: Campaign start date (ISO 8601)
              example: '2025-01-15T00:00:00Z'
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
            endDate:
              description: Campaign end date (ISO 8601)
              example: '2025-03-31T23:59:59Z'
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
          required:
            - startDate
            - endDate
        budget:
          description: Updated budget configuration (partial updates allowed)
          type: object
          properties:
            total:
              type: number
              minimum: 0
              exclusiveMinimum: true
            currency:
              default: USD
              type: string
              minLength: 3
              maxLength: 3
            dailyCap:
              type: number
              minimum: 0
              exclusiveMinimum: true
            pacing:
              type: string
              enum:
                - EVEN
                - ASAP
                - FRONTLOADED
        brief:
          description: Updated campaign brief
          type: string
          maxLength: 5000
        constraints:
          description: Updated targeting constraints
          type: object
          properties:
            channels:
              description: Channels to target (e.g., ["ctv", "display"])
              type: array
              items:
                type: string
            countries:
              description: Countries to target (ISO 3166-1 alpha-2 codes)
              maxItems: 250
              type: array
              items:
                type: string
                pattern: ^[A-Z]{2}$
        storefrontIds:
          description: >-
            Updated storefront filter for the campaign. Pass an empty array to clear (no storefront limit). Subsequent
            product discovery runs against this campaign auto-apply the new filter.
          example:
            - 42
            - 57
          maxItems: 50
          type: array
          items:
            type: integer
            exclusiveMinimum: true
            maximum: 9007199254740991
        discoveryId:
          description: Attach a discovery session to the campaign
          type: string
          minLength: 1
        audienceConfig:
          description: 'Audience targeting and suppression configuration. Use deleteMissing: true to replace the full audience set.'
          type: object
          properties:
            targetAudienceIds:
              description: Audience IDs to target. Can be empty when deleteMissing is true to remove all targeted audiences.
              example:
                - aud_123
                - aud_456
              maxItems: 100
              type: array
              items:
                type: string
                minLength: 1
            suppressAudienceIds:
              description: Audience IDs to suppress. Can be empty when deleteMissing is true to remove all suppressed audiences.
              example:
                - aud_789
              maxItems: 100
              type: array
              items:
                type: string
                minLength: 1
            deleteMissing:
              description: When true, audiences NOT in the respective lists are removed. When false or omitted, lists are additive.
              type: boolean
        performanceConfig:
          description: Updated performance configuration
          allOf:
            - $ref: '#/components/schemas/PerformanceConfig'
        optimizationApplyMode:
          description: >-
            Controls whether Scope3 AI model optimizations to media buys are applied automatically or require manual
            approval. If omitted, inherits the advertiser-level setting.
          allOf:
            - $ref: '#/components/schemas/OptimizationApplyMode'
        catalogId:
          description: Catalog ID to attach (or null to detach the current catalog)
          nullable: true
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
        mediaBuys:
          description: >-
            Media buy actions. Each entry targets a specific media buy by ID. Use action: "update" (default) to modify,
            "cancel" to cancel, or "delete" to archive.
          type: array
          items:
            type: object
            properties:
              action:
                description: >-
                  Action to perform. "update" (default) modifies the media buy, "cancel" cancels it, "delete" archives
                  it.
                type: string
                enum:
                  - update
                  - cancel
                  - delete
              mediaBuyId:
                description: ID of the media buy to act on
                type: string
                minLength: 1
              reason:
                description: 'Cancellation reason (only for action: "cancel")'
                type: string
                maxLength: 1000
              packageIds:
                description: 'Cancel specific packages instead of the whole media buy (only for action: "cancel")'
                type: array
                items:
                  type: string
                  minLength: 1
              name:
                description: Updated media buy name
                type: string
                minLength: 1
                maxLength: 255
              packages:
                description: Per-package updates (for ACTIVE media buys with deployed packages)
                type: array
                items:
                  type: object
                  properties:
                    packageId:
                      description: Package ID to update
                      type: string
                      minLength: 1
                    budget:
                      description: Updated budget amount
                      type: number
                      minimum: 0
                      exclusiveMinimum: true
                    pacing:
                      description: Updated pacing strategy
                      type: string
                      enum:
                        - even
                        - asap
                    bid_price:
                      description: Updated bid price
                      nullable: true
                      type: number
                  required:
                    - packageId
                  additionalProperties: false
              products:
                description: >-
                  Product updates — additive (existing products not listed are preserved). Use remove: true to delete a
                  product.
                type: array
                items:
                  type: object
                  properties:
                    product_id:
                      description: Product ID
                      type: string
                      minLength: 1
                    pricing_option_id:
                      type: string
                    budget:
                      type: number
                      minimum: 0
                      exclusiveMinimum: true
                    pacing:
                      type: string
                      enum:
                        - asap
                        - even
                        - front_loaded
                    bid_price:
                      nullable: true
                      type: number
                    remove:
                      description: Set to true to remove this product from the media buy
                      type: boolean
                  required:
                    - product_id
                  additionalProperties: false
              start_time:
                description: >-
                  "asap" or ISO 8601 date-time. Start of this media buy. Cannot be earlier than the campaign's
                  flightDates.startDate. Media buy dates MAY correspond to a pacingPeriods[].start when the media buy
                  represents a specific period, but pacing periods do not govern media buy dates — a media buy can have
                  any start within the campaign flight, with or without pacing periods.
                type: string
              end_time:
                description: >-
                  ISO 8601 date-time. End of this media buy. Must fall within the campaign's flight dates. Media buy
                  dates MAY correspond to a pacingPeriods[].end when the media buy represents a specific period, but
                  pacing periods do not govern media buy dates — a media buy can have any end within the campaign
                  flight, with or without pacing periods.
                type: string
              updated_reason:
                description: Reason for the update (stored with the new version for SCD Type 2)
                type: string
              suggestion_id:
                description: Suggestion ID from RL optimizer
                type: string
              optimization_goals:
                type: array
                items:
                  anyOf:
                    - type: object
                      properties:
                        kind:
                          type: string
                          enum:
                            - metric
                        metric:
                          anyOf:
                            - type: string
                              enum:
                                - clicks
                            - type: string
                              enum:
                                - views
                            - type: string
                              enum:
                                - completed_views
                            - type: string
                              enum:
                                - viewed_seconds
                            - type: string
                              enum:
                                - attention_seconds
                            - type: string
                              enum:
                                - attention_score
                            - type: string
                              enum:
                                - engagements
                            - type: string
                              enum:
                                - follows
                            - type: string
                              enum:
                                - saves
                            - type: string
                              enum:
                                - profile_visits
                            - type: string
                              enum:
                                - reach
                        reach_unit:
                          anyOf:
                            - type: string
                              enum:
                                - individuals
                            - type: string
                              enum:
                                - households
                            - type: string
                              enum:
                                - devices
                            - type: string
                              enum:
                                - accounts
                            - type: string
                              enum:
                                - cookies
                            - type: string
                              enum:
                                - custom
                        target_frequency:
                          type: object
                          additionalProperties: {}
                        view_duration_seconds:
                          type: number
                        target:
                          anyOf:
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - cost_per
                                value:
                                  type: number
                              required:
                                - kind
                                - value
                              additionalProperties: {}
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - threshold_rate
                                value:
                                  type: number
                              required:
                                - kind
                                - value
                              additionalProperties: {}
                        priority:
                          type: number
                      required:
                        - kind
                        - metric
                      additionalProperties: {}
                    - type: object
                      properties:
                        kind:
                          type: string
                          enum:
                            - event
                        event_sources:
                          type: array
                          items:
                            type: object
                            properties:
                              event_source_id:
                                type: string
                              event_type:
                                anyOf:
                                  - type: string
                                    enum:
                                      - page_view
                                  - type: string
                                    enum:
                                      - view_content
                                  - type: string
                                    enum:
                                      - select_content
                                  - type: string
                                    enum:
                                      - select_item
                                  - type: string
                                    enum:
                                      - search
                                  - type: string
                                    enum:
                                      - share
                                  - type: string
                                    enum:
                                      - add_to_cart
                                  - type: string
                                    enum:
                                      - remove_from_cart
                                  - type: string
                                    enum:
                                      - viewed_cart
                                  - type: string
                                    enum:
                                      - add_to_wishlist
                                  - type: string
                                    enum:
                                      - initiate_checkout
                                  - type: string
                                    enum:
                                      - add_payment_info
                                  - type: string
                                    enum:
                                      - purchase
                                  - type: string
                                    enum:
                                      - refund
                                  - type: string
                                    enum:
                                      - lead
                                  - type: string
                                    enum:
                                      - qualify_lead
                                  - type: string
                                    enum:
                                      - close_convert_lead
                                  - type: string
                                    enum:
                                      - disqualify_lead
                                  - type: string
                                    enum:
                                      - complete_registration
                                  - type: string
                                    enum:
                                      - subscribe
                                  - type: string
                                    enum:
                                      - start_trial
                                  - type: string
                                    enum:
                                      - app_install
                                  - type: string
                                    enum:
                                      - app_launch
                                  - type: string
                                    enum:
                                      - contact
                                  - type: string
                                    enum:
                                      - schedule
                                  - type: string
                                    enum:
                                      - donate
                                  - type: string
                                    enum:
                                      - submit_application
                                  - type: string
                                    enum:
                                      - custom
                              custom_event_name:
                                type: string
                              value_field:
                                type: string
                              value_factor:
                                type: number
                            required:
                              - event_source_id
                              - event_type
                            additionalProperties: {}
                        target:
                          anyOf:
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - cost_per
                                value:
                                  type: number
                              required:
                                - kind
                                - value
                              additionalProperties: {}
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - per_ad_spend
                                value:
                                  type: number
                              required:
                                - kind
                                - value
                              additionalProperties: {}
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - maximize_value
                              required:
                                - kind
                              additionalProperties: {}
                        attribution_window:
                          type: object
                          properties:
                            post_click:
                              type: object
                              properties:
                                interval:
                                  type: number
                                unit:
                                  anyOf:
                                    - type: string
                                      enum:
                                        - seconds
                                    - type: string
                                      enum:
                                        - minutes
                                    - type: string
                                      enum:
                                        - hours
                                    - type: string
                                      enum:
                                        - days
                                    - type: string
                                      enum:
                                        - campaign
                              required:
                                - interval
                                - unit
                              additionalProperties: {}
                            post_view:
                              type: object
                              properties:
                                interval:
                                  type: number
                                unit:
                                  anyOf:
                                    - type: string
                                      enum:
                                        - seconds
                                    - type: string
                                      enum:
                                        - minutes
                                    - type: string
                                      enum:
                                        - hours
                                    - type: string
                                      enum:
                                        - days
                                    - type: string
                                      enum:
                                        - campaign
                              required:
                                - interval
                                - unit
                              additionalProperties: {}
                          required:
                            - post_click
                          additionalProperties: {}
                        priority:
                          type: number
                      required:
                        - kind
                        - event_sources
                      additionalProperties: {}
              creative_ids:
                description: >-
                  Explicit creative IDs to attach to this media buy. When provided, overrides the campaign-level
                  auto-sync (which otherwise pushes the campaign's manifest-linked creatives, filtered to formats
                  accepted by this buy's products). Pass an empty array to clear all creatives. Omit (or leave
                  undefined) to use auto-sync. Each ID must already be linked to this campaign and must match a format
                  accepted by the media buy's products — otherwise the update fails with a validation error.
                type: array
                items:
                  type: string
                  minLength: 1
            required:
              - mediaBuyId
            additionalProperties: false
        pacingPeriods:
          description: >-
            Pacing schedule for the campaign. Set to null to remove pacing periods and revert to standard single-period
            behavior. Can only be modified on DRAFT campaigns.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/PacingPeriods'
        utmConfig:
          description: >-
            UTM (Urchin Tracking Module) parameter configuration for this campaign. Use deleteMissing: true to replace;
            otherwise additive.
          allOf:
            - $ref: '#/components/schemas/CampaignUtmConfig'
        dataDelivery:
          description: >-
            Campaign-scoped data-delivery configuration. Groups Data Delivery Outputs that override advertiser-scoped
            delivery for the same `dataDeliveryType`. Omit to leave existing config untouched.
          type: object
          properties:
            outputs:
              description: >-
                Campaign-scoped Data Delivery Outputs. Override advertiser-scoped Outputs by `dataDeliveryType`.
                Replaces all existing campaign-scoped Outputs when provided. Pass an empty array to clear. Omit to leave
                existing Outputs untouched.
              allOf:
                - $ref: '#/components/schemas/DataDeliveryOutputArrayInput'
        frequencyCaps:
          description: >-
            Buyer-side frequency cap configs for this campaign. When provided, replaces all existing non-archived caps
            for this campaign (pass an empty array to clear). Omit to leave existing caps untouched.
          type: array
          items:
            type: object
            properties:
              max_impressions:
                description: Maximum number of impressions allowed within the window
                example: 3
                type: integer
                exclusiveMinimum: true
                maximum: 9007199254740991
              window:
                type: object
                properties:
                  interval:
                    type: number
                  unit:
                    anyOf:
                      - type: string
                        enum:
                          - seconds
                      - type: string
                        enum:
                          - minutes
                      - type: string
                        enum:
                          - hours
                      - type: string
                        enum:
                          - days
                      - type: string
                        enum:
                          - campaign
                required:
                  - interval
                  - unit
                additionalProperties: {}
            required:
              - max_impressions
              - window
            additionalProperties: {}
    ExecuteCampaignBody:
      description: Optional request body for executing a campaign
      type: object
      properties:
        debug:
          description: When true, includes detailed debug information in error responses from media buy execution
          type: boolean
    AutoSelectProductsRequest:
      description: Optional refinement parameters for iterative auto-select product selection. Based on ADCP refine spec.
      type: object
      properties:
        refine:
          description: >-
            Array of refinement directives from a previous auto-select response. Supports request-scoped direction and
            product-scoped include/omit/more_like_this actions.
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/RefinementItem'
        maxProducts:
          description: Maximum number of products to select
          example: 5
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
        minBudgetPerProduct:
          description: Minimum budget to allocate per product
          example: 500
          type: number
          minimum: 0
          exclusiveMinimum: true
    RefinementItem:
      description: A single refinement directive (request-scoped or product-scoped)
      oneOf:
        - description: 'Request-scoped refinement: direction for the overall selection'
          type: object
          properties:
            scope:
              description: Applies direction to the overall selection
              type: string
              enum:
                - request
            ask:
              description: Free-text direction for the overall selection, e.g. "more video options and less display"
              type: string
              minLength: 1
          required:
            - scope
            - ask
        - description: 'Product-scoped refinement: target a specific product'
          type: object
          properties:
            scope:
              description: Targets a specific product from a prior auto-select response
              type: string
              enum:
                - product
            id:
              description: Product ID from a prior auto-select response
              type: string
              minLength: 1
            action:
              description: 'include: keep this product; omit: exclude it; moreLikeThis: find similar products'
              type: string
              enum:
                - include
                - omit
                - moreLikeThis
            ask:
              description: Optional direction when action is include or more_like_this
              type: string
              minLength: 1
          required:
            - scope
            - id
            - action
      type: object
    CreateCreativeManifestMetadata:
      description: JSON metadata for creating a creative manifest
      type: object
      properties:
        name:
          description: Manifest name (auto-generated if omitted)
          type: string
          minLength: 1
          maxLength: 255
        message:
          description: Creative brief / direction text
          type: string
          minLength: 1
          maxLength: 5000
        url_asset:
          description: Add a URL asset (per AdCP url-asset spec). Requires url_type.
          type: object
          properties:
            url:
              description: URL to add as asset (must be http/https)
              type: string
              format: uri
            url_type:
              description: URL type classification
              type: string
              enum:
                - CLICKTHROUGH
                - TRACKER_PIXEL
                - TRACKER_SCRIPT
                - VAST
          required:
            - url
            - url_type
        webhook_asset:
          description: Add a webhook asset for DCO (dynamic content).
          type: object
          properties:
            url:
              description: URL to add as asset (must be http/https)
              type: string
              format: uri
            method:
              type: string
              enum:
                - GET
                - POST
            timeout_ms:
              type: integer
              minimum: 10
              maximum: 5000
            response_type:
              type: string
              enum:
                - html
                - json
                - xml
                - javascript
            security:
              type: object
              properties:
                method:
                  type: string
                  enum:
                    - hmac_sha256
                    - api_key
                    - none
                hmac_header:
                  type: string
                api_key_header:
                  type: string
              required:
                - method
          required:
            - url
            - response_type
            - security
        format_id:
          type: object
          properties:
            agent_url:
              type: string
            id:
              type: string
            width:
              type: number
            height:
              type: number
            duration_ms:
              type: number
          required:
            - agent_url
            - id
          additionalProperties: {}
        template_id:
          description: >-
            Creative template ID — ADCP format ID (e.g., "display_image", "display_html", "video_standard") or vendor
            tag (e.g., "vendor_dcm_tag")
          type: string
        assets:
          description: Metadata for uploaded files. If omitted, all uploaded files are auto-classified.
          type: array
          items:
            type: object
            properties:
              filename:
                description: Must match an uploaded file's originalname
                type: string
                minLength: 1
              asset_type:
                description: Asset type (auto-detected from MIME if omitted)
                type: string
                enum:
                  - IMAGE
                  - VIDEO
                  - AUDIO
                  - HTML
                  - JAVASCRIPT
                  - CSS
                  - TEXT
                  - URL
                  - VAST
                  - FONT
                  - LOGO
                  - DOCUMENT
              label:
                description: Label/key for this asset in the manifest (auto-generated if omitted)
                type: string
            required:
              - filename
        frequencyCaps:
          description: Buyer-defined frequency caps for this creative. When provided, sets the full list.
          type: array
          items:
            type: object
            properties:
              max_impressions:
                description: Maximum number of impressions allowed within the window
                example: 3
                type: integer
                exclusiveMinimum: true
                maximum: 9007199254740991
              window:
                type: object
                properties:
                  interval:
                    type: number
                  unit:
                    anyOf:
                      - type: string
                        enum:
                          - seconds
                      - type: string
                        enum:
                          - minutes
                      - type: string
                        enum:
                          - hours
                      - type: string
                        enum:
                          - days
                      - type: string
                        enum:
                          - campaign
                required:
                  - interval
                  - unit
                additionalProperties: {}
            required:
              - max_impressions
              - window
            additionalProperties: {}
    UpdateCreativeManifestMetadata:
      description: JSON metadata for updating a creative manifest
      type: object
      properties:
        name:
          description: Updated manifest name
          type: string
          minLength: 1
          maxLength: 255
        message:
          description: Updated creative brief
          type: string
          maxLength: 5000
        format_id:
          type: object
          properties:
            agent_url:
              type: string
            id:
              type: string
            width:
              type: number
            height:
              type: number
            duration_ms:
              type: number
          required:
            - agent_url
            - id
          additionalProperties: {}
        template_id:
          description: Updated creative template ID
          type: string
        url_asset:
          description: Add a URL asset (per AdCP url-asset spec). Requires url_type.
          type: object
          properties:
            url:
              description: URL to add as asset (must be http/https)
              type: string
              format: uri
            url_type:
              description: URL type classification
              type: string
              enum:
                - CLICKTHROUGH
                - TRACKER_PIXEL
                - TRACKER_SCRIPT
                - VAST
          required:
            - url
            - url_type
        webhook_asset:
          description: Add a webhook asset for DCO (dynamic content).
          type: object
          properties:
            url:
              description: URL to add as asset (must be http/https)
              type: string
              format: uri
            method:
              type: string
              enum:
                - GET
                - POST
            timeout_ms:
              type: integer
              minimum: 10
              maximum: 5000
            response_type:
              type: string
              enum:
                - html
                - json
                - xml
                - javascript
            security:
              type: object
              properties:
                method:
                  type: string
                  enum:
                    - hmac_sha256
                    - api_key
                    - none
                hmac_header:
                  type: string
                api_key_header:
                  type: string
              required:
                - method
          required:
            - url
            - response_type
            - security
        delete_asset_ids:
          description: Asset IDs to remove from the manifest (max 100)
          maxItems: 100
          type: array
          items:
            type: string
            minLength: 1
        reclassify_assets:
          description: Reclassify existing assets to a different type
          maxItems: 100
          type: array
          items:
            type: object
            properties:
              asset_id:
                type: string
                minLength: 1
              asset_type:
                description: Creative asset type (AdCP spec + extensions)
                type: string
                enum:
                  - IMAGE
                  - VIDEO
                  - AUDIO
                  - HTML
                  - JAVASCRIPT
                  - CSS
                  - TEXT
                  - URL
                  - VAST
                  - FONT
                  - LOGO
                  - DOCUMENT
            required:
              - asset_id
              - asset_type
        new_assets:
          description: Metadata for newly uploaded files being added
          type: array
          items:
            type: object
            properties:
              filename:
                description: Must match an uploaded file's originalname
                type: string
                minLength: 1
              asset_type:
                description: Creative asset type (AdCP spec + extensions)
                type: string
                enum:
                  - IMAGE
                  - VIDEO
                  - AUDIO
                  - HTML
                  - JAVASCRIPT
                  - CSS
                  - TEXT
                  - URL
                  - VAST
                  - FONT
                  - LOGO
                  - DOCUMENT
              label:
                type: string
            required:
              - filename
        frequencyCaps:
          description: Buyer-defined frequency caps for this creative. When provided, replaces the existing list; omit to preserve.
          type: array
          items:
            type: object
            properties:
              max_impressions:
                description: Maximum number of impressions allowed within the window
                example: 3
                type: integer
                exclusiveMinimum: true
                maximum: 9007199254740991
              window:
                type: object
                properties:
                  interval:
                    type: number
                  unit:
                    anyOf:
                      - type: string
                        enum:
                          - seconds
                      - type: string
                        enum:
                          - minutes
                      - type: string
                        enum:
                          - hours
                      - type: string
                        enum:
                          - days
                      - type: string
                        enum:
                          - campaign
                required:
                  - interval
                  - unit
                additionalProperties: {}
            required:
              - max_impressions
              - window
            additionalProperties: {}
    SyncEventSourcesRequest:
      description: Request body for syncing event sources (ADCP spec)
      type: object
      properties:
        account:
          description: Advertiser account to sync event sources onto
          type: object
          properties:
            account_id:
              description: Advertiser ID (seat_id) to attach catalogs to
              example: '12345'
              type: string
              minLength: 1
          required:
            - account_id
        event_sources:
          description: Event sources to sync (up to 50 per call)
          minItems: 1
          maxItems: 50
          type: array
          items:
            $ref: '#/components/schemas/SyncEventSourceObject'
        delete_missing:
          description: Archive buyer-managed event sources not included in this request
          default: false
          type: boolean
      required:
        - account
        - event_sources
    SyncEventSourceObject:
      description: A single event source to sync
      type: object
      properties:
        event_source_id:
          description: Buyer-assigned event source identifier
          example: website_pixel
          type: string
          minLength: 1
          maxLength: 255
        name:
          description: Human-readable label for this event source
          example: Website Pixel
          type: string
          minLength: 1
          maxLength: 255
        event_types:
          description: Event types this source handles. When omitted, accepts all event types.
          example:
            - purchase
            - add_to_cart
          minItems: 1
          type: array
          items:
            description: IAB ECAPI event type to optimize for
            type: string
            enum:
              - page_view
              - view_content
              - select_content
              - select_item
              - search
              - share
              - add_to_cart
              - remove_from_cart
              - viewed_cart
              - add_to_wishlist
              - initiate_checkout
              - add_payment_info
              - purchase
              - refund
              - lead
              - qualify_lead
              - close_convert_lead
              - disqualify_lead
              - complete_registration
              - subscribe
              - start_trial
              - app_install
              - app_launch
              - contact
              - schedule
              - donate
              - submit_application
              - custom
        allowed_domains:
          description: Domains authorized to send events for this source
          example:
            - shop.example.com
            - checkout.example.com
          type: array
          items:
            type: string
            minLength: 1
      required:
        - event_source_id
    EventSummaryType:
      description: 'Type of event to filter by: conversion, click, impression, measurement, or mmp'
      type: string
      enum:
        - conversion
        - click
        - impression
        - measurement
        - mmp
    SyncMeasurementDataRequest:
      description: Request body for syncing measurement data (ADCP spec alternative to CAPI)
      type: object
      properties:
        measurements:
          description: Measurement data points to sync (up to 1000 per call)
          minItems: 1
          maxItems: 1000
          type: array
          items:
            $ref: '#/components/schemas/SyncMeasurementObject'
      required:
        - measurements
    SyncMeasurementObject:
      description: A single measurement data point to sync
      type: object
      properties:
        start_time:
          description: Start of the measurement period (ISO 8601 with timezone)
          example: '2026-03-01T00:00:00-05:00'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
        end_time:
          description: End of the measurement period (ISO 8601 with timezone)
          example: '2026-03-07T23:59:59-05:00'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
        metric_id:
          description: Type of metric being measured
          example: incremental_revenue
          type: string
          enum:
            - revenue
            - incremental_revenue
            - conversions
            - incremental_conversions
            - page_view_count
            - add_to_cart_count
            - purchase_count
            - ltv_1d
            - ltv_7d
            - ltv_30d
        metric_value:
          description: Measured value for this metric
          example: 8450.75
          type: number
        unit:
          description: Unit of measure for the metric value
          example: currency
          type: string
          enum:
            - currency
            - count
            - ratio
            - percentage
        currency:
          description: ISO 4217 currency code — required when unit is "currency"
          example: USD
          type: string
          pattern: ^[A-Z]{3}$
        campaign_id:
          description: Campaign identifier
          example: camp_456
          type: string
          minLength: 1
          maxLength: 255
        media_buy_id:
          description: Media buy identifier
          example: mb_789
          type: string
          minLength: 1
          maxLength: 255
        package_id:
          description: Package identifier
          example: pkg_001
          type: string
          minLength: 1
          maxLength: 255
        creative_id:
          description: Creative identifier
          example: cr_002
          type: string
          minLength: 1
          maxLength: 255
        source:
          description: Who sent the data
          example: advertiser
          type: string
          enum:
            - advertiser
            - mmp
            - measurement_partner
        source_platform:
          description: Platform the measurement data originates from
          example: billy_grace
          type: string
          minLength: 1
          maxLength: 255
        source_metric_name:
          description: Raw partner metric name for mapping
          example: Incremental Revenue
          type: string
          minLength: 1
          maxLength: 255
        external_row_id:
          description: External row identifier for idempotency
          example: bg_row_001
          type: string
          minLength: 1
          maxLength: 255
      required:
        - start_time
        - end_time
        - metric_id
        - metric_value
        - unit
    CreateTestCohortInput:
      description: Request body for creating a new test cohort
      type: object
      properties:
        name:
          description: Name of the test cohort
          example: West Coast Treatment Group
          type: string
          minLength: 1
          maxLength: 255
        description:
          description: Optional description of the test cohort
          example: Users in CA, OR, WA receiving full ad exposure
          type: string
          maxLength: 1000
        cohortType:
          description: Type classification for the cohort
          example: geographic
          type: string
          minLength: 1
        role:
          description: 'Role of the cohort in the test (default: TREATMENT)'
          default: TREATMENT
          type: string
          enum:
            - TREATMENT
            - CONTROL
            - OBSERVATION
        definition:
          description: Cohort targeting definition
          allOf:
            - $ref: '#/components/schemas/CohortDefinition'
        estimatedSize:
          description: Estimated number of users in this cohort
          example: 50000
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - name
        - cohortType
        - definition
    CohortDefinition:
      description: Flexible definition for cohort targeting criteria. Type is required, additional fields vary by type.
      type: object
      properties:
        type:
          description: Type of cohort definition (e.g., "zip_code", "user_segment", "geo_region", "custom")
          example: zip_code
          type: string
          minLength: 1
      required:
        - type
      additionalProperties: {}
    UpdateTestCohortInput:
      description: Request body for updating a test cohort (all fields optional)
      type: object
      properties:
        name:
          description: Updated name of the test cohort
          example: West Coast Treatment Group - Updated
          type: string
          minLength: 1
          maxLength: 255
        description:
          description: Updated description of the test cohort
          type: string
          maxLength: 1000
        cohortType:
          description: Updated type classification for the cohort
          type: string
          minLength: 1
        role:
          description: Updated role of the cohort in the test
          type: string
          enum:
            - TREATMENT
            - CONTROL
            - OBSERVATION
        definition:
          description: Updated cohort targeting definition
          allOf:
            - $ref: '#/components/schemas/CohortDefinition'
        estimatedSize:
          description: Updated estimated number of users in this cohort
          type: integer
          minimum: 0
          maximum: 9007199254740991
    UpdateMeasurementConfigInput:
      description: Request body for updating measurement configuration
      type: object
      properties:
        mmmEnabled:
          description: Whether Marketing Mix Modeling is enabled
          type: boolean
        mmmConfig:
          description: MMM configuration settings
          allOf:
            - $ref: '#/components/schemas/MmmConfig'
        incrementalityTestingEnabled:
          description: Whether incrementality testing is enabled
          type: boolean
        brandLiftEnabled:
          description: Whether brand lift measurement is enabled
          type: boolean
        settings:
          description: Additional measurement settings as key-value pairs
          type: object
          additionalProperties: {}
    MmmConfig:
      description: Marketing Mix Modeling configuration with optional additional fields
      type: object
      properties:
        provider:
          description: MMM provider name
          example: measured
          type: string
        dataSourceIds:
          description: IDs of data sources connected for MMM analysis
          example:
            - ds_123
            - ds_456
          type: array
          items:
            type: string
        reportingFrequency:
          description: How often MMM reports are generated
          type: string
          enum:
            - weekly
            - monthly
            - quarterly
      additionalProperties: {}
    CreateChildAccountBody:
      description: Request body for creating a child customer account
      type: object
      properties:
        name:
          description: Name for the new child account
          example: Nike
          type: string
          minLength: 1
          maxLength: 255
        customerRole:
          description: Whether the account is a buyer or seller
          example: BUYER
          type: string
          enum:
            - BUYER
            - SELLER
        parentName:
          description: >-
            Name for the parent account created during standalone conversion. Defaults to "{company} (Admin)" if
            omitted.
          example: Acme HQ
          type: string
          minLength: 1
          maxLength: 255
        customerDomain:
          description: >-
            Registered organization domain. For SELLER accounts, also seeds the auto-created storefront's publisher and
            operator domain.
          example: nike.com
          type: string
          maxLength: 255
          pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$
      required:
        - name
        - customerRole
    UpdateCustomerDomainBody:
      description: Request body for updating a customer's organization domain
      type: object
      properties:
        customerDomain:
          description: Registered organization domain to set on the customer.
          example: nike.com
          type: string
          maxLength: 255
          pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$
      required:
        - customerDomain
    UpdateReportingBucketBody:
      description: Request body for updating the offline reporting bucket on a linked partner account
      type: object
      properties:
        reporting_bucket:
          description: Reporting bucket configuration to set on the linked account, or null to clear it.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ReportingBucket'
      required:
        - reporting_bucket
    ReportingBucket:
      description: Customer-owned object storage bucket where sales agents can write offline delivery reports
      type: object
      properties:
        protocol:
          description: Object storage protocol
          example: s3
          type: string
          enum:
            - s3
            - gcs
            - azure_blob
        bucket:
          description: Bucket name. Lowercase alphanumerics, dots and hyphens; must start and end with an alphanumeric; 3-63 chars.
          example: my-org.adcp.reports
          type: string
          minLength: 3
          maxLength: 63
          pattern: ^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$
        prefix:
          description: Object key prefix within the bucket
          example: reports/
          type: string
          maxLength: 512
          pattern: ^[a-zA-Z0-9/_.-]+$
        region:
          description: Storage region identifier (lowercase alphanumerics and hyphens)
          example: us-east-1
          type: string
          maxLength: 64
          pattern: ^[a-z0-9-]+$
        format:
          description: Report file format
          default: jsonl
          type: string
          enum:
            - jsonl
            - csv
            - parquet
            - avro
            - orc
        compression:
          description: Compression applied to report files
          default: gzip
          type: string
          enum:
            - gzip
            - none
        file_retention_days:
          description: Number of days the customer retains report files in the bucket
          example: 30
          type: integer
          minimum: 1
          maximum: 9007199254740991
        setup_instructions:
          description: Optional URL pointing to setup instructions for granting the agent access to the bucket
          example: https://example.com/adcp/bucket-setup
          type: string
          format: uri
      required:
        - protocol
        - bucket
        - file_retention_days
    SyncAudiencesBody:
      description: Sync audience data into Scope3
      type: object
      properties:
        audiences:
          description: Audiences to sync
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/AudienceItem'
        deleteMissing:
          description: When true, audiences not in this request are marked as deleted.
          type: boolean
        pushNotificationConfig:
          type: object
          properties:
            url:
              type: string
            token:
              type: string
            authentication:
              type: object
              properties:
                schemes:
                  type: array
                  items:
                    anyOf:
                      - type: string
                        enum:
                          - Bearer
                      - type: string
                        enum:
                          - HMAC-SHA256
                credentials:
                  type: string
              required:
                - schemes
                - credentials
              additionalProperties: {}
          required:
            - url
          additionalProperties: {}
      required:
        - audiences
    AudienceItem:
      description: Audience to sync with member changes
      type: object
      properties:
        audienceId:
          description: Buyer's identifier for this audience. Used in targeting overlays.
          type: string
          minLength: 1
          maxLength: 255
        name:
          description: Human-readable name
          type: string
          maxLength: 255
        add:
          description: Members to add to this audience
          maxItems: 100000
          type: array
          items:
            type: object
            properties:
              externalId:
                description: Unique identifier for this member within the audience
                type: string
                minLength: 1
              hashedEmail:
                description: SHA-256 hash of lowercase, trimmed email (64-char hex)
                example: a1b2c3d4e5f6...
                type: string
                pattern: ^[0-9a-f]{64}$
              hashedPhone:
                description: SHA-256 hash of E.164-formatted phone number (64-char hex)
                example: f6e5d4c3b2a1...
                type: string
                pattern: ^[0-9a-f]{64}$
              uids:
                description: Universal IDs for user matching
                minItems: 1
                type: array
                items:
                  type: object
                  properties:
                    type:
                      description: Universal ID type (rampid, uid2, maid, etc.)
                      type: string
                      minLength: 1
                    value:
                      description: Universal ID value
                      type: string
                      minLength: 1
                  required:
                    - type
                    - value
            required:
              - externalId
        remove:
          description: Members to remove by external ID
          maxItems: 100000
          type: array
          items:
            $ref: '#/components/schemas/RemoveMember'
        delete:
          description: When true, delete this audience entirely
          type: boolean
        consentBasis:
          description: GDPR lawful basis for processing this audience
          type: string
          enum:
            - consent
            - legitimate_interest
            - contract
            - legal_obligation
      required:
        - audienceId
    RemoveMember:
      description: Member to remove from the audience
      type: object
      properties:
        externalId:
          description: Unique identifier for this member within the audience
          type: string
          minLength: 1
        hashedEmail:
          description: SHA-256 hash of lowercase, trimmed email (64-char hex)
          example: a1b2c3d4e5f6...
          type: string
          pattern: ^[0-9a-f]{64}$
        hashedPhone:
          description: SHA-256 hash of E.164-formatted phone number (64-char hex)
          example: f6e5d4c3b2a1...
          type: string
          pattern: ^[0-9a-f]{64}$
        uids:
          description: Universal IDs for user matching
          minItems: 1
          type: array
          items:
            type: object
            properties:
              type:
                description: Universal ID type (rampid, uid2, maid, etc.)
                type: string
                minLength: 1
              value:
                description: Universal ID value
                type: string
                minLength: 1
            required:
              - type
              - value
      required:
        - externalId
    CreatePropertyListInput:
      description: Request body for creating a property list
      type: object
      properties:
        name:
          description: Human-readable name for the property list
          example: Q1 Campaign - UK Premium
          type: string
          minLength: 1
          maxLength: 255
        purpose:
          description: Whether properties in this list should be included or excluded
          example: include
          type: string
          enum:
            - include
            - exclude
        domains:
          description: >-
            Domain identifiers (convenience shorthand for `identifiers` entries with `type: "domain"`). Provide
            `domains`, `identifiers`, or both. Large lists are chunked server-side against the AAO registry and local
            database; the response includes a `resolutionSummary` with the counts.
          example:
            - nytimes.com
            - cnn.com
            - bbc.co.uk
          maxItems: 100000
          type: array
          items:
            type: string
            minLength: 1
        identifiers:
          description: >-
            Typed property identifiers (AdCP-aligned) — mix of website domains, mobile app bundles/packages, store IDs,
            and CTV app IDs. Provide `domains`, `identifiers`, or both; combined total must be between 1 and 100000.
          example:
            - type: domain
              value: nytimes.com
            - type: ios_bundle
              value: com.facebook.katana
            - type: android_package
              value: com.facebook.katana
            - type: apple_app_store_id
              value: '284882215'
          maxItems: 100000
          type: array
          items:
            type: object
            properties:
              type:
                anyOf:
                  - type: string
                    enum:
                      - domain
                  - type: string
                    enum:
                      - subdomain
                  - type: string
                    enum:
                      - network_id
                  - type: string
                    enum:
                      - ios_bundle
                  - type: string
                    enum:
                      - android_package
                  - type: string
                    enum:
                      - apple_app_store_id
                  - type: string
                    enum:
                      - google_play_id
                  - type: string
                    enum:
                      - roku_store_id
                  - type: string
                    enum:
                      - fire_tv_asin
                  - type: string
                    enum:
                      - samsung_app_id
                  - type: string
                    enum:
                      - apple_tv_bundle
                  - type: string
                    enum:
                      - bundle_id
                  - type: string
                    enum:
                      - venue_id
                  - type: string
                    enum:
                      - screen_id
                  - type: string
                    enum:
                      - openooh_venue_type
                  - type: string
                    enum:
                      - rss_url
                  - type: string
                    enum:
                      - apple_podcast_id
                  - type: string
                    enum:
                      - spotify_collection_id
                  - type: string
                    enum:
                      - podcast_guid
                  - type: string
                    enum:
                      - station_id
                  - type: string
                    enum:
                      - facility_id
              value:
                type: string
            required:
              - type
              - value
            additionalProperties: {}
        filters:
          description: Filter configuration — controls which SmartPropertyLists this list is linked to
          nullable: true
          allOf:
            - $ref: '#/components/schemas/PropertyListFilters'
      required:
        - name
        - purpose
    PropertyListFilters:
      type: object
      properties:
        channels_any:
          description: Restrict to SmartPropertyLists matching these channels
          example:
            - display
            - olv
          nullable: true
          type: array
          items:
            type: string
            enum:
              - display
              - olv
              - social
              - search
              - ctv
              - linear_tv
              - radio
              - streaming_audio
              - podcast
              - dooh
              - ooh
              - print
              - cinema
              - email
              - gaming
              - retail_media
              - influencer
              - affiliate
              - product_placement
        countries_all:
          description: ISO 3166-1 alpha-2 country codes
          example:
            - US
            - GB
          nullable: true
          type: array
          items:
            type: string
            minLength: 2
            maxLength: 2
        property_types:
          description: Property inventory types
          nullable: true
          type: array
          items:
            type: string
            enum:
              - website
              - mobile_app
              - ctv_app
              - desktop_app
              - dooh
              - podcast
              - radio
              - streaming_audio
        feature_requirements:
          description: Feature-based requirements (e.g. IVT, MFA, green)
          nullable: true
          type: array
          items:
            type: object
            properties:
              feature_id:
                type: string
              min_value:
                nullable: true
                type: number
              max_value:
                nullable: true
                type: number
              allowed_values:
                nullable: true
                type: array
                items: {}
              if_not_covered:
                nullable: true
                type: string
                enum:
                  - exclude
                  - include
            required:
              - feature_id
    UpdatePropertyListInput:
      description: Request body for updating a property list
      type: object
      properties:
        name:
          description: Updated name for the property list
          type: string
          minLength: 1
          maxLength: 255
        domains:
          description: >-
            Updated domain list (convenience shorthand for `identifiers` with `type: "domain"`). If provided together
            with `identifiers`, both are merged. Replaces the existing identifier set entirely. Large lists are chunked
            server-side; the response includes a `resolutionSummary` with the counts.
          maxItems: 100000
          type: array
          items:
            type: string
            minLength: 1
        identifiers:
          description: >-
            Updated typed identifiers (domains + bundles). Replaces the existing identifier set entirely when either
            `domains` or `identifiers` is provided.
          maxItems: 100000
          type: array
          items:
            type: object
            properties:
              type:
                anyOf:
                  - type: string
                    enum:
                      - domain
                  - type: string
                    enum:
                      - subdomain
                  - type: string
                    enum:
                      - network_id
                  - type: string
                    enum:
                      - ios_bundle
                  - type: string
                    enum:
                      - android_package
                  - type: string
                    enum:
                      - apple_app_store_id
                  - type: string
                    enum:
                      - google_play_id
                  - type: string
                    enum:
                      - roku_store_id
                  - type: string
                    enum:
                      - fire_tv_asin
                  - type: string
                    enum:
                      - samsung_app_id
                  - type: string
                    enum:
                      - apple_tv_bundle
                  - type: string
                    enum:
                      - bundle_id
                  - type: string
                    enum:
                      - venue_id
                  - type: string
                    enum:
                      - screen_id
                  - type: string
                    enum:
                      - openooh_venue_type
                  - type: string
                    enum:
                      - rss_url
                  - type: string
                    enum:
                      - apple_podcast_id
                  - type: string
                    enum:
                      - spotify_collection_id
                  - type: string
                    enum:
                      - podcast_guid
                  - type: string
                    enum:
                      - station_id
                  - type: string
                    enum:
                      - facility_id
              value:
                type: string
            required:
              - type
              - value
            additionalProperties: {}
    CheckPropertyListBody:
      description: Request body for checking domains and bundles
      type: object
      properties:
        domains:
          description: 'Domain values to check (convenience shorthand for `identifiers` with `type: "domain"`).'
          maxItems: 100000
          type: array
          items:
            type: string
            minLength: 1
        identifiers:
          description: >-
            Typed identifiers to check (domains and mobile app bundle IDs). Provide `domains`, `identifiers`, or both;
            combined total must be 1..100000. Bundle identifiers are not currently checked against the AAO registry and
            are returned in the `assess` bucket pending upstream support.
          maxItems: 100000
          type: array
          items:
            type: object
            properties:
              type:
                anyOf:
                  - type: string
                    enum:
                      - domain
                  - type: string
                    enum:
                      - subdomain
                  - type: string
                    enum:
                      - network_id
                  - type: string
                    enum:
                      - ios_bundle
                  - type: string
                    enum:
                      - android_package
                  - type: string
                    enum:
                      - apple_app_store_id
                  - type: string
                    enum:
                      - google_play_id
                  - type: string
                    enum:
                      - roku_store_id
                  - type: string
                    enum:
                      - fire_tv_asin
                  - type: string
                    enum:
                      - samsung_app_id
                  - type: string
                    enum:
                      - apple_tv_bundle
                  - type: string
                    enum:
                      - bundle_id
                  - type: string
                    enum:
                      - venue_id
                  - type: string
                    enum:
                      - screen_id
                  - type: string
                    enum:
                      - openooh_venue_type
                  - type: string
                    enum:
                      - rss_url
                  - type: string
                    enum:
                      - apple_podcast_id
                  - type: string
                    enum:
                      - spotify_collection_id
                  - type: string
                    enum:
                      - podcast_guid
                  - type: string
                    enum:
                      - station_id
                  - type: string
                    enum:
                      - facility_id
              value:
                type: string
            required:
              - type
              - value
            additionalProperties: {}
    ErrorResponse:
      description: Standard error response
      type: object
      properties:
        data:
          type: string
          nullable: true
          enum:
            - null
        error:
          $ref: '#/components/schemas/ApiError'
      required:
        - data
        - error
      additionalProperties: false
    ApiError:
      description: Structured error object
      type: object
      properties:
        code:
          description: Machine-readable error code
          type: string
        message:
          description: Human-readable error message
          type: string
        field:
          description: Field path associated with the error
          type: string
        details:
          description: Additional error context
          type: object
          additionalProperties: {}
      required:
        - code
        - message
      additionalProperties: false
    DiscoverProductsResponse:
      description: Response from discovering products
      type: object
      properties:
        discoveryId:
          description: Discovery ID
          example: abc123-def456-ghi789
          type: string
        productGroups:
          description: Products grouped by publisher
          type: array
          items:
            $ref: '#/components/schemas/ProductGroup'
        totalGroups:
          description: Total number of product groups available
          example: 25
          type: integer
          minimum: 0
          maximum: 9007199254740991
        hasMoreGroups:
          description: Whether more groups are available beyond those shown
          type: boolean
        summary:
          description: Summary statistics for discovered products
          allOf:
            - $ref: '#/components/schemas/DiscoverySummary'
        budgetContext:
          description: Budget context if budget was provided
          allOf:
            - $ref: '#/components/schemas/BudgetContextResponse'
        proposals:
          description: >-
            Recommended media plans from sales agents (ADCP v3). Each proposal explains WHY certain products are
            recommended together and how budget should be allocated.
          type: array
          items:
            $ref: '#/components/schemas/Proposal'
        agentResults:
          description: Debug info for failed agents only. Only present when debug=true and at least one agent failed.
          type: array
          items:
            $ref: '#/components/schemas/AgentDiscoveryResult'
        refinementApplied:
          description: >-
            Seller's response to each refinement instruction, matched by position to the request's refine array. Only
            present when refine was provided.
          type: array
          items:
            $ref: '#/components/schemas/RefinementApplied'
      required:
        - discoveryId
        - productGroups
        - totalGroups
        - hasMoreGroups
        - summary
      additionalProperties: false
    ProductGroup:
      description: Group of products from a publisher
      type: object
      properties:
        groupId:
          description: Unique identifier for the product group
          type: string
        groupName:
          description: Name of the group (typically publisher name)
          type: string
        description:
          description: Description of the product group
          type: string
        products:
          description: Products in this group
          type: array
          items:
            $ref: '#/components/schemas/Product'
        productCount:
          description: Number of products in this group
          type: integer
          minimum: 0
          maximum: 9007199254740991
        totalProducts:
          description: Total number of products available in this group
          type: integer
          minimum: 0
          maximum: 9007199254740991
        hasMoreProducts:
          description: Whether more products are available beyond those returned
          type: boolean
      required:
        - groupId
        - groupName
        - products
        - productCount
        - totalProducts
        - hasMoreProducts
      additionalProperties: false
    Product:
      description: Product resource for campaign inventory
      type: object
      properties:
        productId:
          description: Unique identifier for the product
          example: prod_123
          type: string
        name:
          description: Product name
          example: Premium CTV Inventory - Sports
          type: string
        channel:
          description: Channel type
          example: ctv
          type: string
        formatTypes:
          description: Supported format types
          example:
            - video
            - 15s
            - 30s
          type: array
          items:
            type: string
        cpm:
          description: Cost per mille (CPM)
          example: 12.5
          type: number
        salesAgentId:
          description: Sales agent ID
          type: string
        salesAgentName:
          description: Sales agent name
          type: string
        description:
          description: Product description
          type: string
        deliveryType:
          description: Delivery type — guaranteed means fixed delivery commitment
          example: guaranteed
          type: string
          enum:
            - guaranteed
            - non_guaranteed
        briefRelevance:
          description: AI-generated explanation of why this product matches the campaign brief
          type: string
        productCard:
          description: Standard visual card (300x400px) for UI rendering
          allOf:
            - $ref: '#/components/schemas/ProductCardData'
        productCardDetailed:
          description: Detailed card with carousel and full specifications
          allOf:
            - $ref: '#/components/schemas/ProductCardData'
        pricingOptions:
          description: Full pricing options from the sales agent
          type: array
          items:
            $ref: '#/components/schemas/PricingOptionData'
        estimatedExposures:
          description: Estimated impressions for guaranteed products
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        forecast:
          description: Structured delivery forecast with budget points and metric ranges (ADCP 3.15+)
          type: object
          additionalProperties: {}
        publisherProperties:
          description: Publisher properties from ADCP (domains, property types, etc.)
          type: array
          items:
            type: object
            properties:
              publisherDomain:
                type: string
              propertyType:
                type: string
              name:
                type: string
              selectionType:
                type: string
              identifiers:
                type: array
                items:
                  type: object
                  additionalProperties: {}
            additionalProperties: false
        isSandbox:
          description: Whether this product was discovered in sandbox mode
          type: boolean
      required:
        - productId
        - name
      additionalProperties: false
    ProductCardData:
      description: Visual card data for rendering a product in UI
      type: object
      properties:
        formatId:
          type: object
          properties:
            agentUrl:
              type: string
            id:
              type: string
          required:
            - agentUrl
            - id
          additionalProperties: false
        manifest:
          type: object
          additionalProperties: {}
      required:
        - formatId
        - manifest
      additionalProperties: false
    PricingOptionData:
      description: Pricing option from a sales agent
      type: object
      properties:
        pricingOptionId:
          type: string
        pricingModel:
          type: string
        isFixed:
          type: boolean
        rate:
          type: number
        floorPrice:
          type: number
        fixedPrice:
          type: number
        currency:
          type: string
      additionalProperties: false
    DiscoverySummary:
      description: Summary statistics for the discovery
      type: object
      properties:
        totalProducts:
          description: Total number of products in the discovery
          example: 150
          type: integer
          minimum: 0
          maximum: 9007199254740991
        publishersCount:
          description: Number of unique publishers
          example: 25
          type: integer
          minimum: 0
          maximum: 9007199254740991
        priceRange:
          description: CPM price range across products
          type: object
          properties:
            min:
              nullable: true
              type: number
            max:
              nullable: true
              type: number
            avg:
              nullable: true
              type: number
          required:
            - min
            - max
            - avg
          additionalProperties: false
      required:
        - totalProducts
        - publishersCount
      additionalProperties: false
    BudgetContextResponse:
      description: Budget allocation context
      type: object
      properties:
        sessionBudget:
          description: Total budget set for the session
          nullable: true
          type: number
        allocatedBudget:
          description: Budget allocated to selected products
          type: number
        remainingBudget:
          description: Remaining unallocated budget
          nullable: true
          type: number
        budgetWarning:
          description: Warning message if budget allocation has issues
          type: string
      required:
        - sessionBudget
        - allocatedBudget
        - remainingBudget
      additionalProperties: false
    Proposal:
      description: A recommended media plan with budget allocations across products (ADCP v3)
      type: object
      properties:
        proposalId:
          description: Unique identifier — used to refine or execute the proposal
          type: string
        name:
          description: Human-readable name for this media plan proposal
          type: string
        description:
          description: Strategic explanation of what the proposal achieves
          type: string
        briefAlignment:
          description: Explanation of how this proposal aligns with the brief
          type: string
        salesAgentId:
          description: Sales agent that generated this proposal
          type: string
        salesAgentName:
          description: Human-readable sales agent name
          type: string
        allocations:
          description: Budget distribution across products — percentages sum to 100
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/ProductAllocation'
        expiresAt:
          description: When the proposal expires (ISO 8601)
          type: string
        totalBudgetGuidance:
          description: Budget guidance for this proposal
          type: object
          properties:
            min:
              type: number
            recommended:
              type: number
            max:
              type: number
            currency:
              type: string
          additionalProperties: false
      required:
        - proposalId
        - name
        - allocations
      additionalProperties: false
    ProductAllocation:
      description: Budget allocation for a product within a proposal
      type: object
      properties:
        productId:
          description: Product ID — references a product in the sibling products array
          type: string
        allocationPercentage:
          description: Percentage of total budget allocated to this product
          type: number
          minimum: 0
          maximum: 100
        pricingOptionId:
          description: Recommended pricing option ID from the product pricing_options
          type: string
        rationale:
          description: Why this product and allocation are recommended
          type: string
        sequence:
          description: Ordering hint for multi-line-item plans (1-based)
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        tags:
          description: Categorical tags (e.g., "desktop", "mobile")
          type: array
          items:
            type: string
      required:
        - productId
        - allocationPercentage
      additionalProperties: false
    AgentDiscoveryResult:
      description: Per-agent discovery result with optional debug info. Same structure as v1 media_product_discover debug output.
      type: object
      properties:
        agentId:
          description: Sales agent ID
          type: string
        agentName:
          description: Sales agent name
          type: string
        success:
          description: Whether the agent responded successfully
          type: boolean
        productCount:
          description: Number of products returned by the agent
          type: integer
          minimum: 0
          maximum: 9007199254740991
        error:
          description: Error message if the agent failed
          type: string
        skipReason:
          description: >-
            Human-readable explanation of why the agent was skipped or failed (e.g. 'We do not support the list of
            channels you specified'). Prefer this over `error` when surfacing the reason in a UI; falls back to the raw
            error string when no structured reason is available. Untrusted agent-controlled content; sanitize before
            rendering in HTML.
          type: string
        rawResponseData:
          description: Raw response data from the agent (only present when debug=true)
        debugLogs:
          description: Full ADCP request/response debug logs (only present when debug=true)
          type: array
          items:
            $ref: '#/components/schemas/AgentDebugLog'
      required:
        - agentId
        - agentName
        - success
        - productCount
      additionalProperties: false
    AgentDebugLog:
      description: A single debug log entry from ADCP agent communication
      type: object
      properties:
        timestamp:
          type: string
        type:
          type: string
        message:
          type: string
        request:
          type: object
          additionalProperties: {}
        response:
          type: object
          additionalProperties: {}
      additionalProperties: false
    RefinementApplied:
      description: Seller's response to a refinement instruction, matched by position to the request's refine array
      type: object
      properties:
        scope:
          description: Echoes the scope from the corresponding refinement instruction
          type: string
          enum:
            - request
            - product
            - proposal
        id:
          description: Echoes the id from the corresponding refinement instruction (for product and proposal scopes)
          type: string
        status:
          description: '''applied'': the ask was fulfilled. ''partial'': partially fulfilled. ''unable'': could not fulfill.'
          type: string
          enum:
            - applied
            - partial
            - unable
        notes:
          description: Seller explanation of the result
          type: string
      required:
        - status
      additionalProperties: false
    SessionProductsResponse:
      description: Response containing selected products
      type: object
      properties:
        discoveryId:
          description: Discovery ID
          type: string
        products:
          description: Selected products in the discovery session
          type: array
          items:
            $ref: '#/components/schemas/SelectedProduct'
        totalProducts:
          description: Total number of selected products
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        budgetContext:
          description: Budget allocation context
          allOf:
            - $ref: '#/components/schemas/BudgetContextResponse'
      required:
        - discoveryId
        - products
        - totalProducts
      additionalProperties: false
    SelectedProduct:
      description: A product selected for inclusion in a discovery session
      type: object
      properties:
        productId:
          description: Product ID
          type: string
        salesAgentId:
          description: Sales agent ID
          type: string
        cpm:
          description: CPM for the product
          type: number
        budget:
          description: Budget allocation for this product
          type: number
        selectedAt:
          description: When the product was selected (ISO 8601)
          type: string
        groupId:
          description: Group ID where product was discovered
          type: string
        groupName:
          description: Name of the group
          type: string
      required:
        - productId
        - salesAgentId
        - selectedAt
        - groupId
        - groupName
      additionalProperties: false
    ApplyProposalResponse:
      description: Response from applying a proposal
      type: object
      properties:
        discoveryId:
          description: Discovery ID
          type: string
        proposal:
          description: The proposal that was applied
          allOf:
            - $ref: '#/components/schemas/AppliedProposalSummary'
        totalBudgetUsed:
          description: Total budget distributed across products from this proposal
          type: number
        productsApplied:
          description: Number of products added from the proposal
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        productsSkipped:
          description: Product IDs from the proposal that could not be found in discovery results
          type: array
          items:
            type: string
        products:
          description: All selected products after applying the proposal
          type: array
          items:
            $ref: '#/components/schemas/SelectedProduct'
        totalProducts:
          description: Total number of selected products
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        budgetContext:
          description: Budget allocation context
          allOf:
            - $ref: '#/components/schemas/BudgetContextResponse'
      required:
        - discoveryId
        - proposal
        - totalBudgetUsed
        - productsApplied
        - productsSkipped
        - products
        - totalProducts
      additionalProperties: false
    AppliedProposalSummary:
      description: Summary of the proposal that was applied
      type: object
      properties:
        proposalId:
          description: ID of the applied proposal
          type: string
        name:
          description: Name of the applied proposal
          type: string
        salesAgentName:
          description: Sales agent that generated the proposal
          type: string
      required:
        - proposalId
        - name
      additionalProperties: false
    CampaignListResponse:
      description: Response containing a paginated list of campaign summaries
      type: object
      properties:
        campaigns:
          description: Campaigns matching the query, projected to the summary shape. Use `get_campaign` for full detail.
          type: array
          items:
            $ref: '#/components/schemas/CampaignSummary'
        total:
          description: Total count of campaigns matching the query
          example: 42
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - campaigns
        - total
      additionalProperties: false
    CampaignSummary:
      description: Compact campaign view returned by list endpoints. Use `get_campaign` for the full resource.
      type: object
      properties:
        campaignId:
          description: Unique identifier for the campaign
          example: cmp_987654321
          type: string
        advertiserId:
          description: Advertiser ID that owns this campaign
          example: '12345'
          type: string
        name:
          description: Campaign name
          example: Summer 2025 Campaign
          type: string
        status:
          description: Current campaign status
          type: string
          enum:
            - DRAFT
            - ACTIVE
            - PAUSED
            - COMPLETED
            - ARCHIVED
        campaignType:
          description: >-
            Determines Scope3's role in the campaign. DECISIONED campaigns use Scope3 optimization; ROUTED campaigns
            pass through to the sales agent using customer credentials. Immutable after creation. Absent for older
            campaigns where the type was never recorded.
          allOf:
            - $ref: '#/components/schemas/CampaignType'
        flightDates:
          description: Campaign flight dates
          type: object
          properties:
            startDate:
              description: Campaign start date (ISO 8601)
              example: '2025-01-15T00:00:00Z'
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
            endDate:
              description: Campaign end date (ISO 8601)
              example: '2025-03-31T23:59:59Z'
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
          required:
            - startDate
            - endDate
          additionalProperties: false
        productCount:
          description: >-
            Number of products selected for this campaign. Only present for DRAFT campaigns; after execution, product
            data is represented through media buys.
          example: 15
          type: integer
          minimum: 0
          maximum: 9007199254740991
        createdAt:
          description: When the campaign was created (ISO 8601)
          example: '2025-01-15T10:30:00Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          description: When the campaign was last updated (ISO 8601)
          example: '2025-01-20T14:45:00Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        budget:
          description: >-
            Compact budget — total + currency only. Use `get_campaign` for the full budget (dailyCap, pacing) plus
            mediaBudget, fees, allocatedBudget, unallocatedBudget.
          type: object
          properties:
            total:
              type: number
              minimum: 0
              exclusiveMinimum: true
            currency:
              default: USD
              type: string
              minLength: 3
              maxLength: 3
          required:
            - total
            - currency
          additionalProperties: false
      required:
        - campaignId
        - advertiserId
        - name
        - status
        - createdAt
        - updatedAt
      additionalProperties: false
    CampaignResponse:
      description: Response containing a single campaign
      type: object
      properties:
        campaign:
          $ref: '#/components/schemas/Campaign'
      required:
        - campaign
      additionalProperties: false
    Campaign:
      description: Campaign resource representation
      type: object
      properties:
        campaignId:
          description: Unique identifier for the campaign
          example: cmp_987654321
          type: string
        advertiserId:
          description: Advertiser ID that owns this campaign
          example: '12345'
          type: string
        name:
          description: Campaign name
          example: Summer 2025 Campaign
          type: string
        status:
          description: Current campaign status
          type: string
          enum:
            - DRAFT
            - ACTIVE
            - PAUSED
            - COMPLETED
            - ARCHIVED
        mediaBuyRefs:
          description: >-
            Lightweight references to every media buy on this campaign (id + status). Surfaced early in the response so
            LLM callers can enumerate media buy IDs even when the full nested `mediaBuys[]` tail is truncated by a small
            context window. Use the `mediaBuyId` query param on `get_campaign` to drill into specific buys without
            loading the full tree.
          type: array
          items:
            $ref: '#/components/schemas/MediaBuyRef'
        campaignType:
          description: >-
            Determines Scope3's role in the campaign. DECISIONED campaigns use Scope3 optimization; ROUTED campaigns
            pass through to the sales agent using customer credentials. Immutable after creation. Absent for older
            campaigns where the type was never recorded.
          allOf:
            - $ref: '#/components/schemas/CampaignType'
        brief:
          description: Campaign brief
          type: string
        flightDates:
          description: Campaign flight dates
          type: object
          properties:
            startDate:
              description: Campaign start date (ISO 8601)
              example: '2025-01-15T00:00:00Z'
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
            endDate:
              description: Campaign end date (ISO 8601)
              example: '2025-03-31T23:59:59Z'
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
          required:
            - startDate
            - endDate
          additionalProperties: false
        budget:
          description: Campaign budget configuration
          type: object
          properties:
            total:
              type: number
              minimum: 0
              exclusiveMinimum: true
            currency:
              default: USD
              type: string
              minLength: 3
              maxLength: 3
            dailyCap:
              type: number
              minimum: 0
              exclusiveMinimum: true
            pacing:
              type: string
              enum:
                - EVEN
                - ASAP
                - FRONTLOADED
          required:
            - total
            - currency
          additionalProperties: false
        mediaBudget:
          description: >-
            Budget available for media spend after fees are deducted (`budget.total - sum(fees[].amount)`). Only present
            when the campaign has a budget.total set.
          allOf:
            - $ref: '#/components/schemas/MediaBudget'
        fees:
          description: >-
            Array of fee line items applied to the campaign budget. Typically contains a single Scope3 fee. Only present
            when the campaign has a budget.total set and pricing is configured.
          allOf:
            - $ref: '#/components/schemas/CampaignFees'
        allocatedBudget:
          description: >-
            Sum of active media buy budgets (plus performance spend on archived media buys) on this campaign. Only
            present when the campaign has a budget.total set. Expressed in the campaign budget currency.
          example: 7500
          type: number
          minimum: 0
        unallocatedBudget:
          description: >-
            Media budget remaining for new media buys, computed as `mediaBudget.total - allocatedBudget`. Only present
            when the campaign has a budget.total set. Expressed in the campaign budget currency. May be negative if
            archived performance spend exceeds the media budget.
          example: 2500
          type: number
        pacingPeriods:
          description: >-
            Pacing schedule for the campaign, if configured. In responses, each period includes a resolved budget
            (computed dollar amount). In weight mode, weights are preserved alongside the resolved budget.
          allOf:
            - $ref: '#/components/schemas/PacingPeriodsOutput'
        constraints:
          description: Targeting constraints
          type: object
          properties:
            channels:
              description: Channels to target (e.g., ["ctv", "display"])
              type: array
              items:
                type: string
            countries:
              description: Countries to target (ISO 3166-1 alpha-2 codes)
              maxItems: 250
              type: array
              items:
                type: string
                pattern: ^[A-Z]{2}$
          additionalProperties: false
        storefronts:
          description: >-
            Storefronts the campaign is pinned to. When set, every product discovery run for this campaign auto-applies
            the corresponding storefront filter. Each entry includes both the storefront DB `id` and the public
            `platformId` + `name` so the response is renderable without a follow-up lookup. Absent or empty means the
            campaign is not pinned to any specific storefronts.
          type: array
          items:
            $ref: '#/components/schemas/CampaignStorefrontRef'
        performanceConfig:
          description: Performance configuration (present for performance campaigns)
          allOf:
            - $ref: '#/components/schemas/PerformanceConfigOutput'
        optimizationApplyMode:
          description: >-
            Controls whether Scope3 AI model optimizations to media buys are applied automatically or require manual
            approval. Defaults to the advertiser-level setting if not explicitly set on the campaign.
          allOf:
            - $ref: '#/components/schemas/OptimizationApplyMode'
        catalogId:
          description: Attached catalog ID
          example: 42
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
        discoveryId:
          description: >-
            ID of the discovery session used to select products for this campaign. Only present for DRAFT campaigns;
            after execution, product data is represented through media buys.
          example: session_abc123
          type: string
        productCount:
          description: >-
            Number of products selected for this campaign. Only present for DRAFT campaigns; after execution, product
            data is represented through media buys.
          example: 15
          type: integer
          minimum: 0
          maximum: 9007199254740991
        products:
          description: >-
            Products selected for this campaign. Only present for DRAFT campaigns; after execution, product data is
            represented through media buys.
          type: array
          items:
            type: object
            properties:
              productId:
                description: Unique identifier for the product
                example: prod_123
                type: string
            required:
              - productId
            additionalProperties: false
        audiences:
          description: Audiences associated with this campaign (both targeted and suppressed)
          type: array
          items:
            type: object
            properties:
              audienceId:
                description: Unique identifier for the audience
                example: aud_123
                type: string
              name:
                description: Display name of the audience
                example: Tech Enthusiasts 25-34
                nullable: true
                type: string
              status:
                description: Processing status of the audience (e.g. READY, PROCESSING, TOO_SMALL)
                example: READY
                type: string
                enum:
                  - PROCESSING
                  - ERROR
                  - READY
                  - TOO_SMALL
              type:
                description: Whether this audience is targeted or suppressed (excluded)
                example: TARGET
                type: string
                enum:
                  - TARGET
                  - SUPPRESS
              enabledAt:
                description: When the audience was enabled for this campaign (ISO 8601)
                example: '2025-03-01T12:00:00Z'
                type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
            required:
              - audienceId
              - name
              - status
              - type
              - enabledAt
            additionalProperties: false
        creativeFormats:
          description: >-
            Creative format coverage for this campaign — which formats are required by the selected products, which are
            already covered by uploaded creatives, and which are still missing. Surface `missing` to prompt the user to
            upload the remaining creatives.
          type: object
          properties:
            required:
              type: array
              items:
                type: object
                properties:
                  agent_url:
                    type: string
                  id:
                    type: string
                required:
                  - agent_url
                  - id
                additionalProperties: false
            covered:
              type: array
              items:
                type: object
                properties:
                  agent_url:
                    type: string
                  id:
                    type: string
                required:
                  - agent_url
                  - id
                additionalProperties: false
            missing:
              type: array
              items:
                type: object
                properties:
                  agent_url:
                    type: string
                  id:
                    type: string
                required:
                  - agent_url
                  - id
                additionalProperties: false
          required:
            - required
            - covered
            - missing
          additionalProperties: false
        mediaBuys:
          description: >-
            Media buys associated with this campaign. Present after execution; contains the product allocations,
            packages, and delivery data for each sales agent.
          type: array
          items:
            type: object
            properties:
              mediaBuyId:
                description: Unique identifier for the media buy
                type: string
              name:
                description: Media buy name
                type: string
              status:
                description: Current media buy status (e.g. DRAFT, ACTIVE, PAUSED, COMPLETED)
                type: string
              startTime:
                description: >-
                  When this media buy starts. Either "asap" (start immediately on activation) or an ISO 8601 date-time.
                  Falls within the parent campaign's flightDates.
                example: '2025-04-14T00:00:00Z'
                type: string
              endTime:
                description: When this media buy ends, as an ISO 8601 date-time. Falls within the parent campaign's flightDates.
                example: '2025-04-30T23:59:59Z'
                type: string
              products:
                description: Products configured for this media buy
                type: array
                items:
                  type: object
                  properties:
                    productId:
                      description: Product identifier
                      type: string
                    salesAgentName:
                      description: Name of the sales agent for this product
                      type: string
                    budget:
                      description: Budget allocated to this product
                      type: number
                    budgetCurrency:
                      description: Currency for the budget
                      type: string
                  required:
                    - productId
                  additionalProperties: false
              packages:
                description: Packages created after media buy execution
                type: array
                items:
                  type: object
                  properties:
                    packageId:
                      description: Package identifier
                      type: string
                    status:
                      description: Package status (active, paused)
                      type: string
                    budget:
                      description: Package budget amount
                      type: number
                    budgetCurrency:
                      description: Budget currency code (e.g. USD)
                      type: string
                    pacing:
                      description: Pacing strategy (even, asap, front_loaded)
                      type: string
                    bidPrice:
                      description: Bid price for this package
                      type: number
                    productIds:
                      description: Product IDs in this package
                      type: array
                      items:
                        type: string
                    delivery:
                      description: Delivery metrics for this package
                      type: object
                      properties:
                        impressions:
                          description: Delivered impressions
                          type: number
                        spend:
                          description: Amount spent
                          type: number
                        clicks:
                          description: Click count
                          nullable: true
                          type: number
                      required:
                        - impressions
                        - spend
                        - clicks
                      additionalProperties: false
                  required:
                    - packageId
                    - status
                    - productIds
                  additionalProperties: false
              optimizationGoals:
                type: array
                items:
                  anyOf:
                    - type: object
                      properties:
                        kind:
                          type: string
                          enum:
                            - metric
                        metric:
                          anyOf:
                            - type: string
                              enum:
                                - clicks
                            - type: string
                              enum:
                                - views
                            - type: string
                              enum:
                                - completed_views
                            - type: string
                              enum:
                                - viewed_seconds
                            - type: string
                              enum:
                                - attention_seconds
                            - type: string
                              enum:
                                - attention_score
                            - type: string
                              enum:
                                - engagements
                            - type: string
                              enum:
                                - follows
                            - type: string
                              enum:
                                - saves
                            - type: string
                              enum:
                                - profile_visits
                            - type: string
                              enum:
                                - reach
                        reach_unit:
                          anyOf:
                            - type: string
                              enum:
                                - individuals
                            - type: string
                              enum:
                                - households
                            - type: string
                              enum:
                                - devices
                            - type: string
                              enum:
                                - accounts
                            - type: string
                              enum:
                                - cookies
                            - type: string
                              enum:
                                - custom
                        target_frequency:
                          type: object
                          additionalProperties: {}
                        view_duration_seconds:
                          type: number
                        target:
                          anyOf:
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - cost_per
                                value:
                                  type: number
                              required:
                                - kind
                                - value
                              additionalProperties: {}
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - threshold_rate
                                value:
                                  type: number
                              required:
                                - kind
                                - value
                              additionalProperties: {}
                        priority:
                          type: number
                      required:
                        - kind
                        - metric
                      additionalProperties: {}
                    - type: object
                      properties:
                        kind:
                          type: string
                          enum:
                            - event
                        event_sources:
                          type: array
                          items:
                            type: object
                            properties:
                              event_source_id:
                                type: string
                              event_type:
                                anyOf:
                                  - type: string
                                    enum:
                                      - page_view
                                  - type: string
                                    enum:
                                      - view_content
                                  - type: string
                                    enum:
                                      - select_content
                                  - type: string
                                    enum:
                                      - select_item
                                  - type: string
                                    enum:
                                      - search
                                  - type: string
                                    enum:
                                      - share
                                  - type: string
                                    enum:
                                      - add_to_cart
                                  - type: string
                                    enum:
                                      - remove_from_cart
                                  - type: string
                                    enum:
                                      - viewed_cart
                                  - type: string
                                    enum:
                                      - add_to_wishlist
                                  - type: string
                                    enum:
                                      - initiate_checkout
                                  - type: string
                                    enum:
                                      - add_payment_info
                                  - type: string
                                    enum:
                                      - purchase
                                  - type: string
                                    enum:
                                      - refund
                                  - type: string
                                    enum:
                                      - lead
                                  - type: string
                                    enum:
                                      - qualify_lead
                                  - type: string
                                    enum:
                                      - close_convert_lead
                                  - type: string
                                    enum:
                                      - disqualify_lead
                                  - type: string
                                    enum:
                                      - complete_registration
                                  - type: string
                                    enum:
                                      - subscribe
                                  - type: string
                                    enum:
                                      - start_trial
                                  - type: string
                                    enum:
                                      - app_install
                                  - type: string
                                    enum:
                                      - app_launch
                                  - type: string
                                    enum:
                                      - contact
                                  - type: string
                                    enum:
                                      - schedule
                                  - type: string
                                    enum:
                                      - donate
                                  - type: string
                                    enum:
                                      - submit_application
                                  - type: string
                                    enum:
                                      - custom
                              custom_event_name:
                                type: string
                              value_field:
                                type: string
                              value_factor:
                                type: number
                            required:
                              - event_source_id
                              - event_type
                            additionalProperties: {}
                        target:
                          anyOf:
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - cost_per
                                value:
                                  type: number
                              required:
                                - kind
                                - value
                              additionalProperties: {}
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - per_ad_spend
                                value:
                                  type: number
                              required:
                                - kind
                                - value
                              additionalProperties: {}
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - maximize_value
                              required:
                                - kind
                              additionalProperties: {}
                        attribution_window:
                          type: object
                          properties:
                            post_click:
                              type: object
                              properties:
                                interval:
                                  type: number
                                unit:
                                  anyOf:
                                    - type: string
                                      enum:
                                        - seconds
                                    - type: string
                                      enum:
                                        - minutes
                                    - type: string
                                      enum:
                                        - hours
                                    - type: string
                                      enum:
                                        - days
                                    - type: string
                                      enum:
                                        - campaign
                              required:
                                - interval
                                - unit
                              additionalProperties: {}
                            post_view:
                              type: object
                              properties:
                                interval:
                                  type: number
                                unit:
                                  anyOf:
                                    - type: string
                                      enum:
                                        - seconds
                                    - type: string
                                      enum:
                                        - minutes
                                    - type: string
                                      enum:
                                        - hours
                                    - type: string
                                      enum:
                                        - days
                                    - type: string
                                      enum:
                                        - campaign
                              required:
                                - interval
                                - unit
                              additionalProperties: {}
                          required:
                            - post_click
                          additionalProperties: {}
                        priority:
                          type: number
                      required:
                        - kind
                        - event_sources
                      additionalProperties: {}
              createdAt:
                description: When the media buy was created (ISO 8601)
                type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
              updatedAt:
                description: When the media buy was last updated (ISO 8601)
                type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
            required:
              - mediaBuyId
              - name
              - status
              - createdAt
              - updatedAt
            additionalProperties: false
        createdAt:
          description: When the campaign was created (ISO 8601)
          example: '2025-01-15T10:30:00Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          description: When the campaign was last updated (ISO 8601)
          example: '2025-01-20T14:45:00Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        dataDelivery:
          $ref: '#/components/schemas/CampaignDataDelivery'
        frequencyCaps:
          description: >-
            Buyer-side frequency cap configs for this campaign. Returned by `get_campaign`; not present on
            `list_campaigns` summary.
          type: array
          items:
            type: object
            properties:
              max_impressions:
                description: Maximum number of impressions allowed within the window
                example: 3
                type: integer
                exclusiveMinimum: true
                maximum: 9007199254740991
              window:
                type: object
                properties:
                  interval:
                    type: number
                  unit:
                    anyOf:
                      - type: string
                        enum:
                          - seconds
                      - type: string
                        enum:
                          - minutes
                      - type: string
                        enum:
                          - hours
                      - type: string
                        enum:
                          - days
                      - type: string
                        enum:
                          - campaign
                required:
                  - interval
                  - unit
                additionalProperties: {}
              id:
                description: Unique identifier for the frequency cap config
                example: '12345'
                type: string
              targetLevel:
                description: Level of the entity the cap applies to
                allOf:
                  - $ref: '#/components/schemas/FrequencyCapTargetLevel'
              targetId:
                description: >-
                  Identifier of the entity at the chosen target level: advertiser_id when targetLevel is ADVERTISER,
                  campaign_id when CAMPAIGN, creative_id when CREATIVE.
                example: camp_abc123
                type: string
              createdAt:
                description: ISO 8601 creation timestamp
                type: string
              updatedAt:
                description: ISO 8601 last-updated timestamp
                type: string
              archivedAt:
                description: ISO 8601 archive timestamp; null for active configs
                nullable: true
                type: string
            required:
              - max_impressions
              - window
              - id
              - targetLevel
              - targetId
              - createdAt
              - updatedAt
            additionalProperties: {}
      required:
        - campaignId
        - advertiserId
        - name
        - status
        - optimizationApplyMode
        - createdAt
        - updatedAt
      additionalProperties: false
    MediaBuyRef:
      description: >-
        Lightweight media buy reference (id + status). Used in Campaign.mediaBuyRefs so callers can enumerate media buys
        without loading the full nested tree.
      type: object
      properties:
        mediaBuyId:
          description: Unique identifier for the media buy
          example: mb_ETBn4gJ9Wu
          type: string
        status:
          description: Current media buy status (DRAFT, PENDING_APPROVAL, ACTIVE, PAUSED, COMPLETED, CANCELED).
          example: ACTIVE
          type: string
      required:
        - mediaBuyId
        - status
      additionalProperties: false
    MediaBudget:
      description: Budget available for media spend after fees are deducted.
      type: object
      properties:
        total:
          description: Total budget available for media spend (campaign budget minus fees), expressed in the campaign currency.
          type: number
          minimum: 0
          exclusiveMinimum: true
        currency:
          description: ISO 4217 currency code (e.g. USD).
          type: string
          minLength: 3
          maxLength: 3
      required:
        - total
        - currency
      additionalProperties: false
    CampaignFees:
      description: >-
        Fees applied to the campaign budget. Typically contains a single Scope3 fee today; structured as an array so
        additional fees can be surfaced without a breaking change.
      type: array
      items:
        $ref: '#/components/schemas/CampaignFee'
    CampaignFee:
      description: A single fee line item applied to a campaign.
      type: object
      properties:
        label:
          description: Human-readable name for the fee (e.g. "Scope3 fee").
          type: string
        amount:
          description: >-
            Fee amount deducted from the campaign budget, expressed in the campaign currency. For MARGIN fees this is
            the computed amount; for UNIT fees this is 0 at creation and accumulates as units are delivered.
          type: number
          minimum: 0
        currency:
          description: ISO 4217 currency code for the fee amount (e.g. USD).
          type: string
          minLength: 3
          maxLength: 3
        pricingType:
          description: Pricing type of the fee.
          allOf:
            - $ref: '#/components/schemas/CampaignFeePricingType'
        marginPercent:
          description: Margin as a percentage (e.g. 8 for 8%) when pricingType is MARGIN.
          type: number
          minimum: 0
        unit:
          description: Billing unit when pricingType is UNIT.
          allOf:
            - $ref: '#/components/schemas/CampaignFeeUnit'
        unitPrice:
          description: Price per unit in the campaign currency when pricingType is UNIT.
          type: number
          minimum: 0
      required:
        - label
        - amount
        - currency
      additionalProperties: false
    CampaignFeePricingType:
      description: MARGIN fees scale with the campaign budget; UNIT fees are billed per unit (CPM, record, flat rate).
      type: string
      enum:
        - MARGIN
        - UNIT
    CampaignFeeUnit:
      description: Unit that a UNIT fee is charged against.
      type: string
      enum:
        - CPM
        - RECORD
        - FLAT_RATE
    CampaignStorefrontRef:
      description: A storefront the campaign is pinned to, hydrated from the storefront IDs the buyer set on create/update.
      type: object
      properties:
        id:
          description: Storefront DB ID
          example: 42
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
        platformId:
          description: Public-facing storefront slug (the platform identifier returned by `list_storefronts`)
          example: acme-media
          type: string
        name:
          description: Storefront display name
          example: Acme Media
          type: string
      required:
        - id
        - platformId
        - name
      additionalProperties: false
    CampaignDataDelivery:
      description: >-
        Resolved data-delivery configuration for this campaign. Groups standing Data Delivery Outputs (with
        advertiser/campaign-scoped overrides applied). Distinct from media-buy reporting fields elsewhere in the API.
      type: object
      properties:
        outputs:
          description: >-
            Resolved Data Delivery Outputs for this campaign. Campaign-scoped Outputs override advertiser-scoped Outputs
            by `dataDeliveryType`. Each entry is tagged with `source` ("advertiser" or "campaign").
          type: array
          items:
            $ref: '#/components/schemas/DataDeliveryOutput'
      additionalProperties: false
    DataDeliveryOutput:
      description: Resolved Data Delivery Output as returned by the API.
      type: object
      properties:
        outputConfigId:
          description: Database identifier for the underlying output config row.
          type: string
        dataDeliveryType:
          type: string
          enum:
            - MB_DELIVERY
            - IMPRESSIONS
            - CLICKS
            - VAST_EVENTS
            - CAPI_ATTRIBUTION
            - MMP_POSTBACKS
            - MEASUREMENT
        cadence:
          type: string
          enum:
            - HOURLY
            - DAILY
            - WEEKLY
        syncWeeklyDay:
          type: integer
          minimum: 0
          maximum: 6
        enabled:
          type: boolean
        deliveryConfig:
          $ref: '#/components/schemas/DeliveryConfigOutput'
        source:
          description: Where this Output was configured — "advertiser" for default, "campaign" for an override.
          type: string
          enum:
            - advertiser
            - campaign
        createdAt:
          type: string
        updatedAt:
          type: string
      required:
        - outputConfigId
        - dataDeliveryType
        - cadence
        - enabled
        - deliveryConfig
        - source
        - createdAt
        - updatedAt
      additionalProperties: false
    FrequencyCapTargetLevel:
      description: Level of the entity the frequency cap applies to
      type: string
      enum:
        - ADVERTISER
        - CAMPAIGN
        - CREATIVE
    CampaignStatusChangeResponse:
      description: Response from executing or pausing a campaign
      type: object
      properties:
        campaignId:
          description: Campaign ID
          example: cmp_987654321
          type: string
        previousStatus:
          description: Previous campaign status
          type: string
          enum:
            - DRAFT
            - ACTIVE
            - PAUSED
            - COMPLETED
            - ARCHIVED
        newStatus:
          description: New campaign status
          type: string
          enum:
            - DRAFT
            - ACTIVE
            - PAUSED
            - COMPLETED
            - ARCHIVED
        success:
          description: Whether the status change was fully successful. False when any media buy execution failed.
          type: boolean
        errors:
          description: Structured error details per failed media buy. Only present when there are failures.
          type: array
          items:
            $ref: '#/components/schemas/ExecutionError'
      required:
        - campaignId
        - previousStatus
        - newStatus
        - success
      additionalProperties: false
    ExecutionError:
      description: Structured error detail for a failed media buy execution
      type: object
      properties:
        mediaBuyId:
          description: The media buy ID that failed
          type: string
        salesAgentId:
          description: The sales agent ID associated with the failed media buy
          type: string
        message:
          description: Human-readable error message
          type: string
        debug:
          $ref: '#/components/schemas/ExecuteMediaBuyDebugInfo'
      required:
        - mediaBuyId
        - salesAgentId
        - message
      additionalProperties: false
    ExecuteMediaBuyDebugInfo:
      description: >-
        Full debug info including ADCP request, response, and A2A debug logs. Only present when debug=true. Same
        structure as v1 execute_media_buy debug output.
      type: object
      properties:
        request:
          description: The full ADCP create_media_buy request payload sent to the sales agent
          type: object
          additionalProperties: {}
        response:
          description: The full ADCP response from the sales agent
          type: object
          additionalProperties: {}
        debugLogs:
          description: Full A2A request/response debug logs from the ADCP client
          type: array
          items:
            type: object
            additionalProperties: {}
        error:
          description: Error message if the execution failed
          type: string
      additionalProperties: false
    AutoSelectProductsResponse:
      description: Response from auto-selecting products for a performance campaign
      type: object
      properties:
        campaignId:
          description: Campaign ID
          type: string
        discoveryId:
          description: Discovery session ID containing the selected products
          type: string
        selectedProducts:
          description: Products selected and added to the discovery session
          type: array
          items:
            type: object
            properties:
              productId:
                type: string
              name:
                type: string
              salesAgentId:
                type: string
              groupId:
                type: string
              groupName:
                type: string
              cpm:
                type: number
              budget:
                type: number
              pricingOptionId:
                type: string
            required:
              - productId
              - name
              - salesAgentId
              - groupId
              - groupName
              - budget
            additionalProperties: false
        budgetContext:
          description: Budget allocation summary
          type: object
          properties:
            campaignBudget:
              type: number
            totalAllocated:
              type: number
            remainingBudget:
              type: number
            currency:
              type: string
          required:
            - campaignBudget
            - totalAllocated
            - remainingBudget
            - currency
          additionalProperties: false
        productCount:
          description: Total number of products selected
          type: integer
          minimum: 0
          maximum: 9007199254740991
        previouslySelectedCount:
          description: Number of previously selected products that were replaced by auto-select
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - campaignId
        - discoveryId
        - selectedProducts
        - budgetContext
        - productCount
      additionalProperties: false
    GetAdcpStatusOutput:
      type: object
      properties:
        campaign_id:
          type: string
        media_buys:
          type: array
          items:
            type: object
            properties:
              media_buy_id:
                type: string
              adcp_media_buy_id:
                type: string
              internal_status:
                type: string
              adcp_status:
                nullable: true
                type: string
              previous_internal_status:
                type: string
              previous_adcp_status:
                nullable: true
                type: string
              updated:
                type: boolean
            required:
              - media_buy_id
              - adcp_media_buy_id
              - internal_status
              - adcp_status
              - previous_internal_status
              - previous_adcp_status
              - updated
            additionalProperties: false
        agents_queried:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        errors:
          type: array
          items:
            type: object
            properties:
              media_buy_id:
                type: string
              error:
                type: string
            required:
              - media_buy_id
              - error
            additionalProperties: false
      required:
        - campaign_id
        - media_buys
        - agents_queried
        - errors
      additionalProperties: false
    CampaignProductsResponse:
      description: Products staged on a campaign along with their discovery run and media buy execution status
      type: object
      properties:
        campaignId:
          description: Campaign ID
          type: string
        discoveryId:
          description: Discovery session attached to the campaign, or null if none attached
          nullable: true
          type: string
        products:
          description: Products staged on this campaign
          type: array
          items:
            $ref: '#/components/schemas/CampaignProductEntry'
        searchContexts:
          description: Discovery runs that have contributed products
          type: array
          items:
            $ref: '#/components/schemas/CampaignSearchContextSummary'
        summary:
          description: Aggregate counts for products on the campaign
          type: object
          properties:
            totalProducts:
              description: Total number of products staged on the campaign
              type: integer
              minimum: 0
              maximum: 9007199254740991
            productsOnMediaBuys:
              description: Products already attached to a media buy
              type: integer
              minimum: 0
              maximum: 9007199254740991
            productsPending:
              description: Products staged but not yet on a media buy
              type: integer
              minimum: 0
              maximum: 9007199254740991
          required:
            - totalProducts
            - productsOnMediaBuys
            - productsPending
          additionalProperties: false
      required:
        - campaignId
        - discoveryId
        - products
        - searchContexts
        - summary
      additionalProperties: false
    CampaignProductEntry:
      description: A product staged on a campaign with discovery and execution context
      type: object
      properties:
        productId:
          description: Unique product identifier
          type: string
        productName:
          description: Human-readable product name
          type: string
        salesAgentId:
          description: Sales agent ID that supplied this product
          type: string
        publisherDomain:
          description: Publisher domain for this product
          type: string
        bidPrice:
          description: Bid price set on the product
          type: number
        budget:
          description: Budget allocated to this product
          type: number
        pricingOptionId:
          description: Selected pricing option ID for the product
          type: string
        pricingModel:
          description: Pricing model (e.g. CPM, fixed)
          type: string
        selectedAt:
          description: When this product was selected (ISO 8601)
          type: string
        searchContext:
          description: Discovery run (search context) that surfaced this product
          type: object
          properties:
            id:
              type: string
            brief:
              type: string
          required:
            - id
            - brief
          additionalProperties: false
        mediaBuys:
          description: >-
            Media buys this product is attached to (empty if the product has not been executed; can contain multiple
            entries on multi-strategy campaigns)
          type: array
          items:
            type: object
            properties:
              mediaBuyId:
                type: string
              status:
                type: string
              name:
                type: string
            required:
              - mediaBuyId
              - status
              - name
            additionalProperties: false
      required:
        - productId
        - salesAgentId
        - selectedAt
        - mediaBuys
      additionalProperties: false
    CampaignSearchContextSummary:
      description: Summary of a single discovery run within a campaign
      type: object
      properties:
        id:
          description: Search context (run) identifier
          type: string
        brief:
          description: Brief used for this run
          type: string
        channels:
          description: Channels used for this run
          type: array
          items:
            type: string
        countries:
          description: Countries used for this run
          type: array
          items:
            type: string
        createdAt:
          description: When this run was started (ISO 8601)
          type: string
        productCount:
          description: Number of products discovered in this run
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - id
        - brief
        - channels
        - countries
        - createdAt
        - productCount
      additionalProperties: false
    ListBuyerActivityResponse:
      description: Paginated list of buyer activity audit logs
      type: object
      properties:
        logs:
          type: array
          items:
            $ref: '#/components/schemas/BuyerAuditLog'
        total:
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - logs
        - total
      additionalProperties: false
    BuyerAuditLog:
      description: Audit log row surfaced to the buyer activity feed
      type: object
      properties:
        id:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        timestamp:
          type: string
        createdAt:
          type: string
        action:
          type: string
        resourceType:
          type: string
        resourceId:
          nullable: true
          type: string
        resourceName:
          nullable: true
          type: string
        parentType:
          nullable: true
          type: string
        advertiserId:
          nullable: true
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        userId:
          nullable: true
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        userEmail:
          nullable: true
          type: string
        userName:
          nullable: true
          type: string
        serviceTokenId:
          nullable: true
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        serviceTokenName:
          nullable: true
          type: string
        parameters:
          nullable: true
          type: object
          additionalProperties: {}
        changes:
          nullable: true
          type: object
          additionalProperties: {}
        description:
          type: string
      required:
        - id
        - timestamp
        - createdAt
        - action
        - resourceType
        - resourceId
        - resourceName
        - parentType
        - advertiserId
        - userId
        - userEmail
        - userName
        - serviceTokenId
        - serviceTokenName
        - parameters
        - changes
        - description
      additionalProperties: false
    CreativeManifestResponse:
      description: Creative manifest with inline assets
      type: object
      properties:
        creative_id:
          description: Creative manifest ID
          type: string
        name:
          description: Manifest name
          type: string
        message:
          description: Creative brief text
          type: string
        brand_domain:
          description: Brand domain (auto-resolved)
          type: string
        template_id:
          description: Creative template used for this manifest
          type: string
        format_id:
          type: object
          properties:
            id:
              type: string
            agent_url:
              type: string
            width:
              type: number
            height:
              type: number
            duration_ms:
              type: number
          required:
            - id
            - agent_url
          additionalProperties: {}
        target_format_ids:
          description: Target format IDs (from campaign products)
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              agent_url:
                type: string
              width:
                type: number
              height:
                type: number
              duration_ms:
                type: number
            required:
              - id
              - agent_url
            additionalProperties: {}
        preview_url:
          description: URL to preview the processed creative (processed HTML hosted in GCS)
          type: string
          format: uri
        assets:
          description: Uploaded assets in this manifest
          type: array
          items:
            $ref: '#/components/schemas/ManifestAssetResponse'
        html_processing:
          description: Result of HTML processing (CDN URL rewriting + macro insertion)
          type: object
          properties:
            processed_html:
              description: Full processed HTML (only included in create response, not GET)
              type: string
            processed_html_url:
              description: URL to processed HTML in GCS (for preview)
              type: string
              format: uri
            rewritten_refs:
              description: Asset references rewritten to CDN URLs
              type: array
              items:
                type: object
                properties:
                  original:
                    type: string
                  cdn_url:
                    type: string
                required:
                  - original
                  - cdn_url
                additionalProperties: false
            unresolved_refs:
              description: Local references found in HTML that did not match any uploaded asset
              type: array
              items:
                type: string
            inserted_macros:
              description: ADCP macros that were inserted
              type: array
              items:
                type: string
          required:
            - rewritten_refs
            - unresolved_refs
            - inserted_macros
          additionalProperties: false
        auto_detected_template:
          description: Auto-detected template info (populated when template_id was not explicitly provided)
          type: object
          properties:
            template_id:
              type: string
            template_name:
              type: string
            method:
              type: string
              enum:
                - tag_hints
                - html_analysis
                - file_analysis
                - none
          required:
            - template_id
            - template_name
            - method
          additionalProperties: false
        creative_manifest:
          description: Full ADCP creative manifest (built for sync)
        sync_status:
          description: Sync status across sales agents
          allOf:
            - $ref: '#/components/schemas/CreativeManifestSyncStatus'
        tracking:
          description: Auto-generated Scope3 tracking URLs for impression and click measurement
          type: object
          properties:
            impression_tracker_url:
              description: Scope3 impression tracker pixel URL with macro placeholders
              type: string
            click_tracker_url:
              description: Scope3 click tracker URL wrapping the original clickthrough with macro placeholders
              type: string
            supported_macros:
              description: ADCP macros supported by this creative format (filled at ad serving time)
              type: array
              items:
                type: string
          required:
            - supported_macros
          additionalProperties: false
        campaign_id:
          description: Campaign ID
          type: string
        frequencyCaps:
          description: Buyer-defined frequency caps configured for this creative
          type: array
          items:
            type: object
            properties:
              max_impressions:
                description: Maximum number of impressions allowed within the window
                example: 3
                type: integer
                exclusiveMinimum: true
                maximum: 9007199254740991
              window:
                type: object
                properties:
                  interval:
                    type: number
                  unit:
                    anyOf:
                      - type: string
                        enum:
                          - seconds
                      - type: string
                        enum:
                          - minutes
                      - type: string
                        enum:
                          - hours
                      - type: string
                        enum:
                          - days
                      - type: string
                        enum:
                          - campaign
                required:
                  - interval
                  - unit
                additionalProperties: {}
              id:
                description: Unique identifier for the frequency cap config
                example: '12345'
                type: string
              targetLevel:
                description: Level of the entity the cap applies to
                allOf:
                  - $ref: '#/components/schemas/FrequencyCapTargetLevel'
              targetId:
                description: >-
                  Identifier of the entity at the chosen target level: advertiser_id when targetLevel is ADVERTISER,
                  campaign_id when CAMPAIGN, creative_id when CREATIVE.
                example: camp_abc123
                type: string
              createdAt:
                description: ISO 8601 creation timestamp
                type: string
              updatedAt:
                description: ISO 8601 last-updated timestamp
                type: string
              archivedAt:
                description: ISO 8601 archive timestamp; null for active configs
                nullable: true
                type: string
            required:
              - max_impressions
              - window
              - id
              - targetLevel
              - targetId
              - createdAt
              - updatedAt
            additionalProperties: {}
        created_at:
          description: Created timestamp
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updated_at:
          description: Updated timestamp
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - creative_id
        - name
        - assets
        - campaign_id
        - created_at
        - updated_at
      additionalProperties: false
    ManifestAssetResponse:
      description: Asset within a creative manifest
      type: object
      properties:
        asset_id:
          description: Asset ID
          type: string
        name:
          description: Display name
          type: string
        original_filename:
          description: Original uploaded filename
          type: string
        asset_type:
          description: Asset type
          type: string
          enum:
            - IMAGE
            - VIDEO
            - AUDIO
            - HTML
            - JAVASCRIPT
            - CSS
            - TEXT
            - URL
            - VAST
            - FONT
            - LOGO
            - DOCUMENT
        content_type:
          description: MIME type
          type: string
        file_size:
          description: File size in bytes
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        public_url:
          description: Public URL
          type: string
          format: uri
        asset_source:
          description: Whether this asset was uploaded by the user or generated by the system
          type: string
          enum:
            - CREATIVE_SOURCE
            - USER_UPLOADED
            - SYSTEM_PROCESSED
        created_at:
          description: Upload timestamp
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - asset_id
        - name
        - original_filename
        - asset_type
        - content_type
        - file_size
        - public_url
        - asset_source
        - created_at
      additionalProperties: false
    CreativeManifestSyncStatus:
      description: Sync status across sales agents for a creative manifest.
      type: object
      properties:
        synced:
          description: True when the manifest is synced with at least one agent
          type: boolean
        agent_count:
          description: Number of sales agents the manifest is synced with
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        last_synced_at:
          description: Timestamp of the most recent successful sync
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - synced
        - agent_count
      additionalProperties: false
    CreativeManifestListResponse:
      description: Paginated list of creative manifest summaries
      type: object
      properties:
        manifests:
          description: Manifests projected to the summary shape. Use `get_creative` for full detail.
          type: array
          items:
            $ref: '#/components/schemas/CreativeManifestSummary'
        total:
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - manifests
        - total
      additionalProperties: false
    CreativeManifestSummary:
      description: Compact creative-manifest view returned by list endpoints. Use `get_creative` for the full resource.
      type: object
      properties:
        creative_id:
          description: Creative manifest ID
          type: string
        campaign_id:
          description: Campaign ID
          type: string
        name:
          description: Manifest name
          type: string
        format_id:
          type: object
          properties:
            id:
              type: string
            agent_url:
              type: string
            width:
              type: number
            height:
              type: number
            duration_ms:
              type: number
          required:
            - id
            - agent_url
          additionalProperties: {}
        template_id:
          description: Creative template used for this manifest
          type: string
        brand_domain:
          description: Brand domain (auto-resolved)
          type: string
        preview_url:
          description: URL to preview the processed creative (processed HTML hosted in GCS)
          type: string
          format: uri
        created_at:
          description: Created timestamp
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updated_at:
          description: Updated timestamp
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        asset_count:
          description: Number of uploaded assets in this manifest. Replaces the embedded `assets[]` array on summary rows.
          example: 3
          type: integer
          minimum: 0
          maximum: 9007199254740991
        sync_status:
          description: >-
            Compact sync status across sales agents. Use `get_creative` for the full sync metadata (including
            `last_synced_at`).
          type: object
          properties:
            synced:
              description: True when the manifest is synced with at least one agent
              type: boolean
            agent_count:
              description: Number of sales agents the manifest is synced with
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
          required:
            - synced
            - agent_count
          additionalProperties: false
      required:
        - creative_id
        - campaign_id
        - name
        - created_at
        - updated_at
        - asset_count
      additionalProperties: false
    EventSourceListResponse:
      description: Response containing a paginated list of event sources
      type: object
      properties:
        eventSources:
          description: List of event sources
          type: array
          items:
            $ref: '#/components/schemas/EventSourceOutput'
        total:
          description: Total count of event sources matching the query
          example: 5
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - eventSources
        - total
      additionalProperties: false
    EventSourceOutput:
      description: Event source resource representation
      type: object
      properties:
        eventSourceId:
          description: Identifier for this event source
          example: retailer_sales
          type: string
        name:
          description: Human-readable name
          example: Retailer Sales Pixel
          type: string
        eventTypes:
          description: Event types this source handles (null = all types accepted)
          nullable: true
          type: array
          items:
            description: IAB ECAPI event type to optimize for
            type: string
            enum:
              - page_view
              - view_content
              - select_content
              - select_item
              - search
              - share
              - add_to_cart
              - remove_from_cart
              - viewed_cart
              - add_to_wishlist
              - initiate_checkout
              - add_payment_info
              - purchase
              - refund
              - lead
              - qualify_lead
              - close_convert_lead
              - disqualify_lead
              - complete_registration
              - subscribe
              - start_trial
              - app_install
              - app_launch
              - contact
              - schedule
              - donate
              - submit_application
              - custom
        allowedDomains:
          description: Domains authorized to send events
          nullable: true
          type: array
          items:
            type: string
        createdAt:
          description: When the event source was created (ISO 8601)
          example: '2026-01-15T10:30:00.000Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          description: When the event source was last updated (ISO 8601)
          example: '2026-01-20T14:45:00.000Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - eventSourceId
        - name
        - eventTypes
        - allowedDomains
        - createdAt
        - updatedAt
      additionalProperties: false
    SyncEventSourcesResponse:
      description: Response from sync_event_sources
      type: object
      properties:
        event_sources:
          description: Per-source sync results
          type: array
          items:
            $ref: '#/components/schemas/EventSourceSyncResult'
      required:
        - event_sources
      additionalProperties: false
    EventSourceSyncResult:
      description: Per-source result from sync_event_sources
      type: object
      properties:
        event_source_id:
          description: Event source identifier
          type: string
        action:
          description: What happened to this event source during sync
          type: string
          enum:
            - created
            - updated
            - unchanged
            - failed
            - deleted
        error:
          description: Error message when action is "failed"
          type: string
      required:
        - event_source_id
        - action
      additionalProperties: false
    EventSummaryResponse:
      description: Response containing hourly-aggregated event counts for an advertiser
      type: object
      properties:
        periodStart:
          description: Start of the queried period (inclusive, ISO 8601)
          example: '2026-03-27T14:00:00.000Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        periodEnd:
          description: End of the queried period (exclusive, ISO 8601)
          example: '2026-03-27T15:00:00.000Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        entries:
          description: Aggregated event entries within the queried period
          type: array
          items:
            $ref: '#/components/schemas/EventSummaryEntry'
        totalEventCount:
          description: Sum of all event counts across all entries
          example: 5000
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - periodStart
        - periodEnd
        - entries
        - totalEventCount
      additionalProperties: false
    EventSummaryEntry:
      description: A single hourly aggregation entry
      type: object
      properties:
        eventHour:
          description: Start of the aggregated hour window (ISO 8601)
          example: '2026-03-27T14:00:00.000Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        eventType:
          description: Type of event
          allOf:
            - $ref: '#/components/schemas/EventSummaryType'
        eventCount:
          description: Number of events in this hour for this type
          example: 1500
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - eventHour
        - eventType
        - eventCount
      additionalProperties: false
    SyncMeasurementDataResponse:
      description: Response from sync_measurement_data
      type: object
      properties:
        measurements:
          description: Per-record sync results
          type: array
          items:
            $ref: '#/components/schemas/MeasurementDataSyncResult'
      required:
        - measurements
      additionalProperties: false
    MeasurementDataSyncResult:
      description: Per-record result from sync_measurement_data
      type: object
      properties:
        index:
          description: Index of this measurement in the request array
          type: integer
          minimum: 0
          maximum: 9007199254740991
        action:
          description: What happened to this measurement during sync
          type: string
          enum:
            - created
            - updated
            - unchanged
            - failed
        error:
          description: Error message when action is "failed"
          type: string
      required:
        - index
        - action
      additionalProperties: false
    TestCohortListResponse:
      description: Response containing a paginated list of test-cohort summaries
      type: object
      properties:
        cohorts:
          description: Test cohorts projected to the summary shape. Use `get_test_cohort` for the full resource.
          type: array
          items:
            $ref: '#/components/schemas/TestCohortSummary'
        total:
          description: Total count of cohorts matching the query
          example: 6
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - cohorts
        - total
      additionalProperties: false
    TestCohortSummary:
      description: Compact test-cohort view returned by list endpoints. Use `get_test_cohort` for the full resource.
      type: object
      properties:
        id:
          description: Unique identifier for the test cohort
          example: cohort_abc123
          type: string
        advertiserId:
          description: Advertiser ID that owns this cohort
          example: '12345'
          type: string
        name:
          description: Name of the test cohort
          example: West Coast Treatment Group
          type: string
        cohortType:
          description: Type classification for the cohort
          example: geographic
          type: string
        role:
          description: Role of the cohort in the test
          type: string
          enum:
            - TREATMENT
            - CONTROL
            - OBSERVATION
        estimatedSize:
          description: Estimated number of users in this cohort
          example: 50000
          type: integer
          minimum: 0
          maximum: 9007199254740991
        isActive:
          description: Whether the cohort is currently active
          type: boolean
        createdAt:
          description: When the cohort was created (ISO 8601)
          example: '2025-01-15T10:30:00Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          description: When the cohort was last updated (ISO 8601)
          example: '2025-01-20T14:45:00Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - id
        - advertiserId
        - name
        - cohortType
        - role
        - isActive
        - createdAt
        - updatedAt
      additionalProperties: false
    TestCohortResponse:
      description: Response containing a single test cohort
      type: object
      properties:
        cohort:
          $ref: '#/components/schemas/TestCohortOutput'
      required:
        - cohort
      additionalProperties: false
    TestCohortOutput:
      description: Test cohort resource representation
      type: object
      properties:
        id:
          description: Unique identifier for the test cohort
          example: cohort_abc123
          type: string
        advertiserId:
          description: Advertiser ID that owns this cohort
          example: '12345'
          type: string
        name:
          description: Name of the test cohort
          example: West Coast Treatment Group
          type: string
        description:
          description: Description of the test cohort
          type: string
        cohortType:
          description: Type classification for the cohort
          example: geographic
          type: string
        role:
          description: Role of the cohort in the test
          type: string
          enum:
            - TREATMENT
            - CONTROL
            - OBSERVATION
        definition:
          description: Cohort targeting definition
          allOf:
            - $ref: '#/components/schemas/CohortDefinition'
        estimatedSize:
          description: Estimated number of users in this cohort
          example: 50000
          type: integer
          minimum: 0
          maximum: 9007199254740991
        isActive:
          description: Whether the cohort is currently active
          type: boolean
        createdAt:
          description: When the cohort was created (ISO 8601)
          example: '2025-01-15T10:30:00Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          description: When the cohort was last updated (ISO 8601)
          example: '2025-01-20T14:45:00Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - id
        - advertiserId
        - name
        - cohortType
        - role
        - definition
        - isActive
        - createdAt
        - updatedAt
      additionalProperties: false
    MeasurementConfigResponse:
      description: Response containing measurement configuration
      type: object
      properties:
        measurementConfig:
          $ref: '#/components/schemas/MeasurementConfigOutput'
      required:
        - measurementConfig
      additionalProperties: false
    MeasurementConfigOutput:
      description: Full measurement configuration for an advertiser
      type: object
      properties:
        advertiserId:
          description: Unique identifier for the advertiser
          example: '12345'
          type: string
        mmmEnabled:
          description: Whether Marketing Mix Modeling is enabled
          type: boolean
        mmmConfig:
          description: MMM configuration settings (present when mmmEnabled is true)
          allOf:
            - $ref: '#/components/schemas/MmmConfig'
        incrementalityTestingEnabled:
          description: Whether incrementality testing is enabled
          type: boolean
        brandLiftEnabled:
          description: Whether brand lift measurement is enabled
          type: boolean
        settings:
          description: Additional measurement settings as key-value pairs
          type: object
          additionalProperties: {}
        createdAt:
          description: When the measurement config was created (ISO 8601)
          example: '2025-01-15T10:30:00Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          description: When the measurement config was last updated (ISO 8601)
          example: '2025-01-20T14:45:00Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - advertiserId
        - mmmEnabled
        - incrementalityTestingEnabled
        - brandLiftEnabled
        - createdAt
        - updatedAt
      additionalProperties: false
    ReportingMetricsResponse:
      description: 'Hierarchical reporting response: advertiser → campaign → media buy → package'
      type: object
      properties:
        advertisers:
          description: Advertiser-level reporting data
          type: array
          items:
            $ref: '#/components/schemas/AdvertiserReporting'
        totals:
          description: Aggregated totals across all advertisers
          allOf:
            - $ref: '#/components/schemas/ReportingMetrics'
        periodStart:
          description: Start of the reporting period (YYYY-MM-DD)
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        periodEnd:
          description: End of the reporting period (YYYY-MM-DD)
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      required:
        - advertisers
        - totals
        - periodStart
        - periodEnd
      additionalProperties: false
    AdvertiserReporting:
      description: Advertiser-level reporting metrics with campaign breakdown
      type: object
      properties:
        advertiserId:
          description: Advertiser identifier (seat ID)
          type: string
        advertiserName:
          description: Advertiser name
          type: string
        metrics:
          $ref: '#/components/schemas/ReportingMetrics'
        campaigns:
          description: Campaign-level breakdown
          type: array
          items:
            $ref: '#/components/schemas/CampaignReporting'
      required:
        - advertiserId
        - advertiserName
        - metrics
        - campaigns
      additionalProperties: false
    ReportingMetrics:
      description: Raw and calculated reporting metrics
      type: object
      properties:
        impressions:
          description: Total impressions
          type: integer
          minimum: 0
          maximum: 9007199254740991
        spend:
          description: Total spend in USD
          type: number
          minimum: 0
        clicks:
          description: Total clicks
          type: integer
          minimum: 0
          maximum: 9007199254740991
        views:
          description: >-
            Viewable impressions (the MRC-viewable subset of impressions, per AdCP). For viewability rate, divide by
            impressions.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        completedViews:
          description: Video/audio completions (qualified by view_duration_seconds when set on the goal)
          type: integer
          minimum: 0
          maximum: 9007199254740991
        conversions:
          description: Total conversions
          type: integer
          minimum: 0
          maximum: 9007199254740991
        leads:
          description: Total leads
          type: integer
          minimum: 0
          maximum: 9007199254740991
        videoCompletions:
          description: Total video completions
          type: integer
          minimum: 0
          maximum: 9007199254740991
        ecpm:
          description: 'Effective CPM: (spend * 1000) / impressions'
          nullable: true
          type: number
        cpc:
          description: 'Cost per click: spend / clicks'
          nullable: true
          type: number
        ctr:
          description: 'Click-through rate: clicks / impressions'
          nullable: true
          type: number
        completionRate:
          description: 'Completion rate: completedViews / views'
          nullable: true
          type: number
      required:
        - impressions
        - spend
        - clicks
        - views
        - completedViews
        - conversions
        - leads
        - videoCompletions
        - ecpm
        - cpc
        - ctr
        - completionRate
      additionalProperties: false
    CampaignReporting:
      description: Campaign-level reporting metrics with media buy breakdown
      type: object
      properties:
        campaignId:
          description: Campaign identifier
          type: string
        campaignName:
          description: Campaign name
          type: string
        metrics:
          $ref: '#/components/schemas/ReportingMetrics'
        mediaBuys:
          description: Media buy-level breakdown
          type: array
          items:
            $ref: '#/components/schemas/MediaBuyReporting'
      required:
        - campaignId
        - campaignName
        - metrics
        - mediaBuys
      additionalProperties: false
    MediaBuyReporting:
      description: Media buy-level reporting metrics with package breakdown
      type: object
      properties:
        mediaBuyId:
          description: Media buy identifier
          type: string
        name:
          description: Media buy name
          type: string
        status:
          description: Media buy status
          type: string
        budget:
          description: Total allocated budget for this media buy (sum of product budgets), null if no budget set
          nullable: true
          type: number
        metrics:
          $ref: '#/components/schemas/ReportingMetrics'
        packages:
          description: Package-level breakdown
          type: array
          items:
            $ref: '#/components/schemas/PackageReporting'
      required:
        - mediaBuyId
        - name
        - status
        - budget
        - metrics
        - packages
      additionalProperties: false
    PackageReporting:
      description: Package-level reporting metrics
      type: object
      properties:
        packageId:
          description: Package identifier
          type: string
        productId:
          description: Product identifier for this package
          nullable: true
          type: string
        productName:
          description: Human-readable product name for this package
          nullable: true
          type: string
        metrics:
          $ref: '#/components/schemas/ReportingMetrics'
      required:
        - packageId
        - productId
        - productName
        - metrics
      additionalProperties: false
    CurrentAccountResponse:
      description: Current customer account context
      type: object
      properties:
        id:
          description: Customer ID
          example: 100
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        company:
          description: Company name
          example: Acme Inc
          type: string
        name:
          description: Display name
          example: Acme
          type: string
        role:
          description: User role on this customer
          example: ADMIN
          type: string
      required:
        - id
        - company
        - name
      additionalProperties: false
    ListCustomerAccountsResponse:
      description: List of customer accounts for the authenticated user
      type: object
      properties:
        accounts:
          description: Customer accounts the user has access to
          type: array
          items:
            $ref: '#/components/schemas/OrgAccountSummary'
      required:
        - accounts
      additionalProperties: false
    OrgAccountSummary:
      description: Summary of a customer organization account
      type: object
      properties:
        id:
          description: Customer ID
          example: 100
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        company:
          description: Company name
          example: Acme Inc
          type: string
        name:
          description: Display name
          example: Acme
          type: string
        role:
          description: User role on this customer (MEMBER, ADMIN, SUPER_ADMIN)
          example: ADMIN
          type: string
      required:
        - id
        - company
        - name
      additionalProperties: false
    CreateChildAccountResponse:
      description: Full user context scoped to the new child customer
      type: object
      properties:
        user:
          description: User profile data
          type: object
          properties: {}
          additionalProperties: {}
        customer:
          description: Customer context for the newly created child
          type: object
          properties: {}
          additionalProperties: {}
        customers:
          description: All accessible customer accounts
          type: array
          items:
            type: object
            properties: {}
            additionalProperties: {}
        showPsaBox:
          description: Whether to show the ToS acceptance dialog
          type: boolean
        tosBlockedReason:
          description: >-
            When set, the user cannot accept ToS themselves and must contact an organization admin. Only emitted when
            showPsaBox is also true.
          type: string
          enum:
            - PARENT_MUST_ACCEPT_TOS
        hasContract:
          description: Whether the customer has an active contract
          type: boolean
        latestPsaVersion:
          description: Latest PSA version identifier
          type: string
        convertedFromStandalone:
          description: True if the request triggered a standalone-to-parent conversion
          type: boolean
      required:
        - user
        - customer
        - customers
        - showPsaBox
        - hasContract
        - latestPsaVersion
        - convertedFromStandalone
      additionalProperties: false
    UpdateCustomerDomainResponse:
      description: Updated customer domain
      type: object
      properties:
        id:
          description: Customer ID
          example: 200
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        customerDomain:
          description: Registered organization domain on the customer
          example: nike.com
          nullable: true
          type: string
      required:
        - id
        - customerDomain
      additionalProperties: false
    AvailableAccountListResponse:
      description: Response containing a list of available accounts from a partner
      type: object
      properties:
        accounts:
          description: List of available (discovered) accounts
          type: array
          items:
            $ref: '#/components/schemas/AvailableAccountOutput'
        total:
          description: Total count of available accounts
          example: 8
          type: integer
          minimum: 0
          maximum: 9007199254740991
        synced:
          description: >-
            True when no accounts matched and a sync_accounts call was automatically triggered to provision this account
            at the partner. The list reflects the post-sync state.
          type: boolean
        billingOptions:
          description: Billing options supported by this partner agent, as reported in its ADCP capabilities.
          type: object
          properties:
            default:
              nullable: true
              type: string
            supported:
              type: array
              items:
                type: string
          required:
            - default
            - supported
          additionalProperties: false
      required:
        - accounts
        - total
      additionalProperties: false
    AvailableAccountOutput:
      description: Discovered account available to be linked to an advertiser
      type: object
      properties:
        accountId:
          description: Partner account identifier
          example: acc_acme_pinnacle
          type: string
        name:
          description: Human-readable account name from the partner
          example: Acme c/o Pinnacle
          nullable: true
          type: string
        advertiser:
          description: Advertiser name as recorded by the partner platform
          example: Acme Corp
          nullable: true
          type: string
        billingProxy:
          description: Billing proxy entity (e.g. agency buying on behalf of advertiser)
          example: Pinnacle Media
          nullable: true
          type: string
        house:
          description: Domain or house identifier for the account
          example: acme-corp.com
          nullable: true
          type: string
        billing:
          description: Billing arrangement type
          example: advertiser
          nullable: true
          type: string
        sources:
          description: >-
            Storefront sources that surface this discovered account to the buyer. Same account may appear via multiple
            sources when the underlying agent is shared across storefronts.
          type: array
          items:
            $ref: '#/components/schemas/BuyerCredentialSourceRef'
        status:
          description: Current account status on the partner platform
          type: string
          enum:
            - active
            - pending_approval
            - payment_required
            - suspended
            - closed
      required:
        - accountId
        - sources
        - status
      additionalProperties: false
    BuyerCredentialSourceRef:
      description: A storefront/source pair that a single credential row gives the buyer access to
      type: object
      properties:
        storefrontId:
          description: Storefront ID this credential covers
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        storefrontName:
          description: Storefront display name
          type: string
        sourceId:
          description: Inventory source ID within the storefront
          type: string
        sourceName:
          description: Inventory source display name
          type: string
      required:
        - storefrontId
        - storefrontName
        - sourceId
        - sourceName
      additionalProperties: false
    AccountResponse:
      description: Response containing a single linked account
      type: object
      properties:
        account:
          $ref: '#/components/schemas/AccountOutput'
      required:
        - account
      additionalProperties: false
    AccountOutput:
      description: Linked account resource on a partner platform
      type: object
      properties:
        linkId:
          description: Unique identifier for the advertiser-account link
          example: '42'
          type: string
        accountId:
          description: Partner account identifier
          example: acc_acme_pinnacle
          type: string
        name:
          description: Human-readable account name from the partner
          example: Acme c/o Pinnacle
          nullable: true
          type: string
        advertiser:
          description: Advertiser name as recorded by the partner platform
          example: Acme Corp
          nullable: true
          type: string
        billingProxy:
          description: Billing proxy entity (e.g. agency buying on behalf of advertiser)
          example: Pinnacle Media
          nullable: true
          type: string
        house:
          description: Domain or house identifier for the account
          example: acme-corp.com
          nullable: true
          type: string
        billing:
          description: Billing arrangement type
          example: advertiser
          nullable: true
          type: string
        sources:
          description: >-
            Storefront sources that surface this account to the buyer. A single linked account may be reachable through
            multiple sources when the underlying agent is shared across storefronts. Empty when the underlying agent is
            no longer linked to any active storefront source.
          type: array
          items:
            $ref: '#/components/schemas/BuyerCredentialSourceRef'
        advertiserId:
          description: Advertiser that owns this account link
          example: '12345'
          type: string
        status:
          description: Current account status
          type: string
          enum:
            - active
            - pending_approval
            - payment_required
            - suspended
            - closed
        createdAt:
          description: When the account was created (ISO 8601)
          example: '2025-01-15T10:30:00Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          description: When the account was last updated (ISO 8601)
          example: '2025-01-20T14:45:00Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - linkId
        - accountId
        - sources
        - advertiserId
        - status
        - createdAt
        - updatedAt
      additionalProperties: false
    BuyerStorefrontList:
      description: Paginated list of storefront summaries available to a buyer
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BuyerStorefrontSummary'
        total:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        hasMore:
          type: boolean
        nextOffset:
          nullable: true
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - items
        - total
        - hasMore
        - nextOffset
      additionalProperties: false
    BuyerStorefrontSummary:
      description: Compact storefront view returned by list endpoints. Use the storefront detail endpoint for the full resource.
      type: object
      properties:
        id:
          description: Storefront ID
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        platformId:
          description: Public-facing slug
          type: string
        name:
          description: Storefront display name
          type: string
        publisherDomain:
          description: Publisher domain
          nullable: true
          type: string
        status:
          description: Storefront lifecycle status
          type: string
          enum:
            - PENDING
            - ACTIVE
            - DISABLED
        sourceCount:
          description: >-
            Total number of inventory sources in this storefront. Replaces the embedded `sources[]` array on summary
            rows.
          example: 5
          type: integer
          minimum: 0
          maximum: 9007199254740991
        connectedSourceCount:
          description: >-
            Number of inventory sources the buyer already has working credentials for. Combined with `sourceCount`,
            gives a quick "is this wired up" signal.
          example: 3
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - id
        - platformId
        - name
        - publisherDomain
        - status
        - sourceCount
        - connectedSourceCount
      additionalProperties: false
    BuyerStorefront:
      description: A storefront as seen by a buyer
      type: object
      properties:
        id:
          description: Storefront ID
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        platformId:
          description: Public-facing slug
          type: string
        name:
          description: Storefront display name
          type: string
        publisherDomain:
          description: Publisher domain
          nullable: true
          type: string
        status:
          description: Storefront lifecycle status
          type: string
          enum:
            - PENDING
            - ACTIVE
            - DISABLED
        sources:
          description: Inventory sources available in this storefront
          type: array
          items:
            $ref: '#/components/schemas/BuyerStorefrontSource'
      required:
        - id
        - platformId
        - name
        - publisherDomain
        - status
        - sources
      additionalProperties: false
    BuyerStorefrontSource:
      description: An inventory source within a storefront, as seen by a buyer
      type: object
      properties:
        sourceId:
          description: Inventory source identifier within the storefront
          type: string
        name:
          description: Inventory source display name
          type: string
        requiresCredentials:
          description: Whether the buyer must register credentials to use this source
          type: boolean
        connected:
          description: Whether the buyer has active credentials for this source
          type: boolean
        customerAccounts:
          description: Buyer's registered accounts for this source
          type: array
          items:
            type: object
            properties:
              accountIdentifier:
                type: string
              status:
                type: string
            required:
              - accountIdentifier
              - status
            additionalProperties: false
      required:
        - sourceId
        - name
        - requiresCredentials
        - connected
        - customerAccounts
      additionalProperties: false
    BuyerCredential:
      description: A buyer's registered credential, scoped to the storefront sources it gives access to
      type: object
      properties:
        id:
          description: Credential record ID
          type: string
        accountIdentifier:
          description: The buyer's account identifier at the source
          type: string
        accountType:
          description: Account type (e.g. CLIENT, MARKETPLACE)
          type: string
        status:
          description: Credential status
          type: string
        registeredBy:
          description: Who registered this credential. Null on legacy rows that predate registration tracking.
          nullable: true
          type: string
        createdAt:
          description: When the credential was created (ISO 8601)
          type: string
        updatedAt:
          description: When the credential was last updated (ISO 8601)
          type: string
        sources:
          description: >-
            Storefront sources this credential gives the buyer access to. A single credential may cover multiple sources
            when the same agent backs the same source across storefronts. Can be empty when the credential's underlying
            agent is no longer linked to any active storefront source — the credential row is preserved so buyers can
            see (and clean up) orphaned registrations.
          type: array
          items:
            $ref: '#/components/schemas/BuyerCredentialSourceRef'
      required:
        - id
        - accountIdentifier
        - accountType
        - status
        - registeredBy
        - createdAt
        - updatedAt
        - sources
      additionalProperties: false
    BuyerCredentialRegistrationResponse:
      description: Response for registering credentials against a storefront inventory source
      type: object
      properties:
        id:
          description: Credential record ID
          type: string
        accountIdentifier:
          description: The buyer's account identifier at the source
          type: string
        status:
          description: Credential status
          type: string
        registeredBy:
          description: Who registered this credential. Null on legacy rows that predate registration tracking.
          nullable: true
          type: string
        createdAt:
          description: When the credential was created (ISO 8601)
          type: string
        oauth:
          description: Present when the source uses OAuth — the buyer must visit `authorizationUrl` to complete consent
          allOf:
            - $ref: '#/components/schemas/BuyerCredentialOAuthInfo'
      required:
        - id
        - accountIdentifier
        - status
        - registeredBy
        - createdAt
      additionalProperties: false
    BuyerCredentialOAuthInfo:
      description: OAuth authorization info presented in buyer-facing storefront/source terms
      type: object
      properties:
        authorizationUrl:
          description: URL the buyer must visit to authorize
          type: string
          format: uri
        storefrontId:
          description: Storefront the OAuth flow was initiated for
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        sourceId:
          description: Inventory source the OAuth flow was initiated for
          type: string
        sourceName:
          description: Inventory source display name
          type: string
      required:
        - authorizationUrl
        - storefrontId
        - sourceId
        - sourceName
      additionalProperties: false
    SyndicateResponse:
      description: Response after toggling syndication for one or more ADCP agents
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SyndicationStatusOutput'
      required:
        - data
      additionalProperties: false
    SyndicationStatusOutput:
      description: Syndication status record
      type: object
      properties:
        id:
          description: Syndication record ID
          example: '1'
          type: string
        customerId:
          description: Customer ID
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        seatId:
          description: Advertiser seat ID
          example: '12345'
          type: string
        resourceType:
          type: string
          enum:
            - AUDIENCE
            - EVENT_SOURCE
            - CATALOG
        resourceId:
          description: ID of the resource being syndicated
          type: string
        audienceId:
          description: FK to audience table (populated when resourceType is audience)
          example: '1'
          nullable: true
          type: string
        eventSourceId:
          description: FK to event_sources table (populated when resourceType is event_source)
          nullable: true
          type: string
        catalogId:
          description: FK to catalogs table (populated when resourceType is catalog)
          nullable: true
          type: string
        adcpAgentId:
          description: ADCP agent ID
          example: '42'
          type: string
        adcpAgentAccountId:
          description: ADCP agent account ID (FK to adcp_agent_accounts)
          nullable: true
          type: string
        enabled:
          description: Whether syndication is active
          type: boolean
        status:
          description: Current syndication status
          type: string
          enum:
            - PENDING
            - SYNCING
            - COMPLETED
            - FAILED
            - DISABLED
        errorMessage:
          description: Error message if syndication failed
          nullable: true
          type: string
        responseData:
          description: Response data from the syndication operation
          nullable: true
        createdAt:
          description: ISO 8601 timestamp
          type: string
        updatedAt:
          description: ISO 8601 timestamp
          type: string
        completedAt:
          description: ISO 8601 timestamp when syndication completed
          nullable: true
          type: string
      required:
        - id
        - customerId
        - seatId
        - resourceType
        - resourceId
        - audienceId
        - eventSourceId
        - catalogId
        - adcpAgentId
        - adcpAgentAccountId
        - enabled
        - status
        - errorMessage
        - responseData
        - createdAt
        - updatedAt
        - completedAt
      additionalProperties: false
    SyndicationStatusListResponse:
      description: Paginated list of syndication status records
      type: object
      properties:
        items:
          description: List of syndication status records
          type: array
          items:
            $ref: '#/components/schemas/SyndicationStatusOutput'
        total:
          description: Total count of records matching the query
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - items
        - total
      additionalProperties: false
    SyncAudiencesResponse:
      description: Audience sync accepted for async processing
      type: object
      properties:
        success:
          type: boolean
        accountId:
          description: Advertiser ID (numeric string, e.g. "25") — same as the path parameter
          example: '25'
          type: string
        operationId:
          description: Batch operation UUID for tracking async processing
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        taskId:
          description: Task ID for polling progress via GET /tasks/{taskId}. Same value as operationId.
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      required:
        - success
        - accountId
        - operationId
        - taskId
      additionalProperties: false
    AudienceListResponse:
      description: Paginated list of audience summaries
      type: object
      properties:
        audiences:
          type: array
          items:
            $ref: '#/components/schemas/AudienceSummary'
        total:
          type: number
        take:
          type: number
        skip:
          type: number
      required:
        - audiences
        - total
        - take
        - skip
      additionalProperties: false
    AudienceSummary:
      description: Compact audience view returned by list endpoints. Use `get_audience` for the full resource.
      type: object
      properties:
        audienceId:
          type: string
        name:
          nullable: true
          type: string
        accountId:
          description: Advertiser ID (numeric string, e.g. "25")
          example: '25'
          type: string
        status:
          description: Processing status of this audience
          type: string
          enum:
            - PROCESSING
            - ERROR
            - READY
            - TOO_SMALL
        deleted:
          type: boolean
        uploadedCount:
          nullable: true
          type: number
        matchedCount:
          nullable: true
          type: number
        createdAt:
          type: string
        updatedAt:
          type: string
      required:
        - audienceId
        - name
        - accountId
        - status
        - deleted
        - uploadedCount
        - matchedCount
        - createdAt
        - updatedAt
      additionalProperties: false
    TaskResponse:
      description: Response containing a single task
      type: object
      properties:
        task:
          $ref: '#/components/schemas/TaskOutput'
      required:
        - task
      additionalProperties: false
    TaskOutput:
      description: Async task resource representation
      type: object
      properties:
        taskId:
          description: Unique task identifier
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        taskType:
          description: Type of async operation
          example: audience_sync
          type: string
          enum:
            - audience_sync
            - media_buy_create
            - creative_sync
        status:
          description: Current task status (AdCP states)
          example: submitted
          type: string
          enum:
            - submitted
            - working
            - completed
            - failed
            - input-required
        resourceType:
          description: Type of resource this task operates on
          example: audience
          nullable: true
          type: string
        resourceId:
          description: Identifier of the resulting resource (set on completion)
          example: aud_12345
          nullable: true
          type: string
        error:
          description: AdCP-compatible error object when status is "failed"
          nullable: true
          allOf:
            - $ref: '#/components/schemas/TaskError'
        response:
          description: Original response payload from the downstream system
          nullable: true
          type: object
          additionalProperties: {}
        metadata:
          description: Operation-specific context
          nullable: true
          type: object
          additionalProperties: {}
        retryAfterSeconds:
          description: Suggested polling interval in seconds. Set based on task type to guide how frequently callers should poll.
          example: 30
          nullable: true
          type: number
        createdAt:
          description: When the task was created (ISO 8601)
          example: '2026-01-15T10:30:00.000Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          description: When the task was last updated (ISO 8601)
          example: '2026-01-20T14:45:00.000Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - taskId
        - taskType
        - status
        - resourceType
        - resourceId
        - error
        - response
        - metadata
        - retryAfterSeconds
        - createdAt
        - updatedAt
      additionalProperties: false
    TaskError:
      description: AdCP-compatible error object
      type: object
      properties:
        code:
          description: Error code for programmatic handling
          example: VALIDATION_ERROR
          type: string
        message:
          description: Human-readable error message
          example: Invalid budget value
          type: string
        field:
          description: Field path associated with the error
          example: packages[0].targeting
          type: string
        suggestion:
          description: Suggested fix for the error
          type: string
        retryAfter:
          description: Seconds to wait before retrying the operation
          type: number
        details:
          description: Additional task-specific error details
          type: object
          additionalProperties: {}
        recovery:
          description: >-
            Agent recovery classification: transient (retry), correctable (fix and resend), terminal (requires human
            action)
          type: string
          enum:
            - transient
            - correctable
            - terminal
      required:
        - code
        - message
      additionalProperties: false
    PropertyListListResponse:
      description: Response containing a paginated list of property-list summaries
      type: object
      properties:
        propertyLists:
          description: >-
            Property lists projected to the summary shape. Use `get_property_list` for the full resource (domains,
            filters).
          type: array
          items:
            $ref: '#/components/schemas/PropertyListSummary'
        total:
          description: Total count of property lists matching the query
          example: 3
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - propertyLists
        - total
      additionalProperties: false
    PropertyListSummary:
      description: Compact property-list view returned by list endpoints. Use `get_property_list` for full content.
      type: object
      properties:
        listId:
          description: Unique identifier for this property list
          example: '42'
          type: string
        name:
          description: Human-readable name
          example: Q1 Campaign - UK Premium
          type: string
        purpose:
          description: Whether properties in this list should be included or excluded
          example: include
          type: string
          enum:
            - include
            - exclude
        propertyCount:
          description: Number of resolved properties in the list
          example: 25
          type: integer
          minimum: 0
          maximum: 9007199254740991
        createdAt:
          description: When the property list was created (ISO 8601)
          example: '2026-01-15T10:30:00.000Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          description: When the property list was last updated (ISO 8601)
          example: '2026-01-20T14:45:00.000Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - listId
        - name
        - purpose
        - propertyCount
        - createdAt
        - updatedAt
      additionalProperties: false
    PropertyListResponse:
      description: Response containing a single property list
      type: object
      properties:
        propertyList:
          $ref: '#/components/schemas/PropertyListOutput'
      required:
        - propertyList
      additionalProperties: false
    PropertyListOutput:
      description: Property list resource representation
      type: object
      properties:
        listId:
          description: Unique identifier for this property list
          example: '42'
          type: string
        name:
          description: Human-readable name
          example: Q1 Campaign - UK Premium
          type: string
        purpose:
          description: Whether properties in this list should be included or excluded
          example: include
          type: string
          enum:
            - include
            - exclude
        identifiers:
          description: Resolved typed identifiers (domains and bundles)
          type: array
          items:
            type: object
            properties:
              type:
                anyOf:
                  - type: string
                    enum:
                      - domain
                  - type: string
                    enum:
                      - subdomain
                  - type: string
                    enum:
                      - network_id
                  - type: string
                    enum:
                      - ios_bundle
                  - type: string
                    enum:
                      - android_package
                  - type: string
                    enum:
                      - apple_app_store_id
                  - type: string
                    enum:
                      - google_play_id
                  - type: string
                    enum:
                      - roku_store_id
                  - type: string
                    enum:
                      - fire_tv_asin
                  - type: string
                    enum:
                      - samsung_app_id
                  - type: string
                    enum:
                      - apple_tv_bundle
                  - type: string
                    enum:
                      - bundle_id
                  - type: string
                    enum:
                      - venue_id
                  - type: string
                    enum:
                      - screen_id
                  - type: string
                    enum:
                      - openooh_venue_type
                  - type: string
                    enum:
                      - rss_url
                  - type: string
                    enum:
                      - apple_podcast_id
                  - type: string
                    enum:
                      - spotify_collection_id
                  - type: string
                    enum:
                      - podcast_guid
                  - type: string
                    enum:
                      - station_id
                  - type: string
                    enum:
                      - facility_id
              value:
                type: string
            required:
              - type
              - value
            additionalProperties: {}
        unresolvedIdentifiers:
          description: Identifiers that could not be resolved to internal property records
          type: array
          items:
            type: object
            properties:
              type:
                anyOf:
                  - type: string
                    enum:
                      - domain
                  - type: string
                    enum:
                      - subdomain
                  - type: string
                    enum:
                      - network_id
                  - type: string
                    enum:
                      - ios_bundle
                  - type: string
                    enum:
                      - android_package
                  - type: string
                    enum:
                      - apple_app_store_id
                  - type: string
                    enum:
                      - google_play_id
                  - type: string
                    enum:
                      - roku_store_id
                  - type: string
                    enum:
                      - fire_tv_asin
                  - type: string
                    enum:
                      - samsung_app_id
                  - type: string
                    enum:
                      - apple_tv_bundle
                  - type: string
                    enum:
                      - bundle_id
                  - type: string
                    enum:
                      - venue_id
                  - type: string
                    enum:
                      - screen_id
                  - type: string
                    enum:
                      - openooh_venue_type
                  - type: string
                    enum:
                      - rss_url
                  - type: string
                    enum:
                      - apple_podcast_id
                  - type: string
                    enum:
                      - spotify_collection_id
                  - type: string
                    enum:
                      - podcast_guid
                  - type: string
                    enum:
                      - station_id
                  - type: string
                    enum:
                      - facility_id
              value:
                type: string
            required:
              - type
              - value
            additionalProperties: {}
        registeredIdentifiers:
          description: Identifiers registered in the AAO property registry but not yet available for local targeting
          type: array
          items:
            type: object
            properties:
              type:
                anyOf:
                  - type: string
                    enum:
                      - domain
                  - type: string
                    enum:
                      - subdomain
                  - type: string
                    enum:
                      - network_id
                  - type: string
                    enum:
                      - ios_bundle
                  - type: string
                    enum:
                      - android_package
                  - type: string
                    enum:
                      - apple_app_store_id
                  - type: string
                    enum:
                      - google_play_id
                  - type: string
                    enum:
                      - roku_store_id
                  - type: string
                    enum:
                      - fire_tv_asin
                  - type: string
                    enum:
                      - samsung_app_id
                  - type: string
                    enum:
                      - apple_tv_bundle
                  - type: string
                    enum:
                      - bundle_id
                  - type: string
                    enum:
                      - venue_id
                  - type: string
                    enum:
                      - screen_id
                  - type: string
                    enum:
                      - openooh_venue_type
                  - type: string
                    enum:
                      - rss_url
                  - type: string
                    enum:
                      - apple_podcast_id
                  - type: string
                    enum:
                      - spotify_collection_id
                  - type: string
                    enum:
                      - podcast_guid
                  - type: string
                    enum:
                      - station_id
                  - type: string
                    enum:
                      - facility_id
              value:
                type: string
            required:
              - type
              - value
            additionalProperties: {}
        domains:
          description: Resolved domain values (convenience view of `identifiers` where type="domain")
          type: array
          items:
            type: string
        unresolvedDomains:
          description: Domain values that could not be resolved (convenience view of `unresolvedIdentifiers` where type="domain")
          type: array
          items:
            type: string
        registeredDomains:
          description: >-
            Domain values registered in AAO but not yet locally targetable (convenience view of `registeredIdentifiers`
            where type="domain")
          type: array
          items:
            type: string
        propertyCount:
          description: Number of resolved properties in the list
          example: 25
          type: integer
          minimum: 0
          maximum: 9007199254740991
        resolutionSummary:
          description: >-
            Quick-glance counts for how the submitted identifier set resolved. Populated on create and update only;
            omitted from get/list responses (the stored list contains only resolved identifiers). Always surface these
            counts to users so they know how many of their submitted identifiers will actually target.
          allOf:
            - $ref: '#/components/schemas/PropertyListResolutionSummary'
        cascadeSummary:
          description: >-
            When returned from an update, summarizes how the new list contents were retroactively pushed to active media
            buys whose advertisers reference this list. Omitted on create, get, and list responses.
          allOf:
            - $ref: '#/components/schemas/PropertyListCascadeSummary'
        filters:
          description: Filter configuration stored at creation time
          nullable: true
          allOf:
            - $ref: '#/components/schemas/PropertyListFiltersOutput'
        createdAt:
          description: When the property list was created (ISO 8601)
          example: '2026-01-15T10:30:00.000Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          description: When the property list was last updated (ISO 8601)
          example: '2026-01-20T14:45:00.000Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - listId
        - name
        - purpose
        - identifiers
        - unresolvedIdentifiers
        - registeredIdentifiers
        - domains
        - unresolvedDomains
        - registeredDomains
        - propertyCount
        - createdAt
        - updatedAt
      additionalProperties: false
    PropertyListResolutionSummary:
      description: Counts describing how a submitted identifier set resolved against the AAO registry and local catalog.
      type: object
      properties:
        totalRequested:
          description: Number of unique identifiers the caller submitted (after per-type normalization and dedup)
          example: 500
          type: integer
          minimum: 0
          maximum: 9007199254740991
        resolvedCount:
          description: Identifiers successfully resolved to local Property records
          example: 432
          type: integer
          minimum: 0
          maximum: 9007199254740991
        registeredCount:
          description: Identifiers present in the AAO registry but with no local Property record yet (not yet targetable)
          example: 12
          type: integer
          minimum: 0
          maximum: 9007199254740991
        unresolvedCount:
          description: Identifiers not found anywhere; they will NOT participate in targeting
          example: 56
          type: integer
          minimum: 0
          maximum: 9007199254740991
        resolutionRate:
          description: resolvedCount / totalRequested as a fraction 0–1 (0 when totalRequested is 0)
          example: 0.864
          type: number
          minimum: 0
          maximum: 1
      required:
        - totalRequested
        - resolvedCount
        - registeredCount
        - unresolvedCount
        - resolutionRate
      additionalProperties: false
    PropertyListCascadeSummary:
      description: Summary of the retroactive push of this updated property list to active media buys.
      type: object
      properties:
        totalMediaBuys:
          description: >-
            Active media buys found whose advertisers reference this list. Each received an update_media_buy call with
            the refreshed list reference.
          example: 4
          type: integer
          minimum: 0
          maximum: 9007199254740991
        updatedCount:
          description: Active media buys that were successfully notified of the updated list
          example: 3
          type: integer
          minimum: 0
          maximum: 9007199254740991
        failedCount:
          description: Active media buys where the update_media_buy call failed. See server logs for details.
          example: 1
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - totalMediaBuys
        - updatedCount
        - failedCount
      additionalProperties: false
    EmptyResponse:
      description: No content
      type: object
      properties: {}
      additionalProperties: false
    BuyerInvoicesResponse:
      description: Paginated consolidated invoices for the buyer customer
      type: object
      properties:
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/BuyerInvoiceItem'
        hasMore:
          type: boolean
        cursor:
          nullable: true
          type: string
      required:
        - invoices
        - hasMore
        - cursor
      additionalProperties: false
    BuyerInvoiceItem:
      description: A consolidated invoice issued to the buyer
      type: object
      properties:
        id:
          type: string
        number:
          nullable: true
          type: string
        status:
          nullable: true
          type: string
        currency:
          type: string
        amountDue:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        amountPaid:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        amountRemaining:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        total:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        created:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        dueDate:
          nullable: true
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        periodStart:
          nullable: true
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        periodEnd:
          nullable: true
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        hostedInvoiceUrl:
          nullable: true
          type: string
        invoicePdf:
          nullable: true
          type: string
        description:
          nullable: true
          type: string
        customerEmail:
          nullable: true
          type: string
        customerName:
          nullable: true
          type: string
      required:
        - id
        - number
        - status
        - currency
        - amountDue
        - amountPaid
        - amountRemaining
        - total
        - created
        - dueDate
        - periodStart
        - periodEnd
        - hostedInvoiceUrl
        - invoicePdf
        - description
      additionalProperties: false
    BuyerPendingInvoiceItemsResponse:
      description: Paginated pending line items for the buyer customer’s next consolidated invoice
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BuyerPendingInvoiceItem'
        hasMore:
          type: boolean
        cursor:
          nullable: true
          type: string
      required:
        - items
        - hasMore
        - cursor
      additionalProperties: false
    BuyerPendingInvoiceItem:
      description: A pending line item that will appear on the next consolidated invoice
      type: object
      properties:
        id:
          type: string
        description:
          nullable: true
          type: string
        currency:
          type: string
        amount:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        quantity:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        unitAmount:
          nullable: true
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        date:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        period:
          type: object
          properties:
            start:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            end:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
          required:
            - start
            - end
          additionalProperties: false
        proration:
          type: boolean
        customerId:
          nullable: true
          type: string
      required:
        - id
        - description
        - currency
        - amount
        - quantity
        - unitAmount
        - date
        - period
        - proration
      additionalProperties: false
    PacingPeriodsOutput:
      description: >-
        Defines a pacing schedule for a campaign. Periods represent time windows with varying spend intensity. Gaps
        between periods are treated as pauses (no spend). Use weight mode for relative intensity (e.g., 2x during
        holidays) or budget mode for explicit dollar amounts per period.
      type: object
      properties:
        mode:
          description: >-
            How period budgets are determined. "weight" uses relative weights to distribute the campaign budget
            proportionally. "budget" uses explicit dollar amounts per period.
          type: string
          enum:
            - weight
            - budget
        periods:
          description: Ordered list of pacing periods with date ranges and spend intensity
          minItems: 1
          maxItems: 52
          type: array
          items:
            type: object
            properties:
              label:
                description: Human-readable label for this period (e.g. "Memorial Day Heavy-Up")
                type: string
                minLength: 1
                maxLength: 100
              start:
                description: Period start date (YYYY-MM-DD, inclusive)
                type: string
                pattern: ^\d{4}-\d{2}-\d{2}$
              end:
                description: Period end date (YYYY-MM-DD, inclusive)
                type: string
                pattern: ^\d{4}-\d{2}-\d{2}$
              weight:
                description: Relative spend weight (1.0 = normal, 2.5 = 150% more). Required when mode is "weight".
                type: number
                minimum: 0
                exclusiveMinimum: true
                maximum: 10
              budget:
                description: Absolute budget for this period. Required when mode is "budget".
                type: number
                minimum: 0
                exclusiveMinimum: true
            required:
              - label
              - start
              - end
            additionalProperties: false
      required:
        - mode
        - periods
      additionalProperties: false
    PerformanceConfigOutput:
      description: Configuration for performance campaign optimization
      type: object
      properties:
        optimizationGoals:
          description: Optimization goals for the campaign. Each goal targets either conversion events or seller-native metrics.
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/OptimizationGoalOutput'
      required:
        - optimizationGoals
      additionalProperties: false
    OptimizationGoalOutput:
      description: >-
        A single optimization target. Either kind "event" (conversion events) or kind "metric" (seller-native delivery
        metric).
      oneOf:
        - $ref: '#/components/schemas/EventGoalOutput'
        - $ref: '#/components/schemas/MetricGoalOutput'
      type: object
      discriminator:
        propertyName: kind
        mapping:
          event: '#/components/schemas/EventGoalOutput'
          metric: '#/components/schemas/MetricGoalOutput'
    EventGoalOutput:
      description: Optimize for advertiser-tracked conversion events via event sources.
      type: object
      properties:
        kind:
          type: string
          enum:
            - event
        eventSources:
          description: Event source and type pairs feeding this goal. Seller deduplicates by event_id across entries.
          minItems: 1
          type: array
          items:
            type: object
            properties:
              eventSourceId:
                description: Event source to include (must be configured via sync_event_sources)
                example: website_pixel
                type: string
                minLength: 1
              eventType:
                description: IAB ECAPI event type to optimize for
                type: string
                enum:
                  - page_view
                  - view_content
                  - select_content
                  - select_item
                  - search
                  - share
                  - add_to_cart
                  - remove_from_cart
                  - viewed_cart
                  - add_to_wishlist
                  - initiate_checkout
                  - add_payment_info
                  - purchase
                  - refund
                  - lead
                  - qualify_lead
                  - close_convert_lead
                  - disqualify_lead
                  - complete_registration
                  - subscribe
                  - start_trial
                  - app_install
                  - app_launch
                  - contact
                  - schedule
                  - donate
                  - submit_application
                  - custom
              customEventName:
                description: Required when eventType is 'custom'. Platform-specific custom event name.
                type: string
              valueField:
                description: Field on custom_data carrying the monetary value. Required when target is 'per_ad_spend'.
                example: value
                type: string
              valueFactor:
                description: Multiplier for valueField (default 1). Use -1 for refunds, 0.01 for cents.
                example: 1
                type: number
            required:
              - eventSourceId
              - eventType
            additionalProperties: false
        target:
          description: Target cost or return. When omitted, the seller maximizes conversions within budget.
          oneOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - cost_per
                value:
                  description: Target cost per unit in buy currency
                  example: 25
                  type: number
                  minimum: 0
                  exclusiveMinimum: true
              required:
                - kind
                - value
              additionalProperties: false
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - per_ad_spend
                value:
                  description: Target return ratio (e.g. 4.0 = $4 of value per $1 spent)
                  example: 4
                  type: number
                  minimum: 0
                  exclusiveMinimum: true
              required:
                - kind
                - value
              additionalProperties: false
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - maximize_value
              required:
                - kind
              additionalProperties: false
          type: object
        attributionWindow:
          description: Attribution window for this goal. When omitted, the seller uses their default.
          allOf:
            - $ref: '#/components/schemas/OptimizationAttributionWindowOutput'
        priority:
          description: Priority among goals on this package. 1 = highest. When omitted, sellers use array position.
          example: 1
          type: integer
          minimum: 1
          maximum: 9007199254740991
      required:
        - kind
        - eventSources
      additionalProperties: false
    OptimizationAttributionWindowOutput:
      description: Attribution window for conversion optimization
      type: object
      properties:
        postClick:
          description: Click-through attribution window
          example:
            interval: 7
            unit: days
          allOf:
            - $ref: '#/components/schemas/DurationOutput'
        postView:
          description: View-through attribution window
          example:
            interval: 1
            unit: days
          allOf:
            - $ref: '#/components/schemas/DurationOutput'
      required:
        - postClick
      additionalProperties: false
    DurationOutput:
      description: A duration expressed as an interval and unit
      type: object
      properties:
        interval:
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
        unit:
          type: string
          enum:
            - minutes
            - hours
            - days
            - campaign
      required:
        - interval
        - unit
      additionalProperties: false
    MetricGoalOutput:
      description: Optimize for a seller-tracked delivery metric. No event source required.
      type: object
      properties:
        kind:
          type: string
          enum:
            - metric
        metric:
          description: >-
            Seller-native metric to optimize for. Delivery metrics: clicks, views (viewable impressions, per AdCP),
            completed_views (video/audio completions, qualified by viewDurationSeconds). Duration/score: viewed_seconds,
            attention_seconds, attention_score. Audience action: engagements, follows, saves, profile_visits. To target
            a viewability rate, use metric: 'views' with a threshold_rate target (proportion of impressions).
          type: string
          enum:
            - clicks
            - views
            - completed_views
            - viewed_seconds
            - attention_seconds
            - attention_score
            - engagements
            - follows
            - saves
            - profile_visits
        viewDurationSeconds:
          description: Minimum video view duration in seconds for completed_view. Only applicable when metric is 'completed_views'.
          type: number
          minimum: 0
          exclusiveMinimum: true
        target:
          description: Target for this metric. When omitted, the seller maximizes metric volume within budget.
          oneOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - cost_per
                value:
                  description: Target cost per unit in buy currency
                  example: 25
                  type: number
                  minimum: 0
                  exclusiveMinimum: true
              required:
                - kind
                - value
              additionalProperties: false
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - threshold_rate
                value:
                  description: >-
                    Minimum per-impression value. Units depend on metric: proportion (clicks, views), seconds
                    (viewed_seconds, attention_seconds), or score (attention_score).
                  example: 0.001
                  type: number
                  minimum: 0
                  exclusiveMinimum: true
              required:
                - kind
                - value
              additionalProperties: false
          type: object
        priority:
          description: Priority among goals on this package. 1 = highest. When omitted, sellers use array position.
          example: 2
          type: integer
          minimum: 1
          maximum: 9007199254740991
      required:
        - kind
        - metric
      additionalProperties: false
    DeliveryConfigOutput:
      description: >-
        Per-Output destination shape (non-secret). v1 supports GCS only; additional destination types are added as new
        variants in this discriminated union.
      oneOf:
        - $ref: '#/components/schemas/GcsDeliveryConfigOutput'
      type: object
      discriminator:
        propertyName: type
        mapping:
          GCS: '#/components/schemas/GcsDeliveryConfigOutput'
    GcsDeliveryConfigOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - GCS
        bucket:
          description: Target GCS bucket name (no gs:// prefix)
          type: string
          minLength: 1
          maxLength: 222
          pattern: ^[a-z0-9][a-z0-9._-]*[a-z0-9]$
        pathPrefix:
          description: >-
            Object key prefix within the bucket. Leading slashes are stripped. May contain {YYYY}, {MM}, {DD}, {HH},
            {DATA_DELIVERY_TYPE} placeholders.
          default: ''
          type: string
          maxLength: 1024
        format:
          default: JSONL
          type: string
          enum:
            - JSONL
            - PARQUET
            - CSV
      required:
        - type
        - bucket
        - pathPrefix
        - format
      additionalProperties: false
    PropertyListFiltersOutput:
      type: object
      properties:
        channels_any:
          description: Restrict to SmartPropertyLists matching these channels
          example:
            - display
            - olv
          nullable: true
          type: array
          items:
            type: string
            enum:
              - display
              - olv
              - social
              - search
              - ctv
              - linear_tv
              - radio
              - streaming_audio
              - podcast
              - dooh
              - ooh
              - print
              - cinema
              - email
              - gaming
              - retail_media
              - influencer
              - affiliate
              - product_placement
        countries_all:
          description: ISO 3166-1 alpha-2 country codes
          example:
            - US
            - GB
          nullable: true
          type: array
          items:
            type: string
            minLength: 2
            maxLength: 2
        property_types:
          description: Property inventory types
          nullable: true
          type: array
          items:
            type: string
            enum:
              - website
              - mobile_app
              - ctv_app
              - desktop_app
              - dooh
              - podcast
              - radio
              - streaming_audio
        feature_requirements:
          description: Feature-based requirements (e.g. IVT, MFA, green)
          nullable: true
          type: array
          items:
            type: object
            properties:
              feature_id:
                type: string
              min_value:
                nullable: true
                type: number
              max_value:
                nullable: true
                type: number
              allowed_values:
                nullable: true
                type: array
                items: {}
              if_not_covered:
                nullable: true
                type: string
                enum:
                  - exclude
                  - include
            required:
              - feature_id
            additionalProperties: false
      additionalProperties: false
    McpInitializeRequest:
      type: object
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
          description: JSON-RPC version
        id:
          oneOf:
            - type: string
            - type: number
          description: Request ID
        method:
          type: string
          enum:
            - initialize
          description: Method name
        params:
          type: object
          properties:
            protocolVersion:
              type: string
              description: MCP protocol version
              example: '2024-11-05'
            capabilities:
              type: object
              description: Client capabilities
            clientInfo:
              type: object
              properties:
                name:
                  type: string
                  description: Client name
                version:
                  type: string
                  description: Client version
              required:
                - name
                - version
          required:
            - protocolVersion
            - capabilities
            - clientInfo
      required:
        - jsonrpc
        - id
        - method
        - params
    McpInitializeResponse:
      type: object
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
        id:
          oneOf:
            - type: string
            - type: number
        result:
          type: object
          properties:
            protocolVersion:
              type: string
            capabilities:
              type: object
            serverInfo:
              type: object
              properties:
                name:
                  type: string
                version:
                  type: string
    McpApiCallRequest:
      type: object
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
          description: JSON-RPC version
        id:
          oneOf:
            - type: string
            - type: number
          description: Request ID
        method:
          type: string
          enum:
            - tools/call
          description: Method name
        params:
          type: object
          properties:
            name:
              type: string
              enum:
                - api_call
              description: Tool name
            arguments:
              type: object
              properties:
                method:
                  type: string
                  enum:
                    - GET
                    - POST
                    - PUT
                    - DELETE
                  description: HTTP method
                path:
                  type: string
                  description: API path (e.g., "/advertisers")
                body:
                  type: object
                  description: Request body for POST/PUT
                query:
                  type: object
                  description: Query parameters
              required:
                - method
                - path
          required:
            - name
            - arguments
      required:
        - jsonrpc
        - id
        - method
        - params
    McpAskCapabilityRequest:
      type: object
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
          description: JSON-RPC version
        id:
          oneOf:
            - type: string
            - type: number
          description: Request ID
        method:
          type: string
          enum:
            - tools/call
          description: Method name
        params:
          type: object
          properties:
            name:
              type: string
              enum:
                - ask_about_capability
              description: Tool name
            arguments:
              type: object
              properties:
                question:
                  type: string
                  description: Natural language question about API capabilities
              required:
                - question
          required:
            - name
            - arguments
      required:
        - jsonrpc
        - id
        - method
        - params
    McpToolResponse:
      type: object
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
        id:
          oneOf:
            - type: string
            - type: number
        result:
          type: object
          properties:
            content:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - text
                  text:
                    type: string
                    description: Response content
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token
