@adcp/client 3.25.0 → 4.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/lib/agents/index.generated.d.ts +9 -1
- package/dist/lib/agents/index.generated.d.ts.map +1 -1
- package/dist/lib/agents/index.generated.js +12 -0
- package/dist/lib/agents/index.generated.js.map +1 -1
- package/dist/lib/index.d.ts +3 -3
- package/dist/lib/index.d.ts.map +1 -1
- package/dist/lib/index.js +5 -3
- package/dist/lib/index.js.map +1 -1
- package/dist/lib/types/core.generated.d.ts +175 -78
- package/dist/lib/types/core.generated.d.ts.map +1 -1
- package/dist/lib/types/core.generated.js +1 -1
- package/dist/lib/types/schemas.generated.d.ts +1654 -328
- package/dist/lib/types/schemas.generated.d.ts.map +1 -1
- package/dist/lib/types/schemas.generated.js +182 -87
- package/dist/lib/types/schemas.generated.js.map +1 -1
- package/dist/lib/types/tools.generated.d.ts +496 -482
- package/dist/lib/types/tools.generated.d.ts.map +1 -1
- package/dist/lib/types/tools.generated.js +0 -3
- package/dist/lib/types/tools.generated.js.map +1 -1
- package/dist/lib/utils/capabilities.d.ts +40 -0
- package/dist/lib/utils/capabilities.d.ts.map +1 -1
- package/dist/lib/utils/capabilities.js +25 -0
- package/dist/lib/utils/capabilities.js.map +1 -1
- package/dist/lib/utils/creative-adapter.d.ts +1 -1
- package/dist/lib/utils/creative-adapter.js +3 -3
- package/dist/lib/utils/creative-adapter.js.map +1 -1
- package/dist/lib/utils/pricing-adapter.d.ts +1 -1
- package/dist/lib/utils/pricing-adapter.d.ts.map +1 -1
- package/dist/lib/utils/pricing-adapter.js +6 -3
- package/dist/lib/utils/pricing-adapter.js.map +1 -1
- package/package.json +2 -1
|
@@ -12,10 +12,7 @@ export type GetProductsRequest = {
|
|
|
12
12
|
brief?: string;
|
|
13
13
|
brand?: BrandReference;
|
|
14
14
|
catalog?: Catalog;
|
|
15
|
-
|
|
16
|
-
* Account ID for product lookup. Required when the seller declares account.required_for_products = true in capabilities. Returns products with pricing specific to this account's rate card.
|
|
17
|
-
*/
|
|
18
|
-
account_id?: string;
|
|
15
|
+
account?: AccountReference;
|
|
19
16
|
/**
|
|
20
17
|
* Buyer's campaign reference label. Groups related discovery and buy operations under a single campaign for CRM and ad server correlation (e.g., 'NovaDrink_Meals_Q2').
|
|
21
18
|
*/
|
|
@@ -55,6 +52,21 @@ export type EventType = 'page_view' | 'view_content' | 'select_content' | 'selec
|
|
|
55
52
|
* Identifier type that the event's content_ids field should be matched against for items in this catalog. For example, 'gtin' means content_ids values are Global Trade Item Numbers, 'sku' means retailer SKUs. Omit when using a custom identifier scheme not listed in the enum.
|
|
56
53
|
*/
|
|
57
54
|
export type ContentIDType = 'sku' | 'gtin' | 'offering_id' | 'job_id' | 'hotel_id' | 'flight_id' | 'vehicle_id' | 'listing_id' | 'store_id' | 'program_id' | 'destination_id' | 'app_id';
|
|
55
|
+
/**
|
|
56
|
+
* Account for product lookup. Returns products with pricing specific to this account's rate card.
|
|
57
|
+
*/
|
|
58
|
+
export type AccountReference = {
|
|
59
|
+
/**
|
|
60
|
+
* Seller-assigned account identifier (from sync_accounts or list_accounts)
|
|
61
|
+
*/
|
|
62
|
+
account_id: string;
|
|
63
|
+
} | {
|
|
64
|
+
brand: BrandReference;
|
|
65
|
+
/**
|
|
66
|
+
* Domain of the entity operating on the brand's behalf. When the brand operates directly, this is the brand's domain.
|
|
67
|
+
*/
|
|
68
|
+
operator: string;
|
|
69
|
+
};
|
|
58
70
|
/**
|
|
59
71
|
* Type of inventory delivery
|
|
60
72
|
*/
|
|
@@ -144,7 +156,7 @@ export type SignalID = {
|
|
|
144
156
|
id: string;
|
|
145
157
|
};
|
|
146
158
|
/**
|
|
147
|
-
*
|
|
159
|
+
* Brand reference for product discovery context. Resolved to full brand identity at execution time.
|
|
148
160
|
*/
|
|
149
161
|
export interface BrandReference {
|
|
150
162
|
/**
|
|
@@ -484,7 +496,7 @@ export type PropertyID = string;
|
|
|
484
496
|
*/
|
|
485
497
|
export type PropertyTag = string;
|
|
486
498
|
/**
|
|
487
|
-
*
|
|
499
|
+
* A pricing model option offered by a publisher for a product. Discriminated by pricing_model field. If fixed_price is present, it's fixed pricing. If absent, it's auction-based (floor_price and price_guidance optional). Bid-based auction models may also include max_bid as a boolean signal to interpret bid_price as a buyer ceiling instead of an exact honored price.
|
|
488
500
|
*/
|
|
489
501
|
export type PricingOption = CPMPricingOption | VCPMPricingOption | CPCPricingOption | CPCVPricingOption | CPVPricingOption | CPPPricingOption | CPAPricingOption | FlatRatePricingOption | TimeBasedPricingOption;
|
|
490
502
|
/**
|
|
@@ -492,7 +504,7 @@ export type PricingOption = CPMPricingOption | VCPMPricingOption | CPCPricingOpt
|
|
|
492
504
|
*/
|
|
493
505
|
export type DemographicSystem = 'nielsen' | 'barb' | 'agf' | 'oztam' | 'mediametrie' | 'custom';
|
|
494
506
|
/**
|
|
495
|
-
*
|
|
507
|
+
* How to interpret the points array. 'spend' (default when omitted): points at ascending budget levels. 'reach_freq': points at ascending reach/frequency targets. 'weekly'/'daily': metrics are per-period values. 'clicks'/'conversions': points at ascending outcome targets.
|
|
496
508
|
*/
|
|
497
509
|
export type ForecastRangeUnit = 'spend' | 'reach_freq' | 'weekly' | 'daily' | 'clicks' | 'conversions';
|
|
498
510
|
/**
|
|
@@ -500,7 +512,7 @@ export type ForecastRangeUnit = 'spend' | 'reach_freq' | 'weekly' | 'daily' | 'c
|
|
|
500
512
|
*/
|
|
501
513
|
export type ForecastMethod = 'estimate' | 'modeled' | 'guaranteed';
|
|
502
514
|
/**
|
|
503
|
-
*
|
|
515
|
+
* Unit of measurement for reach and audience_size metrics in this forecast. Required for cross-channel forecast comparison.
|
|
504
516
|
*/
|
|
505
517
|
export type ReachUnit = 'individuals' | 'households' | 'devices' | 'accounts' | 'cookies' | 'custom';
|
|
506
518
|
/**
|
|
@@ -559,7 +571,7 @@ export type DataProviderSignalSelector = {
|
|
|
559
571
|
signal_tags: string[];
|
|
560
572
|
};
|
|
561
573
|
/**
|
|
562
|
-
*
|
|
574
|
+
* Where the conversion event originated
|
|
563
575
|
*/
|
|
564
576
|
export type ActionSource = 'website' | 'app' | 'offline' | 'phone_call' | 'chat' | 'email' | 'in_store' | 'system_generated' | 'other';
|
|
565
577
|
/**
|
|
@@ -673,7 +685,28 @@ export interface Product {
|
|
|
673
685
|
*/
|
|
674
686
|
catalog_types?: CatalogType[];
|
|
675
687
|
/**
|
|
676
|
-
*
|
|
688
|
+
* Metric optimization capabilities for this product. Presence indicates the product supports optimization_goals with kind: 'metric'. No event source or conversion tracking setup required — the seller tracks these metrics natively.
|
|
689
|
+
*/
|
|
690
|
+
metric_optimization?: {
|
|
691
|
+
/**
|
|
692
|
+
* Metric kinds this product can optimize for. Buyers should only request metric goals for kinds listed here.
|
|
693
|
+
*/
|
|
694
|
+
supported_metrics: ('clicks' | 'views' | 'completed_views' | 'viewed_seconds' | 'attention_seconds' | 'attention_score' | 'engagements' | 'follows' | 'saves' | 'profile_visits')[];
|
|
695
|
+
/**
|
|
696
|
+
* Video view duration thresholds (in seconds) this product supports for completed_views goals. Only relevant when supported_metrics includes 'completed_views'. When absent, the seller uses their platform default. Buyers must set view_duration_seconds to a value in this list — sellers reject unsupported values.
|
|
697
|
+
*/
|
|
698
|
+
supported_view_durations?: number[];
|
|
699
|
+
/**
|
|
700
|
+
* Target kinds available for metric goals on this product. Values match target.kind on the optimization goal. Only these target kinds are accepted — goals with unlisted target kinds will be rejected. When omitted, buyers can set target-less metric goals (maximize volume within budget) but cannot set specific targets.
|
|
701
|
+
*/
|
|
702
|
+
supported_targets?: ('cost_per' | 'threshold_rate')[];
|
|
703
|
+
};
|
|
704
|
+
/**
|
|
705
|
+
* Maximum number of optimization_goals this product accepts on a package. When absent, no limit is declared. Most social platforms accept only 1 goal — buyers sending arrays longer than this value should expect the seller to use only the highest-priority (lowest priority number) goal.
|
|
706
|
+
*/
|
|
707
|
+
max_optimization_goals?: number;
|
|
708
|
+
/**
|
|
709
|
+
* Conversion event tracking for this product. Presence indicates the product supports optimization_goals with kind: 'event'. Seller-level capabilities (supported event types, UID types, attribution windows) are declared in get_adcp_capabilities.
|
|
677
710
|
*/
|
|
678
711
|
conversion_tracking?: {
|
|
679
712
|
/**
|
|
@@ -681,9 +714,9 @@ export interface Product {
|
|
|
681
714
|
*/
|
|
682
715
|
action_sources?: ActionSource[];
|
|
683
716
|
/**
|
|
684
|
-
*
|
|
717
|
+
* Target kinds available for event goals on this product. Values match target.kind on the optimization goal. cost_per: target cost per conversion event. per_ad_spend: target return on ad spend (requires value_field on event sources). maximize_value: maximize total conversion value without a specific ratio target (requires value_field). Only these target kinds are accepted — goals with unlisted target kinds will be rejected. A goal without a target implicitly maximizes conversion count within budget — no declaration needed for that mode. When omitted, buyers can still set target-less event goals.
|
|
685
718
|
*/
|
|
686
|
-
|
|
719
|
+
supported_targets?: ('cost_per' | 'per_ad_spend' | 'maximize_value')[];
|
|
687
720
|
/**
|
|
688
721
|
* Whether the seller provides its own always-on measurement (e.g. Amazon sales attribution for Amazon advertisers). When true, sync_event_sources response will include seller-managed event sources with managed_by='seller'.
|
|
689
722
|
*/
|
|
@@ -741,7 +774,7 @@ export interface Product {
|
|
|
741
774
|
ext?: ExtensionObject;
|
|
742
775
|
}
|
|
743
776
|
/**
|
|
744
|
-
*
|
|
777
|
+
* Represents a specific ad placement within a product's inventory
|
|
745
778
|
*/
|
|
746
779
|
export interface Placement {
|
|
747
780
|
/**
|
|
@@ -851,7 +884,7 @@ export interface VCPMPricingOption {
|
|
|
851
884
|
min_spend_per_package?: number;
|
|
852
885
|
}
|
|
853
886
|
/**
|
|
854
|
-
*
|
|
887
|
+
* Cost Per Click pricing. If fixed_price is present, it's fixed pricing. If absent, it's auction-based.
|
|
855
888
|
*/
|
|
856
889
|
export interface CPCPricingOption {
|
|
857
890
|
/**
|
|
@@ -885,7 +918,7 @@ export interface CPCPricingOption {
|
|
|
885
918
|
min_spend_per_package?: number;
|
|
886
919
|
}
|
|
887
920
|
/**
|
|
888
|
-
*
|
|
921
|
+
* Cost Per Completed View (100% video/audio completion) pricing. If fixed_price is present, it's fixed pricing. If absent, it's auction-based.
|
|
889
922
|
*/
|
|
890
923
|
export interface CPCVPricingOption {
|
|
891
924
|
/**
|
|
@@ -919,7 +952,7 @@ export interface CPCVPricingOption {
|
|
|
919
952
|
min_spend_per_package?: number;
|
|
920
953
|
}
|
|
921
954
|
/**
|
|
922
|
-
*
|
|
955
|
+
* Cost Per View (at publisher-defined threshold) pricing for video/audio. If fixed_price is present, it's fixed pricing. If absent, it's auction-based.
|
|
923
956
|
*/
|
|
924
957
|
export interface CPVPricingOption {
|
|
925
958
|
/**
|
|
@@ -964,7 +997,7 @@ export interface CPVPricingOption {
|
|
|
964
997
|
min_spend_per_package?: number;
|
|
965
998
|
}
|
|
966
999
|
/**
|
|
967
|
-
*
|
|
1000
|
+
* Cost Per Point (Gross Rating Point) pricing for TV and audio campaigns. If fixed_price is present, it's fixed pricing. If absent, it's auction-based.
|
|
968
1001
|
*/
|
|
969
1002
|
export interface CPPPricingOption {
|
|
970
1003
|
/**
|
|
@@ -1008,7 +1041,7 @@ export interface CPPPricingOption {
|
|
|
1008
1041
|
min_spend_per_package?: number;
|
|
1009
1042
|
}
|
|
1010
1043
|
/**
|
|
1011
|
-
*
|
|
1044
|
+
* Cost Per Acquisition pricing. Advertiser pays a fixed price when a specified conversion event occurs. The event_type field declares which event triggers billing (e.g., purchase, lead, app_install).
|
|
1012
1045
|
*/
|
|
1013
1046
|
export interface CPAPricingOption {
|
|
1014
1047
|
/**
|
|
@@ -1108,7 +1141,7 @@ export interface FlatRatePricingOption {
|
|
|
1108
1141
|
min_spend_per_package?: number;
|
|
1109
1142
|
}
|
|
1110
1143
|
/**
|
|
1111
|
-
*
|
|
1144
|
+
* Cost per time unit (hour, day, week, or month) - rate scales with campaign duration. If fixed_price is present, it's fixed pricing. If absent, it's auction-based.
|
|
1112
1145
|
*/
|
|
1113
1146
|
export interface TimeBasedPricingOption {
|
|
1114
1147
|
/**
|
|
@@ -1155,7 +1188,7 @@ export interface TimeBasedPricingOption {
|
|
|
1155
1188
|
min_spend_per_package?: number;
|
|
1156
1189
|
}
|
|
1157
1190
|
/**
|
|
1158
|
-
*
|
|
1191
|
+
* Forecasted delivery metrics for this product. Gives buyers an estimate of expected performance before requesting a proposal.
|
|
1159
1192
|
*/
|
|
1160
1193
|
export interface DeliveryForecast {
|
|
1161
1194
|
/**
|
|
@@ -1217,7 +1250,7 @@ export interface ForecastRange {
|
|
|
1217
1250
|
high?: number;
|
|
1218
1251
|
}
|
|
1219
1252
|
/**
|
|
1220
|
-
*
|
|
1253
|
+
* Measurement capabilities included with a product
|
|
1221
1254
|
*/
|
|
1222
1255
|
export interface Measurement {
|
|
1223
1256
|
/**
|
|
@@ -1282,7 +1315,7 @@ export interface CreativePolicy {
|
|
|
1282
1315
|
templates_available: boolean;
|
|
1283
1316
|
}
|
|
1284
1317
|
/**
|
|
1285
|
-
*
|
|
1318
|
+
* A proposed media plan with budget allocations across products. Represents the publisher's strategic recommendation for how to structure a campaign based on the brief. Proposals are actionable - buyers can execute them directly via create_media_buy by providing the proposal_id.
|
|
1286
1319
|
*/
|
|
1287
1320
|
export interface Proposal {
|
|
1288
1321
|
/**
|
|
@@ -1390,7 +1423,7 @@ export interface DaypartTarget {
|
|
|
1390
1423
|
label?: string;
|
|
1391
1424
|
}
|
|
1392
1425
|
/**
|
|
1393
|
-
*
|
|
1426
|
+
* Standard error structure for task-specific errors and warnings
|
|
1394
1427
|
*/
|
|
1395
1428
|
export interface Error {
|
|
1396
1429
|
/**
|
|
@@ -1436,10 +1469,7 @@ export interface PaginationResponse {
|
|
|
1436
1469
|
total_count?: number;
|
|
1437
1470
|
}
|
|
1438
1471
|
/**
|
|
1439
|
-
*
|
|
1440
|
-
*/
|
|
1441
|
-
/**
|
|
1442
|
-
* Filter by format type (technical categories with distinct requirements)
|
|
1472
|
+
* Types of content that can be used as creative assets. Describes what KIND of content an asset contains (image, video, code, etc.), not where it displays.
|
|
1443
1473
|
*/
|
|
1444
1474
|
export type AssetContentType = 'image' | 'video' | 'audio' | 'text' | 'markdown' | 'html' | 'css' | 'javascript' | 'vast' | 'daast' | 'url' | 'webhook';
|
|
1445
1475
|
/**
|
|
@@ -1497,10 +1527,7 @@ export interface ListCreativeFormatsRequest {
|
|
|
1497
1527
|
ext?: ExtensionObject;
|
|
1498
1528
|
}
|
|
1499
1529
|
/**
|
|
1500
|
-
*
|
|
1501
|
-
*/
|
|
1502
|
-
/**
|
|
1503
|
-
* DEPRECATED: High-level category for this format. Use the assets array to understand creative requirements instead - it provides precise information about what asset types are needed.
|
|
1530
|
+
* Types of parameters that template formats accept in format_id objects to create parameterized format identifiers
|
|
1504
1531
|
*/
|
|
1505
1532
|
export type FormatIDParameter = 'dimensions' | 'duration';
|
|
1506
1533
|
/**
|
|
@@ -1508,7 +1535,7 @@ export type FormatIDParameter = 'dimensions' | 'duration';
|
|
|
1508
1535
|
*/
|
|
1509
1536
|
export type UniversalMacro = 'MEDIA_BUY_ID' | 'PACKAGE_ID' | 'CREATIVE_ID' | 'CACHEBUSTER' | 'TIMESTAMP' | 'CLICK_URL' | 'GDPR' | 'GDPR_CONSENT' | 'US_PRIVACY' | 'GPP_STRING' | 'GPP_SID' | 'IP_ADDRESS' | 'LIMIT_AD_TRACKING' | 'DEVICE_TYPE' | 'OS' | 'OS_VERSION' | 'DEVICE_MAKE' | 'DEVICE_MODEL' | 'USER_AGENT' | 'APP_BUNDLE' | 'APP_NAME' | 'COUNTRY' | 'REGION' | 'CITY' | 'ZIP' | 'DMA' | 'LAT' | 'LONG' | 'DEVICE_ID' | 'DEVICE_ID_TYPE' | 'DOMAIN' | 'PAGE_URL' | 'REFERRER' | 'KEYWORDS' | 'PLACEMENT_ID' | 'FOLD_POSITION' | 'AD_WIDTH' | 'AD_HEIGHT' | 'VIDEO_ID' | 'VIDEO_TITLE' | 'VIDEO_DURATION' | 'VIDEO_CATEGORY' | 'CONTENT_GENRE' | 'CONTENT_RATING' | 'PLAYER_WIDTH' | 'PLAYER_HEIGHT' | 'POD_POSITION' | 'POD_SIZE' | 'AD_BREAK_ID' | 'STATION_ID' | 'SHOW_NAME' | 'EPISODE_ID' | 'AUDIO_DURATION' | 'AXEM' | 'CATALOG_ID' | 'SKU' | 'GTIN' | 'OFFERING_ID' | 'JOB_ID' | 'HOTEL_ID' | 'FLIGHT_ID' | 'VEHICLE_ID' | 'LISTING_ID' | 'STORE_ID' | 'PROGRAM_ID' | 'DESTINATION_ID' | 'CREATIVE_VARIANT_ID' | 'APP_ITEM_ID';
|
|
1510
1537
|
/**
|
|
1511
|
-
*
|
|
1538
|
+
* Technical requirements for each item in this group (e.g., max_length for text, min_width/aspect_ratio for images). Applies uniformly to all items in the group.
|
|
1512
1539
|
*/
|
|
1513
1540
|
export type AssetRequirements = ImageAssetRequirements | VideoAssetRequirements | AudioAssetRequirements | TextAssetRequirements | MarkdownAssetRequirements | HTMLAssetRequirements | CSSAssetRequirements | JavaScriptAssetRequirements | VASTAssetRequirements | DAASTAssetRequirements | URLAssetRequirements | WebhookAssetRequirements;
|
|
1514
1541
|
/**
|
|
@@ -1531,7 +1558,7 @@ export type CatalogFieldBinding = ScalarBinding | AssetPoolBinding | {
|
|
|
1531
1558
|
ext?: ExtensionObject;
|
|
1532
1559
|
};
|
|
1533
1560
|
/**
|
|
1534
|
-
*
|
|
1561
|
+
* Capabilities supported by creative agents for format handling
|
|
1535
1562
|
*/
|
|
1536
1563
|
export type CreativeAgentCapability = 'validation' | 'assembly' | 'generation' | 'preview' | 'delivery';
|
|
1537
1564
|
/**
|
|
@@ -1689,9 +1716,6 @@ export interface Format {
|
|
|
1689
1716
|
*/
|
|
1690
1717
|
reported_metrics?: AvailableMetric[];
|
|
1691
1718
|
}
|
|
1692
|
-
/**
|
|
1693
|
-
* Structured format identifier with agent URL and format name
|
|
1694
|
-
*/
|
|
1695
1719
|
export interface BaseIndividualAsset {
|
|
1696
1720
|
/**
|
|
1697
1721
|
* Discriminator indicating this is an individual asset
|
|
@@ -1788,7 +1812,7 @@ export interface BaseGroupAsset {
|
|
|
1788
1812
|
overlays?: Overlay[];
|
|
1789
1813
|
}
|
|
1790
1814
|
/**
|
|
1791
|
-
*
|
|
1815
|
+
* Format-level declaration of what catalog feeds a creative needs. Formats that render product listings, store locators, or promotional content declare which catalog types must be synced and what fields each catalog must provide. Buyers use this to ensure the right catalogs are synced before submitting creatives.
|
|
1792
1816
|
*/
|
|
1793
1817
|
export interface CatalogRequirements {
|
|
1794
1818
|
catalog_type: CatalogType;
|
|
@@ -2130,7 +2154,7 @@ export interface WebhookAssetRequirements {
|
|
|
2130
2154
|
methods?: ('GET' | 'POST')[];
|
|
2131
2155
|
}
|
|
2132
2156
|
/**
|
|
2133
|
-
*
|
|
2157
|
+
* Maps an individual format asset to a catalog item field via dot-notation path.
|
|
2134
2158
|
*/
|
|
2135
2159
|
export interface ScalarBinding {
|
|
2136
2160
|
kind: 'scalar';
|
|
@@ -2159,20 +2183,110 @@ export interface AssetPoolBinding {
|
|
|
2159
2183
|
asset_group_id: string;
|
|
2160
2184
|
ext?: ExtensionObject;
|
|
2161
2185
|
}
|
|
2162
|
-
/**
|
|
2163
|
-
* Standard error structure for task-specific errors and warnings
|
|
2164
|
-
*/
|
|
2165
2186
|
/**
|
|
2166
2187
|
* Budget pacing strategy
|
|
2167
2188
|
*/
|
|
2168
2189
|
export type Pacing = 'even' | 'asap' | 'front_loaded';
|
|
2169
2190
|
/**
|
|
2170
|
-
*
|
|
2191
|
+
* A single optimization target for a package. Packages accept an array of optimization_goals. When multiple goals are present, priority determines which the seller focuses on — 1 is highest priority (primary goal); higher numbers are secondary. Duplicate priority values result in undefined seller behavior.
|
|
2171
2192
|
*/
|
|
2172
|
-
export type
|
|
2193
|
+
export type OptimizationGoal = {
|
|
2194
|
+
kind: 'metric';
|
|
2195
|
+
/**
|
|
2196
|
+
* Seller-native metric to optimize for. Delivery metrics: clicks (link clicks, swipe-throughs, CTA taps that navigate away), views (viewable impressions), completed_views (video/audio completions — see view_duration_seconds). Duration/score metrics: viewed_seconds (time in view per impression), attention_seconds (attention time per impression), attention_score (vendor-specific attention score). Audience action metrics: engagements (any direct interaction with the ad unit beyond viewing — social reactions/comments/shares, story/unit opens, interactive overlay taps, companion banner interactions on audio and CTV), follows (new followers, page likes, artist/podcast/channel subscribes), saves (saves, bookmarks, playlist adds, pins — signals of intent to return), profile_visits (visits to the brand's in-platform page — profile, artist page, channel, or storefront. Does not include external website clicks, which are covered by 'clicks').
|
|
2197
|
+
*/
|
|
2198
|
+
metric: 'clicks' | 'views' | 'completed_views' | 'viewed_seconds' | 'attention_seconds' | 'attention_score' | 'engagements' | 'follows' | 'saves' | 'profile_visits';
|
|
2199
|
+
/**
|
|
2200
|
+
* Minimum video view duration in seconds that qualifies as a completed_view for this goal. Only applicable when metric is 'completed_views'. When omitted, the seller uses their platform default (typically 2–15 seconds). Common values: 2 (Snap/LinkedIn default), 6 (TikTok), 15 (Snap 15-second views, Meta ThruPlay). Sellers declare which durations they support in metric_optimization.supported_view_durations. Sellers must reject goals with unsupported values — silent rounding would create measurement discrepancies.
|
|
2201
|
+
*/
|
|
2202
|
+
view_duration_seconds?: number;
|
|
2203
|
+
/**
|
|
2204
|
+
* Target for this metric. When omitted, the seller optimizes for maximum metric volume within budget.
|
|
2205
|
+
*/
|
|
2206
|
+
target?: {
|
|
2207
|
+
kind: 'cost_per';
|
|
2208
|
+
/**
|
|
2209
|
+
* Target cost per metric unit in the buy currency
|
|
2210
|
+
*/
|
|
2211
|
+
value: number;
|
|
2212
|
+
} | {
|
|
2213
|
+
kind: 'threshold_rate';
|
|
2214
|
+
/**
|
|
2215
|
+
* Minimum per-impression value. Units depend on the metric: proportion (clicks, views, completed_views), seconds (viewed_seconds, attention_seconds), or score (attention_score).
|
|
2216
|
+
*/
|
|
2217
|
+
value: number;
|
|
2218
|
+
};
|
|
2219
|
+
/**
|
|
2220
|
+
* Relative priority among all optimization goals on this package. 1 = highest priority (primary goal); higher numbers are lower priority (secondary signals). When omitted, sellers may use array position as priority.
|
|
2221
|
+
*/
|
|
2222
|
+
priority?: number;
|
|
2223
|
+
} | {
|
|
2224
|
+
kind: 'event';
|
|
2225
|
+
/**
|
|
2226
|
+
* Event source and type pairs that feed this goal. Each entry identifies a source and event type to include. When the seller supports multi_source_event_dedup (declared in get_adcp_capabilities), they deduplicate by event_id across all entries — the same business event from multiple sources counts once, using value_field and value_factor from the first matching entry. When multi_source_event_dedup is false or absent, buyers should use a single entry per goal; the seller will use only the first entry. All event sources must be configured via sync_event_sources.
|
|
2227
|
+
*/
|
|
2228
|
+
event_sources: {
|
|
2229
|
+
/**
|
|
2230
|
+
* Event source to include (must be configured on this account via sync_event_sources)
|
|
2231
|
+
*/
|
|
2232
|
+
event_source_id: string;
|
|
2233
|
+
event_type: EventType;
|
|
2234
|
+
/**
|
|
2235
|
+
* Required when event_type is 'custom'. Platform-specific name for the custom event.
|
|
2236
|
+
*/
|
|
2237
|
+
custom_event_name?: string;
|
|
2238
|
+
/**
|
|
2239
|
+
* Which field in the event's custom_data carries the monetary value. The seller must use this field for value extraction and aggregation when computing ROAS and conversion value metrics. Required on at least one entry when target.kind is 'per_ad_spend' or 'maximize_value'. Common values: 'value', 'order_total', 'profit_margin'. This is not passed as a parameter to underlying platform APIs — the seller maps it to their platform's value ingestion mechanism.
|
|
2240
|
+
*/
|
|
2241
|
+
value_field?: string;
|
|
2242
|
+
/**
|
|
2243
|
+
* Multiplier the seller must apply to value_field before aggregation. Use -1 for refund events (negate the value), 0.01 for values in cents, -0.01 for refunds in cents. A value of 0 zeroes out this source's value contribution (the source still counts for event dedup). Defaults to 1. This is not passed as a parameter to underlying platform APIs — the seller applies it when computing aggregated value metrics.
|
|
2244
|
+
*/
|
|
2245
|
+
value_factor?: number;
|
|
2246
|
+
}[];
|
|
2247
|
+
/**
|
|
2248
|
+
* Target cost or return for this event goal. When omitted, the seller optimizes for maximum conversions within budget.
|
|
2249
|
+
*/
|
|
2250
|
+
target?: {
|
|
2251
|
+
kind: 'cost_per';
|
|
2252
|
+
/**
|
|
2253
|
+
* Target cost per event in the buy currency
|
|
2254
|
+
*/
|
|
2255
|
+
value: number;
|
|
2256
|
+
} | {
|
|
2257
|
+
kind: 'per_ad_spend';
|
|
2258
|
+
/**
|
|
2259
|
+
* Target return ratio (e.g., 4.0 means $4 of value per $1 spent)
|
|
2260
|
+
*/
|
|
2261
|
+
value: number;
|
|
2262
|
+
} | {
|
|
2263
|
+
kind: 'maximize_value';
|
|
2264
|
+
};
|
|
2265
|
+
/**
|
|
2266
|
+
* Attribution window for this optimization goal. Values must match an option declared in the seller's conversion_tracking.attribution_windows capability. Sellers must reject windows not in their declared capabilities. When omitted, the seller uses their default window.
|
|
2267
|
+
*/
|
|
2268
|
+
attribution_window?: {
|
|
2269
|
+
/**
|
|
2270
|
+
* Click-through attribution window (e.g. '7d', '28d', '30d')
|
|
2271
|
+
*/
|
|
2272
|
+
click_through: string;
|
|
2273
|
+
/**
|
|
2274
|
+
* View-through attribution window (e.g. '1d', '7d')
|
|
2275
|
+
*/
|
|
2276
|
+
view_through?: string;
|
|
2277
|
+
};
|
|
2278
|
+
/**
|
|
2279
|
+
* Relative priority among all optimization goals on this package. 1 = highest priority (primary goal); higher numbers are lower priority (secondary signals). When omitted, sellers may use array position as priority.
|
|
2280
|
+
*/
|
|
2281
|
+
priority?: number;
|
|
2282
|
+
};
|
|
2173
2283
|
/**
|
|
2174
2284
|
* Postal code system (e.g., 'us_zip', 'gb_outward'). System name encodes country and precision.
|
|
2175
2285
|
*/
|
|
2286
|
+
export type PostalCodeSystem = 'us_zip' | 'us_zip_plus_four' | 'gb_outward' | 'gb_full' | 'ca_fsa' | 'ca_full' | 'de_plz' | 'fr_code_postal' | 'au_postcode' | 'ch_plz' | 'at_plz';
|
|
2287
|
+
/**
|
|
2288
|
+
* Methods for verifying user age for compliance. Does not include 'inferred' as it is not accepted for regulatory compliance.
|
|
2289
|
+
*/
|
|
2176
2290
|
export type AgeVerificationMethod = 'facial_age_estimation' | 'id_document' | 'digital_id' | 'credit_card' | 'world_id';
|
|
2177
2291
|
/**
|
|
2178
2292
|
* Operating system platforms for device targeting. Browser values from Sec-CH-UA-Platform standard, extended for CTV.
|
|
@@ -2255,7 +2369,7 @@ export type VASTVersion = '2.0' | '3.0' | '4.0' | '4.1' | '4.2';
|
|
|
2255
2369
|
*/
|
|
2256
2370
|
export type VASTTrackingEvent = 'start' | 'firstQuartile' | 'midpoint' | 'thirdQuartile' | 'complete' | 'impression' | 'click' | 'pause' | 'resume' | 'skip' | 'mute' | 'unmute' | 'fullscreen' | 'exitFullscreen' | 'playerExpand' | 'playerCollapse';
|
|
2257
2371
|
/**
|
|
2258
|
-
*
|
|
2372
|
+
* DAAST (Digital Audio Ad Serving Template) tag for third-party audio ad serving
|
|
2259
2373
|
*/
|
|
2260
2374
|
export type DAASTAsset = {
|
|
2261
2375
|
/**
|
|
@@ -2319,7 +2433,7 @@ export type DAASTVersion = '1.0' | '1.1';
|
|
|
2319
2433
|
*/
|
|
2320
2434
|
export type DAASTTrackingEvent = 'start' | 'firstQuartile' | 'midpoint' | 'thirdQuartile' | 'complete' | 'impression' | 'pause' | 'resume' | 'skip' | 'mute' | 'unmute';
|
|
2321
2435
|
/**
|
|
2322
|
-
*
|
|
2436
|
+
* Type of URL asset: 'clickthrough' for user click destination (landing page), 'tracker_pixel' for impression/event tracking via HTTP request (fires GET, expects pixel/204 response), 'tracker_script' for measurement SDKs that must load as <script> tag (OMID verification, native event trackers using method:2)
|
|
2323
2437
|
*/
|
|
2324
2438
|
export type URLAssetType = 'clickthrough' | 'tracker_pixel' | 'tracker_script';
|
|
2325
2439
|
/**
|
|
@@ -2327,7 +2441,7 @@ export type URLAssetType = 'clickthrough' | 'tracker_pixel' | 'tracker_script';
|
|
|
2327
2441
|
*/
|
|
2328
2442
|
export type CreativeStatus = 'processing' | 'approved' | 'rejected' | 'pending_review' | 'archived';
|
|
2329
2443
|
/**
|
|
2330
|
-
*
|
|
2444
|
+
* Campaign start timing: 'asap' or ISO 8601 date-time
|
|
2331
2445
|
*/
|
|
2332
2446
|
export type StartTiming = 'asap' | string;
|
|
2333
2447
|
/**
|
|
@@ -2335,7 +2449,7 @@ export type StartTiming = 'asap' | string;
|
|
|
2335
2449
|
*/
|
|
2336
2450
|
export type AuthenticationScheme = 'Bearer' | 'HMAC-SHA256';
|
|
2337
2451
|
/**
|
|
2338
|
-
*
|
|
2452
|
+
* Request parameters for creating a media buy. Supports two modes: (1) Manual mode - provide packages array with explicit line item configurations, or (2) Proposal mode - provide proposal_id and total_budget to execute a proposal from get_products. One of packages or proposal_id must be provided.
|
|
2339
2453
|
*/
|
|
2340
2454
|
export interface CreateMediaBuyRequest {
|
|
2341
2455
|
/**
|
|
@@ -2346,10 +2460,7 @@ export interface CreateMediaBuyRequest {
|
|
|
2346
2460
|
* Buyer's campaign reference label. Groups related discovery and buy operations under a single campaign for CRM and ad server correlation (e.g., 'NovaDrink_Meals_Q2').
|
|
2347
2461
|
*/
|
|
2348
2462
|
buyer_campaign_ref?: string;
|
|
2349
|
-
|
|
2350
|
-
* Account to bill for this media buy. Required when the agent has access to multiple accounts; when omitted, the seller uses the agent's sole account. The seller maps the agent's brand + operator to an account during sync_accounts; the agent passes that account_id here.
|
|
2351
|
-
*/
|
|
2352
|
-
account_id?: string;
|
|
2463
|
+
account: AccountReference;
|
|
2353
2464
|
/**
|
|
2354
2465
|
* ID of a proposal from get_products to execute. When provided with total_budget, the publisher converts the proposal's allocation percentages into packages automatically. Alternative to providing packages array.
|
|
2355
2466
|
*/
|
|
@@ -2464,7 +2575,10 @@ export interface PackageRequest {
|
|
|
2464
2575
|
*/
|
|
2465
2576
|
paused?: boolean;
|
|
2466
2577
|
catalog?: Catalog;
|
|
2467
|
-
|
|
2578
|
+
/**
|
|
2579
|
+
* Optimization targets for this package. The seller optimizes delivery toward these goals in priority order. Common pattern: event goals (purchase, install) as primary targets at priority 1; metric goals (clicks, views) as secondary proxy signals at priority 2+.
|
|
2580
|
+
*/
|
|
2581
|
+
optimization_goals?: OptimizationGoal[];
|
|
2468
2582
|
targeting_overlay?: TargetingOverlay;
|
|
2469
2583
|
/**
|
|
2470
2584
|
* Assign existing library creatives to this package with optional weights and placement targeting
|
|
@@ -2478,37 +2592,6 @@ export interface PackageRequest {
|
|
|
2478
2592
|
creatives?: CreativeAsset[];
|
|
2479
2593
|
ext?: ExtensionObject;
|
|
2480
2594
|
}
|
|
2481
|
-
/**
|
|
2482
|
-
* Structured format identifier with agent URL and format name. Can reference: (1) a concrete format with fixed dimensions (id only), (2) a template format without parameters (id only), or (3) a template format with parameters (id + dimensions/duration). Template formats accept parameters in format_id while concrete formats have fixed dimensions in their definition. Parameterized format IDs create unique, specific format variants.
|
|
2483
|
-
*/
|
|
2484
|
-
export interface OptimizationGoal {
|
|
2485
|
-
/**
|
|
2486
|
-
* Event source to optimize against (must be configured on this account via sync_event_sources)
|
|
2487
|
-
*/
|
|
2488
|
-
event_source_id: string;
|
|
2489
|
-
event_type: EventType;
|
|
2490
|
-
/**
|
|
2491
|
-
* Target return on ad spend (e.g. 4.0 = $4 conversion value per $1 spent). Mutually exclusive with target_cpa.
|
|
2492
|
-
*/
|
|
2493
|
-
target_roas?: number;
|
|
2494
|
-
/**
|
|
2495
|
-
* Target cost per acquisition in the buy currency. Mutually exclusive with target_roas.
|
|
2496
|
-
*/
|
|
2497
|
-
target_cpa?: number;
|
|
2498
|
-
/**
|
|
2499
|
-
* Attribution window for this optimization goal. Values must match an option declared in the seller's conversion_tracking.attribution_windows capability. When omitted, the seller uses their default window.
|
|
2500
|
-
*/
|
|
2501
|
-
attribution_window?: {
|
|
2502
|
-
/**
|
|
2503
|
-
* Click-through attribution window (e.g. '7d', '28d', '30d')
|
|
2504
|
-
*/
|
|
2505
|
-
click_through: string;
|
|
2506
|
-
/**
|
|
2507
|
-
* View-through attribution window (e.g. '1d', '7d')
|
|
2508
|
-
*/
|
|
2509
|
-
view_through?: string;
|
|
2510
|
-
};
|
|
2511
|
-
}
|
|
2512
2595
|
/**
|
|
2513
2596
|
* Optional restriction overlays for media buys. Most targeting should be expressed in the brief and handled by the publisher. These fields are for functional restrictions: geographic (RCT testing, regulatory compliance), age verification (alcohol, gambling), device platform (app compatibility), and language (localization).
|
|
2514
2597
|
*/
|
|
@@ -2635,7 +2718,7 @@ export interface TargetingOverlay {
|
|
|
2635
2718
|
language?: string[];
|
|
2636
2719
|
}
|
|
2637
2720
|
/**
|
|
2638
|
-
*
|
|
2721
|
+
* Frequency capping settings for package-level application
|
|
2639
2722
|
*/
|
|
2640
2723
|
export interface FrequencyCap {
|
|
2641
2724
|
/**
|
|
@@ -2644,7 +2727,7 @@ export interface FrequencyCap {
|
|
|
2644
2727
|
suppress_minutes: number;
|
|
2645
2728
|
}
|
|
2646
2729
|
/**
|
|
2647
|
-
*
|
|
2730
|
+
* Assignment of a creative asset to a package with optional placement targeting. Used in create_media_buy and update_media_buy requests. Note: sync_creatives does not support placement_ids - use create/update_media_buy for placement-level targeting.
|
|
2648
2731
|
*/
|
|
2649
2732
|
export interface CreativeAssignment {
|
|
2650
2733
|
/**
|
|
@@ -2721,7 +2804,7 @@ export interface CreativeAsset {
|
|
|
2721
2804
|
placement_ids?: string[];
|
|
2722
2805
|
}
|
|
2723
2806
|
/**
|
|
2724
|
-
*
|
|
2807
|
+
* Image asset with URL and dimensions
|
|
2725
2808
|
*/
|
|
2726
2809
|
export interface ImageAsset {
|
|
2727
2810
|
/**
|
|
@@ -3025,7 +3108,7 @@ export interface URLAsset {
|
|
|
3025
3108
|
description?: string;
|
|
3026
3109
|
}
|
|
3027
3110
|
/**
|
|
3028
|
-
*
|
|
3111
|
+
* Optional webhook configuration for async task status notifications. Publisher will send webhooks when status changes (working, input-required, completed, failed). The client generates an operation_id and embeds it in the URL before sending — the publisher echoes it back in webhook payloads for correlation.
|
|
3029
3112
|
*/
|
|
3030
3113
|
export interface PushNotificationConfig {
|
|
3031
3114
|
/**
|
|
@@ -3088,15 +3171,12 @@ export interface ReportingWebhook {
|
|
|
3088
3171
|
*/
|
|
3089
3172
|
requested_metrics?: AvailableMetric[];
|
|
3090
3173
|
}
|
|
3091
|
-
/**
|
|
3092
|
-
* Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.
|
|
3093
|
-
*/
|
|
3094
3174
|
/**
|
|
3095
3175
|
* Response payload for create_media_buy task. Returns either complete success data OR error information, never both. This enforces atomic operation semantics - the media buy is either fully created or not created at all.
|
|
3096
3176
|
*/
|
|
3097
3177
|
export type CreateMediaBuyResponse = CreateMediaBuySuccess | CreateMediaBuyError;
|
|
3098
3178
|
/**
|
|
3099
|
-
*
|
|
3179
|
+
* Success response - media buy created successfully
|
|
3100
3180
|
*/
|
|
3101
3181
|
export interface CreateMediaBuySuccess {
|
|
3102
3182
|
/**
|
|
@@ -3148,25 +3228,18 @@ export interface Account {
|
|
|
3148
3228
|
*/
|
|
3149
3229
|
billing_proxy?: string;
|
|
3150
3230
|
/**
|
|
3151
|
-
* Account status. pending_approval: seller reviewing (credit, contracts). payment_required: credit limit reached or funds depleted. suspended: was active, now paused. closed: terminated.
|
|
3152
|
-
*/
|
|
3153
|
-
status: 'active' | 'pending_approval' | 'payment_required' | 'suspended' | 'closed';
|
|
3154
|
-
/**
|
|
3155
|
-
* House domain where brand.json is hosted. Canonical identity anchor for the brand.
|
|
3231
|
+
* Account status. pending_approval: seller reviewing (credit, contracts). rejected: seller declined the account request. payment_required: credit limit reached or funds depleted. suspended: was active, now paused. closed: was active, now terminated.
|
|
3156
3232
|
*/
|
|
3157
|
-
|
|
3158
|
-
|
|
3159
|
-
* Brand ID within the house portfolio (from brand.json)
|
|
3160
|
-
*/
|
|
3161
|
-
brand_id?: string;
|
|
3233
|
+
status: 'active' | 'pending_approval' | 'rejected' | 'payment_required' | 'suspended' | 'closed';
|
|
3234
|
+
brand?: BrandReference;
|
|
3162
3235
|
/**
|
|
3163
|
-
* Domain of the entity operating this account
|
|
3236
|
+
* Domain of the entity operating this account. When the brand operates directly, this is the brand's domain.
|
|
3164
3237
|
*/
|
|
3165
3238
|
operator?: string;
|
|
3166
3239
|
/**
|
|
3167
|
-
* Who is invoiced on this account.
|
|
3240
|
+
* Who is invoiced on this account. operator: seller invoices the operator (agency or brand buying direct). agent: agent consolidates billing.
|
|
3168
3241
|
*/
|
|
3169
|
-
billing?: '
|
|
3242
|
+
billing?: 'operator' | 'agent';
|
|
3170
3243
|
/**
|
|
3171
3244
|
* Identifier for the rate card applied to this account
|
|
3172
3245
|
*/
|
|
@@ -3199,6 +3272,10 @@ export interface Account {
|
|
|
3199
3272
|
*/
|
|
3200
3273
|
expires_at?: string;
|
|
3201
3274
|
};
|
|
3275
|
+
/**
|
|
3276
|
+
* How the seller scoped this account. operator: shared across all brands for this operator. brand: shared across all operators for this brand. operator_brand: dedicated to a specific operator+brand combination. agent: the agent's default account with no brand or operator association.
|
|
3277
|
+
*/
|
|
3278
|
+
account_scope?: 'operator' | 'brand' | 'operator_brand' | 'agent';
|
|
3202
3279
|
/**
|
|
3203
3280
|
* When true, this is a sandbox account. All requests using this account_id are treated as sandbox — no real platform calls, no real spend.
|
|
3204
3281
|
*/
|
|
@@ -3206,7 +3283,7 @@ export interface Account {
|
|
|
3206
3283
|
ext?: ExtensionObject;
|
|
3207
3284
|
}
|
|
3208
3285
|
/**
|
|
3209
|
-
*
|
|
3286
|
+
* A specific product within a media buy (line item)
|
|
3210
3287
|
*/
|
|
3211
3288
|
export interface Package {
|
|
3212
3289
|
/**
|
|
@@ -3247,7 +3324,10 @@ export interface Package {
|
|
|
3247
3324
|
* Format IDs that creative assets will be provided for this package
|
|
3248
3325
|
*/
|
|
3249
3326
|
format_ids_to_provide?: FormatID[];
|
|
3250
|
-
|
|
3327
|
+
/**
|
|
3328
|
+
* Optimization targets for this package. The seller optimizes delivery toward these goals in priority order. Common pattern: event goals (purchase, install) as primary targets at priority 1; metric goals (clicks, views) as secondary proxy signals at priority 2+.
|
|
3329
|
+
*/
|
|
3330
|
+
optimization_goals?: OptimizationGoal[];
|
|
3251
3331
|
/**
|
|
3252
3332
|
* Whether this package is paused by the buyer. Paused packages do not deliver impressions. Defaults to false.
|
|
3253
3333
|
*/
|
|
@@ -3255,7 +3335,7 @@ export interface Package {
|
|
|
3255
3335
|
ext?: ExtensionObject;
|
|
3256
3336
|
}
|
|
3257
3337
|
/**
|
|
3258
|
-
*
|
|
3338
|
+
* Error response - operation failed, no media buy created
|
|
3259
3339
|
*/
|
|
3260
3340
|
export interface CreateMediaBuyError {
|
|
3261
3341
|
/**
|
|
@@ -3266,20 +3346,14 @@ export interface CreateMediaBuyError {
|
|
|
3266
3346
|
ext?: ExtensionObject;
|
|
3267
3347
|
}
|
|
3268
3348
|
/**
|
|
3269
|
-
*
|
|
3270
|
-
*/
|
|
3271
|
-
/**
|
|
3272
|
-
* Catalog type. Structural types: 'offering' (AdCP Offering objects), 'product' (ecommerce entries), 'inventory' (stock per location), 'store' (physical locations), 'promotion' (deals and pricing). Vertical types: 'hotel', 'flight', 'job', 'vehicle', 'real_estate', 'education', 'destination', 'app' — each with an industry-specific item schema.
|
|
3349
|
+
* Validation strictness. 'strict' fails entire sync on any validation error. 'lenient' processes valid creatives and reports errors.
|
|
3273
3350
|
*/
|
|
3274
3351
|
export type ValidationMode = 'strict' | 'lenient';
|
|
3275
3352
|
/**
|
|
3276
|
-
*
|
|
3353
|
+
* Request parameters for syncing creative assets with upsert semantics - supports bulk operations, scoped updates, and assignment management
|
|
3277
3354
|
*/
|
|
3278
3355
|
export interface SyncCreativesRequest {
|
|
3279
|
-
|
|
3280
|
-
* Account that owns these creatives. Optional if the agent has a single account or the seller can determine the account from context. Required if the agent has multiple accounts and the seller cannot route automatically.
|
|
3281
|
-
*/
|
|
3282
|
-
account_id?: string;
|
|
3356
|
+
account: AccountReference;
|
|
3283
3357
|
/**
|
|
3284
3358
|
* Array of creative assets to sync (create or update)
|
|
3285
3359
|
*
|
|
@@ -3317,9 +3391,6 @@ export interface SyncCreativesRequest {
|
|
|
3317
3391
|
context?: ContextObject;
|
|
3318
3392
|
ext?: ExtensionObject;
|
|
3319
3393
|
}
|
|
3320
|
-
/**
|
|
3321
|
-
* Creative asset for upload to library - supports static assets, generative formats, and third-party snippets
|
|
3322
|
-
*/
|
|
3323
3394
|
/**
|
|
3324
3395
|
* Response from creative sync operation. Returns either per-creative results (best-effort processing) OR operation-level errors (complete failure). This enforces atomic semantics at the operation level while allowing per-item failures within successful operations.
|
|
3325
3396
|
*/
|
|
@@ -3395,7 +3466,7 @@ export interface SyncCreativesSuccess {
|
|
|
3395
3466
|
ext?: ExtensionObject;
|
|
3396
3467
|
}
|
|
3397
3468
|
/**
|
|
3398
|
-
*
|
|
3469
|
+
* Error response - operation failed completely, no creatives were processed
|
|
3399
3470
|
*/
|
|
3400
3471
|
export interface SyncCreativesError {
|
|
3401
3472
|
/**
|
|
@@ -3406,10 +3477,7 @@ export interface SyncCreativesError {
|
|
|
3406
3477
|
ext?: ExtensionObject;
|
|
3407
3478
|
}
|
|
3408
3479
|
/**
|
|
3409
|
-
*
|
|
3410
|
-
*/
|
|
3411
|
-
/**
|
|
3412
|
-
* Status of a creative asset
|
|
3480
|
+
* Field to sort by
|
|
3413
3481
|
*/
|
|
3414
3482
|
export type CreativeSortField = 'created_date' | 'updated_date' | 'name' | 'status' | 'assignment_count' | 'performance_score';
|
|
3415
3483
|
/**
|
|
@@ -3455,7 +3523,7 @@ export interface CreativeFilters {
|
|
|
3455
3523
|
/**
|
|
3456
3524
|
* Filter creatives by owning accounts. Useful for agencies managing multiple client accounts.
|
|
3457
3525
|
*/
|
|
3458
|
-
|
|
3526
|
+
accounts?: AccountReference[];
|
|
3459
3527
|
/**
|
|
3460
3528
|
* Filter by creative format types (e.g., video, audio, display)
|
|
3461
3529
|
*/
|
|
@@ -3520,10 +3588,7 @@ export interface CreativeFilters {
|
|
|
3520
3588
|
has_performance_data?: boolean;
|
|
3521
3589
|
}
|
|
3522
3590
|
/**
|
|
3523
|
-
*
|
|
3524
|
-
*/
|
|
3525
|
-
/**
|
|
3526
|
-
* Sort direction for list queries
|
|
3591
|
+
* Sub-asset for multi-asset creative formats, including carousel images and native ad template variables
|
|
3527
3592
|
*/
|
|
3528
3593
|
export type SubAsset = {
|
|
3529
3594
|
/**
|
|
@@ -3734,9 +3799,6 @@ export interface ListCreativesResponse {
|
|
|
3734
3799
|
context?: ContextObject;
|
|
3735
3800
|
ext?: ExtensionObject;
|
|
3736
3801
|
}
|
|
3737
|
-
/**
|
|
3738
|
-
* Standard cursor-based pagination metadata for list responses
|
|
3739
|
-
*/
|
|
3740
3802
|
/**
|
|
3741
3803
|
* Request parameters for updating campaign and package settings
|
|
3742
3804
|
*/
|
|
@@ -3770,7 +3832,7 @@ export type UpdateMediaBuyRequest = {
|
|
|
3770
3832
|
[k: string]: unknown | undefined;
|
|
3771
3833
|
};
|
|
3772
3834
|
/**
|
|
3773
|
-
*
|
|
3835
|
+
* Package update configuration for update_media_buy. Identifies package by package_id or buyer_ref and specifies fields to modify. Fields not present are left unchanged. Note: product_id, format_ids, and pricing_option_id cannot be changed after creation.
|
|
3774
3836
|
*/
|
|
3775
3837
|
export type PackageUpdate = {
|
|
3776
3838
|
/**
|
|
@@ -3799,7 +3861,10 @@ export type PackageUpdate = {
|
|
|
3799
3861
|
*/
|
|
3800
3862
|
paused?: boolean;
|
|
3801
3863
|
catalog?: Catalog;
|
|
3802
|
-
|
|
3864
|
+
/**
|
|
3865
|
+
* Replace all optimization goals for this package. Uses replacement semantics — omit to leave goals unchanged.
|
|
3866
|
+
*/
|
|
3867
|
+
optimization_goals?: OptimizationGoal[];
|
|
3803
3868
|
targeting_overlay?: TargetingOverlay;
|
|
3804
3869
|
/**
|
|
3805
3870
|
* Replace creative assignments for this package with optional weights and placement targeting. Uses replacement semantics - omit to leave assignments unchanged.
|
|
@@ -3815,15 +3880,12 @@ export type PackageUpdate = {
|
|
|
3815
3880
|
} & {
|
|
3816
3881
|
[k: string]: unknown | undefined;
|
|
3817
3882
|
};
|
|
3818
|
-
/**
|
|
3819
|
-
* Budget pacing strategy
|
|
3820
|
-
*/
|
|
3821
3883
|
/**
|
|
3822
3884
|
* Response payload for update_media_buy task. Returns either complete success data OR error information, never both. This enforces atomic operation semantics - updates are either fully applied or not applied at all.
|
|
3823
3885
|
*/
|
|
3824
3886
|
export type UpdateMediaBuyResponse = UpdateMediaBuySuccess | UpdateMediaBuyError;
|
|
3825
3887
|
/**
|
|
3826
|
-
*
|
|
3888
|
+
* Success response - media buy updated successfully
|
|
3827
3889
|
*/
|
|
3828
3890
|
export interface UpdateMediaBuySuccess {
|
|
3829
3891
|
/**
|
|
@@ -3850,7 +3912,7 @@ export interface UpdateMediaBuySuccess {
|
|
|
3850
3912
|
ext?: ExtensionObject;
|
|
3851
3913
|
}
|
|
3852
3914
|
/**
|
|
3853
|
-
*
|
|
3915
|
+
* Error response - operation failed, no changes applied
|
|
3854
3916
|
*/
|
|
3855
3917
|
export interface UpdateMediaBuyError {
|
|
3856
3918
|
/**
|
|
@@ -3860,9 +3922,6 @@ export interface UpdateMediaBuyError {
|
|
|
3860
3922
|
context?: ContextObject;
|
|
3861
3923
|
ext?: ExtensionObject;
|
|
3862
3924
|
}
|
|
3863
|
-
/**
|
|
3864
|
-
* Standard error structure for task-specific errors and warnings
|
|
3865
|
-
*/
|
|
3866
3925
|
/**
|
|
3867
3926
|
* Status of a media buy
|
|
3868
3927
|
*/
|
|
@@ -3871,10 +3930,7 @@ export type MediaBuyStatus = 'pending_activation' | 'active' | 'paused' | 'compl
|
|
|
3871
3930
|
* Request parameters for retrieving media buy status, creative approval state, and optional delivery snapshots
|
|
3872
3931
|
*/
|
|
3873
3932
|
export interface GetMediaBuysRequest {
|
|
3874
|
-
|
|
3875
|
-
* Filter to a specific account. When omitted, returns media buys across all accessible accounts. Optional if the agent has a single account.
|
|
3876
|
-
*/
|
|
3877
|
-
account_id?: string;
|
|
3933
|
+
account: AccountReference;
|
|
3878
3934
|
/**
|
|
3879
3935
|
* Array of publisher media buy IDs to retrieve. When omitted along with buyer_refs, returns a paginated set of accessible media buys matching status_filter.
|
|
3880
3936
|
*/
|
|
@@ -3896,10 +3952,7 @@ export interface GetMediaBuysRequest {
|
|
|
3896
3952
|
ext?: ExtensionObject;
|
|
3897
3953
|
}
|
|
3898
3954
|
/**
|
|
3899
|
-
*
|
|
3900
|
-
*/
|
|
3901
|
-
/**
|
|
3902
|
-
* Status of a media buy
|
|
3955
|
+
* Approval state of a creative on a specific package
|
|
3903
3956
|
*/
|
|
3904
3957
|
export type CreativeApprovalStatus = 'pending_review' | 'approved' | 'rejected';
|
|
3905
3958
|
/**
|
|
@@ -4065,13 +4118,10 @@ export interface GetMediaBuysResponse {
|
|
|
4065
4118
|
ext?: ExtensionObject;
|
|
4066
4119
|
}
|
|
4067
4120
|
/**
|
|
4068
|
-
*
|
|
4121
|
+
* Request parameters for retrieving comprehensive delivery metrics
|
|
4069
4122
|
*/
|
|
4070
4123
|
export interface GetMediaBuyDeliveryRequest {
|
|
4071
|
-
|
|
4072
|
-
* Filter delivery data to a specific account. When provided, only returns media buys belonging to this account. When omitted, returns data across all accessible accounts. Optional if the agent has a single account.
|
|
4073
|
-
*/
|
|
4074
|
-
account_id?: string;
|
|
4124
|
+
account?: AccountReference;
|
|
4075
4125
|
/**
|
|
4076
4126
|
* Array of publisher media buy IDs to get delivery data for
|
|
4077
4127
|
*/
|
|
@@ -4095,9 +4145,6 @@ export interface GetMediaBuyDeliveryRequest {
|
|
|
4095
4145
|
context?: ContextObject;
|
|
4096
4146
|
ext?: ExtensionObject;
|
|
4097
4147
|
}
|
|
4098
|
-
/**
|
|
4099
|
-
* Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.
|
|
4100
|
-
*/
|
|
4101
4148
|
/**
|
|
4102
4149
|
* Attribution model used to assign credit when multiple touchpoints exist
|
|
4103
4150
|
*/
|
|
@@ -4107,7 +4154,7 @@ export type AttributionModel = 'last_touch' | 'first_touch' | 'linear' | 'time_d
|
|
|
4107
4154
|
*/
|
|
4108
4155
|
export type PricingModel = 'cpm' | 'vcpm' | 'cpc' | 'cpcv' | 'cpv' | 'cpp' | 'cpa' | 'flat_rate' | 'time';
|
|
4109
4156
|
/**
|
|
4110
|
-
*
|
|
4157
|
+
* Response payload for get_media_buy_delivery task
|
|
4111
4158
|
*/
|
|
4112
4159
|
export interface GetMediaBuyDeliveryResponse {
|
|
4113
4160
|
/**
|
|
@@ -4369,7 +4416,7 @@ export interface DeliveryMetrics {
|
|
|
4369
4416
|
*/
|
|
4370
4417
|
views?: number;
|
|
4371
4418
|
/**
|
|
4372
|
-
*
|
|
4419
|
+
* Video/audio completions. When the package has a completed_views optimization goal with view_duration_seconds, completions are counted at that threshold rather than 100% completion.
|
|
4373
4420
|
*/
|
|
4374
4421
|
completed_views?: number;
|
|
4375
4422
|
/**
|
|
@@ -4527,7 +4574,23 @@ export interface DeliveryMetrics {
|
|
|
4527
4574
|
standard?: 'mrc' | 'groupm';
|
|
4528
4575
|
};
|
|
4529
4576
|
/**
|
|
4530
|
-
*
|
|
4577
|
+
* Total engagements — direct interactions with the ad beyond viewing. Includes social reactions/comments/shares, story/unit opens, interactive overlay taps on CTV, companion banner interactions on audio. Platform-specific; corresponds to the 'engagements' optimization metric.
|
|
4578
|
+
*/
|
|
4579
|
+
engagements?: number;
|
|
4580
|
+
/**
|
|
4581
|
+
* New followers, page likes, artist/podcast/channel subscribes attributed to this delivery.
|
|
4582
|
+
*/
|
|
4583
|
+
follows?: number;
|
|
4584
|
+
/**
|
|
4585
|
+
* Saves, bookmarks, playlist adds, pins attributed to this delivery.
|
|
4586
|
+
*/
|
|
4587
|
+
saves?: number;
|
|
4588
|
+
/**
|
|
4589
|
+
* Visits to the brand's in-platform page (profile, artist page, channel, or storefront) attributed to this delivery. Does not include external website clicks.
|
|
4590
|
+
*/
|
|
4591
|
+
profile_visits?: number;
|
|
4592
|
+
/**
|
|
4593
|
+
* Platform-specific engagement rate (0.0 to 1.0). Typically engagements/impressions, but definition varies by platform.
|
|
4531
4594
|
*/
|
|
4532
4595
|
engagement_rate?: number;
|
|
4533
4596
|
/**
|
|
@@ -4553,9 +4616,6 @@ export interface DeliveryMetrics {
|
|
|
4553
4616
|
value?: number;
|
|
4554
4617
|
}[];
|
|
4555
4618
|
}
|
|
4556
|
-
/**
|
|
4557
|
-
* Standard error structure for task-specific errors and warnings
|
|
4558
|
-
*/
|
|
4559
4619
|
/**
|
|
4560
4620
|
* Request payload for provide_performance_feedback task
|
|
4561
4621
|
*/
|
|
@@ -4608,9 +4668,6 @@ export type MetricType = 'overall_performance' | 'conversion_rate' | 'brand_lift
|
|
|
4608
4668
|
* Source of the performance data
|
|
4609
4669
|
*/
|
|
4610
4670
|
export type FeedbackSource = 'buyer_attribution' | 'third_party_measurement' | 'platform_analytics' | 'verification_partner';
|
|
4611
|
-
/**
|
|
4612
|
-
* Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.
|
|
4613
|
-
*/
|
|
4614
4671
|
/**
|
|
4615
4672
|
* Response payload for provide_performance_feedback task. Returns either success confirmation OR error information, never both.
|
|
4616
4673
|
*/
|
|
@@ -4631,7 +4688,7 @@ export interface ProvidePerformanceFeedbackSuccess {
|
|
|
4631
4688
|
ext?: ExtensionObject;
|
|
4632
4689
|
}
|
|
4633
4690
|
/**
|
|
4634
|
-
*
|
|
4691
|
+
* Error response - feedback rejected or could not be processed
|
|
4635
4692
|
*/
|
|
4636
4693
|
export interface ProvidePerformanceFeedbackError {
|
|
4637
4694
|
/**
|
|
@@ -4642,16 +4699,10 @@ export interface ProvidePerformanceFeedbackError {
|
|
|
4642
4699
|
ext?: ExtensionObject;
|
|
4643
4700
|
}
|
|
4644
4701
|
/**
|
|
4645
|
-
*
|
|
4646
|
-
*/
|
|
4647
|
-
/**
|
|
4648
|
-
* Standard marketing event types for event logging, aligned with IAB ECAPI
|
|
4702
|
+
* Request parameters for configuring event sources on an account with upsert semantics. Existing event sources matched by event_source_id are updated, new ones are created. When delete_missing is true, buyer-managed event sources on the account not in this request are removed. When event_sources is omitted, the call is discovery-only: it returns all event sources on the account without modification. The response always includes both synced and seller-managed event sources for full visibility.
|
|
4649
4703
|
*/
|
|
4650
4704
|
export interface SyncEventSourcesRequest {
|
|
4651
|
-
|
|
4652
|
-
* Account to configure event sources for
|
|
4653
|
-
*/
|
|
4654
|
-
account_id: string;
|
|
4705
|
+
account: AccountReference;
|
|
4655
4706
|
/**
|
|
4656
4707
|
* Event sources to sync (create or update). When omitted, the call is discovery-only and returns all existing event sources on the account without modification.
|
|
4657
4708
|
*/
|
|
@@ -4680,15 +4731,12 @@ export interface SyncEventSourcesRequest {
|
|
|
4680
4731
|
context?: ContextObject;
|
|
4681
4732
|
ext?: ExtensionObject;
|
|
4682
4733
|
}
|
|
4683
|
-
/**
|
|
4684
|
-
* Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.
|
|
4685
|
-
*/
|
|
4686
4734
|
/**
|
|
4687
4735
|
* Response from event source sync operation. Returns either per-source results OR operation-level errors.
|
|
4688
4736
|
*/
|
|
4689
4737
|
export type SyncEventSourcesResponse = SyncEventSourcesSuccess | SyncEventSourcesError;
|
|
4690
4738
|
/**
|
|
4691
|
-
*
|
|
4739
|
+
* Success response - sync operation processed event sources
|
|
4692
4740
|
*/
|
|
4693
4741
|
export interface SyncEventSourcesSuccess {
|
|
4694
4742
|
/**
|
|
@@ -4750,7 +4798,7 @@ export interface SyncEventSourcesSuccess {
|
|
|
4750
4798
|
ext?: ExtensionObject;
|
|
4751
4799
|
}
|
|
4752
4800
|
/**
|
|
4753
|
-
*
|
|
4801
|
+
* Error response - operation failed completely
|
|
4754
4802
|
*/
|
|
4755
4803
|
export interface SyncEventSourcesError {
|
|
4756
4804
|
/**
|
|
@@ -4761,10 +4809,7 @@ export interface SyncEventSourcesError {
|
|
|
4761
4809
|
ext?: ExtensionObject;
|
|
4762
4810
|
}
|
|
4763
4811
|
/**
|
|
4764
|
-
*
|
|
4765
|
-
*/
|
|
4766
|
-
/**
|
|
4767
|
-
* Standard event type
|
|
4812
|
+
* User identifiers for attribution matching
|
|
4768
4813
|
*/
|
|
4769
4814
|
export type UserMatch = {
|
|
4770
4815
|
[k: string]: unknown | undefined;
|
|
@@ -4810,7 +4855,7 @@ export type UserMatch = {
|
|
|
4810
4855
|
*/
|
|
4811
4856
|
export type UIDType = 'rampid' | 'id5' | 'uid2' | 'euid' | 'pairid' | 'external_id' | 'maid' | 'other';
|
|
4812
4857
|
/**
|
|
4813
|
-
*
|
|
4858
|
+
* Request parameters for logging marketing events
|
|
4814
4859
|
*/
|
|
4815
4860
|
export interface LogEventRequest {
|
|
4816
4861
|
/**
|
|
@@ -4857,7 +4902,7 @@ export interface Event {
|
|
|
4857
4902
|
ext?: ExtensionObject;
|
|
4858
4903
|
}
|
|
4859
4904
|
/**
|
|
4860
|
-
*
|
|
4905
|
+
* Event-specific data (value, currency, items, etc.)
|
|
4861
4906
|
*/
|
|
4862
4907
|
export interface EventCustomData {
|
|
4863
4908
|
/**
|
|
@@ -4919,9 +4964,6 @@ export interface EventCustomData {
|
|
|
4919
4964
|
}[];
|
|
4920
4965
|
ext?: ExtensionObject;
|
|
4921
4966
|
}
|
|
4922
|
-
/**
|
|
4923
|
-
* Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.
|
|
4924
|
-
*/
|
|
4925
4967
|
/**
|
|
4926
4968
|
* Response from event logging operation. Returns either event processing results OR operation-level errors.
|
|
4927
4969
|
*/
|
|
@@ -4971,7 +5013,7 @@ export interface LogEventSuccess {
|
|
|
4971
5013
|
ext?: ExtensionObject;
|
|
4972
5014
|
}
|
|
4973
5015
|
/**
|
|
4974
|
-
*
|
|
5016
|
+
* Error response - request failed entirely
|
|
4975
5017
|
*/
|
|
4976
5018
|
export interface LogEventError {
|
|
4977
5019
|
/**
|
|
@@ -4981,9 +5023,6 @@ export interface LogEventError {
|
|
|
4981
5023
|
context?: ContextObject;
|
|
4982
5024
|
ext?: ExtensionObject;
|
|
4983
5025
|
}
|
|
4984
|
-
/**
|
|
4985
|
-
* Standard error structure for task-specific errors and warnings
|
|
4986
|
-
*/
|
|
4987
5026
|
/**
|
|
4988
5027
|
* Hashed identifiers for a CRM audience member. All identifiers must be normalized before hashing: emails to lowercase+trim, phone numbers to E.164 format (e.g. +12065551234). At least one identifier is required. Providing multiple identifiers for the same person improves match rates. Composite identifiers (e.g. hashed first name + last name + zip for Google Customer Match) are not yet standardized — use the ext field for platform-specific extensions.
|
|
4989
5028
|
*/
|
|
@@ -5011,13 +5050,10 @@ export type AudienceMember = {
|
|
|
5011
5050
|
ext?: ExtensionObject;
|
|
5012
5051
|
};
|
|
5013
5052
|
/**
|
|
5014
|
-
*
|
|
5053
|
+
* Request parameters for managing CRM-based audiences on an account with upsert semantics. Existing audiences matched by audience_id are updated, new ones are created. Members are specified as delta operations: add appends new members, remove drops existing ones. Recommend no more than 100,000 members per call; for larger lists, chunk and call incrementally using add/remove deltas. When delete_missing is true, buyer-managed audiences on the account not in this request are removed — do not combine with omitted audiences or all buyer-managed audiences will be deleted. When audiences is omitted, the call is discovery-only: it returns all audiences on the account without modification.
|
|
5015
5054
|
*/
|
|
5016
5055
|
export interface SyncAudiencesRequest {
|
|
5017
|
-
|
|
5018
|
-
* Account to manage audiences for
|
|
5019
|
-
*/
|
|
5020
|
-
account_id: string;
|
|
5056
|
+
account: AccountReference;
|
|
5021
5057
|
/**
|
|
5022
5058
|
* Audiences to sync (create or update). When omitted, the call is discovery-only and returns all existing audiences on the account without modification.
|
|
5023
5059
|
*/
|
|
@@ -5054,9 +5090,6 @@ export interface SyncAudiencesRequest {
|
|
|
5054
5090
|
context?: ContextObject;
|
|
5055
5091
|
ext?: ExtensionObject;
|
|
5056
5092
|
}
|
|
5057
|
-
/**
|
|
5058
|
-
* Extension object for platform-specific, vendor-namespaced parameters. Extensions are always optional and must be namespaced under a vendor/platform key (e.g., ext.gam, ext.roku). Used for custom capabilities, partner-specific configuration, and features being proposed for standardization.
|
|
5059
|
-
*/
|
|
5060
5093
|
/**
|
|
5061
5094
|
* Response from audience sync operation. Returns either per-audience results OR operation-level errors.
|
|
5062
5095
|
*/
|
|
@@ -5118,7 +5151,7 @@ export interface SyncAudiencesSuccess {
|
|
|
5118
5151
|
ext?: ExtensionObject;
|
|
5119
5152
|
}
|
|
5120
5153
|
/**
|
|
5121
|
-
*
|
|
5154
|
+
* Error response - operation failed completely
|
|
5122
5155
|
*/
|
|
5123
5156
|
export interface SyncAudiencesError {
|
|
5124
5157
|
/**
|
|
@@ -5129,13 +5162,10 @@ export interface SyncAudiencesError {
|
|
|
5129
5162
|
ext?: ExtensionObject;
|
|
5130
5163
|
}
|
|
5131
5164
|
/**
|
|
5132
|
-
*
|
|
5165
|
+
* Request parameters for syncing catalog feeds with upsert semantics. Supports bulk operations across multiple catalog types (products, inventory, stores, promotions, offerings). Existing catalogs matched by catalog_id are updated, new ones are created. When catalogs is omitted, the call is discovery-only: returns all catalogs on the account without modification.
|
|
5133
5166
|
*/
|
|
5134
5167
|
export interface SyncCatalogsRequest {
|
|
5135
|
-
|
|
5136
|
-
* Account that owns these catalogs. Required if the agent has multiple accounts and the seller cannot route automatically.
|
|
5137
|
-
*/
|
|
5138
|
-
account_id?: string;
|
|
5168
|
+
account: AccountReference;
|
|
5139
5169
|
/**
|
|
5140
5170
|
* Array of catalog feeds to sync (create or update). When omitted, the call is discovery-only and returns all existing catalogs on the account without modification.
|
|
5141
5171
|
*
|
|
@@ -5162,10 +5192,7 @@ export interface SyncCatalogsRequest {
|
|
|
5162
5192
|
ext?: ExtensionObject;
|
|
5163
5193
|
}
|
|
5164
5194
|
/**
|
|
5165
|
-
*
|
|
5166
|
-
*/
|
|
5167
|
-
/**
|
|
5168
|
-
* Response from catalog sync operation. Returns either per-catalog results (best-effort processing) OR operation-level errors (complete failure). Platforms may approve, reject, or flag individual items within each catalog (similar to Google Merchant Center product review).
|
|
5195
|
+
* Response from catalog sync operation. Returns either per-catalog results (best-effort processing) OR operation-level errors (complete failure). Platforms may approve, reject, or flag individual items within each catalog (similar to Google Merchant Center product review).
|
|
5169
5196
|
*/
|
|
5170
5197
|
export type SyncCatalogsResponse = SyncCatalogsSuccess | SyncCatalogsError;
|
|
5171
5198
|
/**
|
|
@@ -5256,7 +5283,7 @@ export interface SyncCatalogsSuccess {
|
|
|
5256
5283
|
ext?: ExtensionObject;
|
|
5257
5284
|
}
|
|
5258
5285
|
/**
|
|
5259
|
-
*
|
|
5286
|
+
* Error response - operation failed completely, no catalogs were processed
|
|
5260
5287
|
*/
|
|
5261
5288
|
export interface SyncCatalogsError {
|
|
5262
5289
|
/**
|
|
@@ -5267,14 +5294,11 @@ export interface SyncCatalogsError {
|
|
|
5267
5294
|
ext?: ExtensionObject;
|
|
5268
5295
|
}
|
|
5269
5296
|
/**
|
|
5270
|
-
*
|
|
5271
|
-
*/
|
|
5272
|
-
/**
|
|
5273
|
-
* Catalog type. Structural types: 'offering' (AdCP Offering objects), 'product' (ecommerce entries), 'inventory' (stock per location), 'store' (physical locations), 'promotion' (deals and pricing). Vertical types: 'hotel', 'flight', 'job', 'vehicle', 'real_estate', 'education', 'destination', 'app' — each with an industry-specific item schema.
|
|
5297
|
+
* HTTP method
|
|
5274
5298
|
*/
|
|
5275
5299
|
export type HTTPMethod = 'GET' | 'POST';
|
|
5276
5300
|
/**
|
|
5277
|
-
*
|
|
5301
|
+
* Expected content type of webhook response
|
|
5278
5302
|
*/
|
|
5279
5303
|
export type WebhookResponseType = 'html' | 'json' | 'xml' | 'javascript';
|
|
5280
5304
|
/**
|
|
@@ -5282,7 +5306,7 @@ export type WebhookResponseType = 'html' | 'json' | 'xml' | 'javascript';
|
|
|
5282
5306
|
*/
|
|
5283
5307
|
export type WebhookSecurityMethod = 'hmac_sha256' | 'api_key' | 'none';
|
|
5284
5308
|
/**
|
|
5285
|
-
*
|
|
5309
|
+
* Campaign-level creative brief with objective, audience, messaging, and reference assets. Can be an inline brief object or a URL to a hosted brief. Supplements the natural language message with structured creative direction.
|
|
5286
5310
|
*/
|
|
5287
5311
|
export type CreativeBriefReference = CreativeBrief | string;
|
|
5288
5312
|
/**
|
|
@@ -5324,7 +5348,7 @@ export interface CreativeManifest {
|
|
|
5324
5348
|
ext?: ExtensionObject;
|
|
5325
5349
|
}
|
|
5326
5350
|
/**
|
|
5327
|
-
*
|
|
5351
|
+
* Webhook for server-side dynamic content rendering (DCO)
|
|
5328
5352
|
*/
|
|
5329
5353
|
export interface WebhookAsset {
|
|
5330
5354
|
/**
|
|
@@ -5361,7 +5385,7 @@ export interface WebhookAsset {
|
|
|
5361
5385
|
};
|
|
5362
5386
|
}
|
|
5363
5387
|
/**
|
|
5364
|
-
*
|
|
5388
|
+
* Inline creative brief object
|
|
5365
5389
|
*/
|
|
5366
5390
|
export interface CreativeBrief {
|
|
5367
5391
|
/**
|
|
@@ -5427,15 +5451,12 @@ export interface ReferenceAsset {
|
|
|
5427
5451
|
*/
|
|
5428
5452
|
description?: string;
|
|
5429
5453
|
}
|
|
5430
|
-
/**
|
|
5431
|
-
* Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.
|
|
5432
|
-
*/
|
|
5433
5454
|
/**
|
|
5434
5455
|
* Response containing the transformed or generated creative manifest, ready for use with preview_creative or sync_creatives. Returns either the complete creative manifest OR error information, never both.
|
|
5435
5456
|
*/
|
|
5436
5457
|
export type BuildCreativeResponse = BuildCreativeSuccess | BuildCreativeError;
|
|
5437
5458
|
/**
|
|
5438
|
-
*
|
|
5459
|
+
* Success response - creative manifest generated successfully
|
|
5439
5460
|
*/
|
|
5440
5461
|
export interface BuildCreativeSuccess {
|
|
5441
5462
|
creative_manifest: CreativeManifest;
|
|
@@ -5447,7 +5468,7 @@ export interface BuildCreativeSuccess {
|
|
|
5447
5468
|
ext?: ExtensionObject;
|
|
5448
5469
|
}
|
|
5449
5470
|
/**
|
|
5450
|
-
*
|
|
5471
|
+
* Error response - creative generation failed
|
|
5451
5472
|
*/
|
|
5452
5473
|
export interface BuildCreativeError {
|
|
5453
5474
|
/**
|
|
@@ -5457,9 +5478,6 @@ export interface BuildCreativeError {
|
|
|
5457
5478
|
context?: ContextObject;
|
|
5458
5479
|
ext?: ExtensionObject;
|
|
5459
5480
|
}
|
|
5460
|
-
/**
|
|
5461
|
-
* Standard error structure for task-specific errors and warnings
|
|
5462
|
-
*/
|
|
5463
5481
|
/**
|
|
5464
5482
|
* Request to generate previews of one or more creative manifests. Accepts either a single creative request or an array of requests for batch processing.
|
|
5465
5483
|
*/
|
|
@@ -5555,11 +5573,11 @@ export type PreviewCreativeRequest = {
|
|
|
5555
5573
|
ext?: ExtensionObject;
|
|
5556
5574
|
};
|
|
5557
5575
|
/**
|
|
5558
|
-
*
|
|
5576
|
+
* Output format for previews. 'url' returns preview_url (iframe-embeddable URL), 'html' returns preview_html (raw HTML for direct embedding). Default: 'url' for backward compatibility.
|
|
5559
5577
|
*/
|
|
5560
5578
|
export type PreviewOutputFormat = 'url' | 'html';
|
|
5561
5579
|
/**
|
|
5562
|
-
*
|
|
5580
|
+
* Complete creative manifest with all required assets
|
|
5563
5581
|
*/
|
|
5564
5582
|
export interface CreativeManifest1 {
|
|
5565
5583
|
format_id: FormatID;
|
|
@@ -5729,7 +5747,7 @@ export type PreviewRender = {
|
|
|
5729
5747
|
};
|
|
5730
5748
|
};
|
|
5731
5749
|
/**
|
|
5732
|
-
*
|
|
5750
|
+
* Single preview response - each preview URL returns an HTML page that can be embedded in an iframe
|
|
5733
5751
|
*/
|
|
5734
5752
|
export interface PreviewCreativeSingleResponse {
|
|
5735
5753
|
/**
|
|
@@ -5780,7 +5798,7 @@ export interface PreviewCreativeSingleResponse {
|
|
|
5780
5798
|
ext?: ExtensionObject;
|
|
5781
5799
|
}
|
|
5782
5800
|
/**
|
|
5783
|
-
*
|
|
5801
|
+
* Batch preview response - contains results for multiple creative requests
|
|
5784
5802
|
*/
|
|
5785
5803
|
export interface PreviewCreativeBatchResponse {
|
|
5786
5804
|
/**
|
|
@@ -5837,19 +5855,13 @@ export interface PreviewCreativeVariantResponse {
|
|
|
5837
5855
|
context?: ContextObject;
|
|
5838
5856
|
ext?: ExtensionObject;
|
|
5839
5857
|
}
|
|
5840
|
-
/**
|
|
5841
|
-
* The rendered creative manifest for this variant — the actual output that was served, not the input assets
|
|
5842
|
-
*/
|
|
5843
5858
|
/**
|
|
5844
5859
|
* Request parameters for retrieving creative delivery data including variant-level metrics from a creative agent. At least one scoping filter (media_buy_ids, media_buy_buyer_refs, or creative_ids) is required.
|
|
5845
5860
|
*/
|
|
5846
5861
|
export type GetCreativeDeliveryRequest = {
|
|
5847
5862
|
[k: string]: unknown | undefined;
|
|
5848
5863
|
} & {
|
|
5849
|
-
|
|
5850
|
-
* Account context for routing and scoping. Limits results to creatives within this account. Optional if the agent has a single account or can determine routing from the media buy identifiers.
|
|
5851
|
-
*/
|
|
5852
|
-
account_id?: string;
|
|
5864
|
+
account?: AccountReference;
|
|
5853
5865
|
/**
|
|
5854
5866
|
* Filter to specific media buys by publisher ID. If omitted, returns creative delivery across all matching media buys.
|
|
5855
5867
|
*/
|
|
@@ -5891,10 +5903,7 @@ export type GetCreativeDeliveryRequest = {
|
|
|
5891
5903
|
ext?: ExtensionObject;
|
|
5892
5904
|
};
|
|
5893
5905
|
/**
|
|
5894
|
-
*
|
|
5895
|
-
*/
|
|
5896
|
-
/**
|
|
5897
|
-
* The event type
|
|
5906
|
+
* A specific execution variant of a creative with delivery metrics. For catalog-driven packages, each catalog item rendered as a distinct ad execution is a variant — the variant's manifest includes the catalog reference with the specific item rendered. For asset group optimization, represents one combination of assets the platform selected. For generative creative, represents a platform-generated variant. For standard creatives, maps 1:1 with the creative itself.
|
|
5898
5907
|
*/
|
|
5899
5908
|
export type CreativeVariant = DeliveryMetrics & {
|
|
5900
5909
|
/**
|
|
@@ -5924,7 +5933,7 @@ export type CreativeVariant = DeliveryMetrics & {
|
|
|
5924
5933
|
};
|
|
5925
5934
|
};
|
|
5926
5935
|
/**
|
|
5927
|
-
*
|
|
5936
|
+
* Type of identifier
|
|
5928
5937
|
*/
|
|
5929
5938
|
export type PropertyIdentifierTypes = 'domain' | 'subdomain' | 'network_id' | 'ios_bundle' | 'android_package' | 'apple_app_store_id' | 'google_play_id' | 'roku_store_id' | 'fire_tv_asin' | 'samsung_app_id' | 'apple_tv_bundle' | 'bundle_id' | 'venue_id' | 'screen_id' | 'openooh_venue_type' | 'rss_url' | 'apple_podcast_id' | 'spotify_show_id' | 'podcast_guid';
|
|
5930
5939
|
/**
|
|
@@ -6016,7 +6025,7 @@ export interface GetCreativeDeliveryResponse {
|
|
|
6016
6025
|
ext?: ExtensionObject;
|
|
6017
6026
|
}
|
|
6018
6027
|
/**
|
|
6019
|
-
*
|
|
6028
|
+
* Property where the artifact appears
|
|
6020
6029
|
*/
|
|
6021
6030
|
export interface Identifier {
|
|
6022
6031
|
type: PropertyIdentifierTypes;
|
|
@@ -6025,9 +6034,6 @@ export interface Identifier {
|
|
|
6025
6034
|
*/
|
|
6026
6035
|
value: string;
|
|
6027
6036
|
}
|
|
6028
|
-
/**
|
|
6029
|
-
* Standard error structure for task-specific errors and warnings
|
|
6030
|
-
*/
|
|
6031
6037
|
/**
|
|
6032
6038
|
* Request parameters for discovering signals. Use signal_spec for natural language discovery, signal_ids for exact lookups, or both (signal_ids take precedence for exact matches, signal_spec provides additional discovery context).
|
|
6033
6039
|
*/
|
|
@@ -6065,7 +6071,7 @@ export type GetSignalsRequest = {
|
|
|
6065
6071
|
ext?: ExtensionObject;
|
|
6066
6072
|
};
|
|
6067
6073
|
/**
|
|
6068
|
-
*
|
|
6074
|
+
* A deployment target where signals can be activated (DSP, sales agent, etc.)
|
|
6069
6075
|
*/
|
|
6070
6076
|
export type Destination = {
|
|
6071
6077
|
/**
|
|
@@ -6120,14 +6126,11 @@ export interface SignalFilters {
|
|
|
6120
6126
|
min_coverage_percentage?: number;
|
|
6121
6127
|
}
|
|
6122
6128
|
/**
|
|
6123
|
-
*
|
|
6124
|
-
*/
|
|
6125
|
-
/**
|
|
6126
|
-
* Universal signal identifier referencing the data provider's catalog. Use this to verify authorization and look up signal definitions.
|
|
6129
|
+
* The data type of this signal's values (binary, categorical, numeric)
|
|
6127
6130
|
*/
|
|
6128
6131
|
export type SignalValueType = 'binary' | 'categorical' | 'numeric';
|
|
6129
6132
|
/**
|
|
6130
|
-
*
|
|
6133
|
+
* A signal deployment to a specific deployment target with activation status and key
|
|
6131
6134
|
*/
|
|
6132
6135
|
export type Deployment = {
|
|
6133
6136
|
/**
|
|
@@ -6209,7 +6212,7 @@ export type ActivationKey = {
|
|
|
6209
6212
|
value: string;
|
|
6210
6213
|
};
|
|
6211
6214
|
/**
|
|
6212
|
-
*
|
|
6215
|
+
* Response payload for get_signals task
|
|
6213
6216
|
*/
|
|
6214
6217
|
export interface GetSignalsResponse {
|
|
6215
6218
|
/**
|
|
@@ -6244,18 +6247,9 @@ export interface GetSignalsResponse {
|
|
|
6244
6247
|
*/
|
|
6245
6248
|
deployments: Deployment[];
|
|
6246
6249
|
/**
|
|
6247
|
-
* Pricing
|
|
6250
|
+
* Pricing options available for this signal. The buyer selects one and passes its pricing_option_id in report_usage for billing verification.
|
|
6248
6251
|
*/
|
|
6249
|
-
|
|
6250
|
-
/**
|
|
6251
|
-
* Cost per thousand impressions
|
|
6252
|
-
*/
|
|
6253
|
-
cpm: number;
|
|
6254
|
-
/**
|
|
6255
|
-
* Currency code
|
|
6256
|
-
*/
|
|
6257
|
-
currency: string;
|
|
6258
|
-
};
|
|
6252
|
+
pricing_options: PricingOption[];
|
|
6259
6253
|
}[];
|
|
6260
6254
|
/**
|
|
6261
6255
|
* Task-specific errors and warnings (e.g., signal discovery or pricing issues)
|
|
@@ -6270,10 +6264,7 @@ export interface GetSignalsResponse {
|
|
|
6270
6264
|
ext?: ExtensionObject;
|
|
6271
6265
|
}
|
|
6272
6266
|
/**
|
|
6273
|
-
*
|
|
6274
|
-
*/
|
|
6275
|
-
/**
|
|
6276
|
-
* A deployment target where signals can be activated (DSP, sales agent, etc.)
|
|
6267
|
+
* Request parameters for activating a signal on a specific deployment target
|
|
6277
6268
|
*/
|
|
6278
6269
|
export interface ActivateSignalRequest {
|
|
6279
6270
|
/**
|
|
@@ -6284,18 +6275,19 @@ export interface ActivateSignalRequest {
|
|
|
6284
6275
|
* Target deployment(s) for activation. If the authenticated caller matches one of these deployment targets, activation keys will be included in the response.
|
|
6285
6276
|
*/
|
|
6286
6277
|
deployments: Destination[];
|
|
6278
|
+
/**
|
|
6279
|
+
* The pricing option selected from the signal's pricing_options in the get_signals response. Required when the signal has pricing options. Records the buyer's pricing commitment at activation time and is referenced in subsequent report_usage calls.
|
|
6280
|
+
*/
|
|
6281
|
+
pricing_option_id?: string;
|
|
6287
6282
|
context?: ContextObject;
|
|
6288
6283
|
ext?: ExtensionObject;
|
|
6289
6284
|
}
|
|
6290
|
-
/**
|
|
6291
|
-
* Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.
|
|
6292
|
-
*/
|
|
6293
6285
|
/**
|
|
6294
6286
|
* Response payload for activate_signal task. Returns either complete success data OR error information, never both. This enforces atomic operation semantics - the signal is either fully activated or not activated at all.
|
|
6295
6287
|
*/
|
|
6296
6288
|
export type ActivateSignalResponse = ActivateSignalSuccess | ActivateSignalError;
|
|
6297
6289
|
/**
|
|
6298
|
-
*
|
|
6290
|
+
* Success response - signal activated successfully to one or more deployment targets
|
|
6299
6291
|
*/
|
|
6300
6292
|
export interface ActivateSignalSuccess {
|
|
6301
6293
|
/**
|
|
@@ -6310,7 +6302,7 @@ export interface ActivateSignalSuccess {
|
|
|
6310
6302
|
ext?: ExtensionObject;
|
|
6311
6303
|
}
|
|
6312
6304
|
/**
|
|
6313
|
-
*
|
|
6305
|
+
* Error response - operation failed, signal not activated
|
|
6314
6306
|
*/
|
|
6315
6307
|
export interface ActivateSignalError {
|
|
6316
6308
|
/**
|
|
@@ -6320,19 +6312,16 @@ export interface ActivateSignalError {
|
|
|
6320
6312
|
context?: ContextObject;
|
|
6321
6313
|
ext?: ExtensionObject;
|
|
6322
6314
|
}
|
|
6323
|
-
/**
|
|
6324
|
-
* Standard error structure for task-specific errors and warnings
|
|
6325
|
-
*/
|
|
6326
6315
|
/**
|
|
6327
6316
|
* A source of properties for a property list. Supports three selection patterns: publisher with tags, publisher with property IDs, or direct identifiers.
|
|
6328
6317
|
*/
|
|
6329
6318
|
export type BasePropertySource = PublisherTagsSource | PublisherPropertyIDsSource | DirectIdentifiersSource;
|
|
6330
6319
|
/**
|
|
6331
|
-
*
|
|
6320
|
+
* Types of addressable advertising properties with verifiable ownership. Property types are a subset of media channels - they represent inventory surfaces that can be validated via adagents.json.
|
|
6332
6321
|
*/
|
|
6333
6322
|
export type PropertyType = 'website' | 'mobile_app' | 'ctv_app' | 'desktop_app' | 'dooh' | 'podcast' | 'radio' | 'streaming_audio';
|
|
6334
6323
|
/**
|
|
6335
|
-
*
|
|
6324
|
+
* Request parameters for creating a new property list
|
|
6336
6325
|
*/
|
|
6337
6326
|
export interface CreatePropertyListRequest {
|
|
6338
6327
|
/**
|
|
@@ -6400,7 +6389,7 @@ export interface DirectIdentifiersSource {
|
|
|
6400
6389
|
identifiers: Identifier[];
|
|
6401
6390
|
}
|
|
6402
6391
|
/**
|
|
6403
|
-
*
|
|
6392
|
+
* Dynamic filters to apply when resolving the list
|
|
6404
6393
|
*/
|
|
6405
6394
|
export interface PropertyListFilters {
|
|
6406
6395
|
/**
|
|
@@ -6450,10 +6439,7 @@ export interface FeatureRequirement {
|
|
|
6450
6439
|
if_not_covered?: 'exclude' | 'include';
|
|
6451
6440
|
}
|
|
6452
6441
|
/**
|
|
6453
|
-
*
|
|
6454
|
-
*/
|
|
6455
|
-
/**
|
|
6456
|
-
* A source of properties for a property list. Supports three selection patterns: publisher with tags, publisher with property IDs, or direct identifiers.
|
|
6442
|
+
* Response payload for create_property_list task
|
|
6457
6443
|
*/
|
|
6458
6444
|
export interface CreatePropertyListResponse {
|
|
6459
6445
|
list: PropertyList;
|
|
@@ -6511,10 +6497,7 @@ export interface PropertyList {
|
|
|
6511
6497
|
property_count?: number;
|
|
6512
6498
|
}
|
|
6513
6499
|
/**
|
|
6514
|
-
*
|
|
6515
|
-
*/
|
|
6516
|
-
/**
|
|
6517
|
-
* A source of properties for a property list. Supports three selection patterns: publisher with tags, publisher with property IDs, or direct identifiers.
|
|
6500
|
+
* Request parameters for updating an existing property list
|
|
6518
6501
|
*/
|
|
6519
6502
|
export interface UpdatePropertyListRequest {
|
|
6520
6503
|
/**
|
|
@@ -6543,18 +6526,12 @@ export interface UpdatePropertyListRequest {
|
|
|
6543
6526
|
ext?: ExtensionObject;
|
|
6544
6527
|
}
|
|
6545
6528
|
/**
|
|
6546
|
-
*
|
|
6547
|
-
*/
|
|
6548
|
-
/**
|
|
6549
|
-
* A source of properties for a property list. Supports three selection patterns: publisher with tags, publisher with property IDs, or direct identifiers.
|
|
6529
|
+
* Response payload for update_property_list task
|
|
6550
6530
|
*/
|
|
6551
6531
|
export interface UpdatePropertyListResponse {
|
|
6552
6532
|
list: PropertyList;
|
|
6553
6533
|
ext?: ExtensionObject;
|
|
6554
6534
|
}
|
|
6555
|
-
/**
|
|
6556
|
-
* The updated property list
|
|
6557
|
-
*/
|
|
6558
6535
|
/**
|
|
6559
6536
|
* Request parameters for retrieving a property list with resolved identifiers
|
|
6560
6537
|
*/
|
|
@@ -6584,10 +6561,7 @@ export interface GetPropertyListRequest {
|
|
|
6584
6561
|
ext?: ExtensionObject;
|
|
6585
6562
|
}
|
|
6586
6563
|
/**
|
|
6587
|
-
*
|
|
6588
|
-
*/
|
|
6589
|
-
/**
|
|
6590
|
-
* A source of properties for a property list. Supports three selection patterns: publisher with tags, publisher with property IDs, or direct identifiers.
|
|
6564
|
+
* Response payload for get_property_list task. Returns identifiers only (not full property objects or scores). Consumers should cache the resolved identifiers and refresh based on cache_valid_until.
|
|
6591
6565
|
*/
|
|
6592
6566
|
export interface GetPropertyListResponse {
|
|
6593
6567
|
list: PropertyList;
|
|
@@ -6612,9 +6586,6 @@ export interface GetPropertyListResponse {
|
|
|
6612
6586
|
};
|
|
6613
6587
|
ext?: ExtensionObject;
|
|
6614
6588
|
}
|
|
6615
|
-
/**
|
|
6616
|
-
* The property list metadata (always returned)
|
|
6617
|
-
*/
|
|
6618
6589
|
/**
|
|
6619
6590
|
* Request parameters for listing property lists
|
|
6620
6591
|
*/
|
|
@@ -6632,10 +6603,7 @@ export interface ListPropertyListsRequest {
|
|
|
6632
6603
|
ext?: ExtensionObject;
|
|
6633
6604
|
}
|
|
6634
6605
|
/**
|
|
6635
|
-
*
|
|
6636
|
-
*/
|
|
6637
|
-
/**
|
|
6638
|
-
* A source of properties for a property list. Supports three selection patterns: publisher with tags, publisher with property IDs, or direct identifiers.
|
|
6606
|
+
* Response payload for list_property_lists task
|
|
6639
6607
|
*/
|
|
6640
6608
|
export interface ListPropertyListsResponse {
|
|
6641
6609
|
/**
|
|
@@ -6645,9 +6613,6 @@ export interface ListPropertyListsResponse {
|
|
|
6645
6613
|
pagination?: PaginationResponse;
|
|
6646
6614
|
ext?: ExtensionObject;
|
|
6647
6615
|
}
|
|
6648
|
-
/**
|
|
6649
|
-
* A managed property list with optional filters for dynamic evaluation. Lists are resolved at setup time and cached by orchestrators/sellers for real-time use.
|
|
6650
|
-
*/
|
|
6651
6616
|
/**
|
|
6652
6617
|
* Request parameters for deleting a property list
|
|
6653
6618
|
*/
|
|
@@ -6659,9 +6624,6 @@ export interface DeletePropertyListRequest {
|
|
|
6659
6624
|
context?: ContextObject;
|
|
6660
6625
|
ext?: ExtensionObject;
|
|
6661
6626
|
}
|
|
6662
|
-
/**
|
|
6663
|
-
* Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.
|
|
6664
|
-
*/
|
|
6665
6627
|
/**
|
|
6666
6628
|
* Response payload for delete_property_list task
|
|
6667
6629
|
*/
|
|
@@ -6677,10 +6639,7 @@ export interface DeletePropertyListResponse {
|
|
|
6677
6639
|
ext?: ExtensionObject;
|
|
6678
6640
|
}
|
|
6679
6641
|
/**
|
|
6680
|
-
*
|
|
6681
|
-
*/
|
|
6682
|
-
/**
|
|
6683
|
-
* Standardized advertising media channels describing how buyers allocate budget. Channels are planning abstractions, not technical substrates. See the Media Channel Taxonomy specification for detailed definitions.
|
|
6642
|
+
* Request parameters for listing content standards configurations
|
|
6684
6643
|
*/
|
|
6685
6644
|
export interface ListContentStandardsRequest {
|
|
6686
6645
|
/**
|
|
@@ -6699,9 +6658,6 @@ export interface ListContentStandardsRequest {
|
|
|
6699
6658
|
context?: ContextObject;
|
|
6700
6659
|
ext?: ExtensionObject;
|
|
6701
6660
|
}
|
|
6702
|
-
/**
|
|
6703
|
-
* Standard cursor-based pagination parameters for list operations
|
|
6704
|
-
*/
|
|
6705
6661
|
/**
|
|
6706
6662
|
* Response payload with list of content standards configurations
|
|
6707
6663
|
*/
|
|
@@ -6731,7 +6687,7 @@ export type ListContentStandardsResponse = {
|
|
|
6731
6687
|
ext?: ExtensionObject;
|
|
6732
6688
|
};
|
|
6733
6689
|
/**
|
|
6734
|
-
*
|
|
6690
|
+
* Authentication for secured URLs
|
|
6735
6691
|
*/
|
|
6736
6692
|
export type AssetAccess = {
|
|
6737
6693
|
method: 'bearer_token';
|
|
@@ -6753,7 +6709,7 @@ export type AssetAccess = {
|
|
|
6753
6709
|
method: 'signed_url';
|
|
6754
6710
|
};
|
|
6755
6711
|
/**
|
|
6756
|
-
*
|
|
6712
|
+
* A content standards configuration defining brand safety and suitability policies. Standards are scoped by brand, geography, and channel. Multiple standards can be active simultaneously for different scopes.
|
|
6757
6713
|
*/
|
|
6758
6714
|
export interface ContentStandards {
|
|
6759
6715
|
/**
|
|
@@ -6793,6 +6749,10 @@ export interface ContentStandards {
|
|
|
6793
6749
|
*/
|
|
6794
6750
|
fail?: Artifact[];
|
|
6795
6751
|
};
|
|
6752
|
+
/**
|
|
6753
|
+
* Pricing options for this content standards service. The buyer passes the selected pricing_option_id in report_usage for billing verification.
|
|
6754
|
+
*/
|
|
6755
|
+
pricing_options?: PricingOption[];
|
|
6796
6756
|
ext?: ExtensionObject;
|
|
6797
6757
|
}
|
|
6798
6758
|
/**
|
|
@@ -6963,9 +6923,6 @@ export interface Artifact {
|
|
|
6963
6923
|
rss_url?: string;
|
|
6964
6924
|
};
|
|
6965
6925
|
}
|
|
6966
|
-
/**
|
|
6967
|
-
* Identifier for the property where this artifact appears
|
|
6968
|
-
*/
|
|
6969
6926
|
/**
|
|
6970
6927
|
* Request parameters for retrieving content safety policies
|
|
6971
6928
|
*/
|
|
@@ -6977,9 +6934,6 @@ export interface GetContentStandardsRequest {
|
|
|
6977
6934
|
context?: ContextObject;
|
|
6978
6935
|
ext?: ExtensionObject;
|
|
6979
6936
|
}
|
|
6980
|
-
/**
|
|
6981
|
-
* Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.
|
|
6982
|
-
*/
|
|
6983
6937
|
/**
|
|
6984
6938
|
* Response payload with content safety policies
|
|
6985
6939
|
*/
|
|
@@ -6995,10 +6949,7 @@ export type GetContentStandardsResponse = ContentStandards | {
|
|
|
6995
6949
|
ext?: ExtensionObject;
|
|
6996
6950
|
};
|
|
6997
6951
|
/**
|
|
6998
|
-
*
|
|
6999
|
-
*/
|
|
7000
|
-
/**
|
|
7001
|
-
* Standardized advertising media channels describing how buyers allocate budget. Channels are planning abstractions, not technical substrates. See the Media Channel Taxonomy specification for detailed definitions.
|
|
6952
|
+
* Request parameters for creating a new content standards configuration
|
|
7002
6953
|
*/
|
|
7003
6954
|
export interface CreateContentStandardsRequest {
|
|
7004
6955
|
/**
|
|
@@ -7069,7 +7020,7 @@ export interface CreateContentStandardsRequest {
|
|
|
7069
7020
|
ext?: ExtensionObject;
|
|
7070
7021
|
}
|
|
7071
7022
|
/**
|
|
7072
|
-
*
|
|
7023
|
+
* Response payload for creating a content standards configuration
|
|
7073
7024
|
*/
|
|
7074
7025
|
export type CreateContentStandardsResponse = {
|
|
7075
7026
|
/**
|
|
@@ -7100,10 +7051,7 @@ export type CreateContentStandardsResponse = {
|
|
|
7100
7051
|
ext?: ExtensionObject;
|
|
7101
7052
|
};
|
|
7102
7053
|
/**
|
|
7103
|
-
*
|
|
7104
|
-
*/
|
|
7105
|
-
/**
|
|
7106
|
-
* Standardized advertising media channels describing how buyers allocate budget. Channels are planning abstractions, not technical substrates. See the Media Channel Taxonomy specification for detailed definitions.
|
|
7054
|
+
* Request parameters for updating an existing content standards configuration. Creates a new version.
|
|
7107
7055
|
*/
|
|
7108
7056
|
export interface UpdateContentStandardsRequest {
|
|
7109
7057
|
/**
|
|
@@ -7177,9 +7125,6 @@ export interface UpdateContentStandardsRequest {
|
|
|
7177
7125
|
context?: ContextObject;
|
|
7178
7126
|
ext?: ExtensionObject;
|
|
7179
7127
|
}
|
|
7180
|
-
/**
|
|
7181
|
-
* Full artifact with pre-extracted content (text, images, video, audio)
|
|
7182
|
-
*/
|
|
7183
7128
|
/**
|
|
7184
7129
|
* Response from updating a content standards configuration
|
|
7185
7130
|
*/
|
|
@@ -7200,10 +7145,7 @@ export interface UpdateContentStandardsResponse {
|
|
|
7200
7145
|
ext?: ExtensionObject;
|
|
7201
7146
|
}
|
|
7202
7147
|
/**
|
|
7203
|
-
*
|
|
7204
|
-
*/
|
|
7205
|
-
/**
|
|
7206
|
-
* Type of identifier
|
|
7148
|
+
* Request parameters for evaluating content during calibration. Multi-turn dialogue is handled at the protocol layer via contextId.
|
|
7207
7149
|
*/
|
|
7208
7150
|
export interface CalibrateContentRequest {
|
|
7209
7151
|
/**
|
|
@@ -7212,9 +7154,6 @@ export interface CalibrateContentRequest {
|
|
|
7212
7154
|
standards_id: string;
|
|
7213
7155
|
artifact: Artifact;
|
|
7214
7156
|
}
|
|
7215
|
-
/**
|
|
7216
|
-
* Artifact to evaluate
|
|
7217
|
-
*/
|
|
7218
7157
|
/**
|
|
7219
7158
|
* Response payload with verdict and detailed explanations for collaborative calibration
|
|
7220
7159
|
*/
|
|
@@ -7264,10 +7203,7 @@ export type CalibrateContentResponse = {
|
|
|
7264
7203
|
};
|
|
7265
7204
|
};
|
|
7266
7205
|
/**
|
|
7267
|
-
*
|
|
7268
|
-
*/
|
|
7269
|
-
/**
|
|
7270
|
-
* Type of identifier
|
|
7206
|
+
* Request parameters for batch validating delivery records against content safety policies
|
|
7271
7207
|
*/
|
|
7272
7208
|
export interface ValidateContentDeliveryRequest {
|
|
7273
7209
|
/**
|
|
@@ -7326,9 +7262,6 @@ export interface ValidateContentDeliveryRequest {
|
|
|
7326
7262
|
context?: ContextObject;
|
|
7327
7263
|
ext?: ExtensionObject;
|
|
7328
7264
|
}
|
|
7329
|
-
/**
|
|
7330
|
-
* Artifact where ad was delivered
|
|
7331
|
-
*/
|
|
7332
7265
|
/**
|
|
7333
7266
|
* Response payload with per-record verdicts and optional feature breakdown
|
|
7334
7267
|
*/
|
|
@@ -7386,17 +7319,11 @@ export type ValidateContentDeliveryResponse = {
|
|
|
7386
7319
|
context?: ContextObject;
|
|
7387
7320
|
ext?: ExtensionObject;
|
|
7388
7321
|
};
|
|
7389
|
-
/**
|
|
7390
|
-
* Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.
|
|
7391
|
-
*/
|
|
7392
7322
|
/**
|
|
7393
7323
|
* Request parameters for retrieving content artifacts from a media buy for validation
|
|
7394
7324
|
*/
|
|
7395
7325
|
export interface GetMediaBuyArtifactsRequest {
|
|
7396
|
-
|
|
7397
|
-
* Filter artifacts to a specific account. When provided, only returns artifacts for media buys belonging to this account. When omitted, returns artifacts across all accessible accounts. Optional if the agent has a single account.
|
|
7398
|
-
*/
|
|
7399
|
-
account_id?: string;
|
|
7326
|
+
account?: AccountReference;
|
|
7400
7327
|
/**
|
|
7401
7328
|
* Media buy to get artifacts from
|
|
7402
7329
|
*/
|
|
@@ -7447,9 +7374,6 @@ export interface GetMediaBuyArtifactsRequest {
|
|
|
7447
7374
|
context?: ContextObject;
|
|
7448
7375
|
ext?: ExtensionObject;
|
|
7449
7376
|
}
|
|
7450
|
-
/**
|
|
7451
|
-
* Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.
|
|
7452
|
-
*/
|
|
7453
7377
|
/**
|
|
7454
7378
|
* Response containing content artifacts from a media buy for validation
|
|
7455
7379
|
*/
|
|
@@ -7543,10 +7467,7 @@ export type GetMediaBuyArtifactsResponse = {
|
|
|
7543
7467
|
ext?: ExtensionObject;
|
|
7544
7468
|
};
|
|
7545
7469
|
/**
|
|
7546
|
-
*
|
|
7547
|
-
*/
|
|
7548
|
-
/**
|
|
7549
|
-
* Catalog type. Structural types: 'offering' (AdCP Offering objects), 'product' (ecommerce entries), 'inventory' (stock per location), 'store' (physical locations), 'promotion' (deals and pricing). Vertical types: 'hotel', 'flight', 'job', 'vehicle', 'real_estate', 'education', 'destination', 'app' — each with an industry-specific item schema.
|
|
7470
|
+
* Request payload for get_creative_features task. Evaluates a creative manifest and returns feature values from a creative governance agent.
|
|
7550
7471
|
*/
|
|
7551
7472
|
export interface GetCreativeFeaturesRequest {
|
|
7552
7473
|
creative_manifest: CreativeManifest;
|
|
@@ -7557,9 +7478,6 @@ export interface GetCreativeFeaturesRequest {
|
|
|
7557
7478
|
context?: ContextObject;
|
|
7558
7479
|
ext?: ExtensionObject;
|
|
7559
7480
|
}
|
|
7560
|
-
/**
|
|
7561
|
-
* The creative manifest to evaluate. Contains format_id and assets.
|
|
7562
|
-
*/
|
|
7563
7481
|
/**
|
|
7564
7482
|
* Response payload for get_creative_features task. Returns feature values for the evaluated creative.
|
|
7565
7483
|
*/
|
|
@@ -7629,9 +7547,6 @@ export interface CreativeFeatureResult {
|
|
|
7629
7547
|
details?: {};
|
|
7630
7548
|
ext?: ExtensionObject;
|
|
7631
7549
|
}
|
|
7632
|
-
/**
|
|
7633
|
-
* Extension object for platform-specific, vendor-namespaced parameters. Extensions are always optional and must be namespaced under a vendor/platform key (e.g., ext.gam, ext.roku). Used for custom capabilities, partner-specific configuration, and features being proposed for standardization.
|
|
7634
|
-
*/
|
|
7635
7550
|
/**
|
|
7636
7551
|
* Get offering details and availability before session handoff. Returns offering information, availability status, and optionally matching products based on context.
|
|
7637
7552
|
*/
|
|
@@ -7654,9 +7569,6 @@ export interface SIGetOfferingRequest {
|
|
|
7654
7569
|
product_limit?: number;
|
|
7655
7570
|
ext?: ExtensionObject;
|
|
7656
7571
|
}
|
|
7657
|
-
/**
|
|
7658
|
-
* Extension object for platform-specific, vendor-namespaced parameters. Extensions are always optional and must be namespaced under a vendor/platform key (e.g., ext.gam, ext.roku). Used for custom capabilities, partner-specific configuration, and features being proposed for standardization.
|
|
7659
|
-
*/
|
|
7660
7572
|
/**
|
|
7661
7573
|
* Offering details, availability status, and optionally matching products. Use the offering_token in si_initiate_session for correlation.
|
|
7662
7574
|
*/
|
|
@@ -7765,9 +7677,6 @@ export interface SIGetOfferingResponse {
|
|
|
7765
7677
|
errors?: Error[];
|
|
7766
7678
|
ext?: ExtensionObject;
|
|
7767
7679
|
}
|
|
7768
|
-
/**
|
|
7769
|
-
* Standard error structure for task-specific errors and warnings
|
|
7770
|
-
*/
|
|
7771
7680
|
/**
|
|
7772
7681
|
* Host initiates a session with a brand agent
|
|
7773
7682
|
*/
|
|
@@ -7953,9 +7862,6 @@ export interface SICapabilities {
|
|
|
7953
7862
|
*/
|
|
7954
7863
|
mcp_apps?: boolean;
|
|
7955
7864
|
}
|
|
7956
|
-
/**
|
|
7957
|
-
* Extension object for platform-specific, vendor-namespaced parameters. Extensions are always optional and must be namespaced under a vendor/platform key (e.g., ext.gam, ext.roku). Used for custom capabilities, partner-specific configuration, and features being proposed for standardization.
|
|
7958
|
-
*/
|
|
7959
7865
|
/**
|
|
7960
7866
|
* Standard visual component that brand returns and host renders
|
|
7961
7867
|
*/
|
|
@@ -7999,9 +7905,6 @@ export interface SIInitiateSessionResponse {
|
|
|
7999
7905
|
errors?: Error[];
|
|
8000
7906
|
ext?: ExtensionObject;
|
|
8001
7907
|
}
|
|
8002
|
-
/**
|
|
8003
|
-
* Intersection of brand and host capabilities for this session
|
|
8004
|
-
*/
|
|
8005
7908
|
/**
|
|
8006
7909
|
* Send a message to the brand agent within an active session
|
|
8007
7910
|
*/
|
|
@@ -8032,10 +7935,7 @@ export type SISendMessageRequest = {
|
|
|
8032
7935
|
ext?: ExtensionObject;
|
|
8033
7936
|
};
|
|
8034
7937
|
/**
|
|
8035
|
-
*
|
|
8036
|
-
*/
|
|
8037
|
-
/**
|
|
8038
|
-
* Standard visual component that brand returns and host renders
|
|
7938
|
+
* Brand agent's response to a user message
|
|
8039
7939
|
*/
|
|
8040
7940
|
export interface SISendMessageResponse {
|
|
8041
7941
|
/**
|
|
@@ -8157,9 +8057,6 @@ export interface A2UIComponent {
|
|
|
8157
8057
|
[k: string]: {} | undefined;
|
|
8158
8058
|
};
|
|
8159
8059
|
}
|
|
8160
|
-
/**
|
|
8161
|
-
* Standard error structure for task-specific errors and warnings
|
|
8162
|
-
*/
|
|
8163
8060
|
/**
|
|
8164
8061
|
* Request to terminate an SI session
|
|
8165
8062
|
*/
|
|
@@ -8197,9 +8094,6 @@ export interface SITerminateSessionRequest {
|
|
|
8197
8094
|
};
|
|
8198
8095
|
ext?: ExtensionObject;
|
|
8199
8096
|
}
|
|
8200
|
-
/**
|
|
8201
|
-
* Extension object for platform-specific, vendor-namespaced parameters. Extensions are always optional and must be namespaced under a vendor/platform key (e.g., ext.gam, ext.roku). Used for custom capabilities, partner-specific configuration, and features being proposed for standardization.
|
|
8202
|
-
*/
|
|
8203
8097
|
/**
|
|
8204
8098
|
* Confirmation of session termination
|
|
8205
8099
|
*/
|
|
@@ -8242,9 +8136,6 @@ export interface SITerminateSessionResponse {
|
|
|
8242
8136
|
errors?: Error[];
|
|
8243
8137
|
ext?: ExtensionObject;
|
|
8244
8138
|
}
|
|
8245
|
-
/**
|
|
8246
|
-
* Standard error structure for task-specific errors and warnings
|
|
8247
|
-
*/
|
|
8248
8139
|
/**
|
|
8249
8140
|
* Request payload for get_adcp_capabilities task. Protocol-level capability discovery that works across all AdCP protocols.
|
|
8250
8141
|
*/
|
|
@@ -8257,10 +8148,7 @@ export interface GetAdCPCapabilitiesRequest {
|
|
|
8257
8148
|
ext?: ExtensionObject;
|
|
8258
8149
|
}
|
|
8259
8150
|
/**
|
|
8260
|
-
*
|
|
8261
|
-
*/
|
|
8262
|
-
/**
|
|
8263
|
-
* Methods for verifying user age for compliance. Does not include 'inferred' as it is not accepted for regulatory compliance.
|
|
8151
|
+
* Response payload for get_adcp_capabilities task. Protocol-level capability discovery across all AdCP protocols. Each domain protocol has its own capability section.
|
|
8264
8152
|
*/
|
|
8265
8153
|
export interface GetAdCPCapabilitiesResponse {
|
|
8266
8154
|
/**
|
|
@@ -8280,6 +8168,10 @@ export interface GetAdCPCapabilitiesResponse {
|
|
|
8280
8168
|
* Account management capabilities. Describes how accounts are established, what billing models are supported, and whether an account is required before browsing products.
|
|
8281
8169
|
*/
|
|
8282
8170
|
account?: {
|
|
8171
|
+
/**
|
|
8172
|
+
* How the seller resolves account references. explicit_account_id: accounts are managed out-of-band (advertiser portal, sales rep) and discovered via list_accounts. implicit_from_sync: buyer declares intent via sync_accounts and the seller provisions accounts.
|
|
8173
|
+
*/
|
|
8174
|
+
account_resolution?: 'explicit_account_id' | 'implicit_from_sync';
|
|
8283
8175
|
/**
|
|
8284
8176
|
* Whether the seller requires operator-level credentials. When false (default), the seller trusts the agent's identity claims — the agent authenticates once and declares brands/operators via sync_accounts. When true, each operator must authenticate independently with the seller, and the agent opens a per-operator session using the operator's credential.
|
|
8285
8177
|
*/
|
|
@@ -8289,17 +8181,17 @@ export interface GetAdCPCapabilitiesResponse {
|
|
|
8289
8181
|
*/
|
|
8290
8182
|
authorization_endpoint?: string;
|
|
8291
8183
|
/**
|
|
8292
|
-
* Billing models this seller supports.
|
|
8184
|
+
* Billing models this seller supports. operator: seller invoices the operator (agency or brand buying direct). agent: agent consolidates billing. The buyer must pass one of these values in sync_accounts.
|
|
8293
8185
|
*/
|
|
8294
|
-
supported_billing: ('
|
|
8186
|
+
supported_billing: ('operator' | 'agent')[];
|
|
8295
8187
|
/**
|
|
8296
|
-
*
|
|
8188
|
+
* Whether an account reference is required for get_products. When true, the buyer must establish an account before browsing products. When false (default), the buyer can browse products without an account — useful for price comparison and discovery before committing to a seller.
|
|
8297
8189
|
*/
|
|
8298
|
-
|
|
8190
|
+
required_for_products?: boolean;
|
|
8299
8191
|
/**
|
|
8300
|
-
* Whether
|
|
8192
|
+
* Whether this seller supports the get_account_financials task for querying account-level financial status (spend, credit, invoices). Only applicable to operator-billed accounts.
|
|
8301
8193
|
*/
|
|
8302
|
-
|
|
8194
|
+
account_financials?: boolean;
|
|
8303
8195
|
};
|
|
8304
8196
|
/**
|
|
8305
8197
|
* Media-buy protocol capabilities. Only present if media_buy is in supported_protocols.
|
|
@@ -8408,6 +8300,14 @@ export interface GetAdCPCapabilitiesResponse {
|
|
|
8408
8300
|
* Australian postcode, 4 digits (e.g., '2000')
|
|
8409
8301
|
*/
|
|
8410
8302
|
au_postcode?: boolean;
|
|
8303
|
+
/**
|
|
8304
|
+
* Swiss Postleitzahl, 4 digits (e.g., '8000')
|
|
8305
|
+
*/
|
|
8306
|
+
ch_plz?: boolean;
|
|
8307
|
+
/**
|
|
8308
|
+
* Austrian Postleitzahl, 4 digits (e.g., '1010')
|
|
8309
|
+
*/
|
|
8310
|
+
at_plz?: boolean;
|
|
8411
8311
|
};
|
|
8412
8312
|
/**
|
|
8413
8313
|
* Age restriction capabilities for compliance (alcohol, gambling)
|
|
@@ -8468,6 +8368,10 @@ export interface GetAdCPCapabilitiesResponse {
|
|
|
8468
8368
|
* Seller-level conversion tracking capabilities. Only present when features.conversion_tracking is true.
|
|
8469
8369
|
*/
|
|
8470
8370
|
conversion_tracking?: {
|
|
8371
|
+
/**
|
|
8372
|
+
* Whether this seller can deduplicate conversion events across multiple event sources within a single goal. When true, the seller honors the deduplication semantics in optimization_goals event_sources arrays — the same event_id from multiple sources counts once. When false or absent, buyers should use a single event source per goal; multi-source arrays will be treated as first-source-wins. Most social platforms cannot deduplicate across independently-managed pixel and CAPI sources.
|
|
8373
|
+
*/
|
|
8374
|
+
multi_source_event_dedup?: boolean;
|
|
8471
8375
|
/**
|
|
8472
8376
|
* Event types this seller can track and attribute. If omitted, all standard event types are supported.
|
|
8473
8377
|
*/
|
|
@@ -8485,7 +8389,7 @@ export interface GetAdCPCapabilitiesResponse {
|
|
|
8485
8389
|
*/
|
|
8486
8390
|
supported_action_sources?: ActionSource[];
|
|
8487
8391
|
/**
|
|
8488
|
-
* Attribution windows available from this seller. Single-element arrays indicate fixed windows; multi-element arrays indicate configurable options the buyer can choose from via
|
|
8392
|
+
* Attribution windows available from this seller. Single-element arrays indicate fixed windows; multi-element arrays indicate configurable options the buyer can choose from via attribution_window on optimization goals.
|
|
8489
8393
|
*/
|
|
8490
8394
|
attribution_windows?: {
|
|
8491
8395
|
event_type?: EventType;
|
|
@@ -8681,9 +8585,6 @@ export interface GetAdCPCapabilitiesResponse {
|
|
|
8681
8585
|
context?: ContextObject;
|
|
8682
8586
|
ext?: ExtensionObject;
|
|
8683
8587
|
}
|
|
8684
|
-
/**
|
|
8685
|
-
* Optional media-buy protocol features. Used in capability declarations (seller declares support) and product filters (buyer requires support). If a seller declares a feature as true, they MUST honor requests using that feature.
|
|
8686
|
-
*/
|
|
8687
8588
|
/**
|
|
8688
8589
|
* Request parameters for listing accounts accessible to the authenticated agent
|
|
8689
8590
|
*/
|
|
@@ -8691,7 +8592,7 @@ export interface ListAccountsRequest {
|
|
|
8691
8592
|
/**
|
|
8692
8593
|
* Filter accounts by status. Omit to return accounts in all statuses.
|
|
8693
8594
|
*/
|
|
8694
|
-
status?: 'active' | 'pending_approval' | 'payment_required' | 'suspended' | 'closed';
|
|
8595
|
+
status?: 'active' | 'pending_approval' | 'rejected' | 'payment_required' | 'suspended' | 'closed';
|
|
8695
8596
|
pagination?: PaginationRequest;
|
|
8696
8597
|
/**
|
|
8697
8598
|
* Filter by sandbox status. true returns only sandbox accounts, false returns only production accounts. Omit to return all accounts.
|
|
@@ -8700,9 +8601,6 @@ export interface ListAccountsRequest {
|
|
|
8700
8601
|
context?: ContextObject;
|
|
8701
8602
|
ext?: ExtensionObject;
|
|
8702
8603
|
}
|
|
8703
|
-
/**
|
|
8704
|
-
* Standard cursor-based pagination parameters for list operations
|
|
8705
|
-
*/
|
|
8706
8604
|
/**
|
|
8707
8605
|
* Response payload for list_accounts task
|
|
8708
8606
|
*/
|
|
@@ -8720,10 +8618,7 @@ export interface ListAccountsResponse {
|
|
|
8720
8618
|
ext?: ExtensionObject;
|
|
8721
8619
|
}
|
|
8722
8620
|
/**
|
|
8723
|
-
*
|
|
8724
|
-
*/
|
|
8725
|
-
/**
|
|
8726
|
-
* Authentication schemes for push notification endpoints
|
|
8621
|
+
* Sync advertiser accounts with a seller using upsert semantics. The agent declares which brands it represents, who operates on each brand's behalf, and the billing model. The seller provisions or links accounts accordingly, returning per-account status.
|
|
8727
8622
|
*/
|
|
8728
8623
|
export interface SyncAccountsRequest {
|
|
8729
8624
|
/**
|
|
@@ -8732,22 +8627,15 @@ export interface SyncAccountsRequest {
|
|
|
8732
8627
|
* @maxItems 1000
|
|
8733
8628
|
*/
|
|
8734
8629
|
accounts: {
|
|
8630
|
+
brand: BrandReference;
|
|
8735
8631
|
/**
|
|
8736
|
-
*
|
|
8632
|
+
* Domain of the entity operating on the brand's behalf (e.g., 'pinnacle-media.com'). When the brand operates directly, this is the brand's domain. Verified against the brand's authorized_operators in brand.json.
|
|
8737
8633
|
*/
|
|
8738
|
-
|
|
8634
|
+
operator: string;
|
|
8739
8635
|
/**
|
|
8740
|
-
*
|
|
8636
|
+
* Who should be invoiced. operator: seller invoices the operator (agency or brand buying direct). agent: agent consolidates billing across brands. The seller must either accept this billing model or reject the request.
|
|
8741
8637
|
*/
|
|
8742
|
-
|
|
8743
|
-
/**
|
|
8744
|
-
* Domain of the entity operating the seat (e.g., 'groupm.com', 'mindshare.com'). Verified against the brand's authorized_operators in brand.json. Omit if the brand operates its own seat.
|
|
8745
|
-
*/
|
|
8746
|
-
operator?: string;
|
|
8747
|
-
/**
|
|
8748
|
-
* Who should be invoiced. brand: seller invoices the brand directly. operator: seller invoices the operator (agency). agent: agent consolidates billing across brands. Omit to accept the seller's default.
|
|
8749
|
-
*/
|
|
8750
|
-
billing?: 'brand' | 'operator' | 'agent';
|
|
8638
|
+
billing: 'operator' | 'agent';
|
|
8751
8639
|
/**
|
|
8752
8640
|
* When true, provision this as a sandbox account. No real platform calls or billing. Sandbox accounts are identified by account_id in subsequent requests.
|
|
8753
8641
|
*/
|
|
@@ -8765,9 +8653,6 @@ export interface SyncAccountsRequest {
|
|
|
8765
8653
|
context?: ContextObject;
|
|
8766
8654
|
ext?: ExtensionObject;
|
|
8767
8655
|
}
|
|
8768
|
-
/**
|
|
8769
|
-
* Optional webhook for async notifications when account status changes (e.g., pending_approval transitions to active).
|
|
8770
|
-
*/
|
|
8771
8656
|
/**
|
|
8772
8657
|
* Response from account sync operation. Returns per-account results with status and billing, or operation-level errors on complete failure.
|
|
8773
8658
|
*/
|
|
@@ -8784,22 +8669,11 @@ export interface SyncAccountsSuccess {
|
|
|
8784
8669
|
* Results for each account processed
|
|
8785
8670
|
*/
|
|
8786
8671
|
accounts: {
|
|
8787
|
-
|
|
8788
|
-
* Seller-assigned account identifier. When billing is 'agent', multiple brands may share the same account_id.
|
|
8789
|
-
*/
|
|
8790
|
-
account_id?: string;
|
|
8791
|
-
/**
|
|
8792
|
-
* House domain, echoed from the request
|
|
8793
|
-
*/
|
|
8794
|
-
house: string;
|
|
8795
|
-
/**
|
|
8796
|
-
* Brand ID within the house portfolio, echoed from request
|
|
8797
|
-
*/
|
|
8798
|
-
brand_id?: string;
|
|
8672
|
+
brand: BrandReference;
|
|
8799
8673
|
/**
|
|
8800
8674
|
* Operator domain, echoed from request
|
|
8801
8675
|
*/
|
|
8802
|
-
operator
|
|
8676
|
+
operator: string;
|
|
8803
8677
|
/**
|
|
8804
8678
|
* Human-readable account name assigned by the seller
|
|
8805
8679
|
*/
|
|
@@ -8809,17 +8683,17 @@ export interface SyncAccountsSuccess {
|
|
|
8809
8683
|
*/
|
|
8810
8684
|
action: 'created' | 'updated' | 'unchanged' | 'failed';
|
|
8811
8685
|
/**
|
|
8812
|
-
* Account status. active: ready for use. pending_approval: seller reviewing (credit, legal). payment_required: credit limit reached or funds depleted. suspended: was active, now paused. closed: terminated.
|
|
8686
|
+
* Account status. active: ready for use. pending_approval: seller reviewing (credit, legal). rejected: seller declined the account request. payment_required: credit limit reached or funds depleted. suspended: was active, now paused. closed: was active, now terminated.
|
|
8813
8687
|
*/
|
|
8814
|
-
status: 'active' | 'pending_approval' | 'payment_required' | 'suspended' | 'closed';
|
|
8688
|
+
status: 'active' | 'pending_approval' | 'rejected' | 'payment_required' | 'suspended' | 'closed';
|
|
8815
8689
|
/**
|
|
8816
|
-
* Who is invoiced on this account.
|
|
8690
|
+
* Who is invoiced on this account. Matches the requested billing model.
|
|
8817
8691
|
*/
|
|
8818
|
-
billing?: '
|
|
8692
|
+
billing?: 'operator' | 'agent';
|
|
8819
8693
|
/**
|
|
8820
|
-
*
|
|
8694
|
+
* How the seller scoped this account. operator: shared across all brands for this operator. brand: shared across all operators for this brand. operator_brand: dedicated to this operator+brand pair. agent: the agent's default account.
|
|
8821
8695
|
*/
|
|
8822
|
-
|
|
8696
|
+
account_scope?: 'operator' | 'brand' | 'operator_brand' | 'agent';
|
|
8823
8697
|
/**
|
|
8824
8698
|
* Setup information for pending accounts. Provides the agent (or human) with next steps to complete account activation.
|
|
8825
8699
|
*/
|
|
@@ -8866,7 +8740,7 @@ export interface SyncAccountsSuccess {
|
|
|
8866
8740
|
ext?: ExtensionObject;
|
|
8867
8741
|
}
|
|
8868
8742
|
/**
|
|
8869
|
-
*
|
|
8743
|
+
* Operation failed completely, no accounts were processed
|
|
8870
8744
|
*/
|
|
8871
8745
|
export interface SyncAccountsError {
|
|
8872
8746
|
/**
|
|
@@ -8877,9 +8751,13 @@ export interface SyncAccountsError {
|
|
|
8877
8751
|
ext?: ExtensionObject;
|
|
8878
8752
|
}
|
|
8879
8753
|
/**
|
|
8880
|
-
* Reports how a vendor's service was consumed after campaign delivery. Used by orchestrators (DSPs, storefronts) to inform vendor agents (signals, governance, creative) what was used so the vendor can track earned revenue and verify billing. Records can span multiple accounts
|
|
8754
|
+
* Reports how a vendor's service was consumed after campaign delivery. Used by orchestrators (DSPs, storefronts) to inform vendor agents (signals, governance, creative) what was used so the vendor can track earned revenue and verify billing. Records can span multiple accounts and campaigns in a single request.
|
|
8881
8755
|
*/
|
|
8882
8756
|
export interface ReportUsageRequest {
|
|
8757
|
+
/**
|
|
8758
|
+
* Client-generated unique key for this request. If a request with the same key has already been accepted, the server returns the original response without re-processing. Use a UUID or other unique identifier. Prevents duplicate billing on retries.
|
|
8759
|
+
*/
|
|
8760
|
+
idempotency_key?: string;
|
|
8883
8761
|
/**
|
|
8884
8762
|
* The time range covered by this usage report. Applies to all records in the request.
|
|
8885
8763
|
*/
|
|
@@ -8894,25 +8772,14 @@ export interface ReportUsageRequest {
|
|
|
8894
8772
|
end: string;
|
|
8895
8773
|
};
|
|
8896
8774
|
/**
|
|
8897
|
-
* One or more usage records. Each record is self-contained: it carries its own
|
|
8775
|
+
* One or more usage records. Each record is self-contained: it carries its own account and buyer_campaign_ref, allowing a single request to span multiple accounts and campaigns.
|
|
8898
8776
|
*/
|
|
8899
8777
|
usage: {
|
|
8900
|
-
|
|
8901
|
-
* The account with this vendor agent for this record, obtained from sync_accounts.
|
|
8902
|
-
*/
|
|
8903
|
-
account_id: string;
|
|
8904
|
-
/**
|
|
8905
|
-
* The operator on whose behalf this usage is reported. Identifies the billing party — the entity that owes the vendor for this consumption.
|
|
8906
|
-
*/
|
|
8907
|
-
operator_id: string;
|
|
8778
|
+
account: AccountReference;
|
|
8908
8779
|
/**
|
|
8909
8780
|
* The buyer's campaign reference (e.g., a media_buy_id). Used to group records by campaign.
|
|
8910
8781
|
*/
|
|
8911
8782
|
buyer_campaign_ref?: string;
|
|
8912
|
-
/**
|
|
8913
|
-
* The type of vendor service consumed.
|
|
8914
|
-
*/
|
|
8915
|
-
kind: 'signal' | 'content_standards' | 'creative';
|
|
8916
8783
|
/**
|
|
8917
8784
|
* Amount owed to the vendor for this record, denominated in currency.
|
|
8918
8785
|
*/
|
|
@@ -8922,7 +8789,11 @@ export interface ReportUsageRequest {
|
|
|
8922
8789
|
*/
|
|
8923
8790
|
currency: string;
|
|
8924
8791
|
/**
|
|
8925
|
-
*
|
|
8792
|
+
* Pricing option identifier from the vendor's discovery response (e.g., get_signals, list_content_standards). The vendor uses this to verify the correct rate was applied.
|
|
8793
|
+
*/
|
|
8794
|
+
pricing_option_id?: string;
|
|
8795
|
+
/**
|
|
8796
|
+
* Impressions delivered using this vendor service.
|
|
8926
8797
|
*/
|
|
8927
8798
|
impressions?: number;
|
|
8928
8799
|
/**
|
|
@@ -8930,24 +8801,17 @@ export interface ReportUsageRequest {
|
|
|
8930
8801
|
*/
|
|
8931
8802
|
media_spend?: number;
|
|
8932
8803
|
/**
|
|
8933
|
-
* Signal identifier from get_signals. Required
|
|
8804
|
+
* Signal identifier from get_signals. Required for signals agents.
|
|
8934
8805
|
*/
|
|
8935
8806
|
signal_agent_segment_id?: string;
|
|
8936
8807
|
/**
|
|
8937
|
-
*
|
|
8938
|
-
*/
|
|
8939
|
-
pricing_option_id?: string;
|
|
8940
|
-
/**
|
|
8941
|
-
* Content standards configuration identifier. Required when kind is 'content_standards'.
|
|
8808
|
+
* Content standards configuration identifier. Required for governance agents.
|
|
8942
8809
|
*/
|
|
8943
8810
|
standards_id?: string;
|
|
8944
8811
|
}[];
|
|
8945
8812
|
context?: ContextObject;
|
|
8946
8813
|
ext?: ExtensionObject;
|
|
8947
8814
|
}
|
|
8948
|
-
/**
|
|
8949
|
-
* Opaque correlation data that is echoed unchanged in responses. Used for internal tracking, UI session IDs, trace IDs, and other caller-specific identifiers that don't affect protocol behavior. Context data is never parsed by AdCP agents - it's simply preserved and returned.
|
|
8950
|
-
*/
|
|
8951
8815
|
/**
|
|
8952
8816
|
* Response from report_usage. Partial acceptance is valid — records that pass validation are stored even when others fail.
|
|
8953
8817
|
*/
|
|
@@ -8968,6 +8832,156 @@ export interface ReportUsageResponse {
|
|
|
8968
8832
|
ext?: ExtensionObject;
|
|
8969
8833
|
}
|
|
8970
8834
|
/**
|
|
8971
|
-
*
|
|
8835
|
+
* Request financial status for an operator-billed account. Returns spend summary, credit/balance status, and invoice history. Only applicable when the seller declares account_financials capability.
|
|
8836
|
+
*/
|
|
8837
|
+
export interface GetAccountFinancialsRequest {
|
|
8838
|
+
account: AccountReference;
|
|
8839
|
+
/**
|
|
8840
|
+
* Date range for the spend summary. Defaults to the current billing cycle if omitted.
|
|
8841
|
+
*/
|
|
8842
|
+
period?: {
|
|
8843
|
+
/**
|
|
8844
|
+
* Period start (ISO 8601 date)
|
|
8845
|
+
*/
|
|
8846
|
+
start: string;
|
|
8847
|
+
/**
|
|
8848
|
+
* Period end (ISO 8601 date)
|
|
8849
|
+
*/
|
|
8850
|
+
end: string;
|
|
8851
|
+
};
|
|
8852
|
+
context?: ContextObject;
|
|
8853
|
+
ext?: ExtensionObject;
|
|
8854
|
+
}
|
|
8855
|
+
/**
|
|
8856
|
+
* Financial status for an operator-billed account. Returns spend summary, credit/balance status, payment status, and invoice history. The level of detail varies by seller — only account, currency, and period are guaranteed on success.
|
|
8857
|
+
*/
|
|
8858
|
+
export type GetAccountFinancialsResponse = GetAccountFinancialsSuccess | GetAccountFinancialsError;
|
|
8859
|
+
/**
|
|
8860
|
+
* Financial data retrieved successfully
|
|
8972
8861
|
*/
|
|
8862
|
+
export interface GetAccountFinancialsSuccess {
|
|
8863
|
+
account: AccountReference;
|
|
8864
|
+
/**
|
|
8865
|
+
* ISO 4217 currency code for all monetary amounts in this response
|
|
8866
|
+
*/
|
|
8867
|
+
currency: string;
|
|
8868
|
+
/**
|
|
8869
|
+
* The actual period covered by spend data. May differ from the requested period if the seller adjusts to billing cycle boundaries.
|
|
8870
|
+
*/
|
|
8871
|
+
period: {
|
|
8872
|
+
/**
|
|
8873
|
+
* Period start (ISO 8601 date)
|
|
8874
|
+
*/
|
|
8875
|
+
start: string;
|
|
8876
|
+
/**
|
|
8877
|
+
* Period end (ISO 8601 date)
|
|
8878
|
+
*/
|
|
8879
|
+
end: string;
|
|
8880
|
+
};
|
|
8881
|
+
/**
|
|
8882
|
+
* Spend summary for the period
|
|
8883
|
+
*/
|
|
8884
|
+
spend?: {
|
|
8885
|
+
/**
|
|
8886
|
+
* Total spend in the period, in currency
|
|
8887
|
+
*/
|
|
8888
|
+
total_spend: number;
|
|
8889
|
+
/**
|
|
8890
|
+
* Number of active media buys in the period
|
|
8891
|
+
*/
|
|
8892
|
+
media_buy_count?: number;
|
|
8893
|
+
};
|
|
8894
|
+
/**
|
|
8895
|
+
* Credit status. Present for credit-based accounts (payment_terms like net_30).
|
|
8896
|
+
*/
|
|
8897
|
+
credit?: {
|
|
8898
|
+
/**
|
|
8899
|
+
* Maximum outstanding balance allowed
|
|
8900
|
+
*/
|
|
8901
|
+
credit_limit: number;
|
|
8902
|
+
/**
|
|
8903
|
+
* Remaining credit available (credit_limit minus outstanding balance)
|
|
8904
|
+
*/
|
|
8905
|
+
available_credit: number;
|
|
8906
|
+
/**
|
|
8907
|
+
* Credit utilization as a percentage (0-100)
|
|
8908
|
+
*/
|
|
8909
|
+
utilization_percent?: number;
|
|
8910
|
+
};
|
|
8911
|
+
/**
|
|
8912
|
+
* Prepay balance. Present for prepay accounts.
|
|
8913
|
+
*/
|
|
8914
|
+
balance?: {
|
|
8915
|
+
/**
|
|
8916
|
+
* Remaining prepaid balance
|
|
8917
|
+
*/
|
|
8918
|
+
available: number;
|
|
8919
|
+
/**
|
|
8920
|
+
* Most recent balance top-up
|
|
8921
|
+
*/
|
|
8922
|
+
last_top_up?: {
|
|
8923
|
+
/**
|
|
8924
|
+
* Top-up amount
|
|
8925
|
+
*/
|
|
8926
|
+
amount: number;
|
|
8927
|
+
/**
|
|
8928
|
+
* Date of top-up
|
|
8929
|
+
*/
|
|
8930
|
+
date: string;
|
|
8931
|
+
};
|
|
8932
|
+
};
|
|
8933
|
+
/**
|
|
8934
|
+
* Overall payment status. current: all obligations met. past_due: one or more invoices overdue. suspended: account suspended due to payment issues.
|
|
8935
|
+
*/
|
|
8936
|
+
payment_status?: 'current' | 'past_due' | 'suspended';
|
|
8937
|
+
/**
|
|
8938
|
+
* Payment terms in effect (e.g., 'net_30', 'prepay')
|
|
8939
|
+
*/
|
|
8940
|
+
payment_terms?: string;
|
|
8941
|
+
/**
|
|
8942
|
+
* Recent invoices. Sellers may limit the number returned.
|
|
8943
|
+
*/
|
|
8944
|
+
invoices?: {
|
|
8945
|
+
/**
|
|
8946
|
+
* Seller-assigned invoice identifier
|
|
8947
|
+
*/
|
|
8948
|
+
invoice_id: string;
|
|
8949
|
+
/**
|
|
8950
|
+
* Billing period covered by this invoice
|
|
8951
|
+
*/
|
|
8952
|
+
period?: {
|
|
8953
|
+
start: string;
|
|
8954
|
+
end: string;
|
|
8955
|
+
};
|
|
8956
|
+
/**
|
|
8957
|
+
* Invoice total in currency
|
|
8958
|
+
*/
|
|
8959
|
+
amount: number;
|
|
8960
|
+
/**
|
|
8961
|
+
* Invoice status
|
|
8962
|
+
*/
|
|
8963
|
+
status: 'draft' | 'issued' | 'paid' | 'past_due' | 'void';
|
|
8964
|
+
/**
|
|
8965
|
+
* Payment due date
|
|
8966
|
+
*/
|
|
8967
|
+
due_date?: string;
|
|
8968
|
+
/**
|
|
8969
|
+
* Date payment was received. Present when status is 'paid'.
|
|
8970
|
+
*/
|
|
8971
|
+
paid_date?: string;
|
|
8972
|
+
}[];
|
|
8973
|
+
context?: ContextObject;
|
|
8974
|
+
ext?: ExtensionObject;
|
|
8975
|
+
}
|
|
8976
|
+
/**
|
|
8977
|
+
* Operation failed — financials not available
|
|
8978
|
+
*/
|
|
8979
|
+
export interface GetAccountFinancialsError {
|
|
8980
|
+
/**
|
|
8981
|
+
* Operation-level errors
|
|
8982
|
+
*/
|
|
8983
|
+
errors: Error[];
|
|
8984
|
+
context?: ContextObject;
|
|
8985
|
+
ext?: ExtensionObject;
|
|
8986
|
+
}
|
|
8973
8987
|
//# sourceMappingURL=tools.generated.d.ts.map
|