openapi: 3.2.0 info: title: Scope3 Buyer Campaigns 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 tags: - name: Campaigns description: Manage advertising campaigns paths: /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 pattern: ^\d+$ 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. Accepts a single value or repeated values; pass "ALL" to include every status. Defaults to the non-terminal statuses (ACTIVE, DRAFT, PAUSED) — every campaign that could still spend. Completed, canceled, and archived campaigns require an explicit status filter (or "ALL"). example: ACTIVE anyOf: - type: array items: $ref: '#/components/schemas/CampaignStatusListFilter' - allOf: - $ref: '#/components/schemas/CampaignStatusListFilter' description: Filter by campaign status. Accepts a single value or repeated values; pass "ALL" to include every status. Defaults to the non-terminal statuses (ACTIVE, DRAFT, PAUSED) — every campaign that could still spend. Completed, canceled, and archived campaigns require an explicit status filter (or "ALL"). - in: query name: mode schema: description: Filter by campaign mode. Accepts a single mode (`?mode=directed`) or repeated values (`?mode=discovery&mode=performance`). example: directed anyOf: - type: array items: $ref: '#/components/schemas/CampaignMode' - allOf: - $ref: '#/components/schemas/CampaignMode' description: Filter by campaign mode. Accepts a single mode (`?mode=directed`) or repeated values (`?mode=discovery&mode=performance`). - in: query name: management schema: description: 'Filter by management state: "tracked" (campaigns the platform did not set up, mirrored from connected seller accounts), "managed" (campaigns authored or adopted through the platform), or "all" (both — the default). The default status lens (non-terminal: ACTIVE, DRAFT, PAUSED) is what keeps mirrored history out of the ambient list; browse tracked scale through the connected-account relationship rollup.' example: managed default: all allOf: - $ref: '#/components/schemas/CampaignManagementFilter' description: 'Filter by management state: "tracked" (campaigns the platform did not set up, mirrored from connected seller accounts), "managed" (campaigns authored or adopted through the platform), or "all" (both — the default). The default status lens (non-terminal: ACTIVE, DRAFT, PAUSED) is what keeps mirrored history out of the ambient list; browse tracked scale through the connected-account relationship rollup.' - 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: fields schema: description: Optional response enrichment fields. Pass geo_metro_names to include display labels for geo_metros from the local label table. example: geo_metro_names anyOf: - type: string - type: array items: type: string description: Optional response enrichment fields. Pass geo_metro_names to include display labels for geo_metros from the local label table. - in: query name: cursor schema: description: Opaque pagination cursor returned by the previous response. When provided, skip is derived from the cursor and any explicit skip param is ignored. example: eyJza2lwIjoxMH0= type: string description: Opaque pagination cursor returned by the previous response. When provided, skip is derived from the cursor and any explicit skip param is ignored. - in: query name: take schema: description: Number of results to return (max 250) example: 50 default: 50 type: integer maximum: 250 minimum: 1 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/CreateCampaignOpenApiBody' 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/UpdateCampaignOpenApiBody' 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: fresh schema: description: When true, bypasses the server-side media-buy query cache for this request. Use after a successful lifecycle write when immediate authoritative local readback is required. example: 'true' anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: When true, bypasses the server-side media-buy query cache for this request. Use after a successful lifecycle write when immediate authoritative local readback is required. - 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: query name: includePropertyLists schema: description: When true, embed a `propertyLists` aggregate showing the include/exclude lists actually applied to this campaign via its media-buy packages. Defaults to false to keep the response small. To fetch the aggregate without the rest of the campaign, use `GET /campaigns/:campaignId/property-lists`. example: 'true' anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: When true, embed a `propertyLists` aggregate showing the include/exclude lists actually applied to this campaign via its media-buy packages. Defaults to false to keep the response small. To fetch the aggregate without the rest of the campaign, use `GET /campaigns/:campaignId/property-lists`. - in: query name: includeProductDetails schema: description: When false, strips `formatOptions` from each product in `mediaBuys[].products[]`. Defaults to true (full product details included). Set to false when the goal is to read `packageId` values or other non-product fields and the full product payload would cause response truncation. example: 'false' anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: When false, strips `formatOptions` from each product in `mediaBuys[].products[]`. Defaults to true (full product details included). Set to false when the goal is to read `packageId` values or other non-product fields and the full product payload would cause response truncation. - in: query name: fields schema: description: Optional response enrichment fields. Pass geo_metro_names to include display labels for geo_metros from the local label table. example: geo_metro_names anyOf: - type: string - type: array items: type: string description: Optional response enrichment fields. Pass geo_metro_names to include display labels for geo_metros from the local label table. - 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}/delivery: get: operationId: getDirectedCampaignDelivery summary: Get campaign delivery (alpha) description: Read live delivery through a tracked campaign's connected seller account or an unambiguous single-storefront platform campaign's persisted provider media-buy identity. The latest totals are persisted; PostHog-gated alpha with no upstream write. tags: - Campaigns security: - bearerAuth: [] parameters: - in: query name: startDate schema: description: Inclusive reporting start. Defaults to the subscription backfill boundary, capped at one year ago. example: '2026-07-10' 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])))$ description: Inclusive reporting start. Defaults to the subscription backfill boundary, capped at one year ago. - in: query name: endDate schema: description: Inclusive reporting end. Defaults to yesterday because same-day platform data may be incomplete. example: '2026-07-10' 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])))$ description: Inclusive reporting end. Defaults to yesterday because same-day platform data may be incomplete. - in: query name: placementBreakdown schema: description: Request canonical AdCP by_placement delivery rows when the product declares placement reporting support. type: string enum: - 'true' - 'false' description: Request canonical AdCP by_placement delivery rows when the product declares placement reporting support. - in: query name: placementLimit schema: description: Maximum placement rows per package. Requires placementBreakdown=true. type: integer maximum: 9007199254740991 minimum: 1 description: Maximum placement rows per package. Requires placementBreakdown=true. - in: query name: placementSortBy schema: description: Metric used to order placement rows before applying placementLimit. type: string enum: - impressions - spend - clicks - conversions - in: path name: campaignId schema: type: string minLength: 1 required: true responses: '200': description: Get campaign delivery (alpha) content: application/json: schema: $ref: '#/components/schemas/DirectedCampaignDeliveryResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: The directed-campaigns alpha is not enabled. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No directed campaign mirror with this id. 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. Cascades to all active media buys and reports the per-media-buy outcome. 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/CampaignCascadeResponse' '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}/reactivate: post: operationId: reactivateCampaign summary: Reactivate campaign description: Reactivate a paused campaign. The campaign must be PAUSED. Cascades to all paused media buys and reports the per-media-buy outcome. 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: Reactivate campaign content: application/json: schema: $ref: '#/components/schemas/CampaignCascadeResponse' '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' /media-buys/{mediaBuyId}: get: operationId: getMediaBuy summary: Get media buy description: 'Get a single media buy with its why-visibility fields: pendingReason (why it is not delivering yet and since when), buyer-safe errorCode with ownership, the sanitized source message, forwardedAt, and the buyerReference support handle. One call answers "why is my buy stuck". Use GET /campaigns/{campaignId} for packages, products, and delivery.' tags: - Campaigns security: - bearerAuth: [] parameters: - in: path name: mediaBuyId schema: description: Buyer media buy ID example: mb_ETBn4gJ9Wu type: string minLength: 1 required: true description: Buyer media buy ID responses: '200': description: Get media buy content: application/json: schema: $ref: '#/components/schemas/BuyerMediaBuyResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Caller is not a buyer — the route is mounted behind the buyer role guard. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No media buy with this id owned by the caller. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: operationId: updateMediaBuy summary: Update media buy description: 'Partially update a single media buy, resolved top-level by mediaBuyId — the owning campaign is resolved server-side, consistent with GET /media-buys/{mediaBuyId}. Rejected outright (not a warning) when it would violate a campaign invariant: currency (a product''s replacement pricing option settles in a different currency than this buy), budget headroom (the update would exceed the campaign''s remaining all-in budget), or mode compatibility (the campaign is directed and has no platform-managed update path). A flight date outside the campaign''s current window is not a failure — the campaign flight is widened to cover it and a warning is returned.' tags: - Campaigns security: - bearerAuth: [] parameters: - in: path name: mediaBuyId schema: description: Buyer media buy ID example: mb_ETBn4gJ9Wu type: string minLength: 1 required: true description: Buyer media buy ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateMediaBuyRequest' responses: '200': description: Update media buy content: application/json: schema: $ref: '#/components/schemas/UpdateMediaBuyResponse' '400': description: 'Validation failed: the campaign is directed, the campaign is completed/archived/cancelled, the update would exceed the campaign''s remaining budget headroom, or a product''s replacement pricing option settles in a different currency than this buy.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Caller is not a buyer — the route is mounted behind the buyer role guard. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No media buy with this id owned by the caller. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: The media buy is in a terminal status and can no longer be updated. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /media-buys/{mediaBuyId}/packages: get: operationId: getMediaBuyPackages summary: List media buy packages description: 'List a media buy''s packages with the attributes that identify each one: productId, productName, the package''s own startTime/endTime, and its pacingPeriod (index plus the campaign''s label, e.g. "Week 6"). Use this to turn a description of a package ("the display package ending 2026-08-11") into the packageId to send to an update. Prefer it over GET /campaigns/{campaignId} whenever the goal is to pick a package: it carries no targeting, creative, or format detail, so it stays small enough for an agent to read in full. A paced buy has one package per product per period, and the trailing number on a package id is dispatch order, NOT the period — read pacingPeriod instead of parsing the id.' tags: - Campaigns security: - bearerAuth: [] parameters: - in: path name: mediaBuyId schema: description: Buyer media buy ID example: mb_ETBn4gJ9Wu type: string minLength: 1 required: true description: Buyer media buy ID responses: '200': description: List media buy packages content: application/json: schema: $ref: '#/components/schemas/BuyerMediaBuyPackagesResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Caller is not a buyer — the route is mounted behind the buyer role guard. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No media buy with this id owned by the caller. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /media-buys/{mediaBuyId}/pause: post: operationId: pauseMediaBuy summary: Pause media buy description: Pause a single active media buy without affecting the rest of its campaign or any sibling media buys. tags: - Campaigns security: - bearerAuth: [] parameters: - in: path name: mediaBuyId schema: description: Buyer media buy ID example: mb_ETBn4gJ9Wu type: string minLength: 1 required: true description: Buyer media buy ID responses: '200': description: Pause media buy content: application/json: schema: $ref: '#/components/schemas/MediaBuyStatusChangeResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No media buy with this id owned by the caller. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: The media buy is not currently ACTIVE. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /media-buys/{mediaBuyId}/reactivate: post: operationId: reactivateMediaBuy summary: Reactivate media buy description: Reactivate a single paused media buy without affecting the rest of its campaign or any sibling media buys. tags: - Campaigns security: - bearerAuth: [] parameters: - in: path name: mediaBuyId schema: description: Buyer media buy ID example: mb_ETBn4gJ9Wu type: string minLength: 1 required: true description: Buyer media buy ID responses: '200': description: Reactivate media buy content: application/json: schema: $ref: '#/components/schemas/MediaBuyStatusChangeResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No media buy with this id owned by the caller. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: The media buy is not currently PAUSED. 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' /targeting/dimensions: get: operationId: listTargetingDimensions summary: List targeting dimensions description: List supported targeting dimensions and the campaign constraint fields that accept them. tags: - Campaigns security: - bearerAuth: [] parameters: - in: query name: locale schema: description: Display-label locale. Currently only en-US is supported. example: en-US default: en-US type: string enum: - en-US description: Display-label locale. Currently only en-US is supported. responses: '200': description: List targeting dimensions content: application/json: schema: $ref: '#/components/schemas/ListTargetingDimensionsResponse' '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' /targeting/dimensions/{system}: get: operationId: listTargetingDimensionValues summary: List targeting dimension values description: List code-name pairs for a targeting dimension. Send only returned codes in campaign constraints. tags: - Campaigns security: - bearerAuth: [] parameters: - in: query name: locale schema: description: Display-label locale. Currently only en-US is supported. example: en-US default: en-US type: string enum: - en-US description: Display-label locale. Currently only en-US is supported. - in: path name: system schema: $ref: '#/components/schemas/TargetingDimensionSystem' required: true description: Supported targeting dimension system responses: '200': description: List targeting dimension values content: application/json: schema: $ref: '#/components/schemas/TargetingDimensionValuesResponse' '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' /targeting/dimensions/{system}/resolve: get: operationId: resolveTargetingDimension summary: Resolve targeting dimension text description: Resolve localized targeting text to code candidates within a specific dimension. Use the top candidate only when the response is not ambiguous. tags: - Campaigns security: - bearerAuth: [] parameters: - in: query name: q schema: description: Localized text to resolve to targeting codes example: LA DMA type: string minLength: 1 required: true description: Localized text to resolve to targeting codes - in: query name: locale schema: description: Display-label locale. Currently only en-US is supported. example: en-US default: en-US type: string enum: - en-US description: Display-label locale. Currently only en-US is supported. - in: path name: system schema: $ref: '#/components/schemas/TargetingDimensionSystem' required: true description: Supported targeting dimension system responses: '200': description: Resolve targeting dimension text content: application/json: schema: $ref: '#/components/schemas/ResolveTargetingDimensionResponse' '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' /targeting/geo-metros: get: operationId: listGeoMetros summary: List geo metros description: List geo metro code-name pairs for buyer-side targeting resolution and display. Send only numeric string codes in campaign constraints.geo_metros; request fields=geo_metro_names on campaign reads when display labels are needed. tags: - Campaigns security: - bearerAuth: [] parameters: - in: query name: system schema: description: Targeting system to look up. Defaults to nielsen_dma; currently only nielsen_dma is supported. example: nielsen_dma default: nielsen_dma allOf: - $ref: '#/components/schemas/TargetingDimensionSystem' description: Targeting system to look up. Defaults to nielsen_dma; currently only nielsen_dma is supported. responses: '200': description: List geo metros content: application/json: schema: $ref: '#/components/schemas/GeoMetrosResponse' '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' components: schemas: StorefrontEndpointDirectedCampaignInfo: description: Provenance and dual-key identity for a direct buy through one storefront AdCP endpoint. type: object properties: provenance: description: This directed campaign was created by an external AdCP buyer addressing one storefront endpoint. type: string enum: - storefront_endpoint storefrontId: description: Storefront DB id that owns execution for this campaign. example: 42 type: integer maximum: 9007199254740991 minimum: 1 buyerMediaBuyId: description: AdCP media-buy id used by the external buyer at the storefront boundary. example: buyer_mb_44521 type: string minLength: 1 mediaBuyId: description: Interchange media-buy id used by the campaign, contract, reporting, and ledger layers. Omitted only for legacy endpoint shells created before this projection was recorded. example: mb_ETBn4gJ9Wu type: string minLength: 1 required: - provenance - storefrontId - buyerMediaBuyId additionalProperties: false ExecuteCampaignBody: description: Optional request body for executing a campaign. Unknown fields are rejected. type: object properties: debug: description: When true, includes detailed debug information in error responses from media buy execution type: boolean additionalProperties: false CreateDiscoveryCampaignBody: description: Request body for creating a discovery-mode campaign type: object properties: advertiserId: description: Advertiser ID that will own this campaign example: 12345 type: integer maximum: 9007199254740991 minimum: 1 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 exclusiveMinimum: 0 currency: description: Optional ISO 4217 currency. If provided it must match the advertiser's primary currency; otherwise the advertiser's currency is used. Campaigns cannot be created in a currency other than the advertiser's. type: string minLength: 3 maxLength: 3 dailyCap: type: number exclusiveMinimum: 0 pacing: type: string enum: - EVEN - ASAP - FRONTLOADED required: - total 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: geo_countries: type: array items: type: string geo_countries_exclude: type: array items: type: string geo_regions: type: array items: type: string geo_regions_exclude: type: array items: type: string geo_metros: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_metros_exclude: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas_exclude: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} language: type: array items: type: string device_platform: type: array items: anyOf: - type: string enum: - ios - type: string enum: - android - type: string enum: - windows - type: string enum: - macos - type: string enum: - linux - type: string enum: - chromeos - type: string enum: - tvos - type: string enum: - tizen - type: string enum: - webos - type: string enum: - fire_os - type: string enum: - roku_os - type: string enum: - unknown device_type: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown device_type_exclude: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown channels: description: Channels to target (e.g., ["ctv", "display"]) type: array items: type: string countries: description: 'Deprecated: use geo_countries. Countries to target (ISO 3166-1 alpha-2 codes). Values are normalized into geo_countries on write.' deprecated: true maxItems: 250 type: array items: type: string pattern: ^[A-Z]{2}$ additionalProperties: {} 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 maximum: 9007199254740991 minimum: 1 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 maximum: 9007199254740991 minimum: 1 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 advertiser-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: $ref: '#/components/schemas/FrequencyCapConfigInput' mode: description: '"I have a brief; find it for me" — platform-managed.' type: string enum: - discovery required: - advertiserId - name - flightDates - budget - mode DeliveryConfigOutput: description: Per-Output destination shape (non-secret). Additional destination types are added as new variants in this discriminated union. oneOf: - $ref: '#/components/schemas/GcsDeliveryConfigOutput' - $ref: '#/components/schemas/S3DeliveryConfigOutput' - $ref: '#/components/schemas/AzureBlobDeliveryConfigOutput' type: object discriminator: propertyName: type mapping: GCS: '#/components/schemas/GcsDeliveryConfigOutput' S3: '#/components/schemas/S3DeliveryConfigOutput' AZURE_BLOB: '#/components/schemas/AzureBlobDeliveryConfigOutput' FrequencyCapWindow: description: Rolling time window over which max_impressions applies (AdCP Duration shape). type: object properties: interval: type: number minimum: 1 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: {} CampaignStatusListFilter: description: Campaign statuses to include in the list, or "ALL" to include every status. Defaults to the non-terminal statuses (ACTIVE, DRAFT, PAUSED) — every campaign that could still spend. type: string enum: - DRAFT - ACTIVE - PAUSED - COMPLETED - CANCELED - ARCHIVED - ALL BuyerMediaBuy: description: A single media buy with its optimization goals and why-visibility annotation (pendingReason, errorCode, forwardedAt, buyerReference). Use get_campaign for packages, products, and delivery. type: object properties: mediaBuyId: description: Buyer media buy ID example: mb_ETBn4gJ9Wu type: string name: description: Media buy name type: string status: description: Interchange media buy status (DRAFT, PENDING_APPROVAL, ACTIVE, PAUSED, COMPLETED, CANCELED, FAILED, REJECTED). example: PENDING_APPROVAL type: string pendingAt: description: Which layer the buy is parked at; only present while status is PENDING_APPROVAL. Use pendingReason for the specific wait. type: string enum: - storefront - salesagent - unknown pendingChange: description: A submitted change that has not yet reached the delivering buy. Every other field on this object describes what is LIVE, so this is the only place a queued change surfaces. Absent when there is nothing pending. allOf: - $ref: '#/components/schemas/MediaBuyPendingChange' pendingReason: description: Why the buy is not delivering yet, rolled up to the most-blocking wait across its legs. An annotation derived from persisted forwarding state — never a status. Absent when the buy is delivering, terminal, or not storefront-routed. allOf: - $ref: '#/components/schemas/MediaBuyPendingReason' pendingSince: description: When the current wait began (ISO 8601). Present when pendingReason is set and the start of the wait is known. 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))$ errorCode: description: Buyer-safe structured error code when forwarding failed or the buy was rejected. Internal platform codes are mapped to this set and never emitted raw. allOf: - $ref: '#/components/schemas/BuyerMediaBuyErrorCode' errorOwner: description: Which party owns fixing the error. Present whenever errorCode is present. allOf: - $ref: '#/components/schemas/MediaBuyErrorOwner' sourceMessage: description: The source's rejection or moderation message, when one was provided — whitespace-collapsed, truncated, and known upstream identifiers removed. type: string forwardedAt: description: When the buy was forwarded to its inventory source(s) (ISO 8601). Absent when it has not been forwarded. 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))$ buyerReference: description: Support reference for this buy (`sf::`). Quote it with the request timestamp when contacting the seller or Scope3 support. example: sf:42:sf_mb_1783031864469_8pbc8mmr type: string startTime: description: 'When this media buy starts: "asap" or an ISO 8601 date-time.' type: string endTime: description: When this media buy ends (ISO 8601). type: string optimizationGoals: description: Optimization goals applied to this media buy and its packages. Absent when no goals are configured. 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 properties: min: type: number minimum: 1 max: type: number minimum: 1 window: type: object properties: interval: type: number minimum: 1 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: - window 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 minimum: 1 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 minLength: 1 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: - follow - type: string enum: - content_view - type: string enum: - watch_milestone - 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 minimum: 1 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 minimum: 1 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: {} model: anyOf: - type: string enum: - last_touch - type: string enum: - first_touch - type: string enum: - linear - type: string enum: - time_decay - type: string enum: - data_driven additionalProperties: {} priority: type: number minimum: 1 required: - kind - event_sources additionalProperties: {} - type: object properties: kind: type: string enum: - vendor_metric vendor: type: object properties: domain: type: string pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: url: type: string pattern: ^https:\/\/ email: type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ languages: type: array items: type: string additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: number minimum: 1 height: type: number minimum: 1 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_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))$ created_time: 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))$ c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} embedded_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))$ required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_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))$ required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: number minimum: 1 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: 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))$ result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} metric_id: type: string 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 minimum: 1 required: - kind - vendor - metric_id 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 UpdateLegacyCampaignBody: 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 exclusiveMinimum: 0 currency: default: USD type: string minLength: 3 maxLength: 3 dailyCap: type: number exclusiveMinimum: 0 pacing: type: string enum: - EVEN - ASAP - FRONTLOADED brief: description: Updated campaign brief type: string maxLength: 5000 constraints: description: Updated targeting constraints type: object properties: geo_countries: type: array items: type: string geo_countries_exclude: type: array items: type: string geo_regions: type: array items: type: string geo_regions_exclude: type: array items: type: string geo_metros: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_metros_exclude: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas_exclude: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} language: type: array items: type: string device_platform: type: array items: anyOf: - type: string enum: - ios - type: string enum: - android - type: string enum: - windows - type: string enum: - macos - type: string enum: - linux - type: string enum: - chromeos - type: string enum: - tvos - type: string enum: - tizen - type: string enum: - webos - type: string enum: - fire_os - type: string enum: - roku_os - type: string enum: - unknown device_type: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown device_type_exclude: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown channels: description: Channels to target (e.g., ["ctv", "display"]) type: array items: type: string countries: description: 'Deprecated: use geo_countries. Countries to target (ISO 3166-1 alpha-2 codes). Values are normalized into geo_countries on write.' deprecated: true maxItems: 250 type: array items: type: string pattern: ^[A-Z]{2}$ additionalProperties: {} 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 maximum: 9007199254740991 minimum: 1 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. Pass null to clear an existing configuration; this is only valid for a campaign currently in performance mode. 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) type: - integer - 'null' maximum: 9007199254740991 minimum: 1 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 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 exclusiveMinimum: 0 pacing: description: Updated pacing strategy type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. type: - number - 'null' startTime: description: Updated flight start date/time for this package (ISO 8601). Must fall within the media buy's date range. 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))$ endTime: description: Updated flight end date/time for this package (ISO 8601). Must fall within the media buy's date range. 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))$ targetingOverlay: description: Governed audience IDs to merge into the existing package targeting overlay. type: object properties: audience_include: type: array items: type: string audience_exclude: type: array items: type: string additionalProperties: false required: - packageId additionalProperties: false pacingPeriods: description: Per-media-buy pacing schedule. When set, replaces the campaign-level pacingPeriods for this specific buy. Use to heavy-up or shape spend on one media buy without affecting others. Pass null to clear an existing per-buy schedule. Bootstrapping a schedule onto an unpaced media buy is only allowed in DRAFT or PENDING_APPROVAL status. See the Pacing Periods guide for the full state matrix and sales-agent capability requirements. allOf: - $ref: '#/components/schemas/PacingPeriods' products: description: 'Product updates — additive (existing products not listed are preserved). Use remove: true to delete a product.' type: array items: type: object properties: productId: description: Product ID type: string minLength: 1 pricingOptionId: type: string budget: type: number exclusiveMinimum: 0 pacing: type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. type: - number - 'null' remove: description: Set to true to remove this product from the media buy type: boolean pageId: description: Platform-specific page identity for ad placements. Required for Meta products when the connected ad account has more than one authorized Facebook Page — pass one of the page IDs listed in the error message. Omit when the account has exactly one authorized page. example: '1147910135081908' type: string minLength: 1 pixelId: description: 'Meta Pixel / Dataset ID for conversion tracking. Required for Meta Sales (OUTCOME_SALES) products — pass the pixel ID listed in the error message. There is no auto-select: every Meta Sales buy must explicitly specify a pixel.' example: '123456789012345' type: string minLength: 1 required: - productId 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: description: 'Optimization goals applied to every package at execution time. Each goal is either `{ kind: "event", event_sources: [{ event_source_id, event_type }], target? }` or `{ kind: "metric", metric, target? }`. Event target kinds: `cost_per` (CPA), `per_ad_spend` (ROAS), `maximize_value`. Metric target kinds: `cost_per`, `threshold_rate`. ALWAYS ask the buyer what they want to optimize for before updating — do not change goals silently. Pass an empty array to clear all 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 properties: min: type: number minimum: 1 max: type: number minimum: 1 window: type: object properties: interval: type: number minimum: 1 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: - window 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 minimum: 1 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 minLength: 1 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: - follow - type: string enum: - content_view - type: string enum: - watch_milestone - 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 minimum: 1 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 minimum: 1 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: {} model: anyOf: - type: string enum: - last_touch - type: string enum: - first_touch - type: string enum: - linear - type: string enum: - time_decay - type: string enum: - data_driven additionalProperties: {} priority: type: number minimum: 1 required: - kind - event_sources additionalProperties: {} - type: object properties: kind: type: string enum: - vendor_metric vendor: type: object properties: domain: type: string pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: url: type: string pattern: ^https:\/\/ email: type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ languages: type: array items: type: string additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: number minimum: 1 height: type: number minimum: 1 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_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))$ created_time: 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))$ c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} embedded_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))$ required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_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))$ required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: number minimum: 1 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: 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))$ result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} metric_id: type: string 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 minimum: 1 required: - kind - vendor - metric_id 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. 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: $ref: '#/components/schemas/FrequencyCapConfigInput' mode: not: {} UpdateCampaignOpenApiBody: anyOf: - $ref: '#/components/schemas/UpdateLegacyCampaignBody' - $ref: '#/components/schemas/UpdateDiscoveryCampaignBody' - $ref: '#/components/schemas/UpdatePerformanceCampaignBody' - $ref: '#/components/schemas/RefreshDirectedCampaignBody' ResolveTargetingDimensionResponse: description: Resolution candidates for localized targeting text within a dimension. type: object properties: system: $ref: '#/components/schemas/TargetingDimensionSystem' locale: description: Locale used for the resolution example: en-US type: string enum: - en-US query: description: Original query text example: LA DMA type: string candidates: description: Candidate targeting codes ordered by descending confidence. Empty when no dictionary entry matches. type: array items: $ref: '#/components/schemas/TargetingDimensionResolveCandidate' ambiguous: description: True when the top candidates are close enough that the caller should ask for clarification. example: false type: boolean required: - system - locale - query - candidates - ambiguous additionalProperties: false CampaignCascadeResponse: description: Campaign cascade operation outcome, including the status change result for each media buy type: object properties: campaignId: description: Campaign ID example: cmp_987654321 type: string campaignName: description: Campaign name type: string previousStatus: description: Previous campaign status type: string enum: - DRAFT - ACTIVE - PAUSED - COMPLETED - CANCELED - ARCHIVED newStatus: description: New campaign status type: string enum: - DRAFT - ACTIVE - PAUSED - COMPLETED - CANCELED - ARCHIVED mediaBuyResults: description: Per-media-buy cascade outcomes type: array items: $ref: '#/components/schemas/MediaBuyCascadeResult' totalMediaBuys: description: Total number of media buys the cascade attempted type: integer minimum: -9007199254740991 maximum: 9007199254740991 successCount: description: Number of media buys updated successfully type: integer minimum: -9007199254740991 maximum: 9007199254740991 failureCount: description: Number of media buys that failed to update type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - campaignId - campaignName - previousStatus - newStatus - mediaBuyResults - totalMediaBuys - successCount - failureCount additionalProperties: false MediaBuyStatusChangeResponse: description: Response from pausing or reactivating a single media buy. Only this media buy is affected — its campaign is never cascaded. type: object properties: mediaBuyId: description: The media buy ID type: string name: description: The media buy name type: string previousStatus: description: Status of the media buy before the status change type: string newStatus: description: Status of the media buy after the status change type: string success: description: Whether the media buy status change succeeded type: boolean error: description: Error message when the media buy status change failed type: string required: - mediaBuyId - name - previousStatus - newStatus - success additionalProperties: false FrequencyCapConfigInput: description: Frequency cap entry supplied inside a parent advertiser/campaign/creative request body. On PUT, the full array replaces all existing caps for that target. type: object properties: max_impressions: description: Maximum number of impressions allowed within the window example: 3 type: integer maximum: 9007199254740991 minimum: 1 window: $ref: '#/components/schemas/FrequencyCapWindow' required: - max_impressions - window additionalProperties: {} 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 - CANCELED - ARCHIVED mode: description: 'Who is steering this campaign — discovery, performance, or directed. Backfilled by projection for existing campaigns (see deriveCampaignMode); no data movement. The "directed" value is deprecated: read `management` instead.' allOf: - $ref: '#/components/schemas/CampaignMode' management: description: 'Whether the platform acts on this campaign: "tracked" (a campaign the platform did not set up, mirrored read-only from a connected seller account) or "managed" (authored or adopted through the platform).' allOf: - $ref: '#/components/schemas/CampaignManagement' directed: description: Subscription-backed directed mirror state — connection, upstream account, dual-keyed ids, and sync health. Not present on inbound single-storefront AdCP campaigns. allOf: - $ref: '#/components/schemas/DirectedCampaignInfo' 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' 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 exclusiveMinimum: 0 currency: default: USD type: string minLength: 3 maxLength: 3 dailyCap: type: number exclusiveMinimum: 0 pacing: type: string enum: - EVEN - ASAP - FRONTLOADED required: - total - currency additionalProperties: false 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 the media portion of budget.total (after the Scope3 fee) minus 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: geo_countries: type: array items: type: string geo_countries_exclude: type: array items: type: string geo_regions: type: array items: type: string geo_regions_exclude: type: array items: type: string geo_metros: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_metros_exclude: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas_exclude: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} language: type: array items: type: string device_platform: type: array items: anyOf: - type: string enum: - ios - type: string enum: - android - type: string enum: - windows - type: string enum: - macos - type: string enum: - linux - type: string enum: - chromeos - type: string enum: - tvos - type: string enum: - tizen - type: string enum: - webos - type: string enum: - fire_os - type: string enum: - roku_os - type: string enum: - unknown device_type: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown device_type_exclude: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown channels: description: Channels to target (e.g., ["ctv", "display"]) type: array items: type: string countries: description: 'Deprecated: use geo_countries. Countries to target (ISO 3166-1 alpha-2 codes). Values are normalized into geo_countries on write.' deprecated: true maxItems: 250 type: array items: type: string pattern: ^[A-Z]{2}$ geo_metro_names: description: Display labels for included geo_metros codes. Only present when requested with fields=geo_metro_names. allOf: - $ref: '#/components/schemas/CampaignGeoMetroNames' geo_metro_names_exclude: description: Display labels for excluded geo_metros_exclude codes. Only present when requested with fields=geo_metro_names. allOf: - $ref: '#/components/schemas/CampaignGeoMetroNames' additionalProperties: {} 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 maximum: 9007199254740991 minimum: 1 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 type: - string - 'null' 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: Canonical creative format coverage for this campaign — URL-free format kinds required by selected products, covered by uploaded creatives, and still missing. Surface `missing` to prompt the user to upload the remaining creatives. type: object properties: required: type: array items: type: object properties: format_kind: type: string required: - format_kind additionalProperties: false covered: type: array items: type: object properties: format_kind: type: string required: - format_kind additionalProperties: false missing: type: array items: type: object properties: format_kind: type: string required: - format_kind additionalProperties: false required: - required - covered - missing additionalProperties: false propertyLists: description: Include/exclude property lists actually applied to this campaign via its media-buy packages. Only present when `includePropertyLists=true` is passed. An empty `propertyLists` array is the authoritative answer that no lists are applied; do not infer presence from the campaign brief or constraints. type: object properties: propertyLists: type: array items: type: object properties: listId: type: string name: type: string purpose: type: string enum: - include - exclude propertyCount: type: integer minimum: 0 maximum: 9007199254740991 createdAt: type: string updatedAt: type: string viaMediaBuys: type: array items: type: object properties: mediaBuyId: type: string packageIds: type: array items: type: string required: - mediaBuyId - packageIds additionalProperties: false required: - listId - name - purpose - propertyCount - createdAt - updatedAt - viaMediaBuys additionalProperties: false summary: type: object properties: totalLists: type: integer minimum: 0 maximum: 9007199254740991 includeCount: type: integer minimum: 0 maximum: 9007199254740991 excludeCount: type: integer minimum: 0 maximum: 9007199254740991 required: - totalLists - includeCount - excludeCount additionalProperties: false required: - propertyLists - summary 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 revision: description: Last authoritative provider revision observed for this media buy. type: integer minimum: 0 maximum: 9007199254740991 validActions: description: Provider-reported AdCP actions that are currently valid for this media buy. type: array items: type: string pendingAt: description: Which layer the media buy is parked at; only present while status is PENDING_APPROVAL. 'storefront' = waiting for the storefront operator's manual approval, 'salesagent' = the inventory source is still processing the buy, 'unknown' = the pending layer is indeterminate. type: string enum: - storefront - salesagent - unknown pendingReason: description: Why the buy is not delivering yet, rolled up to the most-blocking wait across its legs. An annotation derived from persisted forwarding state — never a status. Absent when the buy is delivering, terminal, or not storefront-routed. allOf: - $ref: '#/components/schemas/MediaBuyPendingReason' pendingSince: description: When the current wait began (ISO 8601). Present when pendingReason is set and the start of the wait is known. 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))$ errorCode: description: Buyer-safe structured error code when forwarding failed or the buy was rejected. Internal platform codes are mapped to this set and never emitted raw. allOf: - $ref: '#/components/schemas/BuyerMediaBuyErrorCode' errorOwner: description: Which party owns fixing the error. Present whenever errorCode is present. allOf: - $ref: '#/components/schemas/MediaBuyErrorOwner' sourceMessage: description: The source's rejection or moderation message, when one was provided — whitespace-collapsed, truncated, and known upstream identifiers removed. type: string forwardedAt: description: When the buy was forwarded to its inventory source(s) (ISO 8601). Absent when it has not been forwarded. 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))$ buyerReference: description: Support reference for this buy (`sf::`). Quote it with the request timestamp when contacting the seller or Scope3 support. example: sf:42:sf_mb_1783031864469_8pbc8mmr 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 budget_denomination: description: 'Denomination marker: every budget on this media buy is GROSS (fee-inclusive) in the buyer currency. Present only for buys with locked fee terms (it travels with budget_breakdown); absent for legacy buys created before fee terms were locked, whose budgets pass through as stored.' type: string enum: - gross budget_breakdown: description: Read-only gross/media/fee split of the buy's total budget at the fee terms locked when the media buy was created. Omitted for legacy buys created before fee terms were locked. Buyer surfaces only. type: object properties: media_budget: description: Media portion of the gross budget (gross minus the buyer fee) at the fee terms locked when the media buy was created, in major units. type: number fee_amount: description: Buyer fee carved from the gross budget at the locked fee rate, in major units. type: number fee_rate_percent: description: The Scope3 fee as a percentage of the media budget (fee ÷ media × 100). For example, a 5% fee on media produces a value of 5 here regardless of how the fee was stored internally. type: number effective_gross_cpm: description: Gross budget ÷ impression goal × 1000 — the CPM that makes "budget ÷ CPM = impressions" hold for the gross numbers the buyer operates on. Null when the buy has no positive impression goal. type: - number - 'null' required: - media_budget - fee_amount - fee_rate_percent - effective_gross_cpm additionalProperties: false products: description: Products configured for this media buy type: array items: type: object properties: productId: description: Product identifier type: string productName: description: Human-readable product name. May be absent for products whose `products` cache row has not yet been populated. type: string publisherName: description: Publisher name for this product. May be absent for products whose `products` cache row has not yet been populated. 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 formatOptions: description: Publisher-declared format requirements for this product. Each entry has a stable format_option_id selector when supplied by the seller, a format_kind (e.g. "video_vast", "video_hosted", "image", "html5"), and a params object. For video products, check entries with format_kind "video_vast" or "video_hosted" for params.duration_ms_exact (required duration in ms), params.width and params.height (required pixel dimensions). type: array items: type: object properties: format_kind: type: string enum: - image - html5 - display_tag - image_carousel - video_hosted - video_vast - audio_hosted - audio_daast - sponsored_placement - native_in_feed - responsive_creative - agent_placement - custom params: type: object properties: width: type: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 sizes: minItems: 1 type: array items: type: object properties: width: type: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 required: - width - height additionalProperties: false min_width: type: integer minimum: 1 maximum: 9007199254740991 max_width: type: integer minimum: 1 maximum: 9007199254740991 min_height: type: integer minimum: 1 maximum: 9007199254740991 max_height: type: integer minimum: 1 maximum: 9007199254740991 duration_ms_exact: type: integer minimum: 1 maximum: 9007199254740991 duration_ms_range: type: array items: type: - number - 'null' additionalProperties: {} format_option_id: type: string minLength: 1 required: - format_kind - params additionalProperties: false required: - productId additionalProperties: false pacingPeriods: description: Per-media-buy pacing schedule. When set, this buy is shaped by its own schedule rather than the campaign-level pacingPeriods. Each period includes a resolved budget; in weight mode, weights are preserved alongside the resolved budget. allOf: - $ref: '#/components/schemas/PacingPeriodsOutput' 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 startTime: description: Flight start date/time for this package (ISO 8601), if set. type: string endTime: description: Flight end date/time for this package (ISO 8601), if set. type: string targetingOverlay: allOf: - $ref: '#/components/schemas/CampaignPackageTargetingOverlay' providerTargeting: allOf: - $ref: '#/components/schemas/ProviderTargetingReadback' providerPlacementControls: type: object properties: placement_soft_opt_out: type: object properties: {} additionalProperties: false required: - placement_soft_opt_out additionalProperties: false requestedTargeting: description: Canonical targeting requested when Scope3 created this adapter package. allOf: - $ref: '#/components/schemas/ProviderTargetingReadback' targetingMatchesRequest: description: Whether the current provider-normalized targeting still equals the canonical request. type: boolean geoRegionMappings: description: ISO subdivision to provider-region identity evidence. type: array items: type: object properties: iso_code: type: string provider_key: type: string required: - iso_code - provider_key additionalProperties: false 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: Delivered spend in the buyer's GROSS (fee-inclusive) denomination, grossed up at the buy's pinned pricing terms. Net-as-reported for legacy buys with no pinned terms. type: number clicks: description: Click count type: - number - 'null' required: - impressions - spend - clicks additionalProperties: false creatives: description: Creatives assigned to this package type: array items: type: object properties: creativeId: description: Creative manifest ID type: string name: description: Creative display name type: string formatId: description: Format ID for this creative type: object properties: id: description: Format identifier (e.g. display_300x250) type: string agent_url: description: ADCP agent URL this format belongs to type: string required: - id - agent_url additionalProperties: {} status: description: Creative status type: string sourceSyncStatus: description: Per-source creative sync verdicts. Empty array when the creative has not yet been synced to any source. type: array items: type: object properties: agentId: description: Legacy internal ADCP agent database ID, preserved for compatibility type: string sourceId: description: Public ADCP agent or inventory source ID captured for this creative sync route. A legacy-agent value is the protocol-level agent ID, never the numeric database ID; null means retained history predates a captured public source identity type: - string - 'null' approvalStatus: description: Approval status returned by the source for this creative type: - string - 'null' rejectionReason: description: Rejection reason returned by the source, if any type: - string - 'null' required: - agentId - sourceId - approvalStatus - rejectionReason additionalProperties: false storefrontReviewStatus: description: Storefront operator review status for this creative. Null when the storefront uses automatic approval or the creative has not been submitted for review. allOf: - $ref: '#/components/schemas/CreativeReviewStatus' required: - creativeId - name - formatId - status - sourceSyncStatus - storefrontReviewStatus additionalProperties: false required: - packageId - status - productIds additionalProperties: false optimizationGoals: description: 'Optimization goals applied to every package at execution time. Each goal is either `{ kind: "event", event_sources: [{ event_source_id, event_type }], target? }` or `{ kind: "metric", metric, target? }`. Event target kinds: `cost_per` (CPA), `per_ad_spend` (ROAS), `maximize_value`. Metric target kinds: `cost_per`, `threshold_rate`.' 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 properties: min: type: number minimum: 1 max: type: number minimum: 1 window: type: object properties: interval: type: number minimum: 1 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: - window 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 minimum: 1 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 minLength: 1 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: - follow - type: string enum: - content_view - type: string enum: - watch_milestone - 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 minimum: 1 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 minimum: 1 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: {} model: anyOf: - type: string enum: - last_touch - type: string enum: - first_touch - type: string enum: - linear - type: string enum: - time_decay - type: string enum: - data_driven additionalProperties: {} priority: type: number minimum: 1 required: - kind - event_sources additionalProperties: {} - type: object properties: kind: type: string enum: - vendor_metric vendor: type: object properties: domain: type: string pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: url: type: string pattern: ^https:\/\/ email: type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ languages: type: array items: type: string additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: number minimum: 1 height: type: number minimum: 1 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_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))$ created_time: 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))$ c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} embedded_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))$ required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_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))$ required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: number minimum: 1 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: 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))$ result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} metric_id: type: string 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 minimum: 1 required: - kind - vendor - metric_id additionalProperties: {} performance: description: Latest aggregate delivery snapshot for this media buy. windowStart/windowEnd identify the exact inclusive reporting period represented by the totals. type: object properties: impressions: description: Total impressions delivered type: number spend: description: Total delivered spend in the buyer's GROSS (fee-inclusive) denomination, grossed up at the buy's pinned pricing terms. Net-as-reported for legacy buys with no pinned terms. type: number clicks: description: Total clicks type: number views: description: Total views (engagement-qualified) type: number completedViews: description: Total completed views (video / audio completions) type: number conversions: description: Total attributed conversions type: number leads: description: Total leads type: number lastUpdated: description: When this snapshot was last refreshed (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))$ windowStart: description: Inclusive start date represented by this aggregate snapshot. 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])))$ windowEnd: description: Inclusive end date represented by this aggregate snapshot. 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: - impressions - spend - clicks - views - completedViews - conversions - leads additionalProperties: false creatives: description: Creatives assigned to this media buy. Each entry includes source sync status across all sales agents. type: array items: type: object properties: creativeId: description: Creative manifest ID type: string name: description: Creative display name type: string formatId: description: Format ID for this creative type: object properties: id: description: Format identifier (e.g. display_300x250) type: string agent_url: description: ADCP agent URL this format belongs to type: string required: - id - agent_url additionalProperties: {} status: description: Creative status type: string sourceSyncStatus: description: Per-source creative sync verdicts. Empty array when the creative has not yet been synced to any source. type: array items: type: object properties: agentId: description: Legacy internal ADCP agent database ID, preserved for compatibility type: string sourceId: description: Public ADCP agent or inventory source ID captured for this creative sync route. A legacy-agent value is the protocol-level agent ID, never the numeric database ID; null means retained history predates a captured public source identity type: - string - 'null' approvalStatus: description: Approval status returned by the source for this creative type: - string - 'null' rejectionReason: description: Rejection reason returned by the source, if any type: - string - 'null' required: - agentId - sourceId - approvalStatus - rejectionReason additionalProperties: false storefrontReviewStatus: description: Storefront operator review status for this creative. Null when the storefront uses automatic approval or the creative has not been submitted for review. allOf: - $ref: '#/components/schemas/CreativeReviewStatus' required: - creativeId - name - formatId - status - sourceSyncStatus - storefrontReviewStatus additionalProperties: false 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))$ revision: description: Monotonically increasing revision counter. Incremented on every mutation. Pass as expectedRevision in save_campaign to enable optimistic concurrency. example: 1 default: 1 type: integer minimum: 1 maximum: 9007199254740991 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: $ref: '#/components/schemas/FrequencyCapConfig' required: - campaignId - advertiserId - name - status - mode - management - optimizationApplyMode - createdAt - updatedAt - revision additionalProperties: false ErrorResponse: description: Standard error response type: object properties: data: type: - string - 'null' enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false 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, 0 = skip this period). Required when mode is "weight". type: number minimum: 0 maximum: 10 budget: description: Absolute budget for this period (0 = skip this period). Required when mode is "budget". type: number minimum: 0 required: - label - start - end required: - mode - periods 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 - follow - content_view - watch_milestone - 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 exclusiveMinimum: 0 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 exclusiveMinimum: 0 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 UpdateMediaBuyRequest: description: 'Partial update for a single media buy, resolved top-level by mediaBuyId. Rejected outright (not warned) when it would violate a campaign invariant: currency (a product''s replacement pricing option settles in a different currency), budget headroom (the update would exceed the campaign''s remaining all-in budget), or mode compatibility (the campaign is directed — its mirrored media buy has no platform-managed update path).' type: object properties: name: description: Updated media buy name type: string minLength: 1 maxLength: 255 packages: description: Per-package updates (for media buys with deployed packages) type: array items: $ref: '#/components/schemas/UpdateMediaBuyPackageInput' products: description: Product updates — additive (existing products not listed are preserved). type: array items: $ref: '#/components/schemas/UpdateMediaBuyProductInput' start_time: description: '"asap" or ISO 8601 date-time. A value earlier than the campaign''s current flight start does not fail the request — it is applied and surfaced as a warning, and the campaign flight is widened to cover it.' type: string end_time: description: ISO 8601 date-time. A value later than the campaign's current flight end does not fail the request — it is applied and surfaced as a warning, and the campaign flight is widened to cover it. type: string optimization_goals: description: Replace media-buy-level optimization goals; applied to every package at execution time. Pass an empty array to clear all 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 properties: min: type: number minimum: 1 max: type: number minimum: 1 window: type: object properties: interval: type: number minimum: 1 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: - window 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 minimum: 1 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 minLength: 1 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: - follow - type: string enum: - content_view - type: string enum: - watch_milestone - 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 minimum: 1 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 minimum: 1 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: {} model: anyOf: - type: string enum: - last_touch - type: string enum: - first_touch - type: string enum: - linear - type: string enum: - time_decay - type: string enum: - data_driven additionalProperties: {} priority: type: number minimum: 1 required: - kind - event_sources additionalProperties: {} - type: object properties: kind: type: string enum: - vendor_metric vendor: type: object properties: domain: type: string pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: url: type: string pattern: ^https:\/\/ email: type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ languages: type: array items: type: string additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: number minimum: 1 height: type: number minimum: 1 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_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))$ created_time: 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))$ c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} embedded_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))$ required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_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))$ required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: number minimum: 1 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: 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))$ result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} metric_id: type: string 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 minimum: 1 required: - kind - vendor - metric_id additionalProperties: {} creative_ids: description: Explicit creative IDs to attach to this media buy. Pass an empty array to clear all creatives. type: array items: type: string minLength: 1 updated_reason: description: Reason for the update (stored with the new version) type: string maxLength: 1000 additionalProperties: false 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' DeliveryConfig: description: Per-Output destination shape (non-secret). Additional destination types are added as new variants in this discriminated union. oneOf: - $ref: '#/components/schemas/GcsDeliveryConfig' - $ref: '#/components/schemas/S3DeliveryConfig' - $ref: '#/components/schemas/AzureBlobDeliveryConfig' type: object discriminator: propertyName: type mapping: GCS: '#/components/schemas/GcsDeliveryConfig' S3: '#/components/schemas/S3DeliveryConfig' AZURE_BLOB: '#/components/schemas/AzureBlobDeliveryConfig' CampaignPackageTargetingOverlay: description: Targeting carried on a campaign package; directed adapters populate provider-normalized readback when supported. type: object properties: geo_countries: type: array items: type: string geo_countries_exclude: type: array items: type: string geo_regions: type: array items: type: string geo_regions_exclude: type: array items: type: string geo_metros: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_metros_exclude: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas_exclude: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} daypart_targets: type: array items: type: object properties: days: type: array items: anyOf: - type: string enum: - monday - type: string enum: - tuesday - type: string enum: - wednesday - type: string enum: - thursday - type: string enum: - friday - type: string enum: - saturday - type: string enum: - sunday start_hour: type: number minimum: 0 maximum: 23 end_hour: type: number minimum: 1 maximum: 24 label: type: string required: - days - start_hour - end_hour additionalProperties: {} axe_include_segment: type: string axe_exclude_segment: type: string audience_include: type: array items: type: string audience_exclude: type: array items: type: string signal_targeting_groups: type: object properties: operator: type: string enum: - all groups: type: array items: type: object properties: operator: anyOf: - type: string enum: - any - type: string enum: - none signals: type: array items: type: object properties: pricing_option_id: type: string signal_agent_segment_id: type: string activation_key: anyOf: - type: object properties: type: type: string enum: - segment_id segment_id: type: string required: - type - segment_id additionalProperties: {} - type: object properties: type: type: string enum: - key_value key: type: string value: type: string required: - type - key - value additionalProperties: {} additionalProperties: {} required: - operator - signals additionalProperties: {} required: - operator - groups additionalProperties: {} signal_targeting: type: array items: anyOf: - type: object properties: signal_ref: anyOf: - type: object properties: scope: type: string enum: - product signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - data_provider data_provider_domain: type: string pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - data_provider_domain - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - signal_source signal_source_url: type: string signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_source_url - signal_id additionalProperties: {} signal_id: anyOf: - type: object properties: source: type: string enum: - catalog data_provider_domain: type: string pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - data_provider_domain - id additionalProperties: {} - type: object properties: source: type: string enum: - agent agent_url: type: string id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - agent_url - id additionalProperties: {} value_type: type: string enum: - binary value: type: boolean required: - value_type - value additionalProperties: {} - type: object properties: signal_ref: anyOf: - type: object properties: scope: type: string enum: - product signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - data_provider data_provider_domain: type: string pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - data_provider_domain - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - signal_source signal_source_url: type: string signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_source_url - signal_id additionalProperties: {} signal_id: anyOf: - type: object properties: source: type: string enum: - catalog data_provider_domain: type: string pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - data_provider_domain - id additionalProperties: {} - type: object properties: source: type: string enum: - agent agent_url: type: string id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - agent_url - id additionalProperties: {} value_type: type: string enum: - categorical values: type: array items: type: string required: - value_type - values additionalProperties: {} - type: object properties: signal_ref: anyOf: - type: object properties: scope: type: string enum: - product signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - data_provider data_provider_domain: type: string pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - data_provider_domain - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - signal_source signal_source_url: type: string signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_source_url - signal_id additionalProperties: {} signal_id: anyOf: - type: object properties: source: type: string enum: - catalog data_provider_domain: type: string pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - data_provider_domain - id additionalProperties: {} - type: object properties: source: type: string enum: - agent agent_url: type: string id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - agent_url - id additionalProperties: {} value_type: type: string enum: - numeric min_value: type: number max_value: type: number required: - value_type additionalProperties: {} frequency_cap: type: object properties: suppress: type: object properties: interval: type: number minimum: 1 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: {} suppress_minutes: type: number minimum: 0 max_impressions: type: number minimum: 1 per: 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 window: type: object properties: interval: type: number minimum: 1 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: {} additionalProperties: {} property_list: type: object properties: agent_url: type: string list_id: type: string minLength: 1 auth_token: type: string required: - agent_url - list_id additionalProperties: {} collection_list: type: object properties: agent_url: type: string list_id: type: string minLength: 1 auth_token: type: string required: - agent_url - list_id additionalProperties: {} collection_list_exclude: type: object properties: agent_url: type: string list_id: type: string minLength: 1 auth_token: type: string required: - agent_url - list_id additionalProperties: {} age_restriction: type: object properties: min: type: number minimum: 13 maximum: 99 verification_required: type: boolean accepted_methods: type: array items: anyOf: - type: string enum: - facial_age_estimation - type: string enum: - id_document - type: string enum: - digital_id - type: string enum: - credit_card - type: string enum: - world_id required: - min additionalProperties: {} device_platform: type: array items: anyOf: - type: string enum: - ios - type: string enum: - android - type: string enum: - windows - type: string enum: - macos - type: string enum: - linux - type: string enum: - chromeos - type: string enum: - tvos - type: string enum: - tizen - type: string enum: - webos - type: string enum: - fire_os - type: string enum: - roku_os - type: string enum: - unknown device_type: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown device_type_exclude: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown store_catchments: type: array items: type: object properties: catalog_id: type: string store_ids: type: array items: type: string catchment_ids: type: array items: type: string required: - catalog_id additionalProperties: {} geo_proximity: type: array items: anyOf: - type: object properties: lat: type: number minimum: -90 maximum: 90 lng: type: number minimum: -180 maximum: 180 label: type: string travel_time: type: object properties: value: type: number minimum: 1 unit: anyOf: - type: string enum: - min - type: string enum: - hr required: - value - unit additionalProperties: {} transport_mode: anyOf: - type: string enum: - walking - type: string enum: - cycling - type: string enum: - driving - type: string enum: - public_transport ext: type: object properties: {} additionalProperties: {} required: - lat - lng - travel_time - transport_mode additionalProperties: {} - type: object properties: lat: type: number minimum: -90 maximum: 90 lng: type: number minimum: -180 maximum: 180 label: type: string transport_mode: anyOf: - type: string enum: - walking - type: string enum: - cycling - type: string enum: - driving - type: string enum: - public_transport radius: type: object properties: value: type: number unit: anyOf: - type: string enum: - km - type: string enum: - mi - type: string enum: - m required: - value - unit additionalProperties: {} ext: type: object properties: {} additionalProperties: {} required: - lat - lng - radius additionalProperties: {} - type: object properties: lat: type: number minimum: -90 maximum: 90 lng: type: number minimum: -180 maximum: 180 label: type: string transport_mode: anyOf: - type: string enum: - walking - type: string enum: - cycling - type: string enum: - driving - type: string enum: - public_transport geometry: type: object properties: type: anyOf: - type: string enum: - Polygon - type: string enum: - MultiPolygon coordinates: type: array items: {} required: - type - coordinates additionalProperties: {} ext: type: object properties: {} additionalProperties: {} required: - geometry additionalProperties: {} language: type: array items: type: string keyword_targets: type: array items: type: object properties: keyword: type: string minLength: 1 match_type: anyOf: - type: string enum: - broad - type: string enum: - phrase - type: string enum: - exact bid_price: type: number minimum: 0 required: - keyword - match_type additionalProperties: {} negative_keywords: type: array items: type: object properties: keyword: type: string minLength: 1 match_type: anyOf: - type: string enum: - broad - type: string enum: - phrase - type: string enum: - exact required: - keyword - match_type additionalProperties: {} additionalProperties: {} 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 MediaBuyPendingReason: description: Why a not-yet-delivering media buy is waiting, and implicitly whose side owns the wait. A platform-derived annotation — never a status value. awaiting_storefront_approval / awaiting_source_moderation / creative_processing_at_source / awaiting_creative_approval = the seller side owns the wait; no_creatives_attached / source_rejected_creatives = the buyer owns it (attach or fix creatives); forward_failed_retrying / forward_failed_needs_correction = the platform owns it; accepted_awaiting_trafficking / scheduled_not_started = nothing is wrong, the buy is queued or scheduled. type: string enum: - forward_failed_needs_correction - forward_failed_retrying - awaiting_storefront_approval - awaiting_source_moderation - no_creatives_attached - source_rejected_creatives - creative_processing_at_source - awaiting_creative_approval - accepted_awaiting_trafficking - scheduled_not_started ConnectedAccountDirectedCampaignInfo: description: Subscription-backed directed campaign mirror state — connection, upstream account, dual-keyed identifiers, and sync health. type: object properties: provenance: description: This directed campaign is mirrored from or authored through a connected seller account. type: string enum: - connected_account connectionId: description: The subscribed provider connection this directed campaign is mirrored from. example: conn_abc123 type: string minLength: 1 accountId: description: The connection's upstream account id. example: act_998877 type: string minLength: 1 provider: description: Adapter/provider key the connection resolves to, e.g. "tiktok", "pinterest", "talpa". example: tiktok type: string minLength: 1 storefrontId: description: Storefront DB id backing this connection, when the provider is modeled as an AdCP storefront. example: 42 type: integer maximum: 9007199254740991 minimum: 1 upstreamMediaBuyId: description: The seller's own identifier for the mirrored media buy/campaign — dual-keyed alongside our internal mediaBuyId, per the parity rule (a directed campaign IS a media buy). example: tt_campaign_44521 type: string minLength: 1 mediaBuyId: description: Our internal media buy id correlating to the upstream object, once the mirror row exists. type: string subscribed: description: Whether the connected account is actively subscribed for periodic metadata mirroring. Alpha usage is dark-metered and not billed. type: boolean mirrorState: description: live = mirror is current; stale = last sync failed or is overdue; error = the provider reported an error. type: string enum: - live - stale - error lastSyncedAt: description: When the mirror was last refreshed from the upstream platform (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: - provenance - connectionId - accountId - provider - upstreamMediaBuyId - subscribed - mirrorState 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 cadence: type: string enum: - HOURLY - DAILY - WEEKLY syncWeeklyDay: type: integer minimum: 0 maximum: 6 enabled: type: boolean credentialId: description: Database identifier of the Data Delivery Credential authenticating this Output. type: string credentialName: description: Name of the Data Delivery Credential authenticating this Output (advertiser-scoped, unique among live credentials). type: string 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 - credentialId - credentialName - deliveryConfig - source - createdAt - updatedAt additionalProperties: false CreativeReviewStatus: description: Lifecycle state of a buyer-submitted creative awaiting storefront review. `pending` until an operator decides; `approved` or `rejected` after a decision; `revoked` if an operator pulls a previously-approved creative. type: string enum: - pending - approved - rejected - revoked Duration: description: A duration expressed as an interval and unit type: object properties: interval: type: integer maximum: 9007199254740991 minimum: 1 unit: type: string enum: - minutes - hours - days - campaign required: - interval - unit UpdateMediaBuyProductInput: description: 'Product update — additive (existing products not listed are preserved). Use remove: true to delete a product. Does not add brand-new product selections; use create_media_buys for that.' type: object properties: productId: description: Product ID (must already be on this media buy) type: string minLength: 1 pricingOptionId: description: The replacement pricing option must resolve to this media buy's existing settlement currency — update_media_buy does not re-split a buy across sales agents or currencies. type: string budget: type: number exclusiveMinimum: 0 pacing: type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. type: - number - 'null' remove: description: Set to true to remove this product from the media buy type: boolean pageId: description: Platform-specific page identity for ad placements. Required for Meta products when the connected ad account has more than one authorized Facebook Page — pass one of the page IDs listed in the error message. Omit when the account has exactly one authorized page. example: '1147910135081908' type: string minLength: 1 pixelId: description: 'Meta Pixel / Dataset ID for conversion tracking. Required for Meta Sales (OUTCOME_SALES) products — pass the pixel ID listed in the error message. There is no auto-select: every Meta Sales buy must explicitly specify a pixel.' example: '123456789012345' type: string minLength: 1 required: - productId additionalProperties: false CampaignUtmConfig: description: UTM configuration for a campaign. Overrides advertiser-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 FrequencyCapTargetLevel: description: Level of the entity the frequency cap applies to type: string enum: - ADVERTISER - CAMPAIGN - CREATIVE 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 maximum: 9007199254740991 minimum: 1 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 ListTargetingDimensionsResponse: description: Supported targeting dimensions and their campaign fields. type: object properties: locale: description: Locale for the display labels example: en-US type: string enum: - en-US dimensions: description: Supported targeting dimensions type: array items: $ref: '#/components/schemas/TargetingDimensionSummary' required: - locale - dimensions additionalProperties: false 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 BuyerPackageDelivery: description: Delivery recorded against this package. Absent when the package has not delivered or the source has not reported yet. type: object properties: impressions: description: Impressions delivered against this package so far. type: number spend: description: Spend against this package so far, in the buy's currency, in GROSS (fee-inclusive) denomination grossed up at the buy's pinned pricing terms, so it compares directly against this package's budget. Net-as-reported for legacy buys with no pinned terms. type: number clicks: description: Clicks recorded against this package, when reported. type: - number - 'null' required: - impressions - spend - clicks additionalProperties: false MediaBuyPendingChange: description: A buyer-submitted change that has been accepted by Interchange but has NOT yet taken effect on the delivering buy. Its presence is the signal that this buy has an unapplied change; absence means everything reported is live. Never treat these values as delivering. type: object properties: status: description: 'Lifecycle status of the pending change itself, typically PENDING_APPROVAL. This is NOT the status of the buy: the buy keeps its own top-level status, which reflects what is delivering now.' example: PENDING_APPROVAL type: string pendingAt: description: Which layer the pending change is parked at. 'storefront' = waiting on the storefront operator's manual approval, 'salesagent' = the inventory source is still processing it, 'unknown' = indeterminate. type: string enum: - storefront - salesagent - unknown reason: description: Reason recorded when the change was submitted, when one was supplied. example: Extended to 8/11 with W5+W6 gross budget type: string differences: description: Only the fields whose pending value differs from live appear here. An empty object means a pending change exists whose comparable fields already match live. type: object properties: endTime: description: Flight end date change (ISO 8601). type: object properties: live: description: The value currently in effect on the delivering buy. type: string proposed: description: The value the pending change would set. type: string additionalProperties: false budget: description: Total budget change in the buy's currency, summed across its packages. type: object properties: live: description: The value currently in effect on the delivering buy. type: number proposed: description: The value the pending change would set. type: number additionalProperties: false creatives: description: Creative IDs currently attached compared with the proposed attachment set. type: object properties: live: description: The value currently in effect on the delivering buy. type: array items: type: string proposed: description: The value the pending change would set. type: array items: type: string additionalProperties: false additionalProperties: false required: - status - differences additionalProperties: false TargetingDimensionEntry: type: object properties: code: description: String code for this targeting value example: '532' type: string name: description: Human-readable display label example: Albany-Schenectady-Troy type: string required: - code - name additionalProperties: false DirectedCampaignDeliveryResponse: description: The campaign identifier and its owning connected seller or storefront's AdCP delivery response. type: object properties: campaignId: type: string delivery: type: object additionalProperties: {} required: - campaignId - delivery additionalProperties: false 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 - reach viewDurationSeconds: description: Minimum video view duration in seconds for completed_view. Only applicable when metric is 'completed_views'. type: number exclusiveMinimum: 0 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 exclusiveMinimum: 0 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 exclusiveMinimum: 0 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 CreatePerformanceCampaignBody: description: Request body for creating a performance-mode campaign type: object properties: advertiserId: description: Advertiser ID that will own this campaign example: 12345 type: integer maximum: 9007199254740991 minimum: 1 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 exclusiveMinimum: 0 currency: description: Optional ISO 4217 currency. If provided it must match the advertiser's primary currency; otherwise the advertiser's currency is used. Campaigns cannot be created in a currency other than the advertiser's. type: string minLength: 3 maxLength: 3 dailyCap: type: number exclusiveMinimum: 0 pacing: type: string enum: - EVEN - ASAP - FRONTLOADED required: - total 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: geo_countries: type: array items: type: string geo_countries_exclude: type: array items: type: string geo_regions: type: array items: type: string geo_regions_exclude: type: array items: type: string geo_metros: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_metros_exclude: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas_exclude: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} language: type: array items: type: string device_platform: type: array items: anyOf: - type: string enum: - ios - type: string enum: - android - type: string enum: - windows - type: string enum: - macos - type: string enum: - linux - type: string enum: - chromeos - type: string enum: - tvos - type: string enum: - tizen - type: string enum: - webos - type: string enum: - fire_os - type: string enum: - roku_os - type: string enum: - unknown device_type: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown device_type_exclude: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown channels: description: Channels to target (e.g., ["ctv", "display"]) type: array items: type: string countries: description: 'Deprecated: use geo_countries. Countries to target (ISO 3166-1 alpha-2 codes). Values are normalized into geo_countries on write.' deprecated: true maxItems: 250 type: array items: type: string pattern: ^[A-Z]{2}$ additionalProperties: {} 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 maximum: 9007199254740991 minimum: 1 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. Required for mode: "performance".' 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 maximum: 9007199254740991 minimum: 1 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 advertiser-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: $ref: '#/components/schemas/FrequencyCapConfigInput' mode: description: '"I have an objective; I don''t care what you give me" — platform-managed.' type: string enum: - performance required: - advertiserId - name - flightDates - budget - performanceConfig - mode TargetingDimensionSummary: type: object properties: system: $ref: '#/components/schemas/TargetingDimensionSystem' name: description: Human-readable dimension name example: Nielsen DMA type: string description: description: What this targeting dimension represents type: string locale: description: Locale for the display labels example: en-US type: string enum: - en-US targetingFields: description: Campaign constraint fields that accept this dimension example: - geo_metros - geo_metros_exclude type: array items: type: string entryCount: description: Number of values in this dimension example: 210 type: integer minimum: 0 maximum: 9007199254740991 required: - system - name - description - locale - targetingFields - entryCount additionalProperties: false CampaignManagementFilter: description: 'Management states to include in the list: "tracked", "managed", or "all" (both — the default).' type: string enum: - tracked - managed - all ExecuteWarning: description: A non-fatal outcome from campaign execution oneOf: - type: object properties: type: type: string enum: - creatives_dropped mediaBuyId: description: The media buy ID these creatives were dropped from type: string dropped: description: Creatives that were dropped and why type: array items: type: object properties: creativeId: description: Creative ID that was dropped type: string formatId: description: Format ID of the dropped creative type: string reason: description: Why the creative was dropped from this buy type: string required: - creativeId - formatId - reason additionalProperties: false required: - type - mediaBuyId - dropped additionalProperties: false - type: object properties: type: type: string enum: - stale_draft mediaBuyIds: description: IDs of the existing DRAFT media buys that were retried as-is type: array items: type: string hint: description: 'Actionable guidance: explains why the new discovery selection was not applied and how to apply it' type: string required: - type - mediaBuyIds - hint additionalProperties: false type: object 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 UpdateDiscoveryCampaignBody: description: Request body for updating a discovery-mode 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 exclusiveMinimum: 0 currency: default: USD type: string minLength: 3 maxLength: 3 dailyCap: type: number exclusiveMinimum: 0 pacing: type: string enum: - EVEN - ASAP - FRONTLOADED brief: description: Updated campaign brief type: string maxLength: 5000 constraints: description: Updated targeting constraints type: object properties: geo_countries: type: array items: type: string geo_countries_exclude: type: array items: type: string geo_regions: type: array items: type: string geo_regions_exclude: type: array items: type: string geo_metros: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_metros_exclude: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas_exclude: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} language: type: array items: type: string device_platform: type: array items: anyOf: - type: string enum: - ios - type: string enum: - android - type: string enum: - windows - type: string enum: - macos - type: string enum: - linux - type: string enum: - chromeos - type: string enum: - tvos - type: string enum: - tizen - type: string enum: - webos - type: string enum: - fire_os - type: string enum: - roku_os - type: string enum: - unknown device_type: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown device_type_exclude: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown channels: description: Channels to target (e.g., ["ctv", "display"]) type: array items: type: string countries: description: 'Deprecated: use geo_countries. Countries to target (ISO 3166-1 alpha-2 codes). Values are normalized into geo_countries on write.' deprecated: true maxItems: 250 type: array items: type: string pattern: ^[A-Z]{2}$ additionalProperties: {} 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 maximum: 9007199254740991 minimum: 1 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. Pass null to clear an existing configuration; this is only valid for a campaign currently in performance mode. 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) type: - integer - 'null' maximum: 9007199254740991 minimum: 1 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 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 exclusiveMinimum: 0 pacing: description: Updated pacing strategy type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. type: - number - 'null' startTime: description: Updated flight start date/time for this package (ISO 8601). Must fall within the media buy's date range. 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))$ endTime: description: Updated flight end date/time for this package (ISO 8601). Must fall within the media buy's date range. 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))$ targetingOverlay: description: Governed audience IDs to merge into the existing package targeting overlay. type: object properties: audience_include: type: array items: type: string audience_exclude: type: array items: type: string additionalProperties: false required: - packageId additionalProperties: false pacingPeriods: description: Per-media-buy pacing schedule. When set, replaces the campaign-level pacingPeriods for this specific buy. Use to heavy-up or shape spend on one media buy without affecting others. Pass null to clear an existing per-buy schedule. Bootstrapping a schedule onto an unpaced media buy is only allowed in DRAFT or PENDING_APPROVAL status. See the Pacing Periods guide for the full state matrix and sales-agent capability requirements. allOf: - $ref: '#/components/schemas/PacingPeriods' products: description: 'Product updates — additive (existing products not listed are preserved). Use remove: true to delete a product.' type: array items: type: object properties: productId: description: Product ID type: string minLength: 1 pricingOptionId: type: string budget: type: number exclusiveMinimum: 0 pacing: type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. type: - number - 'null' remove: description: Set to true to remove this product from the media buy type: boolean pageId: description: Platform-specific page identity for ad placements. Required for Meta products when the connected ad account has more than one authorized Facebook Page — pass one of the page IDs listed in the error message. Omit when the account has exactly one authorized page. example: '1147910135081908' type: string minLength: 1 pixelId: description: 'Meta Pixel / Dataset ID for conversion tracking. Required for Meta Sales (OUTCOME_SALES) products — pass the pixel ID listed in the error message. There is no auto-select: every Meta Sales buy must explicitly specify a pixel.' example: '123456789012345' type: string minLength: 1 required: - productId 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: description: 'Optimization goals applied to every package at execution time. Each goal is either `{ kind: "event", event_sources: [{ event_source_id, event_type }], target? }` or `{ kind: "metric", metric, target? }`. Event target kinds: `cost_per` (CPA), `per_ad_spend` (ROAS), `maximize_value`. Metric target kinds: `cost_per`, `threshold_rate`. ALWAYS ask the buyer what they want to optimize for before updating — do not change goals silently. Pass an empty array to clear all 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 properties: min: type: number minimum: 1 max: type: number minimum: 1 window: type: object properties: interval: type: number minimum: 1 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: - window 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 minimum: 1 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 minLength: 1 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: - follow - type: string enum: - content_view - type: string enum: - watch_milestone - 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 minimum: 1 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 minimum: 1 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: {} model: anyOf: - type: string enum: - last_touch - type: string enum: - first_touch - type: string enum: - linear - type: string enum: - time_decay - type: string enum: - data_driven additionalProperties: {} priority: type: number minimum: 1 required: - kind - event_sources additionalProperties: {} - type: object properties: kind: type: string enum: - vendor_metric vendor: type: object properties: domain: type: string pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: url: type: string pattern: ^https:\/\/ email: type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ languages: type: array items: type: string additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: number minimum: 1 height: type: number minimum: 1 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_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))$ created_time: 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))$ c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} embedded_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))$ required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_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))$ required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: number minimum: 1 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: 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))$ result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} metric_id: type: string 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 minimum: 1 required: - kind - vendor - metric_id 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. 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: $ref: '#/components/schemas/FrequencyCapConfigInput' mode: description: Campaign mode. Present for symmetry with create; a campaign cannot change mode via update. type: string enum: - discovery required: - mode 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 BuyerMediaBuyPackagesResponse: description: A media buy's packages with the attributes needed to pick one, sized to be read in full by an agent. type: object properties: mediaBuyId: description: The media buy these packages belong to. example: mb_ETBn4gJ9Wu type: string isPaced: description: Whether this buy was split across pacing periods. When true, expect one package per product per period and use pacingPeriod to tell them apart. type: boolean packageCount: description: How many packages this media buy has. type: integer minimum: -9007199254740991 maximum: 9007199254740991 packages: description: The packages on this media buy, ordered by product then pacing period so the order matches how the ids were assigned. type: array items: $ref: '#/components/schemas/BuyerPackage' required: - mediaBuyId - isPaced - packageCount - packages additionalProperties: false GcsDeliveryConfig: type: object properties: type: type: string enum: - GCS pathPrefix: description: Object key prefix within the credential's bucket. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. default: '' type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type GetAdcpStatusOutput: type: object properties: campaign_id: type: string campaign_status: type: string operational_status: type: string enum: - no_media_buys - draft - pending_creatives - pending_start - active - paused - completed - attention_required media_buys: type: array items: type: object properties: media_buy_id: type: string adcp_media_buy_id: type: - string - 'null' internal_status: type: string adcp_status: type: - string - 'null' operational_status: type: string enum: - not_submitted - pending_creatives - pending_start - active - paused - completed - attention_required previous_internal_status: type: string previous_adcp_status: type: - string - 'null' updated: type: boolean status_refresh_source: type: string enum: - direct_agent - delegated_adapter - storefront_route_rollup - not_submitted - persisted_terminal - refresh_failed blockers: type: array items: type: string pending_reason: description: Why the buy is not delivering yet, rolled up to the most-blocking wait across its source legs. An annotation derived from forwarding state — never a status. allOf: - $ref: '#/components/schemas/MediaBuyPendingReason' pending_since: description: When the current wait began (ISO 8601), when known. 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_code: description: Buyer-safe structured error code when forwarding failed or the buy was rejected. allOf: - $ref: '#/components/schemas/BuyerMediaBuyErrorCode' error_owner: description: Which party owns fixing the error (buyer_input | platform | seller). allOf: - $ref: '#/components/schemas/MediaBuyErrorOwner' source_message: description: The source's sanitized rejection or moderation message, when provided. type: string forwarded_at: description: When the buy was forwarded to its inventory source(s) (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))$ buyer_reference: description: Support reference for this buy (sf::). Quote it with the request timestamp when contacting the seller or Scope3 support. type: string required: - media_buy_id - adcp_media_buy_id - internal_status - adcp_status - operational_status - previous_internal_status - previous_adcp_status - updated - status_refresh_source - blockers 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 code: type: string required: - media_buy_id - error additionalProperties: false blockers: type: array items: type: object properties: code: type: string message: type: string required: - code - message additionalProperties: false pending_creative_reviews: type: integer minimum: 0 maximum: 9007199254740991 has_upstream_media_buy: type: boolean has_delivery: type: boolean required: - campaign_id - campaign_status - operational_status - media_buys - agents_queried - errors - blockers - pending_creative_reviews - has_upstream_media_buy - has_delivery additionalProperties: false DirectedCampaignInfo: description: Directed campaign provenance. Connected-account campaigns expose mirror health; storefront-endpoint campaigns expose the addressed storefront and dual-key identity. oneOf: - $ref: '#/components/schemas/ConnectedAccountDirectedCampaignInfo' - $ref: '#/components/schemas/StorefrontEndpointDirectedCampaignInfo' type: object discriminator: propertyName: provenance mapping: connected_account: '#/components/schemas/ConnectedAccountDirectedCampaignInfo' storefront_endpoint: '#/components/schemas/StorefrontEndpointDirectedCampaignInfo' FrequencyCapConfig: description: Buyer-side frequency cap configuration type: object properties: max_impressions: description: Maximum number of impressions allowed within the window example: 3 type: integer maximum: 9007199254740991 minimum: 1 window: $ref: '#/components/schemas/FrequencyCapWindow' 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 type: - string - 'null' required: - max_impressions - window - id - targetLevel - targetId - createdAt - updatedAt additionalProperties: {} DataDeliveryOutputArrayInput: description: Array of Data Delivery Outputs for one scope (advertiser or campaign). At most one Output per (dataDeliveryType, credentialName) pair — the same data type can ship to multiple credentials by listing one Output per destination. maxItems: 20 type: array items: $ref: '#/components/schemas/DataDeliveryOutputInput' 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, 0 = skip this period). Required when mode is "weight". type: number minimum: 0 maximum: 10 budget: description: Absolute budget for this period (0 = skip this period). Required when mode is "budget". type: number minimum: 0 required: - label - start - end additionalProperties: false required: - mode - periods 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 S3DeliveryConfigOutput: type: object properties: type: type: string enum: - S3 pathPrefix: description: Object key prefix within the credential's S3 bucket. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. default: '' type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type - pathPrefix - format additionalProperties: false 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 - follow - content_view - watch_milestone - 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 exclusiveMinimum: 0 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 exclusiveMinimum: 0 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 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 - reach viewDurationSeconds: description: Minimum video view duration in seconds for completed_view. Only applicable when metric is 'completed_views'. type: number exclusiveMinimum: 0 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 exclusiveMinimum: 0 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 exclusiveMinimum: 0 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 GeoMetrosResponse: description: Geo metro codes and English display labels for buyer-side display and input resolution. type: object properties: system: description: Targeting system these entries belong to example: nielsen_dma allOf: - $ref: '#/components/schemas/TargetingDimensionSystem' locale: description: Locale for the display labels. Currently only English labels are supported. example: en-US type: string enum: - en-US entries: description: Known code-name pairs for this system type: array items: $ref: '#/components/schemas/TargetingDimensionEntry' required: - system - locale - entries additionalProperties: false CampaignProductsResponse: description: Every product attached to a campaign, sourced from the campaign's media buys (authoritative) plus any discovery-staged products that have not yet been executed onto a media buy. Use this to get the full ad-product list for a campaign without paging through the nested `mediaBuys[]` tree on `get_campaign`. Pass `mediaBuyId` to narrow to a specific buy. type: object properties: campaignId: description: Campaign ID type: string discoveryId: description: Discovery session attached to the campaign, or null if none attached type: - string - 'null' 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 TargetingDimensionSystem: description: Supported targeting dimension system example: nielsen_dma type: string enum: - nielsen_dma MediaBuyRef: description: Lightweight media buy reference (id + live 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: 'Status of the LIVE media buy: what is delivering now (DRAFT, PENDING_APPROVAL, ACTIVE, PAUSED, COMPLETED, CANCELED). A buy that is ACTIVE with a change awaiting approval reports ACTIVE here and carries `pendingChange`; a queued change never replaces this value.' example: ACTIVE type: string pendingAt: description: Which layer the media buy itself is parked at; only present while its own status is PENDING_APPROVAL (a buy awaiting its first approval). For a change queued behind an already-live buy, read `pendingChange.pendingAt`. 'storefront' = waiting for the storefront operator's manual approval, 'salesagent' = the inventory source is still processing the buy, 'unknown' = indeterminate. type: string enum: - storefront - salesagent - unknown pendingChange: $ref: '#/components/schemas/MediaBuyRefPendingChange' required: - mediaBuyId - status 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' MediaBuyErrorOwner: description: 'Which party owns fixing the error: buyer_input (the request needs a correction from the buyer), platform (Scope3 owns the fault), seller (the storefront or its source made the decision or is unavailable).' type: string enum: - buyer_input - platform - seller 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 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 - CANCELED - ARCHIVED newStatus: description: New campaign status type: string enum: - DRAFT - ACTIVE - PAUSED - COMPLETED - CANCELED - ARCHIVED success: description: Whether the status change was fully successful. False when any media buy execution failed. type: boolean mediaBuysExecuted: description: Number of media buys that execution was attempted for. Always present on execute responses; absent on pause responses. 0 indicates a no-op execute (nothing to execute, campaign status preserved). example: 2 type: integer minimum: 0 maximum: 9007199254740991 reason: description: Machine-readable reason for a no-op execute. Present only when the campaign had no media buys to execute, in which case the campaign status is preserved rather than set to ACTIVE. type: string enum: - no_media_buys_to_execute errors: description: Structured error details per failed media buy. Only present when there are failures. type: array items: $ref: '#/components/schemas/ExecutionError' warnings: description: 'Non-fatal outcomes from execution. creatives_dropped: a buy forwarded with a compatible creative subset (which may be empty). stale_draft: the existing DRAFT cart was retried as-is because discovery products were updated via add_discovery_products after the last staging run — call create_media_buys with replace: true to apply the new selection.' type: array items: $ref: '#/components/schemas/ExecuteWarning' required: - campaignId - previousStatus - newStatus - success additionalProperties: false BuyerPackage: description: One package on a media buy, carrying the attributes that identify it. Targeting, creatives, and format detail are deliberately omitted; use get_campaign for those. type: object properties: packageId: description: 'The package identifier to quote when updating or pausing this package. Treat it as an opaque string: the trailing number is a dispatch-order position, not a period number. Use pacingPeriod to identify the period.' example: sf_pkg_sf_mb_1783618937177_43ycbp7b_3 type: string productId: description: The seller product this package buys. Together with pacingPeriod this uniquely identifies a package within its media buy. Note the nested package inside GET /campaigns/:id spells this `productIds` as a single-element array; this endpoint uses the singular form, which matches the AdCP Package field. type: - string - 'null' productName: description: The product's name as published by the seller, when it is known locally. type: string status: description: 'Whether this package is currently buying. Independent of the media buy status: a live buy can carry a paused package.' type: string enum: - active - paused - canceled pacingPeriod: allOf: - $ref: '#/components/schemas/PackagePacingPeriod' startTime: description: When this package starts buying (ISO 8601). Absent on packages created before the platform retained its own requested window, in which case fall back to the media buy's window. 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))$ endTime: description: When this package stops buying (ISO 8601). This is the field to match when a buyer names a package by the date it ends. 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: This package's budget, gross of buyer fees, in budgetCurrency. type: - number - 'null' budgetCurrency: description: ISO-4217 currency of budget. example: USD type: string pacing: description: How the package spends its budget (even, asap, front_loaded). type: string delivery: allOf: - $ref: '#/components/schemas/BuyerPackageDelivery' required: - packageId - productId - status - budget additionalProperties: false 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' 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 maximum: 9007199254740991 minimum: 1 minBudgetPerProduct: description: Minimum budget to allocate per product example: 500 type: number exclusiveMinimum: 0 additionalProperties: false UpdatePerformanceCampaignBody: description: Request body for updating a performance-mode 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 exclusiveMinimum: 0 currency: default: USD type: string minLength: 3 maxLength: 3 dailyCap: type: number exclusiveMinimum: 0 pacing: type: string enum: - EVEN - ASAP - FRONTLOADED brief: description: Updated campaign brief type: string maxLength: 5000 constraints: description: Updated targeting constraints type: object properties: geo_countries: type: array items: type: string geo_countries_exclude: type: array items: type: string geo_regions: type: array items: type: string geo_regions_exclude: type: array items: type: string geo_metros: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_metros_exclude: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas_exclude: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} language: type: array items: type: string device_platform: type: array items: anyOf: - type: string enum: - ios - type: string enum: - android - type: string enum: - windows - type: string enum: - macos - type: string enum: - linux - type: string enum: - chromeos - type: string enum: - tvos - type: string enum: - tizen - type: string enum: - webos - type: string enum: - fire_os - type: string enum: - roku_os - type: string enum: - unknown device_type: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown device_type_exclude: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown channels: description: Channels to target (e.g., ["ctv", "display"]) type: array items: type: string countries: description: 'Deprecated: use geo_countries. Countries to target (ISO 3166-1 alpha-2 codes). Values are normalized into geo_countries on write.' deprecated: true maxItems: 250 type: array items: type: string pattern: ^[A-Z]{2}$ additionalProperties: {} 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 maximum: 9007199254740991 minimum: 1 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. Pass null to clear an existing configuration; this is only valid for a campaign currently in performance mode. 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) type: - integer - 'null' maximum: 9007199254740991 minimum: 1 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 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 exclusiveMinimum: 0 pacing: description: Updated pacing strategy type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. type: - number - 'null' startTime: description: Updated flight start date/time for this package (ISO 8601). Must fall within the media buy's date range. 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))$ endTime: description: Updated flight end date/time for this package (ISO 8601). Must fall within the media buy's date range. 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))$ targetingOverlay: description: Governed audience IDs to merge into the existing package targeting overlay. type: object properties: audience_include: type: array items: type: string audience_exclude: type: array items: type: string additionalProperties: false required: - packageId additionalProperties: false pacingPeriods: description: Per-media-buy pacing schedule. When set, replaces the campaign-level pacingPeriods for this specific buy. Use to heavy-up or shape spend on one media buy without affecting others. Pass null to clear an existing per-buy schedule. Bootstrapping a schedule onto an unpaced media buy is only allowed in DRAFT or PENDING_APPROVAL status. See the Pacing Periods guide for the full state matrix and sales-agent capability requirements. allOf: - $ref: '#/components/schemas/PacingPeriods' products: description: 'Product updates — additive (existing products not listed are preserved). Use remove: true to delete a product.' type: array items: type: object properties: productId: description: Product ID type: string minLength: 1 pricingOptionId: type: string budget: type: number exclusiveMinimum: 0 pacing: type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. type: - number - 'null' remove: description: Set to true to remove this product from the media buy type: boolean pageId: description: Platform-specific page identity for ad placements. Required for Meta products when the connected ad account has more than one authorized Facebook Page — pass one of the page IDs listed in the error message. Omit when the account has exactly one authorized page. example: '1147910135081908' type: string minLength: 1 pixelId: description: 'Meta Pixel / Dataset ID for conversion tracking. Required for Meta Sales (OUTCOME_SALES) products — pass the pixel ID listed in the error message. There is no auto-select: every Meta Sales buy must explicitly specify a pixel.' example: '123456789012345' type: string minLength: 1 required: - productId 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: description: 'Optimization goals applied to every package at execution time. Each goal is either `{ kind: "event", event_sources: [{ event_source_id, event_type }], target? }` or `{ kind: "metric", metric, target? }`. Event target kinds: `cost_per` (CPA), `per_ad_spend` (ROAS), `maximize_value`. Metric target kinds: `cost_per`, `threshold_rate`. ALWAYS ask the buyer what they want to optimize for before updating — do not change goals silently. Pass an empty array to clear all 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 properties: min: type: number minimum: 1 max: type: number minimum: 1 window: type: object properties: interval: type: number minimum: 1 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: - window 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 minimum: 1 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 minLength: 1 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: - follow - type: string enum: - content_view - type: string enum: - watch_milestone - 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 minimum: 1 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 minimum: 1 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: {} model: anyOf: - type: string enum: - last_touch - type: string enum: - first_touch - type: string enum: - linear - type: string enum: - time_decay - type: string enum: - data_driven additionalProperties: {} priority: type: number minimum: 1 required: - kind - event_sources additionalProperties: {} - type: object properties: kind: type: string enum: - vendor_metric vendor: type: object properties: domain: type: string pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: url: type: string pattern: ^https:\/\/ email: type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ languages: type: array items: type: string additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: number minimum: 1 height: type: number minimum: 1 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_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))$ created_time: 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))$ c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} embedded_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))$ required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_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))$ required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: number minimum: 1 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: 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))$ result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} metric_id: type: string 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 minimum: 1 required: - kind - vendor - metric_id 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. 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: $ref: '#/components/schemas/FrequencyCapConfigInput' mode: description: Campaign mode. Present for symmetry with create; a campaign cannot change mode via update. type: string enum: - performance required: - mode DurationOutput: description: A duration expressed as an interval and unit type: object properties: interval: type: integer maximum: 9007199254740991 minimum: 1 unit: type: string enum: - minutes - hours - days - campaign required: - interval - unit additionalProperties: false AzureBlobDeliveryConfigOutput: type: object properties: type: type: string enum: - AZURE_BLOB pathPrefix: description: Blob name prefix within the credential's Azure container. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. default: '' type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type - pathPrefix - format additionalProperties: false AzureBlobDeliveryConfig: type: object properties: type: type: string enum: - AZURE_BLOB pathPrefix: description: Blob name prefix within the credential's Azure container. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. default: '' type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type BuyerMediaBuyErrorCode: description: Buyer-safe structured error code for a media buy that failed to forward or was rejected. Paired with errorOwner (who owns the fix) and, when the source provided one, a sanitized human-readable message. type: string enum: - product_no_longer_available - source_rejected - storefront_rejected - source_unavailable - invalid_request - quote_expired - platform_error S3DeliveryConfig: type: object properties: type: type: string enum: - S3 pathPrefix: description: Object key prefix within the credential's S3 bucket. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. default: '' type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type CampaignMode: description: 'Who is steering the campaign. "discovery" (brief-driven) and "performance" (objective-driven) are platform-managed. "directed" is a deprecated wire value retained for compatibility: read `management` instead — a directed campaign is either tracked (mirrored from a seller account we did not set up) or managed (authored through the platform against one storefront).' type: string enum: - discovery - performance - directed 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 - CANCELED - ARCHIVED mode: description: 'Who is steering this campaign — discovery, performance, or directed. Backfilled by projection for existing campaigns (see deriveCampaignMode); no data movement. The "directed" value is deprecated: read `management` instead.' allOf: - $ref: '#/components/schemas/CampaignMode' management: description: 'Whether the platform acts on this campaign: "tracked" (a campaign the platform did not set up, mirrored read-only from a connected seller account) or "managed" (authored or adopted through the platform).' allOf: - $ref: '#/components/schemas/CampaignManagement' directed: description: Subscription-backed directed mirror state — connection, upstream account, dual-keyed ids, and sync health. Not present on inbound single-storefront AdCP campaigns. allOf: - $ref: '#/components/schemas/DirectedCampaignInfo' 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 constraints: description: Targeting constraints type: object properties: geo_countries: type: array items: type: string geo_countries_exclude: type: array items: type: string geo_regions: type: array items: type: string geo_regions_exclude: type: array items: type: string geo_metros: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_metros_exclude: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas_exclude: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} language: type: array items: type: string device_platform: type: array items: anyOf: - type: string enum: - ios - type: string enum: - android - type: string enum: - windows - type: string enum: - macos - type: string enum: - linux - type: string enum: - chromeos - type: string enum: - tvos - type: string enum: - tizen - type: string enum: - webos - type: string enum: - fire_os - type: string enum: - roku_os - type: string enum: - unknown device_type: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown device_type_exclude: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown channels: description: Channels to target (e.g., ["ctv", "display"]) type: array items: type: string countries: description: 'Deprecated: use geo_countries. Countries to target (ISO 3166-1 alpha-2 codes). Values are normalized into geo_countries on write.' deprecated: true maxItems: 250 type: array items: type: string pattern: ^[A-Z]{2}$ geo_metro_names: description: Display labels for included geo_metros codes. Only present when requested with fields=geo_metro_names. allOf: - $ref: '#/components/schemas/CampaignGeoMetroNames' geo_metro_names_exclude: description: Display labels for excluded geo_metros_exclude codes. Only present when requested with fields=geo_metro_names. allOf: - $ref: '#/components/schemas/CampaignGeoMetroNames' additionalProperties: {} 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 allocatedBudget, unallocatedBudget. type: object properties: total: type: number exclusiveMinimum: 0 currency: default: USD type: string minLength: 3 maxLength: 3 required: - total - currency additionalProperties: false required: - campaignId - advertiserId - name - status - mode - management - createdAt - updatedAt additionalProperties: false TargetingDimensionResolveCandidate: type: object properties: system: $ref: '#/components/schemas/TargetingDimensionSystem' code: description: Resolved targeting code example: '803' type: string name: description: Display label for the resolved code example: Los Angeles type: string locale: description: Locale for the display label example: en-US type: string enum: - en-US confidence: description: Heuristic confidence score for this match example: 0.96 type: number minimum: 0 maximum: 1 matched: description: Dictionary label or alias that matched the query example: LA DMA type: string matchType: description: How the candidate matched the query example: alias type: string enum: - code - name - alias - partial required: - system - code - name - locale - confidence - matched - matchType 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 GcsDeliveryConfigOutput: type: object properties: type: type: string enum: - GCS pathPrefix: description: Object key prefix within the credential's bucket. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. default: '' type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type - pathPrefix - format additionalProperties: false TargetingDimensionValuesResponse: description: Targeting dimension codes and localized display labels for buyer-side display and input resolution. type: object properties: system: $ref: '#/components/schemas/TargetingDimensionSystem' name: description: Human-readable dimension name example: Nielsen DMA type: string description: description: What this targeting dimension represents type: string locale: description: Locale for the display labels example: en-US type: string enum: - en-US targetingFields: description: Campaign constraint fields that accept this dimension example: - geo_metros - geo_metros_exclude type: array items: type: string entries: description: Known code-name pairs for this system type: array items: $ref: '#/components/schemas/TargetingDimensionEntry' required: - system - name - description - locale - targetingFields - entries additionalProperties: false MediaBuyCascadeResult: description: Outcome of a single media buy status change in the cascade type: object properties: mediaBuyId: description: The media buy ID type: string name: description: The media buy name type: string previousStatus: description: Status of the media buy before the cascade ran type: string success: description: Whether the media buy status change succeeded type: boolean error: description: Error message when the media buy status change failed type: string required: - mediaBuyId - name - previousStatus - success 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 ProviderTargetingReadback: description: Provider-normalized geographic, demographic, and audience targeting readback. Audience fields contain canonical buyer IDs, never native provider IDs. Only canonical allowlisted fields are exposed; raw provider extensions are never returned. type: object properties: countries: type: array items: type: string regions: type: array items: type: string cities: type: array items: type: string zips: type: array items: type: string age_min: description: Provider-normalized minimum age. Readback can include provider-authored 13–17 targeting even though Scope3 controlled brief writes currently start at 18. type: integer minimum: 13 maximum: 65 age_max: description: Provider-normalized maximum age; 65 represents the provider 65+ upper bucket. type: integer minimum: 13 maximum: 65 genders: description: Provider-normalized gender restrictions. An empty array means unrestricted/all genders. type: array items: type: string enum: - FEMALE - MALE audience_include: description: Canonical buyer audience IDs confirmed as positively targeted. Native provider audience IDs are never exposed. type: array items: type: string minLength: 1 audience_exclude: description: Canonical buyer audience IDs confirmed as excluded. Native provider audience IDs are never exposed. type: array items: type: string minLength: 1 publisher_platforms: type: array items: type: string enum: - facebook - instagram facebook_positions: type: array items: type: string enum: - facebook_reels - feed - story instagram_positions: type: array items: type: string enum: - reels - story - stream threads_positions: type: array items: type: string enum: - threads_stream instream_video_skippable_excluded: type: boolean required: - countries - regions - cities - zips additionalProperties: false UpdateMediaBuyResponse: description: The updated media buy (why-visibility fields included) plus any non-blocking warnings. type: object properties: mediaBuy: $ref: '#/components/schemas/BuyerMediaBuy' warnings: description: Non-blocking notices about this update, e.g. a flight date fell outside the campaign window (the campaign window was widened to cover it, rather than failing the request). type: array items: type: string required: - mediaBuy 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 OptimizationApplyMode: description: Whether optimization suggestions are automatically applied or require human approval. type: string enum: - AUTO - MANUAL 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 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 items: description: V3 projection of campaign list items. Parallel to campaigns[] for backward compatibility. type: array items: type: object properties: campaign: type: object properties: campaignId: type: string name: type: string handling: type: string enum: - tracking - managing phase: type: string enum: - draft - active - completed - canceled isPaused: type: boolean isArchived: type: boolean autonomy: type: object properties: inventorySelection: type: object properties: mode: type: string enum: - manual - propose - automatic source: type: string enum: - inherited - overridden required: - mode - source additionalProperties: false rebriefing: type: object properties: mode: type: string enum: - manual - propose - automatic source: type: string enum: - inherited - overridden required: - mode - source additionalProperties: false required: - inventorySelection - rebriefing additionalProperties: false source: type: object properties: kind: type: string enum: - interchange - connected_account - adcp sellerId: type: string freshness: type: string enum: - live - stale - error lastSyncedAt: type: string required: - kind additionalProperties: false createdAt: type: string updatedAt: type: string required: - campaignId - name - handling - phase - isPaused - isArchived - createdAt - updatedAt additionalProperties: false advertiser: type: object properties: advertiserId: type: string name: type: string required: - advertiserId - name additionalProperties: false flight: type: object properties: startAt: type: string endAt: type: string progress: type: number required: - startAt - endAt additionalProperties: false market: type: string financials: type: object properties: budget: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object spend: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object pacing: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: percent: type: number verdict: type: string enum: - behind - on_track - ahead required: - percent - verdict additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: percent: type: number verdict: type: string enum: - behind - on_track - ahead required: - percent - verdict additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object dailyBudget: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object spendToday: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object required: - budget - spend - pacing additionalProperties: false outcome: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: label: type: string actual: type: number target: type: number unit: type: string verdict: type: string enum: - working - off_goal - neutral required: - label - actual - unit - verdict additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: label: type: string actual: type: number target: type: number unit: type: string verdict: type: string enum: - working - off_goal - neutral required: - label - actual - unit - verdict additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object attention: type: array items: type: string enum: - blocked - off_goal - drifted - stale attentionNote: type: string nextAction: type: object properties: action: type: string label: type: string params: type: object additionalProperties: {} required: - action - label additionalProperties: false required: - campaign - advertiser - financials - outcome - attention additionalProperties: false activeCount: description: Count of active (not paused/archived) campaigns across the whole query scope, independent of pagination. Present only for the V3 Campaigns experience. example: 23 type: integer minimum: 0 maximum: 9007199254740991 v3Enabled: description: Whether the V3 Campaigns experience (enriched list + redesign) is enabled for this caller via the campaigns-v3 flag. The widget renders the V3 redesign only when true. type: boolean nextCursor: description: Opaque cursor for the next page. Absent when there is no next page. type: string hasMore: description: Whether there are more campaigns beyond this page. type: boolean required: - campaigns - total - hasMore additionalProperties: false 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 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 credentialName: description: Name of the Data Delivery Credential (within the same advertiser) that authenticates this Output. The credential carries the auth target (e.g., GCS bucket) and is Probe-validated. Must reference a credential whose destinationType matches deliveryConfig.type. type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ deliveryConfig: $ref: '#/components/schemas/DeliveryConfig' required: - dataDeliveryType - cadence - credentialName - deliveryConfig CampaignManagement: description: 'Whether the platform acts on this campaign. "tracked" = a campaign the platform did not set up, mirrored from a connected seller account: the shell is derived from the buys underneath, read-only, and updates automatically as the seller changes things. "managed" = a campaign authored or adopted through the platform (get_products → create_media_buy → update_media_buy) — the platform sends instructions down. In both states the execution system remains the source of truth.' type: string enum: - tracked - managed BuyerMediaBuyResponse: description: Response containing a single media buy with why-visibility type: object properties: mediaBuy: $ref: '#/components/schemas/BuyerMediaBuy' required: - mediaBuy additionalProperties: false UpdateMediaBuyPackageInput: description: Per-package update for a media buy with deployed packages type: object properties: packageId: description: Package ID to update type: string minLength: 1 budget: description: Updated budget amount type: number exclusiveMinimum: 0 pacing: description: Updated pacing strategy type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. type: - number - 'null' startTime: description: Updated flight start date/time for this package (ISO 8601). Must fall within the media buy's date range. 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))$ endTime: description: Updated flight end date/time for this package (ISO 8601). Must fall within the media buy's date range. 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))$ targetingOverlay: description: Governed audience IDs to merge into the existing package targeting overlay. type: object properties: audience_include: type: array items: type: string audience_exclude: type: array items: type: string additionalProperties: false required: - packageId additionalProperties: false PackagePacingPeriod: description: 'Which pacing period a package was cut for. This is what the numeric suffix on a storefront-minted package id refers to: package ids are assigned in product-then-period order at dispatch, so the suffix is a position, not a meaning. Read this field rather than parsing the id. Absent when the media buy is not paced, and on packages created before period identity was recorded.' type: object properties: index: description: One-based ordinal of the pacing period this package was cut for, counting from the first period on the campaign. example: 6 type: integer maximum: 9007199254740991 minimum: 1 label: description: The period label as named on the campaign, when the campaign named it. example: Week 6 type: string required: - index additionalProperties: false MediaBuyRefPendingChange: description: Present when this buy has a submitted change that has not yet reached the delivering buy. Call `get_media_buy` for the field-level differences; this reference stays lightweight by design. type: object properties: status: description: Lifecycle status of the queued change, typically PENDING_APPROVAL. example: PENDING_APPROVAL type: string pendingAt: description: Which layer the queued change is parked at. type: string enum: - storefront - salesagent - unknown required: - status 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 CampaignGeoMetroNames: description: Display labels for metro codes. Returned only when requested with fields=geo_metro_names; labels are derived from the local geo-metro label table and are not accepted on create/update. type: array items: type: object properties: system: description: Metro targeting system these display labels belong to, e.g. nielsen_dma. type: string minLength: 1 values: maxItems: 250 type: array items: type: object properties: code: description: Metro code from the corresponding metro targeting field. type: string minLength: 1 name: description: Human-readable display label for the metro code. type: string minLength: 1 required: - code - name additionalProperties: false required: - system - values 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 salesAgentName: description: Sales agent display name (from the local `adcp_agent` row) type: string publisherDomain: description: Publisher domain for this product type: string publisherName: description: Publisher display name 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, including the complete package IDs for each buy (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 packageIds: description: Complete package IDs for this product on this media buy. Use these IDs for mediaBuys[].packages[] updates. type: array items: type: string required: - mediaBuyId - status - name - packageIds additionalProperties: false required: - productId - salesAgentId - selectedAt - mediaBuys additionalProperties: false CampaignResponse: description: Response containing a single campaign type: object properties: campaign: $ref: '#/components/schemas/Campaign' warnings: description: Non-blocking advisories about the campaign. On create, includes a soft credit-limit warning when the budget already exceeds the org’s available Scope3 credit (the campaign is still created; the hard 402 gate fires at execute). type: array items: type: string required: - campaign additionalProperties: false CreateCampaignOpenApiBody: oneOf: - $ref: '#/components/schemas/CreateDiscoveryCampaignBody' - $ref: '#/components/schemas/CreatePerformanceCampaignBody' type: object discriminator: propertyName: mode mapping: discovery: '#/components/schemas/CreateDiscoveryCampaignBody' performance: '#/components/schemas/CreatePerformanceCampaignBody' RefreshDirectedCampaignBody: description: Request body for refreshing a directed campaign mirror without an upstream mutation. type: object properties: mode: type: string enum: - directed refresh: description: Trigger a mirror refresh against the upstream seller without writing to it. type: boolean enum: - true required: - mode - refresh additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token