> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk update creatives

> Preview or apply a bulk update to saved campaign creatives. Defaults to dry_run=true so the buyer can confirm the matched set before applying changes.



## OpenAPI

````yaml /v2/buyer-api-v2.yaml post /campaigns/{campaignId}/creatives/bulk-update
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
security: []
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: Event Sources
    description: >-
      Manage event source configurations and log conversion/marketing events for
      attribution
  - 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:
  /campaigns/{campaignId}/creatives/bulk-update:
    post:
      tags:
        - Creatives
      summary: Bulk update creatives
      description: >-
        Preview or apply a bulk update to saved campaign creatives. Defaults to
        dry_run=true so the buyer can confirm the matched set before applying
        changes.
      operationId: bulkUpdateCreatives
      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/BulkUpdateCreativesBody'
      responses:
        '200':
          description: Bulk update creatives
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpdateCreativesResponse'
        '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'
      security:
        - bearerAuth: []
components:
  schemas:
    BulkUpdateCreativesBody:
      description: >-
        Bulk update saved campaign creatives. Use dry_run first to confirm the
        matched set.
      type: object
      properties:
        selection:
          $ref: '#/components/schemas/BulkUpdateCreativeSelection'
        update:
          type: object
          properties:
            click_url:
              description: Set the canonical click-through URL for every selected creative.
              type: string
              format: uri
            format_id:
              description: >-
                Set the primary format for every selected creative. Use to
                retype creatives to a sales agent's required format id (e.g.
                display_300x250_nongenerative).
              type: object
              properties:
                agent_url:
                  type: string
                id:
                  type: string
                  pattern: ^[a-zA-Z0-9_-]+$
                width:
                  type: number
                  minimum: 1
                height:
                  type: number
                  minimum: 1
                duration_ms:
                  type: number
                  minimum: 1
              required:
                - agent_url
                - id
              additionalProperties: {}
            target_format_ids:
              description: >-
                Set the additional format ids every selected creative covers.
                Replaces the existing list on each creative.
              type: array
              items:
                type: object
                properties:
                  agent_url:
                    type: string
                  id:
                    type: string
                    pattern: ^[a-zA-Z0-9_-]+$
                  width:
                    type: number
                    minimum: 1
                  height:
                    type: number
                    minimum: 1
                  duration_ms:
                    type: number
                    minimum: 1
                required:
                  - agent_url
                  - id
                additionalProperties: {}
        dry_run:
          description: >-
            When true, return the matched creative set without applying changes.
            Defaults to true for human confirmation.
          default: true
          type: boolean
        exclude_creative_ids:
          description: >-
            Creative IDs to remove from the matched set before applying the
            update
          maxItems: 200
          type: array
          items:
            type: string
            minLength: 1
        limit:
          description: Maximum number of creatives to match/update
          default: 200
          type: integer
          minimum: 1
          maximum: 500
        confirm_partial_batch:
          description: >-
            When false, applying a bulk update is rejected if more creatives
            match than the requested limit. Set true only when the buyer
            explicitly confirms a partial batch.
          default: false
          type: boolean
      required:
        - selection
        - update
    BulkUpdateCreativesResponse:
      description: >-
        Bulk creative update preview or execution result suitable for
        confirmation UI.
      type: object
      properties:
        dry_run:
          type: boolean
        matched_count:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        total_matches:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        returned_count:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        truncated:
          type: boolean
        updated_count:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        selection:
          $ref: '#/components/schemas/BulkUpdateCreativeSelectionOutput'
        exclude_creative_ids:
          type: array
          items:
            type: string
        limit:
          type: integer
          maximum: 9007199254740991
          minimum: 1
        updates:
          type: object
          properties:
            click_url:
              description: URL to add as asset (must be http/https)
              type: string
              format: uri
            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:
              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: {}
          additionalProperties: false
        creatives:
          type: array
          items:
            $ref: '#/components/schemas/BulkUpdateCreativeResultItem'
      required:
        - dry_run
        - matched_count
        - total_matches
        - returned_count
        - truncated
        - updated_count
        - selection
        - limit
        - updates
        - creatives
      additionalProperties: false
    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
    BulkUpdateCreativeSelection:
      description: Selectors for a campaign-scoped bulk creative update
      type: object
      properties:
        collection_id:
          description: >-
            Creative collection ID to use as the matched set. Only creative
            members in the collection are included.
          type: string
          minLength: 1
          maxLength: 255
        creative_ids:
          description: Exact creative IDs to include
          minItems: 1
          maxItems: 200
          type: array
          items:
            type: string
            minLength: 1
        name_contains:
          description: Case-insensitive partial creative name match
          type: string
          minLength: 1
          maxLength: 200
        created_after:
          description: Include creatives created at or after this ISO 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))$
        created_before:
          description: Include creatives created at or before this ISO 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_after:
          description: Include creatives updated at or after this ISO 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_before:
          description: Include creatives updated at or before this ISO 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))$
        template_id:
          description: Match creatives using this template ID
          type: string
          minLength: 1
          maxLength: 255
        format_kind:
          description: Match creatives using this canonical format kind
          type: string
          minLength: 1
          maxLength: 255
        asset_type:
          description: Match creatives containing at least one active asset type
          type: string
          enum:
            - IMAGE
            - VIDEO
            - AUDIO
            - HTML
            - JAVASCRIPT
            - CSS
            - TEXT
            - URL
            - VAST
            - FONT
            - LOGO
            - DOCUMENT
    BulkUpdateCreativeSelectionOutput:
      description: Selectors for a campaign-scoped bulk creative update
      type: object
      properties:
        collection_id:
          description: >-
            Creative collection ID to use as the matched set. Only creative
            members in the collection are included.
          type: string
          minLength: 1
          maxLength: 255
        creative_ids:
          description: Exact creative IDs to include
          minItems: 1
          maxItems: 200
          type: array
          items:
            type: string
            minLength: 1
        name_contains:
          description: Case-insensitive partial creative name match
          type: string
          minLength: 1
          maxLength: 200
        created_after:
          description: Include creatives created at or after this ISO 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))$
        created_before:
          description: Include creatives created at or before this ISO 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_after:
          description: Include creatives updated at or after this ISO 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_before:
          description: Include creatives updated at or before this ISO 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))$
        template_id:
          description: Match creatives using this template ID
          type: string
          minLength: 1
          maxLength: 255
        format_kind:
          description: Match creatives using this canonical format kind
          type: string
          minLength: 1
          maxLength: 255
        asset_type:
          description: Match creatives containing at least one active asset type
          type: string
          enum:
            - IMAGE
            - VIDEO
            - AUDIO
            - HTML
            - JAVASCRIPT
            - CSS
            - TEXT
            - URL
            - VAST
            - FONT
            - LOGO
            - DOCUMENT
      additionalProperties: false
    BulkUpdateCreativeResultItem:
      description: A creative selected by a bulk update dry-run or execution result.
      type: object
      properties:
        creative_id:
          description: Creative manifest ID
          type: string
        campaign_id:
          description: Campaign ID (omitted for advertiser-level masters)
          type: string
        name:
          description: Manifest name
          type: string
        format_id:
          description: ADCP format identifier
          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: {}
        format_kind:
          description: AdCP 3.1 canonical format kind (e.g. image_carousel, video_hosted)
          type: string
        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
        requires_upgrade:
          description: >-
            True when this creative has no format_kind and must be upgraded
            before it can be assigned to new media buys. Call POST .../upgrade
            to set format_kind and clear this flag.
          type: boolean
        reuse_count:
          description: >-
            Number of campaigns this creative is actively attached to. A reuse
            signal for the advertiser library (returned on the advertiser-scoped
            list); omitted on single-manifest reads.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        creative_role:
          description: >-
            Advertiser-library role (evergreen or reference). Absent for
            flight-specific creatives that live on their campaign.
          allOf:
            - $ref: '#/components/schemas/CreativeRole'
        creative_source:
          description: >-
            Provenance of the creative (uploaded/generated/connected). Today
            always "uploaded".
          allOf:
            - $ref: '#/components/schemas/CreativeSource'
        platform_links:
          description: >-
            Provider/sales-agent creative identifiers captured from
            sync_creatives for round-trip comparison.
          type: array
          items:
            $ref: '#/components/schemas/CreativeManifestPlatformLink'
        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
        primary_asset_type:
          description: >-
            The dominant media asset type (VIDEO > AUDIO > IMAGE/HTML) — lets
            clients classify a creative by medium even when format_kind is
            absent (e.g. a bare upload). Omitted when the manifest has no media
            asset.
          type: string
          enum:
            - IMAGE
            - VIDEO
            - AUDIO
            - HTML
            - JAVASCRIPT
            - CSS
            - TEXT
            - URL
            - VAST
            - FONT
            - LOGO
            - DOCUMENT
        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
        target_format_ids:
          description: >-
            Additional format IDs this creative covers beyond its primary
            format_id.
          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: {}
        placements:
          description: >-
            Resolved placements this creative maps to (primary + target
            formats), named against the campaign's required placements.
            Populated by the campaign creative-manifest list.
          type: array
          items:
            type: object
            properties:
              placement_id:
                type: string
              placement_name:
                type: string
            required:
              - placement_id
              - placement_name
            additionalProperties: false
        status:
          description: >-
            matched means dry-run only, updated means mutation succeeded, failed
            means this creative was matched but not updated.
          type: string
          enum:
            - matched
            - updated
            - failed
        error:
          description: Failure message when status is failed
          type: string
        warnings:
          description: >-
            Format compatibility warnings emitted when the updated format_id
            does not match any campaign product format.
          type: array
          items:
            type: string
      required:
        - creative_id
        - name
        - created_at
        - updated_at
        - asset_count
        - status
      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
    CreativeRole:
      description: >-
        Advertiser creative-library role: evergreen (serve-ready, reusable
        across campaigns) or reference (a generation input, not served). Absent
        for flight-specific creatives.
      type: string
      enum:
        - evergreen
        - reference
    CreativeSource:
      description: >-
        Origin of the creative: uploaded (bring-your-own), generated (by a
        creative agent), or connected (from a 3p platform).
      type: string
      enum:
        - uploaded
        - generated
        - connected
    CreativeManifestPlatformLink:
      description: >-
        Readback linkage between a campaign creative and the sales
        agent/provider creative created during sync.
      type: object
      properties:
        agent_id:
          description: Stable ADCP sales-agent identifier used for the sync.
          type: string
        agent_name:
          description: Human-readable sales-agent or platform adapter name.
          type: string
        platform_id:
          description: >-
            Provider-assigned creative identifier returned by sync_creatives,
            when available.
          type: string
        status:
          description: Latest sync status reported for this agent.
          type: string
        approval_status:
          description: Latest provider or seller approval status, when available.
          type: string
        synced_at:
          description: Timestamp of the latest completed 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:
        - agent_id
        - agent_name
        - status
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````