openapi: 3.2.0 info: title: Scope3 Buyer Advertisers 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: Advertisers description: Manage advertisers paths: /advertisers: get: operationId: listAdvertisers summary: List advertisers description: List all advertisers with optional filtering and pagination. tags: - Advertisers security: - bearerAuth: [] parameters: - in: query name: status schema: description: Filter by advertiser status. Use ALL to include both active and archived. Defaults to ACTIVE. default: ACTIVE type: string enum: - ACTIVE - ARCHIVED - ALL description: Filter by advertiser status. Use ALL to include both active and archived. Defaults to ACTIVE. - in: query name: name schema: description: Filter by advertiser name (case-insensitive, partial match) example: Acme type: string description: Filter by advertiser name (case-insensitive, partial match) - in: query name: linkedAccountPartnerId schema: description: Filter to advertisers linked to at least one account from this partner / sales agent ID. example: snap type: string description: Filter to advertisers linked to at least one account from this partner / sales agent ID. - in: query name: sandbox schema: description: Filter by sandbox mode. true returns only sandbox advertisers, false returns only production advertisers. Omit to return all. type: boolean description: Filter by sandbox mode. true returns only sandbox advertisers, false returns only production advertisers. Omit to return all. - in: query name: includeBrand schema: description: When true, include linked brand identity data on advertiser summary rows so creative agents can use brand logos, colors, tone, and catalog data. type: boolean description: When true, include linked brand identity data on advertiser summary rows so creative agents can use brand logos, colors, tone, and catalog data. - in: query name: limit schema: description: 'Maximum number of advertisers to return per page (default: 100, max: 100)' example: 100 default: 100 type: integer maximum: 100 minimum: 1 description: 'Maximum number of advertisers to return per page (default: 100, max: 100)' - in: query name: offset schema: description: 'Number of advertisers to skip for pagination (default: 0)' example: 0 default: 0 type: integer minimum: 0 maximum: 9007199254740991 description: 'Number of advertisers to skip for pagination (default: 0)' responses: '200': description: List advertisers content: application/json: schema: $ref: '#/components/schemas/AdvertiserListResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: operationId: createAdvertiser summary: Create advertiser description: Create a new advertiser. Advertisers are the top-level entity for campaigns. tags: - Advertisers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAdvertiserBody' responses: '201': description: Create advertiser content: application/json: schema: $ref: '#/components/schemas/Advertiser' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /all-advertisers-home: get: operationId: listAllAdvertisersHome summary: List all advertisers home description: 'Pre-assembled data for the buyer "All Advertisers Landing" widget: advertiser rows (brand kit, campaign count, resumable-draft flag) plus a portfolio summary. Money rollups (`managed`/`tracked`) are always null pending AI-5642; `attention`/`nextAction` are omitted pending AI-5643.' tags: - Advertisers security: - bearerAuth: [] responses: '200': description: List all advertisers home content: application/json: schema: type: object properties: portfolio: type: object properties: tracked: type: string managed: type: string waitingOnYou: type: number required: - tracked - managed - waitingOnYou additionalProperties: false advertisers: type: array items: type: object properties: advertiserId: type: string name: type: string initials: type: string brandColors: type: object additionalProperties: type: string logoUrl: type: string logoTileColor: type: string logoFill: type: boolean managed: type: - string - 'null' tracked: type: - string - 'null' campaignCount: type: number resumableDraft: type: boolean attention: type: object properties: flags: type: array items: type: object properties: label: type: string tone: type: string enum: - critical - needsAction - info required: - label - tone additionalProperties: false required: - flags additionalProperties: false nextAction: type: object properties: label: type: string required: - label additionalProperties: false required: - advertiserId - name - initials - managed - tracked - campaignCount - resumableDraft additionalProperties: false currentAdvertiserId: type: string required: - portfolio - advertisers additionalProperties: false '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{advertiserId}: get: operationId: getAdvertiser summary: Get advertiser description: Get a single advertiser by ID. Always returns full brand details including the ADCP manifest. tags: - Advertisers security: - bearerAuth: [] parameters: - in: path name: advertiserId schema: description: Unique identifier for the advertiser example: '12345' type: string minLength: 1 required: true description: Unique identifier for the advertiser responses: '200': description: Get advertiser content: application/json: schema: $ref: '#/components/schemas/Advertiser' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' put: operationId: updateAdvertiser summary: Update advertiser description: Update an existing advertiser. tags: - Advertisers security: - bearerAuth: [] parameters: - in: path name: advertiserId schema: description: Unique identifier for the advertiser example: '12345' type: string minLength: 1 required: true description: Unique identifier for the advertiser requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAdvertiserBody' responses: '200': description: Update advertiser content: application/json: schema: $ref: '#/components/schemas/Advertiser' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: operationId: deleteAdvertiser summary: Delete advertiser description: Delete (archive) an advertiser. tags: - Advertisers security: - bearerAuth: [] parameters: - in: path name: advertiserId schema: description: Unique identifier for the advertiser example: '12345' type: string minLength: 1 required: true description: Unique identifier for the advertiser responses: '204': description: No content '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{advertiserId}/restore: post: operationId: restoreAdvertiser summary: Restore advertiser description: Restore a previously deleted (archived) advertiser, making it active again. tags: - Advertisers security: - bearerAuth: [] parameters: - in: path name: advertiserId schema: description: Unique identifier for the advertiser example: '12345' type: string minLength: 1 required: true description: Unique identifier for the advertiser responses: '200': description: Restore advertiser content: application/json: schema: $ref: '#/components/schemas/Advertiser' '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 archived advertiser with this id. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{advertiserId}/data-delivery-credentials/{name}/validate: post: operationId: revalidateDataDeliveryCredential summary: Revalidate data delivery credential description: Re-runs the destination Probe for a supported object-storage credential and returns the updated record with a fresh status (VALIDATED or FAILED). Use after fixing a buyer-side destination access issue (e.g., re-granting GCS bucket IAM) without otherwise editing the credential. tags: - Advertisers security: - bearerAuth: [] parameters: - in: path name: advertiserId schema: description: Advertiser ID (numeric, as a string). type: string minLength: 1 required: true description: Advertiser ID (numeric, as a string). - in: path name: name schema: description: Credential name (unique per advertiser). type: string minLength: 1 required: true description: Credential name (unique per advertiser). responses: '200': description: Revalidate data delivery credential content: application/json: schema: $ref: '#/components/schemas/RevalidateDataDeliveryCredentialResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{advertiserId}/accounts: get: operationId: listAdvertiserAccounts summary: List advertiser accounts description: List the sales-agent accounts already linked to an advertiser, with optional filtering by sales agent. tags: - Advertisers security: - bearerAuth: [] parameters: - in: query name: storefrontId schema: description: Filter accounts to those reachable through this storefront. Pair with `sourceId`. example: 42 type: integer maximum: 9007199254740991 minimum: 1 description: Filter accounts to those reachable through this storefront. Pair with `sourceId`. - in: query name: sourceId schema: description: Filter accounts to those reachable through this inventory source. Pair with `storefrontId`. example: src_main type: string minLength: 1 description: Filter accounts to those reachable through this inventory source. Pair with `storefrontId`. - in: query name: status schema: description: Filter by account status type: string enum: - active - pending_approval - payment_required - suspended - closed - unreachable description: Filter by account status - 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 - in: path name: advertiserId schema: description: Unique identifier for the advertiser example: '12345' type: string minLength: 1 required: true description: Unique identifier for the advertiser responses: '200': description: List advertiser accounts content: application/json: schema: $ref: '#/components/schemas/AccountListResponse' '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: assignAccount summary: Assign account description: Link a partner (source) account discovered via `list_available_accounts` to an advertiser. tags: - Advertisers security: - bearerAuth: [] parameters: - in: path name: advertiserId schema: description: Unique identifier for the advertiser example: '12345' type: string minLength: 1 required: true description: Unique identifier for the advertiser requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssignAccountBody' responses: '201': description: Assign account '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{advertiserId}/accounts/{accountId}: get: operationId: getAdvertiserAccount summary: Get advertiser account description: Get a single linked sales-agent account on an advertiser by its account id. tags: - Advertisers security: - bearerAuth: [] parameters: - in: path name: advertiserId schema: description: Unique identifier for the advertiser example: '12345' type: string minLength: 1 required: true description: Unique identifier for the advertiser - in: path name: accountId schema: description: Unique identifier for the account example: acc_67890 type: string minLength: 1 required: true description: Unique identifier for the account responses: '200': description: Get advertiser account content: application/json: schema: $ref: '#/components/schemas/AdvertiserAccount' '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 linked account with this id. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{advertiserId}/accounts/available: get: operationId: listAvailableAccounts summary: List available accounts description: Discover accounts available to link to an advertiser from a specific sales agent. tags: - Advertisers security: - bearerAuth: [] parameters: - in: query name: storefrontId schema: description: Storefront the source lives on. Pair with `sourceId` to identify the source whose accounts to list. example: 42 type: integer maximum: 9007199254740991 minimum: 1 required: true description: Storefront the source lives on. Pair with `sourceId` to identify the source whose accounts to list. - in: query name: sourceId schema: description: Inventory source within `storefrontId` whose accounts to list. example: src_main type: string minLength: 1 required: true description: Inventory source within `storefrontId` whose accounts to list. - in: query name: refresh schema: description: When true, re-fetches accounts from the source before returning results. Defaults to false (returns cached accounts). example: 'false' type: string enum: - 'true' - 'false' description: When true, re-fetches accounts from the source before returning results. Defaults to false (returns cached accounts). - in: query name: billingType schema: description: Billing arrangement type to filter accounts by (e.g. "advertiser", "operator", "agent"). Must be one of the values supported by this source. Defaults to the source's default billing type if omitted. example: advertiser type: string description: Billing arrangement type to filter accounts by (e.g. "advertiser", "operator", "agent"). Must be one of the values supported by this source. Defaults to the source's default billing type if omitted. - in: query name: credentialId schema: description: ID of a specific registered credential to use for account discovery. Required when the customer has multiple credentials registered for this source. Use GET /storefronts/credentials to list registered credentials and their IDs. example: '42' type: string description: ID of a specific registered credential to use for account discovery. Required when the customer has multiple credentials registered for this source. Use GET /storefronts/credentials to list registered credentials and their IDs. - in: query name: take schema: description: Number of results to return (max 250) example: 50 default: 50 type: integer 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 - in: path name: advertiserId schema: description: Unique identifier for the advertiser example: '12345' type: string minLength: 1 required: true description: Unique identifier for the advertiser responses: '200': description: List available accounts content: application/json: schema: $ref: '#/components/schemas/AvailableAccountListResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{advertiserId}/accounts/{linkId}: delete: operationId: unassignAccount summary: Unmap a partner account from an advertiser description: Soft-delete an advertiser-account link by its `linkId` (returned on mapping rows). The link is preserved for period history; buys for the advertiser on that platform fail with `account_mapping_required` until a new mapping is made. tags: - Advertisers security: - bearerAuth: [] parameters: - in: path name: advertiserId schema: description: Unique identifier for the advertiser example: '12345' type: string minLength: 1 required: true description: Unique identifier for the advertiser - in: path name: linkId schema: description: Identifier of the advertiser-account link row (numeric primary key) example: '42' type: string pattern: ^\d{1,15}$ required: true description: Identifier of the advertiser-account link row (numeric primary key) responses: '200': description: Unmap a partner account from an advertiser content: application/json: schema: $ref: '#/components/schemas/AccountUnlinked' '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 advertiser does not belong to the caller content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: The link does not exist or belongs to another advertiser content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{advertiserId}/accounts/{linkId}/reporting-bucket: put: operationId: updateAccountReportingBucket summary: Update account reporting bucket description: 'Set or clear the offline `reporting_bucket` configuration on a linked partner account, then notify the seller via `sync_accounts`. Pass `reporting_bucket: null` to clear the bucket.' tags: - Advertisers security: - bearerAuth: [] parameters: - in: path name: advertiserId schema: description: Unique identifier for the advertiser example: '12345' type: string minLength: 1 required: true description: Unique identifier for the advertiser - in: path name: linkId schema: description: Identifier of the advertiser-account link row (numeric primary key) example: '42' type: string pattern: ^\d{1,15}$ required: true description: Identifier of the advertiser-account link row (numeric primary key) requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateReportingBucketBody' responses: '200': description: Update account reporting bucket content: application/json: schema: $ref: '#/components/schemas/AccountResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{advertiserId}/catalogs: get: operationId: listCatalogs summary: List catalogs description: List catalogs that have been synced for an advertiser. tags: - Advertisers security: - bearerAuth: [] parameters: - in: query name: type schema: type: string enum: - offering - product - inventory - store - promotion - hotel - flight - job - vehicle - real_estate - education - destination - app - 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 - in: path name: advertiserId schema: description: Unique identifier for the advertiser example: '12345' type: string minLength: 1 required: true description: Unique identifier for the advertiser responses: '200': description: List catalogs content: application/json: schema: type: object properties: catalogs: type: array items: type: object properties: catalogId: type: string platformId: type: string type: type: string enum: - offering - product - inventory - store - promotion - hotel - flight - job - vehicle - real_estate - education - destination - app sourceType: type: string enum: - inline - url - selector name: type: - string - 'null' url: type: - string - 'null' feedFormat: type: - string - 'null' enum: - google_merchant_center - facebook_catalog - shopify - linkedin_jobs - tiktok_shop - pinterest_catalog - openai_product_feed - custom updateFrequency: type: - string - 'null' enum: - realtime - hourly - daily - weekly itemCount: type: integer minimum: 0 maximum: 9007199254740991 syncStatus: description: Raw ingest/sync state for this catalog type: string enum: - pending - syncing - synced - failed - not_synced healthStatus: description: Operational health derived from sync state and freshness windows type: string enum: - not_synced - healthy - stale - warning - failed latestVersionId: type: - string - 'null' latestVersionNumber: type: - integer - 'null' maximum: 9007199254740991 minimum: 1 latestContentHash: type: - string - 'null' activeTransformId: type: - string - 'null' latestActivationPlanId: type: - string - 'null' lastChangeSummary: type: object properties: added: default: 0 type: integer minimum: 0 maximum: 9007199254740991 updated: default: 0 type: integer minimum: 0 maximum: 9007199254740991 unchanged: default: 0 type: integer minimum: 0 maximum: 9007199254740991 removed: default: 0 type: integer minimum: 0 maximum: 9007199254740991 required: - added - updated - unchanged - removed additionalProperties: false lastSyncAttemptAt: type: - string - 'null' 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))$ lastSyncedAt: type: - string - 'null' 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))$ nextSyncAt: type: - string - 'null' 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))$ staleAfterAt: type: - string - 'null' 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))$ versions: type: array items: type: object properties: versionId: type: string versionNumber: type: integer maximum: 9007199254740991 minimum: 1 itemCount: type: integer minimum: 0 maximum: 9007199254740991 contentHash: type: string changeSummary: type: object properties: added: default: 0 type: integer minimum: 0 maximum: 9007199254740991 updated: default: 0 type: integer minimum: 0 maximum: 9007199254740991 unchanged: default: 0 type: integer minimum: 0 maximum: 9007199254740991 removed: default: 0 type: integer minimum: 0 maximum: 9007199254740991 required: - added - updated - unchanged - removed additionalProperties: false syncStatus: type: string enum: - pending - syncing - synced - failed - not_synced createdAt: 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))$ completedAt: type: - string - 'null' 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: - versionId - versionNumber - itemCount - contentHash - changeSummary - syncStatus - createdAt - completedAt additionalProperties: false recentRefreshRuns: type: array items: type: object properties: refreshRunId: type: string status: type: string enum: - syncing - synced - unchanged - failed httpStatus: type: - integer - 'null' minimum: -9007199254740991 maximum: 9007199254740991 itemCount: type: - integer - 'null' minimum: 0 maximum: 9007199254740991 activationSkippedReason: type: - string - 'null' error: type: - string - 'null' startedAt: 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))$ completedAt: type: - string - 'null' 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: - refreshRunId - status - httpStatus - itemCount - activationSkippedReason - error - startedAt - completedAt additionalProperties: false recentActivationExecutions: type: array items: type: object properties: executionId: type: string planId: type: - string - 'null' catalogVersionId: type: - string - 'null' status: type: string enum: - pending - completed - failed trigger: type: string enum: - manual - feed_refresh - scheduled campaignGroupCount: type: integer minimum: 0 maximum: 9007199254740991 creativeAssetCount: type: integer minimum: 0 maximum: 9007199254740991 syndicationTargetCount: type: integer minimum: 0 maximum: 9007199254740991 error: type: - string - 'null' startedAt: 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))$ completedAt: type: - string - 'null' 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: - executionId - planId - catalogVersionId - status - trigger - campaignGroupCount - creativeAssetCount - syndicationTargetCount - error - startedAt - completedAt additionalProperties: false advertiserId: type: string required: - catalogId - platformId - type - sourceType - name - url - feedFormat - updateFrequency - itemCount - syncStatus - healthStatus - latestVersionId - latestVersionNumber - latestContentHash - activeTransformId - latestActivationPlanId - lastChangeSummary - lastSyncAttemptAt - lastSyncedAt - nextSyncAt - staleAfterAt - versions - recentRefreshRuns - recentActivationExecutions - advertiserId additionalProperties: false total: type: integer minimum: 0 maximum: 9007199254740991 required: - catalogs - total additionalProperties: false '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{advertiserId}/catalogs/sync: post: operationId: syncCatalogs summary: Sync catalogs description: Inbound ADCP sync_catalogs endpoint. Buyers call this to sync their catalogs and items to the advertiser. tags: - Advertisers security: - bearerAuth: [] parameters: - in: path name: advertiserId schema: description: Unique identifier for the advertiser example: '12345' type: string minLength: 1 required: true description: Unique identifier for the advertiser requestBody: required: true content: application/json: schema: type: object properties: account: description: Advertiser account to sync catalogs onto type: object properties: account_id: description: Advertiser ID to attach catalogs to example: '12345' type: string minLength: 1 required: - account_id catalogs: description: Catalog feeds to sync (up to 50 per call) minItems: 1 maxItems: 50 type: array items: type: object properties: catalog_id: description: Buyer-assigned catalog identifier example: my-summer-products type: string minLength: 1 type: type: string enum: - offering - product - inventory - store - promotion - hotel - flight - job - vehicle - real_estate - education - destination - app name: description: Display name for the catalog example: Summer Sale 2026 type: string minLength: 1 maxLength: 255 url: description: Remote feed URL (provide this or items, not both) example: https://feeds.example.com/products.xml type: string format: uri feed_format: type: string enum: - google_merchant_center - facebook_catalog - shopify - linkedin_jobs - tiktok_shop - pinterest_catalog - openai_product_feed - custom update_frequency: type: string enum: - realtime - hourly - daily - weekly items: description: Inline catalog items (provide this or url, not both) maxItems: 10000 type: array items: description: An individual catalog item (product, offering, job, etc.) type: object additionalProperties: {} conversion_events: description: Conversion event IDs linked to this catalog example: - purchase - add_to_cart type: array items: type: string required: - catalog_id - type catalog_ids: description: 'Optional: only process these catalog_ids from the catalogs array' type: array items: type: string delete_missing: description: Archive buyer-managed catalogs not included in this request default: false type: boolean dry_run: description: Preview changes without persisting to the database default: false type: boolean validation_mode: description: Item validation strictness default: strict type: string enum: - strict - lenient required: - account - catalogs responses: '200': description: Sync catalogs content: application/json: schema: type: object properties: catalogs: type: array items: type: object properties: catalog_id: type: string action: type: string enum: - created - updated - unchanged - failed - deleted platform_id: type: string catalog_version_id: type: string catalog_version_number: type: integer maximum: 9007199254740991 minimum: 1 content_hash: type: string item_count: type: integer minimum: 0 maximum: 9007199254740991 items_approved: type: integer minimum: 0 maximum: 9007199254740991 items_pending: type: integer minimum: 0 maximum: 9007199254740991 items_rejected: type: integer minimum: 0 maximum: 9007199254740991 item_changes: type: object properties: added: default: 0 type: integer minimum: 0 maximum: 9007199254740991 updated: default: 0 type: integer minimum: 0 maximum: 9007199254740991 unchanged: default: 0 type: integer minimum: 0 maximum: 9007199254740991 removed: default: 0 type: integer minimum: 0 maximum: 9007199254740991 required: - added - updated - unchanged - removed additionalProperties: false health_status: type: string enum: - not_synced - healthy - stale - warning - failed activation_plan_id: type: string item_issues: type: array items: type: object properties: item_id: type: string field: type: string issue: type: string severity: type: string enum: - error - warning required: - issue additionalProperties: false last_synced_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ next_fetch_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ error: type: string required: - catalog_id - action additionalProperties: false dry_run: type: boolean required: - catalogs additionalProperties: false '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{advertiserId}/catalogs/{catalogId}/transform: put: operationId: saveCatalogTransform summary: Save catalog transform description: Save the active deterministic transform that maps catalog feed items into campaign groups, creative prompt cache keys, and budget hints. tags: - Advertisers security: - bearerAuth: [] parameters: - in: path name: advertiserId schema: description: Advertiser ID type: string minLength: 1 required: true description: Advertiser ID - in: path name: catalogId schema: description: Buyer-assigned catalog_id or platform catalog id returned by list catalogs type: string minLength: 1 required: true description: Buyer-assigned catalog_id or platform catalog id returned by list catalogs requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 255 transform: type: object properties: fields: default: [] type: array items: type: object properties: key: description: Derived field key made available to grouping and template rules example: city type: string minLength: 1 pattern: ^[A-Za-z][A-Za-z0-9_]*$ source: description: Dot-path into the raw catalog item, for example location.city example: location.city type: string minLength: 1 template: description: Template using {{field}} placeholders from raw or derived fields example: '{{title}} in {{city}}' type: string minLength: 1 default: description: Fallback value when source or template resolves empty transform: description: Optional deterministic value normalization type: string enum: - string - lowercase - uppercase - title_case - slug required: - key campaign: type: object properties: groupBy: description: Field references used to create campaign groups, usually derived fields such as city example: - city minItems: 1 type: array items: type: string minLength: 1 keyTemplate: description: Optional campaign group key template example: loetje-jobs-{{citySlug}} type: string minLength: 1 nameTemplate: description: Human-readable campaign name template example: Loetje hiring - {{city}} type: string minLength: 1 budget: oneOf: - type: object properties: mode: type: string enum: - none required: - mode - type: object properties: mode: type: string enum: - fixed amount: type: number minimum: 0 currency: default: USD type: string minLength: 3 maxLength: 3 required: - mode - amount - type: object properties: mode: type: string enum: - per_item amountPerItem: type: number minimum: 0 currency: default: USD type: string minLength: 3 maxLength: 3 required: - mode - amountPerItem - type: object properties: mode: type: string enum: - field_sum field: type: string minLength: 1 multiplier: default: 1 type: number currency: default: USD type: string minLength: 3 maxLength: 3 required: - mode - field type: object required: - groupBy creativeAssets: default: [] type: array items: type: object properties: keyTemplate: description: Stable creative asset cache key template. Assets with the same key can reuse generated media. example: loetje-chef-{{jobCategorySlug}} type: string minLength: 1 promptTemplate: description: Prompt template used by the creative generation path example: Generate a chef working in a Loetje kitchen for a {{jobCategory}} hiring ad type: string minLength: 1 groupBy: description: Field references used to fan out unique creative asset prompts example: - jobCategory default: [] type: array items: type: string minLength: 1 required: - keyTemplate - promptTemplate required: - transform responses: '200': description: Save catalog transform content: application/json: schema: type: object properties: transform: type: object properties: transformId: type: string catalogId: type: string platformCatalogId: type: string name: type: string status: type: string enum: - active - archived definitionHash: type: string definition: type: object properties: fields: default: [] type: array items: type: object properties: key: description: Derived field key made available to grouping and template rules example: city type: string minLength: 1 pattern: ^[A-Za-z][A-Za-z0-9_]*$ source: description: Dot-path into the raw catalog item, for example location.city example: location.city type: string minLength: 1 template: description: Template using {{field}} placeholders from raw or derived fields example: '{{title}} in {{city}}' type: string minLength: 1 default: description: Fallback value when source or template resolves empty transform: description: Optional deterministic value normalization type: string enum: - string - lowercase - uppercase - title_case - slug required: - key additionalProperties: false campaign: type: object properties: groupBy: description: Field references used to create campaign groups, usually derived fields such as city example: - city minItems: 1 type: array items: type: string minLength: 1 keyTemplate: description: Optional campaign group key template example: loetje-jobs-{{citySlug}} type: string minLength: 1 nameTemplate: description: Human-readable campaign name template example: Loetje hiring - {{city}} type: string minLength: 1 budget: oneOf: - type: object properties: mode: type: string enum: - none required: - mode additionalProperties: false - type: object properties: mode: type: string enum: - fixed amount: type: number minimum: 0 currency: default: USD type: string minLength: 3 maxLength: 3 required: - mode - amount - currency additionalProperties: false - type: object properties: mode: type: string enum: - per_item amountPerItem: type: number minimum: 0 currency: default: USD type: string minLength: 3 maxLength: 3 required: - mode - amountPerItem - currency additionalProperties: false - type: object properties: mode: type: string enum: - field_sum field: type: string minLength: 1 multiplier: default: 1 type: number currency: default: USD type: string minLength: 3 maxLength: 3 required: - mode - field - multiplier - currency additionalProperties: false type: object required: - groupBy additionalProperties: false creativeAssets: default: [] type: array items: type: object properties: keyTemplate: description: Stable creative asset cache key template. Assets with the same key can reuse generated media. example: loetje-chef-{{jobCategorySlug}} type: string minLength: 1 promptTemplate: description: Prompt template used by the creative generation path example: Generate a chef working in a Loetje kitchen for a {{jobCategory}} hiring ad type: string minLength: 1 groupBy: description: Field references used to fan out unique creative asset prompts example: - jobCategory default: [] type: array items: type: string minLength: 1 required: - keyTemplate - promptTemplate - groupBy additionalProperties: false required: - fields - creativeAssets additionalProperties: false createdAt: 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: 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: - transformId - catalogId - platformCatalogId - name - status - definitionHash - definition - createdAt - updatedAt additionalProperties: false required: - transform additionalProperties: false '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{advertiserId}/catalogs/{catalogId}/activation-plan/preview: post: operationId: previewCatalogActivationPlan summary: Preview catalog activation plan description: Preview or persist the activation plan produced from the current catalog items and a catalog transform. tags: - Advertisers security: - bearerAuth: [] parameters: - in: path name: advertiserId schema: description: Advertiser ID type: string minLength: 1 required: true description: Advertiser ID - in: path name: catalogId schema: description: Buyer-assigned catalog_id or platform catalog id returned by list catalogs type: string minLength: 1 required: true description: Buyer-assigned catalog_id or platform catalog id returned by list catalogs requestBody: required: true content: application/json: schema: type: object properties: transform: description: Optional ad hoc transform. If omitted, the active catalog transform is used. type: object properties: fields: default: [] type: array items: type: object properties: key: description: Derived field key made available to grouping and template rules example: city type: string minLength: 1 pattern: ^[A-Za-z][A-Za-z0-9_]*$ source: description: Dot-path into the raw catalog item, for example location.city example: location.city type: string minLength: 1 template: description: Template using {{field}} placeholders from raw or derived fields example: '{{title}} in {{city}}' type: string minLength: 1 default: description: Fallback value when source or template resolves empty transform: description: Optional deterministic value normalization type: string enum: - string - lowercase - uppercase - title_case - slug required: - key campaign: type: object properties: groupBy: description: Field references used to create campaign groups, usually derived fields such as city example: - city minItems: 1 type: array items: type: string minLength: 1 keyTemplate: description: Optional campaign group key template example: loetje-jobs-{{citySlug}} type: string minLength: 1 nameTemplate: description: Human-readable campaign name template example: Loetje hiring - {{city}} type: string minLength: 1 budget: oneOf: - type: object properties: mode: type: string enum: - none required: - mode - type: object properties: mode: type: string enum: - fixed amount: type: number minimum: 0 currency: default: USD type: string minLength: 3 maxLength: 3 required: - mode - amount - type: object properties: mode: type: string enum: - per_item amountPerItem: type: number minimum: 0 currency: default: USD type: string minLength: 3 maxLength: 3 required: - mode - amountPerItem - type: object properties: mode: type: string enum: - field_sum field: type: string minLength: 1 multiplier: default: 1 type: number currency: default: USD type: string minLength: 3 maxLength: 3 required: - mode - field type: object required: - groupBy creativeAssets: default: [] type: array items: type: object properties: keyTemplate: description: Stable creative asset cache key template. Assets with the same key can reuse generated media. example: loetje-chef-{{jobCategorySlug}} type: string minLength: 1 promptTemplate: description: Prompt template used by the creative generation path example: Generate a chef working in a Loetje kitchen for a {{jobCategory}} hiring ad type: string minLength: 1 groupBy: description: Field references used to fan out unique creative asset prompts example: - jobCategory default: [] type: array items: type: string minLength: 1 required: - keyTemplate - promptTemplate adcpAgentIds: description: Optional seller agents to evaluate for upstream catalog/creative syndication. If omitted, enabled catalog syndication targets are used. default: [] type: array items: type: string minLength: 1 save: description: Persist this activation plan against the latest catalog version. Requires an active saved transform when transform is omitted. default: false type: boolean responses: '200': description: Preview catalog activation plan content: application/json: schema: type: object properties: plan: type: object properties: planId: type: - string - 'null' catalogId: type: string platformCatalogId: type: string catalogVersionId: type: - string - 'null' transformId: type: - string - 'null' planHash: type: string itemCount: type: integer minimum: 0 maximum: 9007199254740991 campaignGroups: type: array items: type: object properties: key: type: string name: type: string fieldValues: type: object additionalProperties: {} itemIds: type: array items: type: string itemCount: type: integer minimum: 0 maximum: 9007199254740991 budget: type: - object - 'null' properties: amount: type: number minimum: 0 currency: type: string minLength: 3 maxLength: 3 required: - amount - currency additionalProperties: false required: - key - name - fieldValues - itemIds - itemCount - budget additionalProperties: false creativeAssets: type: array items: type: object properties: key: type: string prompt: type: string fieldValues: type: object additionalProperties: {} itemIds: type: array items: type: string itemCount: type: integer minimum: 0 maximum: 9007199254740991 required: - key - prompt - fieldValues - itemIds - itemCount additionalProperties: false syndicationTargets: type: array items: type: object properties: adcpAgentId: type: string shareStatus: type: string enum: - ready - unsupported deliveryMode: type: string enum: - native_catalog - native_creative_catalog - assembled_creative - third_party_creative_agent - unsupported usesTransformedCatalog: type: boolean requiresCreativeAssembly: type: boolean creativeAgentId: type: - string - 'null' reason: type: string required: - adcpAgentId - shareStatus - deliveryMode - usesTransformedCatalog - requiresCreativeAssembly - creativeAgentId - reason additionalProperties: false createdAt: type: - string - 'null' 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: - planId - catalogId - platformCatalogId - catalogVersionId - transformId - planHash - itemCount - campaignGroups - creativeAssets - syndicationTargets - createdAt additionalProperties: false required: - plan additionalProperties: false '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{advertiserId}/catalogs/{catalogId}/refresh: post: operationId: refreshCatalog summary: Refresh catalog description: Fetch the latest URL-backed catalog feed, create a new version when content changes, and optionally execute the active activation plan. tags: - Advertisers security: - bearerAuth: [] parameters: - in: path name: advertiserId schema: description: Advertiser ID type: string minLength: 1 required: true description: Advertiser ID - in: path name: catalogId schema: description: Buyer-assigned catalog_id or platform catalog id returned by list catalogs type: string minLength: 1 required: true description: Buyer-assigned catalog_id or platform catalog id returned by list catalogs requestBody: required: true content: application/json: schema: type: object properties: executeActivation: description: When true, a successful refresh with an active transform immediately saves/executes the latest activation plan, creating creative-generation and syndication jobs. default: false type: boolean adcpAgentIds: description: Optional seller agents to evaluate/execute for activation after refresh. If omitted, enabled catalog syndication targets are used. default: [] type: array items: type: string minLength: 1 responses: '200': description: Refresh catalog content: application/json: schema: type: object properties: catalog: type: object properties: catalog_id: type: string action: type: string enum: - created - updated - unchanged - failed - deleted platform_id: type: string catalog_version_id: type: string catalog_version_number: type: integer maximum: 9007199254740991 minimum: 1 content_hash: type: string item_count: type: integer minimum: 0 maximum: 9007199254740991 items_approved: type: integer minimum: 0 maximum: 9007199254740991 items_pending: type: integer minimum: 0 maximum: 9007199254740991 items_rejected: type: integer minimum: 0 maximum: 9007199254740991 item_changes: type: object properties: added: default: 0 type: integer minimum: 0 maximum: 9007199254740991 updated: default: 0 type: integer minimum: 0 maximum: 9007199254740991 unchanged: default: 0 type: integer minimum: 0 maximum: 9007199254740991 removed: default: 0 type: integer minimum: 0 maximum: 9007199254740991 required: - added - updated - unchanged - removed additionalProperties: false health_status: type: string enum: - not_synced - healthy - stale - warning - failed activation_plan_id: type: string item_issues: type: array items: type: object properties: item_id: type: string field: type: string issue: type: string severity: type: string enum: - error - warning required: - issue additionalProperties: false last_synced_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ next_fetch_at: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ error: type: string required: - catalog_id - action additionalProperties: false refreshRun: type: object properties: refreshRunId: type: string status: type: string enum: - syncing - synced - unchanged - failed httpStatus: type: - integer - 'null' minimum: -9007199254740991 maximum: 9007199254740991 sourceContentHash: type: - string - 'null' itemCount: type: - integer - 'null' minimum: 0 maximum: 9007199254740991 activationSkippedReason: type: - string - 'null' error: type: - string - 'null' startedAt: 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))$ completedAt: type: - string - 'null' 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: - refreshRunId - status - httpStatus - sourceContentHash - itemCount - activationSkippedReason - error - startedAt - completedAt additionalProperties: false activation: type: - object - 'null' properties: plan: type: object properties: planId: type: - string - 'null' catalogId: type: string platformCatalogId: type: string catalogVersionId: type: - string - 'null' transformId: type: - string - 'null' planHash: type: string itemCount: type: integer minimum: 0 maximum: 9007199254740991 campaignGroups: type: array items: type: object properties: key: type: string name: type: string fieldValues: type: object additionalProperties: {} itemIds: type: array items: type: string itemCount: type: integer minimum: 0 maximum: 9007199254740991 budget: type: - object - 'null' properties: amount: type: number minimum: 0 currency: type: string minLength: 3 maxLength: 3 required: - amount - currency additionalProperties: false required: - key - name - fieldValues - itemIds - itemCount - budget additionalProperties: false creativeAssets: type: array items: type: object properties: key: type: string prompt: type: string fieldValues: type: object additionalProperties: {} itemIds: type: array items: type: string itemCount: type: integer minimum: 0 maximum: 9007199254740991 required: - key - prompt - fieldValues - itemIds - itemCount additionalProperties: false syndicationTargets: type: array items: type: object properties: adcpAgentId: type: string shareStatus: type: string enum: - ready - unsupported deliveryMode: type: string enum: - native_catalog - native_creative_catalog - assembled_creative - third_party_creative_agent - unsupported usesTransformedCatalog: type: boolean requiresCreativeAssembly: type: boolean creativeAgentId: type: - string - 'null' reason: type: string required: - adcpAgentId - shareStatus - deliveryMode - usesTransformedCatalog - requiresCreativeAssembly - creativeAgentId - reason additionalProperties: false createdAt: type: - string - 'null' 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: - planId - catalogId - platformCatalogId - catalogVersionId - transformId - planHash - itemCount - campaignGroups - creativeAssets - syndicationTargets - createdAt additionalProperties: false execution: type: object properties: executionId: type: string planId: type: - string - 'null' catalogId: type: string platformCatalogId: type: string catalogVersionId: type: - string - 'null' transformId: type: - string - 'null' status: type: string enum: - pending - completed - failed trigger: type: string enum: - manual - feed_refresh - scheduled steps: type: array items: type: object properties: stepId: type: string stepType: type: string enum: - campaign_activation_request - sync_catalogs - sync_creatives - creative_generation_request - third_party_creative_agent - unsupported status: type: string enum: - pending - completed - failed - skipped targetAdcpAgentId: type: - string - 'null' creativeAssetKey: type: - string - 'null' campaignGroupKey: type: - string - 'null' error: type: - string - 'null' required: - stepId - stepType - status - targetAdcpAgentId - creativeAssetKey - campaignGroupKey - error additionalProperties: false creativeGenerationRequests: type: array items: type: object properties: requestId: type: string creativeAssetKey: type: string prompt: type: string targetAdcpAgentId: type: - string - 'null' creativeAgentId: type: - string - 'null' status: type: string enum: - pending - processing - completed - failed - skipped required: - requestId - creativeAssetKey - prompt - targetAdcpAgentId - creativeAgentId - status additionalProperties: false startedAt: 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))$ completedAt: type: - string - 'null' 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: - executionId - planId - catalogId - platformCatalogId - catalogVersionId - transformId - status - trigger - steps - creativeGenerationRequests - startedAt - completedAt additionalProperties: false required: - plan - execution additionalProperties: false required: - catalog - refreshRun - activation additionalProperties: false '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{advertiserId}/catalogs/{catalogId}/activation-plan/execute: post: operationId: executeCatalogActivationPlan summary: Execute catalog activation plan description: Execute a saved or newly built catalog activation plan, creating downstream campaign, creative-generation, and syndication jobs. tags: - Advertisers security: - bearerAuth: [] parameters: - in: path name: advertiserId schema: description: Advertiser ID type: string minLength: 1 required: true description: Advertiser ID - in: path name: catalogId schema: description: Buyer-assigned catalog_id or platform catalog id returned by list catalogs type: string minLength: 1 required: true description: Buyer-assigned catalog_id or platform catalog id returned by list catalogs requestBody: required: true content: application/json: schema: type: object properties: planId: description: Optional saved activation plan id. If omitted, the latest saved plan is used, or a plan is created from the active transform. type: string minLength: 1 adcpAgentIds: description: Optional seller agents to evaluate/execute. If omitted, enabled catalog syndication targets are used. default: [] type: array items: type: string minLength: 1 dryRun: description: When true, build and return the execution plan without creating durable downstream jobs. default: false type: boolean responses: '200': description: Execute catalog activation plan content: application/json: schema: type: object properties: plan: type: object properties: planId: type: - string - 'null' catalogId: type: string platformCatalogId: type: string catalogVersionId: type: - string - 'null' transformId: type: - string - 'null' planHash: type: string itemCount: type: integer minimum: 0 maximum: 9007199254740991 campaignGroups: type: array items: type: object properties: key: type: string name: type: string fieldValues: type: object additionalProperties: {} itemIds: type: array items: type: string itemCount: type: integer minimum: 0 maximum: 9007199254740991 budget: type: - object - 'null' properties: amount: type: number minimum: 0 currency: type: string minLength: 3 maxLength: 3 required: - amount - currency additionalProperties: false required: - key - name - fieldValues - itemIds - itemCount - budget additionalProperties: false creativeAssets: type: array items: type: object properties: key: type: string prompt: type: string fieldValues: type: object additionalProperties: {} itemIds: type: array items: type: string itemCount: type: integer minimum: 0 maximum: 9007199254740991 required: - key - prompt - fieldValues - itemIds - itemCount additionalProperties: false syndicationTargets: type: array items: type: object properties: adcpAgentId: type: string shareStatus: type: string enum: - ready - unsupported deliveryMode: type: string enum: - native_catalog - native_creative_catalog - assembled_creative - third_party_creative_agent - unsupported usesTransformedCatalog: type: boolean requiresCreativeAssembly: type: boolean creativeAgentId: type: - string - 'null' reason: type: string required: - adcpAgentId - shareStatus - deliveryMode - usesTransformedCatalog - requiresCreativeAssembly - creativeAgentId - reason additionalProperties: false createdAt: type: - string - 'null' 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: - planId - catalogId - platformCatalogId - catalogVersionId - transformId - planHash - itemCount - campaignGroups - creativeAssets - syndicationTargets - createdAt additionalProperties: false execution: type: object properties: executionId: type: string planId: type: - string - 'null' catalogId: type: string platformCatalogId: type: string catalogVersionId: type: - string - 'null' transformId: type: - string - 'null' status: type: string enum: - pending - completed - failed trigger: type: string enum: - manual - feed_refresh - scheduled steps: type: array items: type: object properties: stepId: type: string stepType: type: string enum: - campaign_activation_request - sync_catalogs - sync_creatives - creative_generation_request - third_party_creative_agent - unsupported status: type: string enum: - pending - completed - failed - skipped targetAdcpAgentId: type: - string - 'null' creativeAssetKey: type: - string - 'null' campaignGroupKey: type: - string - 'null' error: type: - string - 'null' required: - stepId - stepType - status - targetAdcpAgentId - creativeAssetKey - campaignGroupKey - error additionalProperties: false creativeGenerationRequests: type: array items: type: object properties: requestId: type: string creativeAssetKey: type: string prompt: type: string targetAdcpAgentId: type: - string - 'null' creativeAgentId: type: - string - 'null' status: type: string enum: - pending - processing - completed - failed - skipped required: - requestId - creativeAssetKey - prompt - targetAdcpAgentId - creativeAgentId - status additionalProperties: false startedAt: 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))$ completedAt: type: - string - 'null' 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: - executionId - planId - catalogId - platformCatalogId - catalogVersionId - transformId - status - trigger - steps - creativeGenerationRequests - startedAt - completedAt additionalProperties: false required: - plan - execution additionalProperties: false '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{accountId}/audiences/sync: post: operationId: syncAudiences summary: Sync audiences description: Sync first-party CRM audiences for an account. Processing is asynchronous — returns 202 with an operation ID. tags: - Advertisers security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SyncAudiencesBody' responses: '202': description: Sync audiences content: application/json: schema: $ref: '#/components/schemas/SyncAudiencesResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /advertisers/{accountId}/audiences: get: operationId: listAudiences summary: List audiences description: List stored audience metadata for an account. tags: - Advertisers security: - bearerAuth: [] parameters: - in: query name: take schema: description: Number of results to return (max 250) example: 50 default: 50 type: integer 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 audiences content: application/json: schema: $ref: '#/components/schemas/AudienceListResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: AzureBlobAuthInput: description: How Scope3 authenticates to the buyer-owned Azure Blob container. SAS_TOKEN uses a container-scoped Shared Access Signature. oneOf: - $ref: '#/components/schemas/AzureBlobSasAuthInput' type: object discriminator: propertyName: mode mapping: SAS_TOKEN: '#/components/schemas/AzureBlobSasAuthInput' 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' AvailableAccountListResponse: description: Response containing a list of available accounts from a partner type: object properties: accounts: description: List of available (discovered) accounts type: array items: $ref: '#/components/schemas/AvailableAccountOutput' total: description: Total count of available accounts example: 8 type: integer minimum: 0 maximum: 9007199254740991 synced: description: True when no accounts matched and a sync_accounts call was automatically triggered to provision this account at the partner. The list reflects the post-sync state. type: boolean billingOptions: description: Billing options supported by this partner agent, as reported in its ADCP capabilities. type: object properties: default: type: - string - 'null' supported: type: array items: type: string required: - default - supported additionalProperties: false required: - accounts - total additionalProperties: false 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: {} RevalidateDataDeliveryCredentialResponse: description: Updated credential after re-running the destination Probe. type: object properties: credential: $ref: '#/components/schemas/DataDeliveryCredential' required: - credential additionalProperties: false UpdateReportingBucketBody: description: Request body for updating the offline reporting bucket on a linked partner account type: object properties: reporting_bucket: description: Reporting bucket configuration to set on the linked account, or null to clear it. allOf: - $ref: '#/components/schemas/ReportingBucket' required: - reporting_bucket LinkedAccountInput: description: An account to link to the advertiser type: object properties: storefrontId: description: Storefront the source lives on. Pair with `sourceId` to identify the source whose account is being linked. example: 42 type: integer maximum: 9007199254740991 minimum: 1 sourceId: description: Inventory source within `storefrontId` whose account is being linked. example: src_main type: string minLength: 1 accountId: description: Account ID at the source to link to this advertiser. Must come from `list_available_accounts`. example: acc_123 type: string minLength: 1 credentialId: description: Credential ID returned by `list_available_accounts`. Include it when multiple mapped connections expose the same account ID. example: '42' type: string billingType: description: Billing arrangement type (e.g. "advertiser", "operator", "agent") example: advertiser type: string required: - storefrontId - sourceId - accountId GcsCredentialConfig: type: object properties: type: type: string enum: - GCS bucket: description: Target GCS bucket the Probe writes to and Data Delivery Outputs ship objects into. The Scope3 service account must have objectCreator on this bucket. type: string minLength: 1 maxLength: 222 pattern: ^[a-z0-9][a-z0-9._-]*[a-z0-9]$ required: - type - bucket AudienceListResponse: description: Paginated list of audience summaries type: object properties: audiences: type: array items: $ref: '#/components/schemas/AudienceSummary' total: type: number take: type: number skip: type: number required: - audiences - total - take - skip additionalProperties: false Advertiser: description: Advertiser resource representation type: object properties: id: description: Unique identifier for the advertiser example: '12345' type: string name: description: Name of the advertiser example: Acme Corp type: string description: description: Description of the advertiser example: Global advertising account for Acme Corporation type: string status: description: Current status of the advertiser type: string enum: - ACTIVE - ARCHIVED createdAt: description: When the advertiser 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 advertiser 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))$ linkedBrand: description: The brand linked to this advertiser. Only present when includeBrand=true is passed to the list endpoint. type: object properties: id: description: Brand ID example: brand_123 type: string name: description: Brand name example: Acme Brand type: string domain: description: Brand domain example: acme.com type: string manifest: description: Full resolved brand identity data — includes logos, colors, fonts, tone, tagline, assets, product catalog, disclaimers, and more allOf: - $ref: '#/components/schemas/BrandManifestJson' logoUrl: description: Primary brand logo URL example: https://acme.com/logo.png type: string industry: description: Brand industry example: Technology type: string colors: description: Brand color palette example: primary: '#FF5733' type: object additionalProperties: type: string tagline: description: Brand tagline example: Innovation for Everyone type: string tone: description: Brand voice and tone example: Professional, friendly, and innovative type: string required: - id - name - domain - manifest additionalProperties: false brand: description: The brand domain associated with this advertiser example: nike.com type: string brandWarning: description: Warning about brand resolution (e.g., manifest not found) type: string sandbox: description: When true, this advertiser is in sandbox mode. All ADCP operations use sandbox-flagged accounts. Cannot be changed after creation. type: boolean optimizationApplyMode: description: Default mode for applying Scope3 AI model optimizations to media buys for campaigns under this advertiser. When set to "AUTO", optimizations are applied automatically; when "MANUAL", they require approval. allOf: - $ref: '#/components/schemas/OptimizationApplyMode' primaryCurrency: description: Primary ISO 4217 currency for this advertiser. Every campaign under this advertiser is created in this currency, and selected product pricing must match it. example: USD type: string minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ currencyLocked: description: True once the advertiser has at least one campaign. While false, `primaryCurrency` can still be changed; once true it is locked. type: boolean linkedAccounts: description: Linked partner accounts for this advertiser. Only present when includeAccounts=true is passed to the list endpoint. type: array items: $ref: '#/components/schemas/LinkedAccount' utmConfig: description: Advertiser-level UTM parameter configuration. Only present when UTM params are configured for this advertiser. type: array items: type: object properties: paramKey: description: Output query parameter key example: utm_campaign type: string paramValue: description: Macro or static value example: '{CAMPAIGN_ID}' type: string source: description: Where this param was configured — "advertiser" for advertiser default, "campaign" for campaign override type: string enum: - advertiser - campaign required: - paramKey - paramValue - source additionalProperties: false dataDelivery: $ref: '#/components/schemas/AdvertiserDataDelivery' frequencyCaps: description: Buyer-side frequency cap configs for this advertiser. Always present on single-GET; on LIST only when includeFrequencyCaps=true. type: array items: $ref: '#/components/schemas/FrequencyCapConfig' required: - id - name - status - createdAt - updatedAt - sandbox - optimizationApplyMode - primaryCurrency - currencyLocked additionalProperties: false RemoveMember: description: Member to remove from the audience type: object properties: externalId: description: Unique identifier for this member within the audience type: string minLength: 1 hashedEmail: description: SHA-256 hash of lowercase, trimmed email (64-char hex) example: a1b2c3d4e5f6... type: string pattern: ^[0-9a-f]{64}$ hashedPhone: description: SHA-256 hash of E.164-formatted phone number (64-char hex) example: f6e5d4c3b2a1... type: string pattern: ^[0-9a-f]{64}$ uids: description: Universal IDs for user matching minItems: 1 type: array items: type: object properties: type: description: Universal ID type (rampid, uid2, maid, etc.) type: string minLength: 1 value: description: Universal ID value type: string minLength: 1 required: - type - value required: - externalId ReportingBucket: description: Customer-owned object storage bucket where sales agents can write offline delivery reports type: object properties: protocol: description: Object storage protocol example: s3 type: string enum: - s3 - gcs - azure_blob bucket: description: Bucket name. Lowercase alphanumerics, dots and hyphens; must start and end with an alphanumeric; 3-63 chars. example: my-org.adcp.reports type: string minLength: 3 maxLength: 63 pattern: ^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$ prefix: description: Object key prefix within the bucket example: reports/ type: string maxLength: 512 pattern: ^[a-zA-Z0-9/_.-]+$ region: description: Storage region identifier (lowercase alphanumerics and hyphens) example: us-east-1 type: string maxLength: 64 pattern: ^[a-z0-9-]+$ format: description: Report file format default: jsonl type: string enum: - jsonl - csv - parquet - avro - orc compression: description: Compression applied to report files default: gzip type: string enum: - gzip - none file_retention_days: description: Number of days the customer retains report files in the bucket example: 30 type: integer minimum: 1 maximum: 9007199254740991 setup_instructions: description: Optional URL pointing to setup instructions for granting the agent access to the bucket example: https://example.com/adcp/bucket-setup type: string format: uri required: - protocol - bucket - file_retention_days AudienceItem: description: Audience to sync with member changes type: object properties: audienceId: description: Buyer's identifier for this audience. Used in targeting overlays. type: string minLength: 1 maxLength: 255 name: description: Human-readable name type: string maxLength: 255 add: description: Members to add to this audience maxItems: 100000 type: array items: type: object properties: externalId: description: Unique identifier for this member within the audience type: string minLength: 1 hashedEmail: description: SHA-256 hash of lowercase, trimmed email (64-char hex) example: a1b2c3d4e5f6... type: string pattern: ^[0-9a-f]{64}$ hashedPhone: description: SHA-256 hash of E.164-formatted phone number (64-char hex) example: f6e5d4c3b2a1... type: string pattern: ^[0-9a-f]{64}$ uids: description: Universal IDs for user matching minItems: 1 type: array items: type: object properties: type: description: Universal ID type (rampid, uid2, maid, etc.) type: string minLength: 1 value: description: Universal ID value type: string minLength: 1 required: - type - value required: - externalId remove: description: Members to remove by external ID maxItems: 100000 type: array items: $ref: '#/components/schemas/RemoveMember' delete: description: When true, delete this audience entirely type: boolean consentBasis: description: GDPR lawful basis for processing this audience type: string enum: - consent - legitimate_interest - contract - legal_obligation required: - audienceId S3CredentialConfigOutput: type: object properties: type: type: string enum: - S3 bucket: description: Target S3 bucket the Probe writes to and Data Delivery Outputs ship objects into. The bucket policy must grant the Scope3 AWS IAM principal s3:PutObject (and s3:DeleteObject for the Probe sweep) on objects under the Output path prefix. type: string minLength: 3 maxLength: 63 pattern: ^[a-z0-9][a-z0-9.-]*[a-z0-9]$ region: description: AWS region of the target bucket. Supports commercial, GovCloud, and ISO partitions (e.g., us-east-1, us-gov-east-1). type: string pattern: ^[a-z]{2}(-[a-z]+)+-\d+$ required: - type - bucket - region 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 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: {} SyncAudiencesResponse: description: Audience sync accepted for async processing type: object properties: success: type: boolean accountId: description: Advertiser ID (numeric string, e.g. "25") — same as the path parameter example: '25' type: string operationId: description: Batch operation UUID for tracking async processing type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ taskId: description: Task ID for polling progress via GET /tasks/{taskId}. Same value as operationId. type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - success - accountId - operationId - taskId additionalProperties: false AssignAccountBody: description: Request body for assigning a source account to an advertiser type: object properties: storefrontId: description: Storefront the source lives on. Pair with `sourceId`. example: 42 type: integer maximum: 9007199254740991 minimum: 1 sourceId: description: Inventory source within `storefrontId` to register this account against. example: src_main type: string minLength: 1 accountId: description: Account ID at the source to assign to this advertiser. Must come from `list_available_accounts`. example: acc_67890 type: string minLength: 1 credentialId: description: Credential ID returned by `list_available_accounts`. Required when the same account ID is exposed by more than one mapped connection. example: '42' type: string billingType: description: Billing arrangement type for this account (e.g. "advertiser", "operator", "agent"). Defaults to the source's default billing type. example: advertiser type: string required: - storefrontId - sourceId - accountId ErrorResponse: description: Standard error response type: object properties: data: type: - string - 'null' enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false OptimizationApplyMode: description: Whether optimization suggestions are automatically applied or require human approval. type: string enum: - AUTO - MANUAL DataDeliveryCredential: description: Resolved Data Delivery Credential as returned by the API. type: object properties: credentialId: description: Database identifier for the credential row. type: string name: type: string destinationType: type: string enum: - GCS - S3 - AZURE_BLOB - SNOWFLAKE - DATABRICKS config: $ref: '#/components/schemas/CredentialConfig' status: description: Outcome of the most recent Probe. PENDING until the first Probe completes, VALIDATED when the credential is reachable, FAILED when not. Data Delivery Outputs may reference any status; ReportDeliveryWorkflow checks at run time. type: string enum: - PENDING - VALIDATED - FAILED statusError: description: Human-readable Probe failure reason when status=FAILED. type: string validatedAt: description: ISO timestamp of the most recent successful Probe. type: string expiresAt: description: ISO timestamp at which the credential is known to expire. Populated for credential shapes that carry an expiry claim (e.g., the `se=` field of an Azure SAS token). Absent when the destination does not encode an expiry. type: string createdAt: type: string updatedAt: type: string required: - credentialId - name - destinationType - config - status - createdAt - updatedAt additionalProperties: false BrandManifestJson: description: Full brand.json profile conforming to the ADCP v2 schema type: object properties: name: description: Brand name (required) example: Acme Corporation type: string minLength: 1 maxLength: 500 url: description: Brand website URL example: https://www.acme.com type: string format: uri logos: description: Brand logos type: array items: type: object properties: url: description: URL to the logo image type: string format: uri tags: description: Tags categorizing the logo (e.g., "primary", "dark", "square") type: array items: type: string background: description: Backdrop the logo is designed for (dark-bg for a light or knockout logo, light-bg for a dark logo, transparent-bg for a logo with no baked-in background). type: string enum: - dark-bg - light-bg - transparent-bg width: description: Width of the logo in pixels type: integer maximum: 9007199254740991 minimum: 1 height: description: Height of the logo in pixels type: integer maximum: 9007199254740991 minimum: 1 required: - url additionalProperties: {} colors: description: Brand color palette type: object properties: primary: description: Primary brand color in hex format example: '#FF5733' type: string pattern: ^#[0-9A-Fa-f]{6}$ secondary: description: Secondary brand color in hex format type: string pattern: ^#[0-9A-Fa-f]{6}$ accent: description: Accent brand color in hex format type: string pattern: ^#[0-9A-Fa-f]{6}$ background: description: Background color in hex format type: string pattern: ^#[0-9A-Fa-f]{6}$ text: description: Text color in hex format type: string pattern: ^#[0-9A-Fa-f]{6}$ additionalProperties: {} fonts: description: Brand typography anyOf: - type: object properties: primary: description: Primary font family name example: Roboto type: string secondary: description: Secondary font family name type: string fontUrls: description: URLs to font files type: array items: type: string format: uri additionalProperties: {} - description: Font list from enrichment sources (Brandfetch format) type: array items: type: object properties: name: type: string role: type: string required: - name additionalProperties: {} tone: description: Brand voice and tone description example: Professional, friendly, and innovative type: string maxLength: 2000 tagline: description: Brand tagline or slogan example: Innovation for Everyone type: string maxLength: 500 assets: description: Brand assets (images, videos, etc.) type: array items: type: object properties: assetId: description: Unique identifier for the asset type: string assetType: description: Type of asset (e.g., "image", "video", "audio") type: string url: description: URL to the asset type: string format: uri name: description: Human-readable name for the asset type: string description: description: Description of the asset type: string tags: description: Tags categorizing the asset type: array items: type: string width: description: Width in pixels (for images/videos) type: integer maximum: 9007199254740991 minimum: 1 height: description: Height in pixels (for images/videos) type: integer maximum: 9007199254740991 minimum: 1 durationSeconds: description: Duration in seconds (for audio/video) type: number exclusiveMinimum: 0 fileSizeBytes: description: File size in bytes type: integer maximum: 9007199254740991 minimum: 1 format: description: File format (e.g., "png", "mp4") type: string metadata: description: Additional metadata type: object additionalProperties: {} required: - assetId - assetType - url additionalProperties: {} productCatalog: description: Product catalog configuration type: object properties: feedUrl: description: URL to the product feed type: string format: uri feedFormat: description: Format of the product feed type: string enum: - google_merchant_center - facebook_catalog - custom categories: description: Product categories type: array items: type: string lastUpdated: description: When the catalog 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))$ updateFrequency: description: How often the catalog is updated type: string enum: - realtime - hourly - daily - weekly required: - feedUrl additionalProperties: {} disclaimers: description: Legal disclaimers and required text type: array items: type: object properties: text: description: Disclaimer text type: string context: description: Context in which the disclaimer applies type: string required: description: Whether the disclaimer is required default: true type: boolean required: - text - required additionalProperties: {} industry: description: Industry or sector example: Technology type: string maxLength: 255 advertiserIndustry: description: Canonical AdCP advertiser-industry code (normalized from the free-text industry). Drives category-based starter briefs and cross-platform interop. example: food_beverage.restaurants type: string enum: - automotive - automotive.electric_vehicles - automotive.parts_accessories - automotive.luxury - beauty_cosmetics - beauty_cosmetics.skincare - beauty_cosmetics.fragrance - beauty_cosmetics.haircare - cannabis - cpg - cpg.personal_care - cpg.household - dating - education - education.higher_education - education.online_learning - education.k12 - energy_utilities - energy_utilities.renewable - fashion_apparel - fashion_apparel.luxury - fashion_apparel.sportswear - finance - finance.banking - finance.insurance - finance.investment - finance.cryptocurrency - food_beverage - food_beverage.alcohol - food_beverage.restaurants - food_beverage.packaged_goods - gambling_betting - gambling_betting.sports_betting - gambling_betting.casino - gaming - gaming.mobile - gaming.console_pc - gaming.esports - government_nonprofit - government_nonprofit.political - government_nonprofit.charity - healthcare - healthcare.pharmaceutical - healthcare.medical_devices - healthcare.wellness - home_garden - home_garden.furniture - home_garden.home_improvement - media_entertainment - media_entertainment.podcasts - media_entertainment.music - media_entertainment.film_tv - media_entertainment.publishing - media_entertainment.live_events - pets - professional_services - professional_services.legal - professional_services.consulting - real_estate - real_estate.residential - real_estate.commercial - recruitment_hr - retail - retail.ecommerce - retail.department_stores - sports_fitness - sports_fitness.equipment - sports_fitness.teams_leagues - technology - technology.software - technology.hardware - technology.ai_ml - telecom - telecom.mobile_carriers - telecom.internet_providers - transportation_logistics - travel_hospitality - travel_hospitality.airlines - travel_hospitality.hotels - travel_hospitality.cruise - travel_hospitality.tourism targetAudience: description: Target audience description example: Small business owners aged 25-45 type: string maxLength: 1000 contact: description: Contact information type: object properties: email: description: Contact email address 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,}$ phone: description: Contact phone number type: string website: description: Contact website URL type: string format: uri additionalProperties: {} metadata: description: Manifest metadata type: object properties: createdDate: description: When the manifest 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))$ updatedDate: description: When the manifest 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))$ version: description: Version of the manifest example: 1.0.0 type: string additionalProperties: {} required: - name additionalProperties: {} AzureBlobAuthStored: oneOf: - $ref: '#/components/schemas/AzureBlobSasAuthStored' type: object discriminator: propertyName: mode mapping: SAS_TOKEN: '#/components/schemas/AzureBlobSasAuthStored' 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 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 AdvertiserSummary: description: Compact advertiser view returned by list endpoints. Use `get_advertiser` for the full resource. type: object properties: id: description: Unique identifier for the advertiser example: '12345' type: string name: description: Name of the advertiser example: Acme Corp type: string status: description: Current status of the advertiser type: string enum: - ACTIVE - ARCHIVED sandbox: description: When true, this advertiser is in sandbox mode. All ADCP operations use sandbox-flagged accounts. Cannot be changed after creation. type: boolean brand: description: The brand domain associated with this advertiser example: nike.com type: string linkedBrand: description: The brand linked to this advertiser. Only present when includeBrand=true is passed to the list endpoint. type: object properties: id: description: Brand ID example: brand_123 type: string name: description: Brand name example: Acme Brand type: string domain: description: Brand domain example: acme.com type: string manifest: description: Full resolved brand identity data — includes logos, colors, fonts, tone, tagline, assets, product catalog, disclaimers, and more allOf: - $ref: '#/components/schemas/BrandManifestJson' logoUrl: description: Primary brand logo URL example: https://acme.com/logo.png type: string industry: description: Brand industry example: Technology type: string colors: description: Brand color palette example: primary: '#FF5733' type: object additionalProperties: type: string tagline: description: Brand tagline example: Innovation for Everyone type: string tone: description: Brand voice and tone example: Professional, friendly, and innovative type: string required: - id - name - domain - manifest additionalProperties: false primaryCurrency: description: Primary ISO 4217 currency for this advertiser. Every campaign under this advertiser is created in this currency, and selected product pricing must match it. example: USD type: string minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ currencyLocked: description: True once the advertiser has at least one campaign. While false, `primaryCurrency` can still be changed; once true it is locked. type: boolean createdAt: description: When the advertiser 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 advertiser 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))$ linkedAccountCount: description: Number of partner accounts linked to this advertiser. Replaces the embedded `linkedAccounts[]` array on summary rows; call `get_advertiser` for the full account list. example: 3 type: integer minimum: 0 maximum: 9007199254740991 required: - id - name - status - sandbox - primaryCurrency - currencyLocked - createdAt - updatedAt - linkedAccountCount additionalProperties: false AudienceSummary: description: Compact audience view returned by list endpoints. Use `get_audience` for the full resource. type: object properties: audienceId: type: string name: type: - string - 'null' accountId: description: Advertiser ID (numeric string, e.g. "25") example: '25' type: string status: description: Processing status of this audience type: string enum: - PROCESSING - ERROR - READY - TOO_SMALL deleted: type: boolean uploadedCount: type: - number - 'null' matchedCount: type: - number - 'null' createdAt: type: string updatedAt: type: string required: - audienceId - name - accountId - status - deleted - uploadedCount - matchedCount - createdAt - updatedAt additionalProperties: false 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: {} 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' AccountOutput: description: Linked account resource on a partner platform type: object properties: linkId: description: Unique identifier for the advertiser-account link example: '42' type: string accountId: description: Partner account identifier example: acc_acme_pinnacle type: string credentialId: description: Credential row that owns this linked account. Include this value when updating linked accounts so duplicate account IDs across mapped connections remain unambiguous. example: '42' type: - string - 'null' name: description: Human-readable account name from the partner example: Acme c/o Pinnacle type: - string - 'null' advertiser: description: Advertiser name as recorded by the partner platform example: Acme Corp type: - string - 'null' billingProxy: description: Billing proxy entity (e.g. agency buying on behalf of advertiser) example: Pinnacle Media type: - string - 'null' house: description: Domain or house identifier for the account example: acme-corp.com type: - string - 'null' billing: description: Billing arrangement type example: advertiser type: - string - 'null' sources: description: Storefront sources that surface this account to the buyer. A single linked account may be reachable through multiple sources when the underlying agent is shared across storefronts. Empty when the underlying agent is no longer linked to any active storefront source. type: array items: $ref: '#/components/schemas/BuyerCredentialSourceRef' advertiserId: description: Advertiser that owns this account link example: '12345' type: string status: description: Current account status type: string enum: - active - pending_approval - payment_required - suspended - closed - unreachable unreachableAt: description: When set, the mapping is preserved but its platform account is no longer reachable through any active connection — the connection that surfaced it was unlinked. Relink the provider (or re-map the account) to restore it. Unreachable mappings never resolve at buy time. example: '2025-01-22T09:00:00Z' type: - string - 'null' 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))$ createdAt: description: When the account was created (ISO 8601) example: '2025-01-15T10:30:00Z' type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ updatedAt: description: When the account was last updated (ISO 8601) example: '2025-01-20T14:45:00Z' type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - linkId - accountId - sources - advertiserId - status - createdAt - updatedAt additionalProperties: false AccountUnlinked: type: object properties: unlinked: type: boolean enum: - true required: - unlinked additionalProperties: false LinkedAccount: description: A partner account linked to this advertiser type: object properties: linkId: description: Unique link identifier type: string accountId: description: Account identifier on the partner platform type: string credentialId: description: Credential row that owns this linked account. Include this value when updating linked accounts so duplicate account IDs across mapped connections remain unambiguous. example: '42' type: - string - 'null' name: description: Account name type: - string - 'null' sources: description: Storefront sources that surface this linked account to the buyer. Empty when the underlying agent is no longer linked to any active storefront source. type: array items: $ref: '#/components/schemas/BuyerCredentialSourceRef' status: description: Account status type: string createdAt: description: When linked (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 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: - linkId - accountId - name - sources - status - createdAt - updatedAt additionalProperties: false BuyerCredentialSourceRef: description: A storefront/source pair that a single credential row gives the buyer access to type: object properties: storefrontId: description: Storefront ID this credential covers type: integer minimum: -9007199254740991 maximum: 9007199254740991 storefrontName: description: Storefront display name type: string sourceId: description: Inventory source ID within the storefront type: string sourceName: description: Inventory source display name type: string required: - storefrontId - storefrontName - sourceId - sourceName additionalProperties: false AdvertiserListResponse: description: Response containing a paginated list of advertiser summaries type: object properties: items: description: Advertisers projected to the summary shape. Use `get_advertiser` for the full resource. type: array items: $ref: '#/components/schemas/AdvertiserSummary' total: description: Total count of advertisers matching the query example: 42 type: integer minimum: 0 maximum: 9007199254740991 hasMore: description: Whether there are more results available type: boolean nextOffset: description: Offset to use for the next page of results, or null if no more results type: - integer - 'null' minimum: 0 maximum: 9007199254740991 currentAdvertiserId: description: The advertiser ID currently scoped by the caller (from X-SCOPE3-SEAT-ID header). Present only when the caller has an active advertiser scope (AI-5568). Used by the all-advertisers-home widget to mark the current advertiser. example: '12345' type: string required: - items - total - hasMore - nextOffset additionalProperties: false AccountListResponse: description: Response containing a paginated list of linked-account summaries type: object properties: accounts: description: Linked accounts projected to the summary shape. Use `get_advertiser_account` for the full resource. type: array items: $ref: '#/components/schemas/AccountSummary' total: description: Total count of accounts matching the query example: 15 type: integer minimum: 0 maximum: 9007199254740991 required: - accounts - total additionalProperties: false AvailableAccountOutput: description: Discovered account available to be linked to an advertiser type: object properties: accountId: description: Partner account identifier example: acc_acme_pinnacle type: string credentialId: description: Credential row that owns this discovered account. Include this value when linking the account so duplicate account IDs across mapped connections remain unambiguous. example: '42' type: - string - 'null' name: description: Human-readable account name from the partner example: Acme c/o Pinnacle type: - string - 'null' advertiser: description: Advertiser name as recorded by the partner platform example: Acme Corp type: - string - 'null' billingProxy: description: Billing proxy entity (e.g. agency buying on behalf of advertiser) example: Pinnacle Media type: - string - 'null' house: description: Domain or house identifier for the account example: acme-corp.com type: - string - 'null' billing: description: Billing arrangement type example: advertiser type: - string - 'null' sources: description: Storefront sources that surface this discovered account to the buyer. Same account may appear via multiple sources when the underlying agent is shared across storefronts. type: array items: $ref: '#/components/schemas/BuyerCredentialSourceRef' status: description: Current account status on the partner platform type: string enum: - active - pending_approval - payment_required - suspended - closed - unreachable required: - accountId - sources - status additionalProperties: false AccountResponse: description: Response containing a single linked account type: object properties: account: $ref: '#/components/schemas/AccountOutput' required: - account additionalProperties: false DataDeliveryCredentialArrayInput: description: Array of Data Delivery Credentials for one advertiser. Names must be unique within the array. maxItems: 20 type: array items: $ref: '#/components/schemas/DataDeliveryCredentialInput' 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 GcsCredentialConfigOutput: type: object properties: type: type: string enum: - GCS bucket: description: Target GCS bucket the Probe writes to and Data Delivery Outputs ship objects into. The Scope3 service account must have objectCreator on this bucket. type: string minLength: 1 maxLength: 222 pattern: ^[a-z0-9][a-z0-9._-]*[a-z0-9]$ required: - type - bucket additionalProperties: false AzureBlobCredentialConfigInput: type: object properties: type: type: string enum: - AZURE_BLOB storageAccountName: description: Azure Storage account hosting the target container, e.g. `datareports`. The container is accessed at `https://.blob.core.windows.net/`. type: string minLength: 3 maxLength: 24 pattern: ^[a-z0-9]+$ containerName: description: Azure Blob container that the Probe writes to and Data Delivery Outputs ship objects into. type: string minLength: 3 maxLength: 63 pattern: ^(?!.*--)[a-z0-9][a-z0-9-]*[a-z0-9]$ auth: $ref: '#/components/schemas/AzureBlobAuthInput' required: - type - storageAccountName - containerName - auth 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 FrequencyCapTargetLevel: description: Level of the entity the frequency cap applies to type: string enum: - ADVERTISER - CAMPAIGN - CREATIVE 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 AzureBlobSasAuthInput: type: object properties: mode: type: string enum: - SAS_TOKEN sasToken: description: Shared Access Signature (SAS) query string. Provide the part after the `?` from the SAS URL — leading `?` is tolerated. Accepts either a Service SAS scoped to the container (`sr=c`) or an Account SAS with `srt` including `o` (Object); blob-scoped Service SAS (`sr=b`) is not supported because the Probe writes to a randomized path. The SAS must grant Create + Write + Delete (`sp=cwd`). Persisted to Google Secret Manager; the credential row stores only a resource reference. Not returned on subsequent GETs — to rotate, submit a new credential. type: string minLength: 1 maxLength: 4096 required: - mode - sasToken CreateAdvertiserBody: description: Request body for creating a new advertiser type: object properties: name: description: Name of the advertiser example: Acme Corp type: string minLength: 1 maxLength: 255 description: description: Optional description of the advertiser example: Global advertising account for Acme Corporation type: string maxLength: 1000 brand: description: Brand domain (e.g., "nike.com") or brand website URL. Brand identity is resolved from /.well-known/brand.json, the AdCP registry, or Brandfetch enrichment. example: nike.com type: string minLength: 1 saveBrand: description: When true, auto-saves the resolved brand identity to the AdCP registry if the brand is not yet registered. Normally not required for advertiser creation when enrichment succeeds; set this only after reviewing enrichment or when the user confirms registry persistence is desired. default: false type: boolean linkedAccounts: description: Accounts to link to this advertiser at creation time. Each entry references a discovered account from a partner. type: array items: $ref: '#/components/schemas/LinkedAccountInput' optimizationApplyMode: description: Default mode for applying Scope3 AI model optimizations to media buys for campaigns under this advertiser. When set to "AUTO", optimizations are applied automatically; when "MANUAL", they require approval. Defaults to "MANUAL". allOf: - $ref: '#/components/schemas/OptimizationApplyMode' primaryCurrency: description: Primary ISO 4217 currency for this advertiser. Required. Every campaign under this advertiser is created in this currency, and media-buy product pricing must match it. The currency can be changed (via update_advertiser) only until the advertiser has its first campaign, after which it is locked. example: USD type: string minLength: 3 maxLength: 3 pattern: ^[A-Za-z]{3}$ sandbox: description: When true, this advertiser operates in sandbox mode. All ADCP operations will use sandbox-flagged accounts — no real platform calls, no real spend. Cannot be changed after creation. default: false type: boolean utmConfig: description: Default UTM (Urchin Tracking Module) parameters for this advertiser. These are appended to landing page URLs during clickthrough redirection. Campaign-level UTM config can override these per param key. maxItems: 20 type: array items: type: object properties: paramKey: description: Output query parameter key appended to landing URL (e.g., "utm_source", "bg_campaign") example: utm_campaign type: string pattern: ^[a-zA-Z0-9_-]{1,100}$ paramValue: description: Macro name (e.g., "{CAMPAIGN_ID}") or static string (e.g., "scope3") to resolve as the value example: '{CAMPAIGN_ID}' type: string minLength: 1 maxLength: 200 required: - paramKey - paramValue dataDelivery: $ref: '#/components/schemas/AdvertiserDataDeliveryInput' frequencyCaps: description: Buyer-side frequency cap configs to apply to this advertiser. Enforced by Scope3 across all publishers; distinct from publisher-side caps in package target_overlay. type: array items: $ref: '#/components/schemas/FrequencyCapConfigInput' required: - name - brand - primaryCurrency S3CredentialConfig: type: object properties: type: type: string enum: - S3 bucket: description: Target S3 bucket the Probe writes to and Data Delivery Outputs ship objects into. The bucket policy must grant the Scope3 AWS IAM principal s3:PutObject (and s3:DeleteObject for the Probe sweep) on objects under the Output path prefix. type: string minLength: 3 maxLength: 63 pattern: ^[a-z0-9][a-z0-9.-]*[a-z0-9]$ region: description: AWS region of the target bucket. Supports commercial, GovCloud, and ISO partitions (e.g., us-east-1, us-gov-east-1). type: string pattern: ^[a-z]{2}(-[a-z]+)+-\d+$ required: - type - bucket - region UpdateAdvertiserBody: description: Request body for updating an advertiser type: object properties: name: description: Updated name of the advertiser example: Acme Corporation type: string minLength: 1 maxLength: 255 description: description: Updated description of the advertiser example: Updated description for Acme Corporation type: string maxLength: 1000 brand: description: Updated brand domain (e.g., "nike.com"). Re-resolves brand identity from /.well-known/brand.json, the AdCP registry, or Brandfetch enrichment. example: nike.com type: string minLength: 1 saveBrand: description: When true, auto-saves the resolved brand identity to the AdCP registry if the brand is not yet registered. Normally not required for advertiser updates; requires brand when sent on update. Set this only after reviewing enrichment or when the user confirms registry persistence is desired. default: false type: boolean linkedAccounts: description: Accounts to add to this advertiser. Existing linked accounts are not removed. type: array items: $ref: '#/components/schemas/LinkedAccountInput' optimizationApplyMode: description: Default mode for applying Scope3 AI model optimizations to media buys for campaigns under this advertiser. When set to "AUTO", optimizations are applied automatically; when "MANUAL", they require approval. allOf: - $ref: '#/components/schemas/OptimizationApplyMode' primaryCurrency: description: Primary ISO 4217 currency for this advertiser. Can only be changed while the advertiser has no campaigns; once the first campaign is created the currency is locked, because every campaign under an advertiser shares the advertiser's single currency. example: USD type: string minLength: 3 maxLength: 3 pattern: ^[A-Za-z]{3}$ utmConfig: description: Default UTM (Urchin Tracking Module) parameters for this advertiser. Replaces all existing advertiser-level UTM params. Pass an empty array to clear. maxItems: 20 type: array items: type: object properties: paramKey: description: Output query parameter key appended to landing URL (e.g., "utm_source", "bg_campaign") example: utm_campaign type: string pattern: ^[a-zA-Z0-9_-]{1,100}$ paramValue: description: Macro name (e.g., "{CAMPAIGN_ID}") or static string (e.g., "scope3") to resolve as the value example: '{CAMPAIGN_ID}' type: string minLength: 1 maxLength: 200 required: - paramKey - paramValue dataDelivery: description: Data-delivery configuration for this advertiser. Groups standing Data Delivery Outputs and the credentials they reference. Omit to leave existing config untouched. type: object properties: credentials: description: Data Delivery Credentials owned by this advertiser. When provided, replaces all existing live credentials (pass an empty array to archive — rejected if any live Output references a credential). Omit to leave existing credentials untouched. Applied before `outputs` so newly created credentials can be referenced by name. allOf: - $ref: '#/components/schemas/DataDeliveryCredentialArrayInput' outputs: description: Standing log-level data subscriptions to ship from Scope3 to a buyer-owned destination. Replaces all existing advertiser-scoped Data Delivery Outputs when provided. Pass an empty array to clear. Omit to leave existing Outputs untouched. allOf: - $ref: '#/components/schemas/DataDeliveryOutputArrayInput' frequencyCaps: description: Buyer-side frequency cap configs to apply to this advertiser. When provided, replaces all existing non-archived caps for this advertiser (pass an empty array to clear). Omit to leave existing caps untouched. type: array items: $ref: '#/components/schemas/FrequencyCapConfigInput' 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' AzureBlobCredentialConfig: type: object properties: type: type: string enum: - AZURE_BLOB storageAccountName: description: Azure Storage account hosting the target container, e.g. `datareports`. The container is accessed at `https://.blob.core.windows.net/`. type: string minLength: 3 maxLength: 24 pattern: ^[a-z0-9]+$ containerName: description: Azure Blob container that the Probe writes to and Data Delivery Outputs ship objects into. type: string minLength: 3 maxLength: 63 pattern: ^(?!.*--)[a-z0-9][a-z0-9-]*[a-z0-9]$ auth: $ref: '#/components/schemas/AzureBlobAuthStored' required: - type - storageAccountName - containerName - auth additionalProperties: false CredentialConfig: description: Destination-specific auth target as stored on the credential row. AZURE_BLOB omits the SAS token — the token lives in Google Secret Manager and is fetched at probe / delivery time. oneOf: - $ref: '#/components/schemas/GcsCredentialConfigOutput' - $ref: '#/components/schemas/S3CredentialConfigOutput' - $ref: '#/components/schemas/AzureBlobCredentialConfig' type: object discriminator: propertyName: type mapping: GCS: '#/components/schemas/GcsCredentialConfigOutput' S3: '#/components/schemas/S3CredentialConfigOutput' AZURE_BLOB: '#/components/schemas/AzureBlobCredentialConfig' SyncAudiencesBody: description: Sync audience data into Scope3 type: object properties: audiences: description: Audiences to sync minItems: 1 type: array items: $ref: '#/components/schemas/AudienceItem' deleteMissing: description: When true, audiences not in this request are marked as deleted. type: boolean pushNotificationConfig: type: object properties: url: type: string operation_id: type: string minLength: 1 maxLength: 255 pattern: ^[A-Za-z0-9_.:-]{1,255}$ token: type: string minLength: 16 maxLength: 4096 authentication: type: object properties: schemes: type: array items: anyOf: - type: string enum: - Bearer - type: string enum: - HMAC-SHA256 credentials: type: string minLength: 32 required: - schemes - credentials additionalProperties: {} required: - url additionalProperties: {} required: - audiences AdvertiserDataDelivery: description: Data-delivery configuration for this advertiser. Groups standing Data Delivery Outputs and the credentials they reference. Distinct from media-buy reporting fields elsewhere in the API. type: object properties: credentials: description: Live Data Delivery Credentials owned by this advertiser. Only present when at least one credential exists. type: array items: $ref: '#/components/schemas/DataDeliveryCredential' outputs: description: Advertiser-scoped Data Delivery Outputs (standing LLD subscriptions). Only present when at least one Output is configured. type: array items: $ref: '#/components/schemas/DataDeliveryOutput' 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 AdvertiserDataDeliveryInput: description: Data-delivery configuration for this advertiser. Groups standing Data Delivery Outputs and the credentials they reference. Distinct from media-buy reporting fields elsewhere in the API. type: object properties: credentials: description: Data Delivery Credentials owned by this advertiser. Replaces all existing live credentials when provided. Pass an empty array to archive every live credential (only allowed when no live Output references one). Applied before `outputs` so newly created credentials can be referenced by name. allOf: - $ref: '#/components/schemas/DataDeliveryCredentialArrayInput' outputs: description: Standing log-level data subscriptions to ship from Scope3 to a buyer-owned destination. Replaces all existing advertiser-scoped Data Delivery Outputs when provided. Pass an empty array to clear. allOf: - $ref: '#/components/schemas/DataDeliveryOutputArrayInput' CredentialConfigInput: description: Destination-specific auth target as submitted by the buyer. AZURE_BLOB carries the SAS token; the API persists it to Google Secret Manager and stores only a reference. Additional destination types are added as new variants. oneOf: - $ref: '#/components/schemas/GcsCredentialConfig' - $ref: '#/components/schemas/S3CredentialConfig' - $ref: '#/components/schemas/AzureBlobCredentialConfigInput' type: object discriminator: propertyName: type mapping: GCS: '#/components/schemas/GcsCredentialConfig' S3: '#/components/schemas/S3CredentialConfig' AZURE_BLOB: '#/components/schemas/AzureBlobCredentialConfigInput' AzureBlobSasAuthStored: type: object properties: mode: type: string enum: - SAS_TOKEN required: - mode additionalProperties: false 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 AdvertiserAccount: type: object properties: linkId: type: string accountId: type: string credentialId: type: - string - 'null' name: type: - string - 'null' advertiser: type: - string - 'null' billingProxy: type: - string - 'null' house: type: - string - 'null' billing: type: - string - 'null' sources: type: array items: type: object additionalProperties: {} advertiserId: type: string status: type: string createdAt: type: string updatedAt: type: string required: - linkId - accountId - name - advertiser - billingProxy - house - billing - sources - advertiserId - status - createdAt - updatedAt additionalProperties: {} DataDeliveryCredentialInput: description: A single Data Delivery Credential entry. Used inline on advertiser create+update; full-replace by name within one request. type: object properties: name: description: Buyer-meaningful identifier for this credential, unique per advertiser among live credentials. Data Delivery Outputs reference this by name. type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ config: $ref: '#/components/schemas/CredentialConfigInput' required: - name - config 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 AccountSummary: description: Compact linked-account view returned by list endpoints. Use `get_advertiser_account` for the full resource. type: object properties: linkId: description: Unique identifier for the advertiser-account link example: '42' type: string accountId: description: Partner account identifier example: acc_acme_pinnacle type: string name: description: Human-readable account name from the partner example: Acme c/o Pinnacle type: - string - 'null' sources: description: Storefront sources that surface this account to the buyer. A single linked account may be reachable through multiple sources when the underlying agent is shared across storefronts. Empty when the underlying agent is no longer linked to any active storefront source. type: array items: $ref: '#/components/schemas/BuyerCredentialSourceRef' advertiserId: description: Advertiser that owns this account link example: '12345' type: string status: description: Current account status type: string enum: - active - pending_approval - payment_required - suspended - closed - unreachable createdAt: description: When the account was created (ISO 8601) example: '2025-01-15T10:30:00Z' type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ updatedAt: description: When the account was last updated (ISO 8601) example: '2025-01-20T14:45:00Z' type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - linkId - accountId - sources - advertiserId - status - createdAt - updatedAt additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token