@adcp/client 0.4.2 → 2.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.
@@ -1,3 +1,14 @@
1
+ /**
2
+ * Brand information manifest providing brand context, assets, and product catalog. Can be provided inline or as a URL reference to a hosted manifest.
3
+ */
4
+ export type BrandManifestReference = BrandManifest | string;
5
+ /**
6
+ * Inline brand manifest object
7
+ */
8
+ export type BrandManifest = BrandManifest1 & BrandManifest2;
9
+ export type BrandManifest1 = {
10
+ [k: string]: unknown;
11
+ };
1
12
  /**
2
13
  * Type of inventory delivery
3
14
  */
@@ -6,18 +17,11 @@ export type DeliveryType = 'guaranteed' | 'non_guaranteed';
6
17
  * Request parameters for discovering available advertising products
7
18
  */
8
19
  export interface GetProductsRequest {
9
- /**
10
- * AdCP schema version for this request
11
- */
12
- adcp_version?: string;
13
20
  /**
14
21
  * Natural language description of campaign requirements
15
22
  */
16
23
  brief?: string;
17
- /**
18
- * Description of advertiser and what is being promoted
19
- */
20
- promoted_offering: string;
24
+ brand_manifest: BrandManifestReference;
21
25
  /**
22
26
  * Structured filters for product discovery
23
27
  */
@@ -34,17 +38,252 @@ export interface GetProductsRequest {
34
38
  /**
35
39
  * Filter by specific format IDs
36
40
  */
37
- format_ids?: string[];
41
+ format_ids?: FormatID[];
38
42
  /**
39
43
  * Only return products accepting IAB standard formats
40
44
  */
41
45
  standard_formats_only?: boolean;
46
+ /**
47
+ * Minimum exposures/impressions needed for measurement validity
48
+ */
49
+ min_exposures?: number;
50
+ };
51
+ }
52
+ export interface BrandManifest2 {
53
+ /**
54
+ * Primary brand URL for context and asset discovery. Creative agents can infer brand information from this URL.
55
+ */
56
+ url?: string;
57
+ /**
58
+ * Brand or business name
59
+ */
60
+ name?: string;
61
+ /**
62
+ * Brand logo assets with semantic tags for different use cases
63
+ */
64
+ logos?: {
65
+ /**
66
+ * URL to the logo asset
67
+ */
68
+ url: string;
69
+ /**
70
+ * Semantic tags describing the logo variant (e.g., 'dark', 'light', 'square', 'horizontal', 'icon')
71
+ */
72
+ tags?: string[];
73
+ /**
74
+ * Logo width in pixels
75
+ */
76
+ width?: number;
77
+ /**
78
+ * Logo height in pixels
79
+ */
80
+ height?: number;
81
+ [k: string]: unknown;
82
+ }[];
83
+ /**
84
+ * Brand color palette
85
+ */
86
+ colors?: {
87
+ /**
88
+ * Primary brand color (hex format)
89
+ */
90
+ primary?: string;
91
+ /**
92
+ * Secondary brand color (hex format)
93
+ */
94
+ secondary?: string;
95
+ /**
96
+ * Accent color (hex format)
97
+ */
98
+ accent?: string;
99
+ /**
100
+ * Background color (hex format)
101
+ */
102
+ background?: string;
103
+ /**
104
+ * Text color (hex format)
105
+ */
106
+ text?: string;
107
+ [k: string]: unknown;
108
+ };
109
+ /**
110
+ * Brand typography guidelines
111
+ */
112
+ fonts?: {
113
+ /**
114
+ * Primary font family name
115
+ */
116
+ primary?: string;
117
+ /**
118
+ * Secondary font family name
119
+ */
120
+ secondary?: string;
121
+ /**
122
+ * URLs to web font files if using custom fonts
123
+ */
124
+ font_urls?: string[];
125
+ [k: string]: unknown;
126
+ };
127
+ /**
128
+ * Brand voice and messaging tone (e.g., 'professional', 'casual', 'humorous', 'trustworthy', 'innovative')
129
+ */
130
+ tone?: string;
131
+ /**
132
+ * Brand tagline or slogan
133
+ */
134
+ tagline?: string;
135
+ /**
136
+ * Brand asset library with explicit assets and tags. Assets are referenced inline with URLs pointing to CDN-hosted files.
137
+ */
138
+ assets?: {
139
+ /**
140
+ * Unique identifier for this asset
141
+ */
142
+ asset_id: string;
143
+ /**
144
+ * Type of asset
145
+ */
146
+ asset_type: 'image' | 'video' | 'audio' | 'text';
147
+ /**
148
+ * URL to CDN-hosted asset file
149
+ */
150
+ url: string;
151
+ /**
152
+ * Tags for asset discovery (e.g., 'holiday', 'lifestyle', 'product_shot')
153
+ */
154
+ tags?: string[];
155
+ /**
156
+ * Human-readable asset name
157
+ */
158
+ name?: string;
159
+ /**
160
+ * Asset description or usage notes
161
+ */
162
+ description?: string;
163
+ /**
164
+ * Image/video width in pixels
165
+ */
166
+ width?: number;
167
+ /**
168
+ * Image/video height in pixels
169
+ */
170
+ height?: number;
171
+ /**
172
+ * Video/audio duration in seconds
173
+ */
174
+ duration_seconds?: number;
175
+ /**
176
+ * File size in bytes
177
+ */
178
+ file_size_bytes?: number;
179
+ /**
180
+ * File format (e.g., 'jpg', 'mp4', 'mp3')
181
+ */
182
+ format?: string;
183
+ /**
184
+ * Additional asset-specific metadata
185
+ */
186
+ metadata?: {
187
+ [k: string]: unknown;
188
+ };
189
+ }[];
190
+ /**
191
+ * Product catalog information for e-commerce advertisers. Enables SKU-level creative generation and product selection.
192
+ */
193
+ product_catalog?: {
194
+ /**
195
+ * URL to product catalog feed
196
+ */
197
+ feed_url: string;
198
+ /**
199
+ * Format of the product feed
200
+ */
201
+ feed_format?: 'google_merchant_center' | 'facebook_catalog' | 'custom';
202
+ /**
203
+ * Product categories available in the catalog (for filtering)
204
+ */
205
+ categories?: string[];
206
+ /**
207
+ * When the product catalog was last updated
208
+ */
209
+ last_updated?: string;
210
+ /**
211
+ * How frequently the product catalog is updated
212
+ */
213
+ update_frequency?: 'realtime' | 'hourly' | 'daily' | 'weekly';
214
+ };
215
+ /**
216
+ * Legal disclaimers or required text that must appear in creatives
217
+ */
218
+ disclaimers?: {
219
+ /**
220
+ * Disclaimer text
221
+ */
222
+ text: string;
223
+ /**
224
+ * When this disclaimer applies (e.g., 'financial_products', 'health_claims', 'all')
225
+ */
226
+ context?: string;
227
+ /**
228
+ * Whether this disclaimer must appear
229
+ */
230
+ required?: boolean;
231
+ [k: string]: unknown;
232
+ }[];
233
+ /**
234
+ * Industry or vertical (e.g., 'retail', 'automotive', 'finance', 'healthcare')
235
+ */
236
+ industry?: string;
237
+ /**
238
+ * Primary target audience description
239
+ */
240
+ target_audience?: string;
241
+ /**
242
+ * Brand contact information
243
+ */
244
+ contact?: {
245
+ /**
246
+ * Contact email
247
+ */
248
+ email?: string;
249
+ /**
250
+ * Contact phone number
251
+ */
252
+ phone?: string;
253
+ [k: string]: unknown;
254
+ };
255
+ /**
256
+ * Additional brand metadata
257
+ */
258
+ metadata?: {
259
+ /**
260
+ * When this brand manifest was created
261
+ */
262
+ created_date?: string;
263
+ /**
264
+ * When this brand manifest was last updated
265
+ */
266
+ updated_date?: string;
267
+ /**
268
+ * Brand card version number
269
+ */
270
+ version?: string;
271
+ [k: string]: unknown;
42
272
  };
43
273
  }
44
274
  /**
45
- * Current task state
275
+ * Structured format identifier with agent URL and format name
46
276
  */
47
- export type TaskStatus = 'submitted' | 'working' | 'input-required' | 'completed' | 'canceled' | 'failed' | 'rejected' | 'auth-required' | 'unknown';
277
+ export interface FormatID {
278
+ /**
279
+ * URL of the agent that defines this format (e.g., 'https://creatives.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats)
280
+ */
281
+ agent_url: string;
282
+ /**
283
+ * Format identifier within the agent's namespace (e.g., 'display_300x250', 'video_standard_30s')
284
+ */
285
+ id: string;
286
+ }
48
287
  /**
49
288
  * Represents available advertising inventory
50
289
  */
@@ -56,6 +295,7 @@ export type PropertyIdentifierTypes = 'domain' | 'subdomain' | 'network_id' | 'i
56
295
  /**
57
296
  * Type of inventory delivery
58
297
  */
298
+ export type PricingOption = CPMFixedRatePricingOption | CPMAuctionPricingOption | VCPMFixedRatePricingOption | VCPMAuctionPricingOption | CPCPricingOption | CPCVPricingOption | CPVPricingOption | CPPPricingOption | FlatRatePricingOption;
59
299
  export type Product2 = {
60
300
  [k: string]: unknown;
61
301
  } | {
@@ -65,11 +305,6 @@ export type Product2 = {
65
305
  * Response payload for get_products task
66
306
  */
67
307
  export interface GetProductsResponse {
68
- /**
69
- * AdCP schema version used for this response
70
- */
71
- adcp_version: string;
72
- status?: TaskStatus;
73
308
  /**
74
309
  * Array of matching products
75
310
  */
@@ -105,399 +340,1292 @@ export interface Product1 {
105
340
  */
106
341
  property_tags?: [string, ...string[]];
107
342
  /**
108
- * Array of supported creative format IDs - use list_creative_formats to get full format details
343
+ * Array of supported creative format IDs - structured format_id objects with agent_url and id
109
344
  */
110
- format_ids: string[];
345
+ format_ids: FormatID[];
111
346
  delivery_type: DeliveryType;
112
347
  /**
113
- * Whether this product has fixed pricing (true) or uses auction (false)
348
+ * Available pricing models for this product
349
+ *
350
+ * @minItems 1
351
+ */
352
+ pricing_options: [PricingOption, ...PricingOption[]];
353
+ /**
354
+ * Estimated exposures/impressions for guaranteed products
355
+ */
356
+ estimated_exposures?: number;
357
+ measurement?: Measurement;
358
+ /**
359
+ * Measurement provider and methodology for delivery metrics. The buyer accepts the declared provider as the source of truth for the buy. REQUIRED for all products.
360
+ */
361
+ delivery_measurement: {
362
+ /**
363
+ * Measurement provider(s) used for this product (e.g., 'Google Ad Manager with IAS viewability', 'Nielsen DAR', 'Geopath for DOOH impressions')
364
+ */
365
+ provider: string;
366
+ /**
367
+ * Additional details about measurement methodology in plain language (e.g., 'MRC-accredited viewability. 50% in-view for 1s display / 2s video', 'Panel-based demographic measurement updated monthly')
368
+ */
369
+ notes?: string;
370
+ [k: string]: unknown;
371
+ };
372
+ reporting_capabilities?: ReportingCapabilities;
373
+ creative_policy?: CreativePolicy;
374
+ /**
375
+ * Whether this is a custom product
376
+ */
377
+ is_custom?: boolean;
378
+ /**
379
+ * Explanation of why this product matches the brief (only included when brief is provided)
380
+ */
381
+ brief_relevance?: string;
382
+ /**
383
+ * Expiration timestamp for custom products
384
+ */
385
+ expires_at?: string;
386
+ }
387
+ /**
388
+ * An advertising property that can be validated via adagents.json
389
+ */
390
+ export interface Property {
391
+ /**
392
+ * Type of advertising property
393
+ */
394
+ property_type: 'website' | 'mobile_app' | 'ctv_app' | 'dooh' | 'podcast' | 'radio' | 'streaming_audio';
395
+ /**
396
+ * Human-readable property name
397
+ */
398
+ name: string;
399
+ /**
400
+ * Array of identifiers for this property
401
+ *
402
+ * @minItems 1
403
+ */
404
+ identifiers: [
405
+ {
406
+ type: PropertyIdentifierTypes;
407
+ /**
408
+ * The identifier value. For domain type: 'example.com' matches www.example.com and m.example.com only; 'subdomain.example.com' matches that specific subdomain; '*.example.com' matches all subdomains
409
+ */
410
+ value: string;
411
+ },
412
+ ...{
413
+ type: PropertyIdentifierTypes;
414
+ /**
415
+ * The identifier value. For domain type: 'example.com' matches www.example.com and m.example.com only; 'subdomain.example.com' matches that specific subdomain; '*.example.com' matches all subdomains
416
+ */
417
+ value: string;
418
+ }[]
419
+ ];
420
+ /**
421
+ * Tags for categorization and grouping (e.g., network membership, content categories)
422
+ */
423
+ tags?: string[];
424
+ /**
425
+ * Domain where adagents.json should be checked for authorization validation
426
+ */
427
+ publisher_domain: string;
428
+ }
429
+ /**
430
+ * Structured format identifier with agent URL and format name
431
+ */
432
+ export interface CPMFixedRatePricingOption {
433
+ /**
434
+ * Unique identifier for this pricing option within the product (e.g., 'cpm_usd_guaranteed')
435
+ */
436
+ pricing_option_id: string;
437
+ /**
438
+ * Cost per 1,000 impressions
439
+ */
440
+ pricing_model: 'cpm';
441
+ /**
442
+ * Fixed CPM rate (cost per 1,000 impressions)
443
+ */
444
+ rate: number;
445
+ /**
446
+ * ISO 4217 currency code
447
+ */
448
+ currency: string;
449
+ /**
450
+ * Minimum spend requirement per package using this pricing option, in the specified currency
451
+ */
452
+ min_spend_per_package?: number;
453
+ }
454
+ /**
455
+ * Cost Per Mille (cost per 1,000 impressions) with auction-based pricing - common for programmatic/non-guaranteed inventory
456
+ */
457
+ export interface CPMAuctionPricingOption {
458
+ /**
459
+ * Unique identifier for this pricing option within the product (e.g., 'cpm_usd_auction')
460
+ */
461
+ pricing_option_id: string;
462
+ /**
463
+ * Cost per 1,000 impressions
464
+ */
465
+ pricing_model: 'cpm';
466
+ /**
467
+ * ISO 4217 currency code
468
+ */
469
+ currency: string;
470
+ /**
471
+ * Pricing guidance for auction-based CPM bidding
472
+ */
473
+ price_guidance: {
474
+ /**
475
+ * Minimum bid price - publisher will reject bids under this value
476
+ */
477
+ floor: number;
478
+ /**
479
+ * 25th percentile winning price
480
+ */
481
+ p25?: number;
482
+ /**
483
+ * Median winning price
484
+ */
485
+ p50?: number;
486
+ /**
487
+ * 75th percentile winning price
488
+ */
489
+ p75?: number;
490
+ /**
491
+ * 90th percentile winning price
492
+ */
493
+ p90?: number;
494
+ [k: string]: unknown;
495
+ };
496
+ /**
497
+ * Minimum spend requirement per package using this pricing option, in the specified currency
114
498
  */
115
- is_fixed_price: boolean;
499
+ min_spend_per_package?: number;
500
+ }
501
+ /**
502
+ * Viewable Cost Per Mille (cost per 1,000 viewable impressions) with guaranteed fixed rate - impressions meeting MRC viewability standard (50% pixels in-view for 1 second for display, 2 seconds for video)
503
+ */
504
+ export interface VCPMFixedRatePricingOption {
505
+ /**
506
+ * Unique identifier for this pricing option within the product (e.g., 'vcpm_usd_guaranteed')
507
+ */
508
+ pricing_option_id: string;
509
+ /**
510
+ * Cost per 1,000 viewable impressions (MRC standard)
511
+ */
512
+ pricing_model: 'vcpm';
513
+ /**
514
+ * Fixed vCPM rate (cost per 1,000 viewable impressions)
515
+ */
516
+ rate: number;
517
+ /**
518
+ * ISO 4217 currency code
519
+ */
520
+ currency: string;
521
+ /**
522
+ * Minimum spend requirement per package using this pricing option, in the specified currency
523
+ */
524
+ min_spend_per_package?: number;
525
+ }
526
+ /**
527
+ * Viewable Cost Per Mille (cost per 1,000 viewable impressions) with auction-based pricing - impressions meeting MRC viewability standard (50% pixels in-view for 1 second for display, 2 seconds for video)
528
+ */
529
+ export interface VCPMAuctionPricingOption {
530
+ /**
531
+ * Unique identifier for this pricing option within the product (e.g., 'vcpm_usd_auction')
532
+ */
533
+ pricing_option_id: string;
534
+ /**
535
+ * Cost per 1,000 viewable impressions (MRC standard)
536
+ */
537
+ pricing_model: 'vcpm';
538
+ /**
539
+ * ISO 4217 currency code
540
+ */
541
+ currency: string;
542
+ /**
543
+ * Statistical guidance for auction pricing
544
+ */
545
+ price_guidance: {
546
+ /**
547
+ * Minimum acceptable bid price
548
+ */
549
+ floor: number;
550
+ /**
551
+ * 25th percentile of recent winning bids
552
+ */
553
+ p25?: number;
554
+ /**
555
+ * Median of recent winning bids
556
+ */
557
+ p50?: number;
558
+ /**
559
+ * 75th percentile of recent winning bids
560
+ */
561
+ p75?: number;
562
+ /**
563
+ * 90th percentile of recent winning bids
564
+ */
565
+ p90?: number;
566
+ [k: string]: unknown;
567
+ };
568
+ /**
569
+ * Minimum spend requirement per package using this pricing option, in the specified currency
570
+ */
571
+ min_spend_per_package?: number;
572
+ }
573
+ /**
574
+ * Cost Per Click fixed-rate pricing for performance-driven advertising campaigns
575
+ */
576
+ export interface CPCPricingOption {
577
+ /**
578
+ * Unique identifier for this pricing option within the product (e.g., 'cpc_usd_fixed')
579
+ */
580
+ pricing_option_id: string;
581
+ /**
582
+ * Cost per click
583
+ */
584
+ pricing_model: 'cpc';
585
+ /**
586
+ * Fixed CPC rate (cost per click)
587
+ */
588
+ rate: number;
589
+ /**
590
+ * ISO 4217 currency code
591
+ */
592
+ currency: string;
593
+ /**
594
+ * Minimum spend requirement per package using this pricing option, in the specified currency
595
+ */
596
+ min_spend_per_package?: number;
597
+ }
598
+ /**
599
+ * Cost Per Completed View (100% video/audio completion) fixed-rate pricing
600
+ */
601
+ export interface CPCVPricingOption {
602
+ /**
603
+ * Unique identifier for this pricing option within the product (e.g., 'cpcv_usd_guaranteed')
604
+ */
605
+ pricing_option_id: string;
606
+ /**
607
+ * Cost per completed view (100% completion)
608
+ */
609
+ pricing_model: 'cpcv';
610
+ /**
611
+ * Fixed CPCV rate (cost per 100% completion)
612
+ */
613
+ rate: number;
614
+ /**
615
+ * ISO 4217 currency code
616
+ */
617
+ currency: string;
618
+ /**
619
+ * Minimum spend requirement per package using this pricing option, in the specified currency
620
+ */
621
+ min_spend_per_package?: number;
622
+ }
623
+ /**
624
+ * Cost Per View (at publisher-defined threshold) fixed-rate pricing for video/audio
625
+ */
626
+ export interface CPVPricingOption {
627
+ /**
628
+ * Unique identifier for this pricing option within the product (e.g., 'cpv_usd_50pct')
629
+ */
630
+ pricing_option_id: string;
631
+ /**
632
+ * Cost per view at threshold
633
+ */
634
+ pricing_model: 'cpv';
635
+ /**
636
+ * Fixed CPV rate (cost per view)
637
+ */
638
+ rate: number;
639
+ /**
640
+ * ISO 4217 currency code
641
+ */
642
+ currency: string;
643
+ /**
644
+ * CPV-specific parameters defining the view threshold
645
+ */
646
+ parameters: {
647
+ view_threshold: number | {
648
+ /**
649
+ * Seconds of viewing required (e.g., 30 for YouTube-style '30 seconds = view')
650
+ */
651
+ duration_seconds: number;
652
+ };
653
+ };
654
+ /**
655
+ * Minimum spend requirement per package using this pricing option, in the specified currency
656
+ */
657
+ min_spend_per_package?: number;
658
+ }
659
+ /**
660
+ * Cost Per Point (Gross Rating Point) fixed-rate pricing for TV and audio campaigns requiring demographic measurement
661
+ */
662
+ export interface CPPPricingOption {
663
+ /**
664
+ * Unique identifier for this pricing option within the product (e.g., 'cpp_usd_p18-49')
665
+ */
666
+ pricing_option_id: string;
667
+ /**
668
+ * Cost per Gross Rating Point
669
+ */
670
+ pricing_model: 'cpp';
671
+ /**
672
+ * Fixed CPP rate (cost per rating point)
673
+ */
674
+ rate: number;
675
+ /**
676
+ * ISO 4217 currency code
677
+ */
678
+ currency: string;
679
+ /**
680
+ * CPP-specific parameters for demographic targeting and GRP requirements
681
+ */
682
+ parameters: {
683
+ /**
684
+ * Target demographic in Nielsen format: P/M/W/A/C + age range. Examples: P18-49 (Persons 18-49), M25-54 (Men 25-54), W35+ (Women 35+), A18-34 (Adults 18-34), C2-11 (Children 2-11)
685
+ */
686
+ demographic: string;
687
+ /**
688
+ * Minimum GRPs/TRPs required for this pricing option
689
+ */
690
+ min_points?: number;
691
+ };
692
+ /**
693
+ * Minimum spend requirement per package using this pricing option, in the specified currency
694
+ */
695
+ min_spend_per_package?: number;
696
+ }
697
+ /**
698
+ * Flat rate pricing for DOOH, sponsorships, and time-based campaigns - fixed cost regardless of delivery volume
699
+ */
700
+ export interface FlatRatePricingOption {
701
+ /**
702
+ * Unique identifier for this pricing option within the product (e.g., 'flat_rate_usd_24h_takeover')
703
+ */
704
+ pricing_option_id: string;
705
+ /**
706
+ * Fixed cost regardless of delivery volume
707
+ */
708
+ pricing_model: 'flat_rate';
709
+ /**
710
+ * Flat rate cost
711
+ */
712
+ rate: number;
713
+ /**
714
+ * ISO 4217 currency code
715
+ */
716
+ currency: string;
717
+ /**
718
+ * Whether this is a fixed rate (true) or auction-based (false)
719
+ */
720
+ is_fixed: true;
721
+ /**
722
+ * Flat rate parameters for DOOH and time-based campaigns
723
+ */
724
+ parameters?: {
725
+ /**
726
+ * Duration in hours for time-based flat rate pricing (DOOH)
727
+ */
728
+ duration_hours?: number;
729
+ /**
730
+ * Guaranteed share of voice as percentage (DOOH, 0-100)
731
+ */
732
+ sov_percentage?: number;
733
+ /**
734
+ * Duration of ad loop rotation in seconds (DOOH)
735
+ */
736
+ loop_duration_seconds?: number;
737
+ /**
738
+ * Minimum number of times ad plays per hour (DOOH frequency guarantee)
739
+ */
740
+ min_plays_per_hour?: number;
741
+ /**
742
+ * Named venue package identifier for DOOH (e.g., 'times_square_network', 'airport_terminals')
743
+ */
744
+ venue_package?: string;
745
+ /**
746
+ * Estimated impressions for this flat rate option (informational, commonly used with SOV or time-based DOOH)
747
+ */
748
+ estimated_impressions?: number;
749
+ /**
750
+ * Specific daypart for time-based pricing (e.g., 'morning_commute', 'evening_prime', 'overnight')
751
+ */
752
+ daypart?: string;
753
+ };
754
+ /**
755
+ * Minimum spend requirement per package using this pricing option, in the specified currency
756
+ */
757
+ min_spend_per_package?: number;
758
+ }
759
+ /**
760
+ * Measurement capabilities included with a product
761
+ */
762
+ export interface Measurement {
763
+ /**
764
+ * Type of measurement
765
+ */
766
+ type: string;
767
+ /**
768
+ * Attribution methodology
769
+ */
770
+ attribution: string;
771
+ /**
772
+ * Attribution window
773
+ */
774
+ window?: string;
775
+ /**
776
+ * Reporting frequency and format
777
+ */
778
+ reporting: string;
779
+ }
780
+ /**
781
+ * Reporting capabilities available for a product
782
+ */
783
+ export interface ReportingCapabilities {
784
+ /**
785
+ * Supported reporting frequency options
786
+ *
787
+ * @minItems 1
788
+ */
789
+ available_reporting_frequencies: ['hourly' | 'daily' | 'monthly', ...('hourly' | 'daily' | 'monthly')[]];
790
+ /**
791
+ * Expected delay in minutes before reporting data becomes available (e.g., 240 for 4-hour delay)
792
+ */
793
+ expected_delay_minutes: number;
794
+ /**
795
+ * Timezone for reporting periods. Use 'UTC' or IANA timezone (e.g., 'America/New_York'). Critical for daily/monthly frequency alignment.
796
+ */
797
+ timezone: string;
798
+ /**
799
+ * Whether this product supports webhook-based reporting notifications
800
+ */
801
+ supports_webhooks: boolean;
802
+ /**
803
+ * Metrics available in reporting. Impressions and spend are always implicitly included.
804
+ */
805
+ available_metrics: ('impressions' | 'spend' | 'clicks' | 'ctr' | 'video_completions' | 'completion_rate' | 'conversions' | 'viewability' | 'engagement_rate')[];
806
+ }
807
+ /**
808
+ * Creative requirements and restrictions for a product
809
+ */
810
+ export interface CreativePolicy {
811
+ /**
812
+ * Co-branding requirement
813
+ */
814
+ co_branding: 'required' | 'optional' | 'none';
815
+ /**
816
+ * Landing page requirements
817
+ */
818
+ landing_page: 'any' | 'retailer_site_only' | 'must_include_retailer';
819
+ /**
820
+ * Whether creative templates are provided
821
+ */
822
+ templates_available: boolean;
823
+ }
824
+ /**
825
+ * Standard error structure for task-specific errors and warnings
826
+ */
827
+ export interface Error {
828
+ /**
829
+ * Error code for programmatic handling
830
+ */
831
+ code: string;
832
+ /**
833
+ * Human-readable error message
834
+ */
835
+ message: string;
836
+ /**
837
+ * Field path associated with the error (e.g., 'packages[0].targeting')
838
+ */
839
+ field?: string;
840
+ /**
841
+ * Suggested fix for the error
842
+ */
843
+ suggestion?: string;
844
+ /**
845
+ * Seconds to wait before retrying the operation
846
+ */
847
+ retry_after?: number;
848
+ /**
849
+ * Additional task-specific error details
850
+ */
851
+ details?: {
852
+ [k: string]: unknown;
853
+ };
854
+ }
855
+ /**
856
+ * Request parameters for discovering supported creative formats
857
+ */
858
+ export interface ListCreativeFormatsRequest {
859
+ /**
860
+ * Return only these specific format IDs (e.g., from get_products response)
861
+ */
862
+ format_ids?: FormatID[];
863
+ /**
864
+ * Filter by format type (technical categories with distinct requirements)
865
+ */
866
+ type?: 'audio' | 'video' | 'display' | 'dooh';
867
+ /**
868
+ * Filter to formats that include these asset types. For third-party tags, search for 'html' or 'javascript'. E.g., ['image', 'text'] returns formats with images and text, ['javascript'] returns formats accepting JavaScript tags.
869
+ */
870
+ asset_types?: ('image' | 'video' | 'audio' | 'text' | 'html' | 'javascript' | 'url')[];
871
+ /**
872
+ * Maximum width in pixels (inclusive). Returns formats where ANY render has width <= this value. For multi-render formats, matches if at least one render fits.
873
+ */
874
+ max_width?: number;
875
+ /**
876
+ * Maximum height in pixels (inclusive). Returns formats where ANY render has height <= this value. For multi-render formats, matches if at least one render fits.
877
+ */
878
+ max_height?: number;
879
+ /**
880
+ * Minimum width in pixels (inclusive). Returns formats where ANY render has width >= this value.
881
+ */
882
+ min_width?: number;
883
+ /**
884
+ * Minimum height in pixels (inclusive). Returns formats where ANY render has height >= this value.
885
+ */
886
+ min_height?: number;
887
+ /**
888
+ * Filter for responsive formats that adapt to container size. When true, returns formats without fixed dimensions.
889
+ */
890
+ is_responsive?: boolean;
891
+ /**
892
+ * Search for formats by name (case-insensitive partial match)
893
+ */
894
+ name_search?: string;
895
+ }
896
+ /**
897
+ * Structured format identifier with agent URL and format name
898
+ */
899
+ /**
900
+ * Response payload for list_creative_formats task
901
+ */
902
+ export interface ListCreativeFormatsResponse {
903
+ /**
904
+ * Full format definitions for all formats this agent supports. Each format's authoritative source is indicated by its agent_url field.
905
+ */
906
+ formats: Format[];
907
+ /**
908
+ * Optional: Creative agents that provide additional formats. Buyers can recursively query these agents to discover more formats. No authentication required for list_creative_formats.
909
+ */
910
+ creative_agents?: {
911
+ /**
912
+ * Base URL for the creative agent (e.g., 'https://reference.adcp.org', 'https://dco.example.com'). Call list_creative_formats on this URL to get its formats.
913
+ */
914
+ agent_url: string;
915
+ /**
916
+ * Human-readable name for the creative agent
917
+ */
918
+ agent_name?: string;
919
+ /**
920
+ * Capabilities this creative agent provides
921
+ */
922
+ capabilities?: ('validation' | 'assembly' | 'generation' | 'preview')[];
923
+ [k: string]: unknown;
924
+ }[];
925
+ /**
926
+ * Task-specific errors and warnings (e.g., format availability issues)
927
+ */
928
+ errors?: Error[];
929
+ }
930
+ /**
931
+ * Represents a creative format with its requirements
932
+ */
933
+ export interface Format {
934
+ format_id: FormatID;
935
+ /**
936
+ * Human-readable format name
937
+ */
938
+ name: string;
939
+ /**
940
+ * Plain text explanation of what this format does and what assets it requires
941
+ */
942
+ description?: string;
943
+ /**
944
+ * Optional preview image URL for format browsing/discovery UI. Should be 400x300px (4:3 aspect ratio) PNG or JPG. Used as thumbnail/card image in format browsers.
945
+ */
946
+ preview_image?: string;
947
+ /**
948
+ * Optional URL to showcase page with examples and interactive demos of this format
949
+ */
950
+ example_url?: string;
951
+ /**
952
+ * Media type of this format - determines rendering method and asset requirements
953
+ */
954
+ type: 'audio' | 'video' | 'display' | 'native' | 'dooh' | 'rich_media' | 'universal';
955
+ /**
956
+ * Specification of rendered pieces for this format. Most formats produce a single render. Companion ad formats (video + banner), adaptive formats, and multi-placement formats produce multiple renders. Each render specifies its role and dimensions.
957
+ *
958
+ * @minItems 1
959
+ */
960
+ renders?: [
961
+ {
962
+ /**
963
+ * Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')
964
+ */
965
+ role: string;
966
+ /**
967
+ * Dimensions for this rendered piece
968
+ */
969
+ dimensions: {
970
+ /**
971
+ * Fixed width in specified units
972
+ */
973
+ width?: number;
974
+ /**
975
+ * Fixed height in specified units
976
+ */
977
+ height?: number;
978
+ /**
979
+ * Minimum width for responsive renders
980
+ */
981
+ min_width?: number;
982
+ /**
983
+ * Minimum height for responsive renders
984
+ */
985
+ min_height?: number;
986
+ /**
987
+ * Maximum width for responsive renders
988
+ */
989
+ max_width?: number;
990
+ /**
991
+ * Maximum height for responsive renders
992
+ */
993
+ max_height?: number;
994
+ /**
995
+ * Indicates which dimensions are responsive/fluid
996
+ */
997
+ responsive?: {
998
+ width: boolean;
999
+ height: boolean;
1000
+ [k: string]: unknown;
1001
+ };
1002
+ /**
1003
+ * Fixed aspect ratio constraint (e.g., '16:9', '4:3', '1:1')
1004
+ */
1005
+ aspect_ratio?: string;
1006
+ /**
1007
+ * Unit of measurement for dimensions
1008
+ */
1009
+ unit: 'px' | 'dp' | 'inches' | 'cm';
1010
+ [k: string]: unknown;
1011
+ };
1012
+ [k: string]: unknown;
1013
+ },
1014
+ ...{
1015
+ /**
1016
+ * Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')
1017
+ */
1018
+ role: string;
1019
+ /**
1020
+ * Dimensions for this rendered piece
1021
+ */
1022
+ dimensions: {
1023
+ /**
1024
+ * Fixed width in specified units
1025
+ */
1026
+ width?: number;
1027
+ /**
1028
+ * Fixed height in specified units
1029
+ */
1030
+ height?: number;
1031
+ /**
1032
+ * Minimum width for responsive renders
1033
+ */
1034
+ min_width?: number;
1035
+ /**
1036
+ * Minimum height for responsive renders
1037
+ */
1038
+ min_height?: number;
1039
+ /**
1040
+ * Maximum width for responsive renders
1041
+ */
1042
+ max_width?: number;
1043
+ /**
1044
+ * Maximum height for responsive renders
1045
+ */
1046
+ max_height?: number;
1047
+ /**
1048
+ * Indicates which dimensions are responsive/fluid
1049
+ */
1050
+ responsive?: {
1051
+ width: boolean;
1052
+ height: boolean;
1053
+ [k: string]: unknown;
1054
+ };
1055
+ /**
1056
+ * Fixed aspect ratio constraint (e.g., '16:9', '4:3', '1:1')
1057
+ */
1058
+ aspect_ratio?: string;
1059
+ /**
1060
+ * Unit of measurement for dimensions
1061
+ */
1062
+ unit: 'px' | 'dp' | 'inches' | 'cm';
1063
+ [k: string]: unknown;
1064
+ };
1065
+ [k: string]: unknown;
1066
+ }[]
1067
+ ];
1068
+ /**
1069
+ * Array of required assets or asset groups for this format. Can contain individual assets or repeatable asset sequences (e.g., carousel products, slideshow frames).
1070
+ */
1071
+ assets_required?: ({
1072
+ /**
1073
+ * Identifier for this asset in the format
1074
+ */
1075
+ asset_id: string;
1076
+ /**
1077
+ * Type of asset
1078
+ */
1079
+ asset_type: 'image' | 'video' | 'audio' | 'text' | 'html' | 'javascript' | 'url' | 'brand_manifest';
1080
+ /**
1081
+ * Purpose of this asset (e.g., 'hero_image', 'logo', 'headline', 'cta_button')
1082
+ */
1083
+ asset_role?: string;
1084
+ /**
1085
+ * Whether this asset is required
1086
+ */
1087
+ required?: boolean;
1088
+ /**
1089
+ * Technical requirements for this asset (dimensions, file size, duration, etc.)
1090
+ */
1091
+ requirements?: {
1092
+ [k: string]: unknown;
1093
+ };
1094
+ [k: string]: unknown;
1095
+ } | {
1096
+ /**
1097
+ * Identifier for this asset group (e.g., 'product', 'slide', 'card')
1098
+ */
1099
+ asset_group_id: string;
1100
+ /**
1101
+ * Indicates this is a repeatable asset group
1102
+ */
1103
+ repeatable: true;
1104
+ /**
1105
+ * Minimum number of repetitions required
1106
+ */
1107
+ min_count: number;
1108
+ /**
1109
+ * Maximum number of repetitions allowed
1110
+ */
1111
+ max_count: number;
1112
+ /**
1113
+ * Assets within each repetition of this group
1114
+ */
1115
+ assets: {
1116
+ /**
1117
+ * Identifier for this asset within the group
1118
+ */
1119
+ asset_id: string;
1120
+ /**
1121
+ * Type of asset
1122
+ */
1123
+ asset_type: 'image' | 'video' | 'audio' | 'text' | 'html' | 'javascript' | 'url' | 'brand_manifest';
1124
+ /**
1125
+ * Purpose of this asset
1126
+ */
1127
+ asset_role?: string;
1128
+ /**
1129
+ * Whether this asset is required in each repetition
1130
+ */
1131
+ required?: boolean;
1132
+ /**
1133
+ * Technical requirements for this asset
1134
+ */
1135
+ requirements?: {
1136
+ [k: string]: unknown;
1137
+ };
1138
+ [k: string]: unknown;
1139
+ }[];
1140
+ [k: string]: unknown;
1141
+ })[];
1142
+ /**
1143
+ * Delivery method specifications (e.g., hosted, VAST, third-party tags)
1144
+ */
1145
+ delivery?: {
1146
+ [k: string]: unknown;
1147
+ };
1148
+ /**
1149
+ * List of universal macros supported by this format (e.g., MEDIA_BUY_ID, CACHEBUSTER, DEVICE_ID). Used for validation and developer tooling.
1150
+ */
1151
+ supported_macros?: string[];
1152
+ /**
1153
+ * For generative formats: array of format IDs that this format can generate. When a format accepts inputs like brand_manifest and message, this specifies what concrete output formats can be produced (e.g., a generative banner format might output standard image banner formats).
1154
+ */
1155
+ output_format_ids?: FormatID1[];
1156
+ }
1157
+ /**
1158
+ * Structured format identifier with agent URL and format name
1159
+ */
1160
+ export interface FormatID1 {
1161
+ /**
1162
+ * URL of the agent that defines this format (e.g., 'https://creatives.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats)
1163
+ */
1164
+ agent_url: string;
1165
+ /**
1166
+ * Format identifier within the agent's namespace (e.g., 'display_300x250', 'video_standard_30s')
1167
+ */
1168
+ id: string;
1169
+ }
1170
+ /**
1171
+ * Standard error structure for task-specific errors and warnings
1172
+ */
1173
+ /**
1174
+ * Budget pacing strategy
1175
+ */
1176
+ export type Pacing = 'even' | 'asap' | 'front_loaded';
1177
+ /**
1178
+ * VAST (Video Ad Serving Template) tag for third-party video ad serving
1179
+ */
1180
+ export type VASTAsset = VASTAsset1 & VASTAsset2;
1181
+ export type VASTAsset2 = {
1182
+ [k: string]: unknown;
1183
+ } | {
1184
+ [k: string]: unknown;
1185
+ };
1186
+ /**
1187
+ * DAAST (Digital Audio Ad Serving Template) tag for third-party audio ad serving
1188
+ */
1189
+ export type DAASTAsset = DAASTAsset1 & DAASTAsset2;
1190
+ export type DAASTAsset2 = {
1191
+ [k: string]: unknown;
1192
+ } | {
1193
+ [k: string]: unknown;
1194
+ };
1195
+ /**
1196
+ * Brand information manifest serving as the namespace and identity for this media buy. Provides brand context, assets, and product catalog. Can be provided inline or as a URL reference to a hosted manifest. Can be cached and reused across multiple requests.
1197
+ */
1198
+ export type StartTiming = 'asap' | string;
1199
+ /**
1200
+ * Request parameters for creating a media buy
1201
+ */
1202
+ export interface CreateMediaBuyRequest {
116
1203
  /**
117
- * Cost per thousand impressions in USD
1204
+ * Buyer's reference identifier for this media buy
118
1205
  */
119
- cpm?: number;
1206
+ buyer_ref: string;
120
1207
  /**
121
- * Minimum budget requirement in USD
1208
+ * Array of package configurations
122
1209
  */
123
- min_spend?: number;
124
- measurement?: Measurement;
125
- creative_policy?: CreativePolicy;
1210
+ packages: PackageRequest[];
1211
+ brand_manifest: BrandManifestReference;
126
1212
  /**
127
- * Whether this is a custom product
1213
+ * Purchase order number for tracking
128
1214
  */
129
- is_custom?: boolean;
1215
+ po_number?: string;
1216
+ start_time: StartTiming;
130
1217
  /**
131
- * Explanation of why this product matches the brief (only included when brief is provided)
1218
+ * Campaign end date/time in ISO 8601 format
132
1219
  */
133
- brief_relevance?: string;
1220
+ end_time: string;
134
1221
  /**
135
- * Expiration timestamp for custom products
1222
+ * Total budget for this media buy. Currency is determined by the pricing_option_id selected in each package.
136
1223
  */
137
- expires_at?: string;
1224
+ budget: number;
1225
+ reporting_webhook?: PushNotificationConfig & {
1226
+ /**
1227
+ * Frequency for automated reporting delivery. Must be supported by all products in the media buy.
1228
+ */
1229
+ reporting_frequency: 'hourly' | 'daily' | 'monthly';
1230
+ /**
1231
+ * Optional list of metrics to include in webhook notifications. If omitted, all available metrics are included. Must be subset of product's available_metrics.
1232
+ */
1233
+ requested_metrics?: ('impressions' | 'spend' | 'clicks' | 'ctr' | 'video_completions' | 'completion_rate' | 'conversions' | 'viewability' | 'engagement_rate')[];
1234
+ [k: string]: unknown;
1235
+ };
138
1236
  }
139
1237
  /**
140
- * An advertising property that can be validated via adagents.json
1238
+ * Package configuration for media buy creation
141
1239
  */
142
- export interface Property {
1240
+ export interface PackageRequest {
143
1241
  /**
144
- * Type of advertising property
1242
+ * Buyer's reference identifier for this package
145
1243
  */
146
- property_type: 'website' | 'mobile_app' | 'ctv_app' | 'dooh' | 'podcast' | 'radio' | 'streaming_audio';
1244
+ buyer_ref: string;
147
1245
  /**
148
- * Human-readable property name
1246
+ * Product ID for this package
149
1247
  */
150
- name: string;
1248
+ product_id: string;
151
1249
  /**
152
- * Array of identifiers for this property
1250
+ * Array of format IDs that will be used for this package - must be supported by the product. If omitted, defaults to all formats supported by the product.
153
1251
  *
154
1252
  * @minItems 1
155
1253
  */
156
- identifiers: [
157
- {
158
- type: PropertyIdentifierTypes;
159
- /**
160
- * The identifier value. For domain type: 'example.com' matches www.example.com and m.example.com only; 'subdomain.example.com' matches that specific subdomain; '*.example.com' matches all subdomains
161
- */
162
- value: string;
163
- },
164
- ...{
165
- type: PropertyIdentifierTypes;
166
- /**
167
- * The identifier value. For domain type: 'example.com' matches www.example.com and m.example.com only; 'subdomain.example.com' matches that specific subdomain; '*.example.com' matches all subdomains
168
- */
169
- value: string;
170
- }[]
171
- ];
1254
+ format_ids?: [FormatID, ...FormatID[]];
172
1255
  /**
173
- * Tags for categorization and grouping (e.g., network membership, content categories)
1256
+ * Budget allocation for this package in the media buy's currency
174
1257
  */
175
- tags?: string[];
1258
+ budget: number;
1259
+ pacing?: Pacing;
176
1260
  /**
177
- * Domain where adagents.json should be checked for authorization validation
1261
+ * ID of the selected pricing option from the product's pricing_options array
178
1262
  */
179
- publisher_domain: string;
1263
+ pricing_option_id: string;
1264
+ /**
1265
+ * Bid price for auction-based CPM pricing (required if using cpm-auction-option)
1266
+ */
1267
+ bid_price?: number;
1268
+ targeting_overlay?: TargetingOverlay;
1269
+ /**
1270
+ * Creative IDs to assign to this package at creation time (references existing library creatives)
1271
+ */
1272
+ creative_ids?: string[];
1273
+ /**
1274
+ * Full creative objects to upload and assign to this package at creation time (alternative to creative_ids - creatives will be added to library). Supports both static and generative creatives.
1275
+ *
1276
+ * @maxItems 100
1277
+ */
1278
+ creatives?: CreativeAsset[];
180
1279
  }
181
1280
  /**
182
- * Measurement capabilities included with a product
1281
+ * Structured format identifier with agent URL and format name
183
1282
  */
184
- export interface Measurement {
1283
+ export interface TargetingOverlay {
185
1284
  /**
186
- * Type of measurement
1285
+ * Restrict delivery to specific countries (ISO codes). Use for regulatory compliance or RCT testing.
187
1286
  */
188
- type: string;
1287
+ geo_country_any_of?: string[];
189
1288
  /**
190
- * Attribution methodology
1289
+ * Restrict delivery to specific regions/states. Use for regulatory compliance or RCT testing.
191
1290
  */
192
- attribution: string;
1291
+ geo_region_any_of?: string[];
193
1292
  /**
194
- * Attribution window
1293
+ * Restrict delivery to specific metro areas (DMA codes). Use for regulatory compliance or RCT testing.
195
1294
  */
196
- window?: string;
1295
+ geo_metro_any_of?: string[];
197
1296
  /**
198
- * Reporting frequency and format
1297
+ * Restrict delivery to specific postal/ZIP codes. Use for regulatory compliance or RCT testing.
199
1298
  */
200
- reporting: string;
1299
+ geo_postal_code_any_of?: string[];
1300
+ frequency_cap?: FrequencyCap;
201
1301
  }
202
1302
  /**
203
- * Creative requirements and restrictions for a product
1303
+ * Frequency capping settings for package-level application
204
1304
  */
205
- export interface CreativePolicy {
206
- /**
207
- * Co-branding requirement
208
- */
209
- co_branding: 'required' | 'optional' | 'none';
210
- /**
211
- * Landing page requirements
212
- */
213
- landing_page: 'any' | 'retailer_site_only' | 'must_include_retailer';
1305
+ export interface FrequencyCap {
214
1306
  /**
215
- * Whether creative templates are provided
1307
+ * Minutes to suppress after impression
216
1308
  */
217
- templates_available: boolean;
1309
+ suppress_minutes: number;
218
1310
  }
219
1311
  /**
220
- * Standard error structure for task-specific errors and warnings
1312
+ * Creative asset for upload to library - supports static assets, generative formats, and third-party snippets
221
1313
  */
222
- export interface Error {
1314
+ export interface CreativeAsset {
223
1315
  /**
224
- * Error code for programmatic handling
1316
+ * Unique identifier for the creative
225
1317
  */
226
- code: string;
1318
+ creative_id: string;
227
1319
  /**
228
- * Human-readable error message
1320
+ * Human-readable creative name
229
1321
  */
230
- message: string;
1322
+ name: string;
1323
+ format_id: FormatID1;
231
1324
  /**
232
- * Field path associated with the error (e.g., 'packages[0].targeting')
1325
+ * Assets required by the format, keyed by asset_role
233
1326
  */
234
- field?: string;
1327
+ assets: {
1328
+ /**
1329
+ * This interface was referenced by `undefined`'s JSON-Schema definition
1330
+ * via the `patternProperty` "^[a-zA-Z0-9_-]+$".
1331
+ */
1332
+ [k: string]: ImageAsset | VideoAsset | AudioAsset | TextAsset | HTMLAsset | CSSAsset | JavaScriptAsset | VASTAsset | DAASTAsset | PromotedOfferingsAsset | URLAsset;
1333
+ };
235
1334
  /**
236
- * Suggested fix for the error
1335
+ * Preview contexts for generative formats - defines what scenarios to generate previews for
237
1336
  */
238
- suggestion?: string;
1337
+ inputs?: {
1338
+ /**
1339
+ * Human-readable name for this preview variant
1340
+ */
1341
+ name: string;
1342
+ /**
1343
+ * Macro values to apply for this preview
1344
+ */
1345
+ macros?: {
1346
+ [k: string]: string;
1347
+ };
1348
+ /**
1349
+ * Natural language description of the context for AI-generated content
1350
+ */
1351
+ context_description?: string;
1352
+ }[];
239
1353
  /**
240
- * Seconds to wait before retrying the operation
1354
+ * User-defined tags for organization and searchability
241
1355
  */
242
- retry_after?: number;
1356
+ tags?: string[];
243
1357
  /**
244
- * Additional task-specific error details
1358
+ * For generative creatives: set to true to approve and finalize, false to request regeneration with updated assets/message. Omit for non-generative creatives.
245
1359
  */
246
- details?: {
247
- [k: string]: unknown;
248
- };
1360
+ approved?: boolean;
249
1361
  }
250
1362
  /**
251
- * Request parameters for discovering supported creative formats
1363
+ * Structured format identifier with agent URL and format name
252
1364
  */
253
- export interface ListCreativeFormatsRequest {
1365
+ export interface ImageAsset {
1366
+ asset_type: 'image';
254
1367
  /**
255
- * AdCP schema version for this request
1368
+ * URL to the image asset
256
1369
  */
257
- adcp_version?: string;
1370
+ url: string;
258
1371
  /**
259
- * Filter by format type
1372
+ * Image width in pixels
260
1373
  */
261
- type?: 'audio' | 'video' | 'display';
1374
+ width?: number;
262
1375
  /**
263
- * Only return IAB standard formats
1376
+ * Image height in pixels
264
1377
  */
265
- standard_only?: boolean;
1378
+ height?: number;
266
1379
  /**
267
- * Filter by format category
1380
+ * Image file format (jpg, png, gif, webp, etc.)
268
1381
  */
269
- category?: 'standard' | 'custom';
1382
+ format?: string;
270
1383
  /**
271
- * Filter by specific format IDs (e.g., from get_products response)
1384
+ * Alternative text for accessibility
272
1385
  */
273
- format_ids?: string[];
1386
+ alt_text?: string;
274
1387
  }
275
1388
  /**
276
- * Current task state
1389
+ * Video asset with URL and specifications
277
1390
  */
278
- export type CreativeAsset = CreativeAsset1 & CreativeAsset2;
279
- /**
280
- * Type of snippet content
281
- */
282
- export type SnippetType = 'vast_xml' | 'vast_url' | 'html' | 'javascript' | 'iframe' | 'daast_url';
283
- /**
284
- * Sub-asset for multi-asset creative formats, including carousel images and native ad template variables
285
- */
286
- export type SubAsset = SubAsset1 & SubAsset2;
287
- export type SubAsset2 = {
288
- [k: string]: unknown;
289
- } | {
290
- [k: string]: unknown;
291
- };
292
- export type CreativeAsset2 = {
293
- [k: string]: unknown;
294
- } | {
295
- [k: string]: unknown;
296
- };
297
- /**
298
- * Response payload for list_creative_formats task
299
- */
300
- export interface ListCreativeFormatsResponse {
1391
+ export interface VideoAsset {
1392
+ asset_type: 'video';
301
1393
  /**
302
- * AdCP schema version used for this response
1394
+ * URL to the video asset
303
1395
  */
304
- adcp_version: string;
305
- status?: TaskStatus;
1396
+ url: string;
306
1397
  /**
307
- * Array of available creative formats
1398
+ * Video width in pixels
308
1399
  */
309
- formats: Format[];
1400
+ width?: number;
310
1401
  /**
311
- * Task-specific errors and warnings (e.g., format availability issues)
1402
+ * Video height in pixels
312
1403
  */
313
- errors?: Error[];
1404
+ height?: number;
1405
+ /**
1406
+ * Video duration in milliseconds
1407
+ */
1408
+ duration_ms?: number;
1409
+ /**
1410
+ * Video file format (mp4, webm, mov, etc.)
1411
+ */
1412
+ format?: string;
1413
+ /**
1414
+ * Video bitrate in kilobits per second
1415
+ */
1416
+ bitrate_kbps?: number;
314
1417
  }
315
1418
  /**
316
- * Represents a creative format with its requirements
1419
+ * Audio asset with URL and specifications
317
1420
  */
318
- export interface Format {
1421
+ export interface AudioAsset {
1422
+ asset_type: 'audio';
319
1423
  /**
320
- * Unique identifier for the format
1424
+ * URL to the audio asset
321
1425
  */
322
- format_id: string;
1426
+ url: string;
323
1427
  /**
324
- * Human-readable format name
1428
+ * Audio duration in milliseconds
325
1429
  */
326
- name: string;
1430
+ duration_ms?: number;
327
1431
  /**
328
- * Media type of this format - determines rendering method and asset requirements
1432
+ * Audio file format (mp3, wav, aac, etc.)
329
1433
  */
330
- type: 'audio' | 'video' | 'display' | 'native' | 'dooh' | 'rich_media' | 'universal';
1434
+ format?: string;
331
1435
  /**
332
- * Format category
1436
+ * Audio bitrate in kilobits per second
333
1437
  */
334
- category?: 'standard' | 'custom';
1438
+ bitrate_kbps?: number;
1439
+ }
1440
+ /**
1441
+ * Text content asset
1442
+ */
1443
+ export interface TextAsset {
1444
+ asset_type: 'text';
335
1445
  /**
336
- * Whether this format follows IAB specifications or AdCP standard format definitions (found in /schemas/v1/standard-formats/)
1446
+ * Text content
337
1447
  */
338
- is_standard?: boolean;
1448
+ content: string;
339
1449
  /**
340
- * Technical specifications for this format (e.g., dimensions, duration, file size limits, codecs)
1450
+ * Maximum character length constraint
341
1451
  */
342
- requirements?: {
343
- [k: string]: unknown;
344
- };
1452
+ max_length?: number;
345
1453
  /**
346
- * Array of required assets for this format
1454
+ * Language code (e.g., 'en', 'es', 'fr')
347
1455
  */
348
- assets_required?: CreativeAsset[];
1456
+ language?: string;
1457
+ }
1458
+ /**
1459
+ * HTML content asset
1460
+ */
1461
+ export interface HTMLAsset {
1462
+ asset_type: 'html';
349
1463
  /**
350
- * Array of optional assets that may be included
1464
+ * HTML content
351
1465
  */
352
- optional_assets?: CreativeAsset2[];
1466
+ content: string;
353
1467
  /**
354
- * Delivery method specifications (e.g., hosted, VAST, third-party tags)
1468
+ * HTML version (e.g., 'HTML5')
355
1469
  */
356
- delivery?: {
357
- [k: string]: unknown;
358
- };
1470
+ version?: string;
1471
+ }
1472
+ /**
1473
+ * CSS stylesheet asset
1474
+ */
1475
+ export interface CSSAsset {
1476
+ asset_type: 'css';
1477
+ /**
1478
+ * CSS content
1479
+ */
1480
+ content: string;
359
1481
  /**
360
- * Whether this format can accept third-party served creative tags as an alternative to hosted assets
1482
+ * CSS media query context (e.g., 'screen', 'print')
361
1483
  */
362
- accepts_3p_tags?: boolean;
1484
+ media?: string;
363
1485
  }
364
- export interface CreativeAsset1 {
1486
+ /**
1487
+ * JavaScript code asset
1488
+ */
1489
+ export interface JavaScriptAsset {
1490
+ asset_type: 'javascript';
365
1491
  /**
366
- * Unique identifier for the creative
1492
+ * JavaScript content
367
1493
  */
368
- creative_id: string;
1494
+ content: string;
369
1495
  /**
370
- * Human-readable creative name
1496
+ * JavaScript module type
371
1497
  */
372
- name: string;
1498
+ module_type?: 'esm' | 'commonjs' | 'script';
1499
+ }
1500
+ export interface VASTAsset1 {
1501
+ asset_type?: 'vast';
373
1502
  /**
374
- * Creative format type (e.g., video, audio, display)
1503
+ * URL endpoint that returns VAST XML
375
1504
  */
376
- format: string;
1505
+ url?: string;
377
1506
  /**
378
- * URL of the creative file (for hosted assets)
1507
+ * Inline VAST XML content
379
1508
  */
380
- media_url?: string;
1509
+ content?: string;
381
1510
  /**
382
- * Third-party tag, VAST XML, or code snippet (for third-party served assets)
1511
+ * VAST specification version
383
1512
  */
384
- snippet?: string;
385
- snippet_type?: SnippetType;
1513
+ vast_version?: '2.0' | '3.0' | '4.0' | '4.1' | '4.2';
386
1514
  /**
387
- * Landing page URL for the creative
1515
+ * Whether VPAID (Video Player-Ad Interface Definition) is supported
388
1516
  */
389
- click_url?: string;
1517
+ vpaid_enabled?: boolean;
390
1518
  /**
391
- * Duration in milliseconds (for video/audio)
1519
+ * Maximum allowed wrapper/redirect depth
392
1520
  */
393
- duration?: number;
1521
+ max_wrapper_depth?: number;
394
1522
  /**
395
- * Width in pixels (for video/display)
1523
+ * Expected video duration in milliseconds (if known)
396
1524
  */
397
- width?: number;
1525
+ duration_ms?: number;
398
1526
  /**
399
- * Height in pixels (for video/display)
1527
+ * Tracking events supported by this VAST tag
400
1528
  */
401
- height?: number;
1529
+ tracking_events?: ('start' | 'firstQuartile' | 'midpoint' | 'thirdQuartile' | 'complete' | 'impression' | 'click' | 'pause' | 'resume' | 'skip' | 'mute' | 'unmute' | 'fullscreen' | 'exitFullscreen' | 'playerExpand' | 'playerCollapse')[];
1530
+ }
1531
+ export interface DAASTAsset1 {
1532
+ asset_type?: 'daast';
402
1533
  /**
403
- * User-defined tags for organization and searchability
1534
+ * URL endpoint that returns DAAST XML
404
1535
  */
405
- tags?: string[];
1536
+ url?: string;
406
1537
  /**
407
- * Sub-assets for multi-asset formats like carousels
1538
+ * Inline DAAST XML content
408
1539
  */
409
- assets?: SubAsset[];
410
- }
411
- export interface SubAsset1 {
1540
+ content?: string;
412
1541
  /**
413
- * Type of asset. Common types: headline, body_text, thumbnail_image, product_image, featured_image, logo, cta_text, price_text, sponsor_name, author_name, click_url
1542
+ * DAAST specification version
414
1543
  */
415
- asset_type?: string;
1544
+ daast_version?: '1.0' | '1.1';
416
1545
  /**
417
- * Unique identifier for the asset within the creative
1546
+ * Expected audio duration in milliseconds (if known)
418
1547
  */
419
- asset_id?: string;
1548
+ duration_ms?: number;
420
1549
  /**
421
- * URL for media assets (images, videos, etc.)
1550
+ * Tracking events supported by this DAAST tag
422
1551
  */
423
- content_uri?: string;
1552
+ tracking_events?: ('start' | 'firstQuartile' | 'midpoint' | 'thirdQuartile' | 'complete' | 'impression' | 'pause' | 'resume' | 'skip' | 'mute' | 'unmute')[];
424
1553
  /**
425
- * Text content for text-based assets like headlines, body text, CTA text, etc.
1554
+ * Whether companion display ads are included
426
1555
  */
427
- content?: string | string[];
1556
+ companion_ads?: boolean;
428
1557
  }
429
1558
  /**
430
- * Standard error structure for task-specific errors and warnings
431
- */
432
- /**
433
- * Budget pacing strategy
434
- */
435
- export type Pacing = 'even' | 'asap' | 'front_loaded';
436
- /**
437
- * Request parameters for creating a media buy
1559
+ * Reference to promoted offerings specification
438
1560
  */
439
- export interface CreateMediaBuyRequest {
440
- /**
441
- * AdCP schema version for this request
442
- */
443
- adcp_version?: string;
1561
+ export interface PromotedOfferingsAsset {
1562
+ asset_type: 'promoted_offerings';
444
1563
  /**
445
- * Buyer's reference identifier for this media buy
1564
+ * URL of the advertiser's brand or offering (e.g., https://retailer.com)
446
1565
  */
447
- buyer_ref: string;
1566
+ url?: string;
448
1567
  /**
449
- * Array of package configurations
1568
+ * Brand colors
450
1569
  */
451
- packages: ({
1570
+ colors?: {
1571
+ primary?: string;
1572
+ secondary?: string;
1573
+ accent?: string;
452
1574
  [k: string]: unknown;
453
- } | {
454
- [k: string]: unknown;
455
- })[];
1575
+ };
456
1576
  /**
457
- * Description of advertiser and what is being promoted
1577
+ * Brand fonts
458
1578
  */
459
- promoted_offering: string;
1579
+ fonts?: string[];
460
1580
  /**
461
- * Purchase order number for tracking
1581
+ * Brand tone/voice
462
1582
  */
463
- po_number?: string;
1583
+ tone?: string;
1584
+ }
1585
+ /**
1586
+ * URL reference asset
1587
+ */
1588
+ export interface URLAsset {
1589
+ asset_type: 'url';
464
1590
  /**
465
- * Campaign start date/time in ISO 8601 format
1591
+ * URL reference
466
1592
  */
467
- start_time: string;
1593
+ url: string;
468
1594
  /**
469
- * Campaign end date/time in ISO 8601 format
1595
+ * Description of what this URL points to
470
1596
  */
471
- end_time: string;
472
- budget: Budget;
1597
+ description?: string;
473
1598
  }
474
- /**
475
- * Budget configuration for a media buy or package
476
- */
477
- export interface Budget {
1599
+ export interface PushNotificationConfig {
478
1600
  /**
479
- * Total budget amount
1601
+ * Webhook endpoint URL for task status notifications
480
1602
  */
481
- total: number;
1603
+ url: string;
482
1604
  /**
483
- * ISO 4217 currency code
1605
+ * Optional client-provided token for webhook validation. Echoed back in webhook payload to validate request authenticity.
484
1606
  */
485
- currency: string;
486
- pacing?: Pacing;
1607
+ token?: string;
1608
+ /**
1609
+ * Authentication configuration for webhook delivery (A2A-compatible)
1610
+ */
1611
+ authentication: {
1612
+ /**
1613
+ * Array of authentication schemes. Supported: ['Bearer'] for simple token auth, ['HMAC-SHA256'] for signature verification (recommended for production)
1614
+ *
1615
+ * @minItems 1
1616
+ * @maxItems 1
1617
+ */
1618
+ schemes: ['Bearer' | 'HMAC-SHA256'];
1619
+ /**
1620
+ * Credentials for authentication. For Bearer: token sent in Authorization header. For HMAC-SHA256: shared secret used to generate signature. Minimum 32 characters. Exchanged out-of-band during onboarding.
1621
+ */
1622
+ credentials: string;
1623
+ };
487
1624
  }
488
1625
  /**
489
- * Current task state - 'completed' for immediate success, 'working' for operations under 120s, 'submitted' for long-running operations, 'input-required' if approval needed
1626
+ * Response payload for create_media_buy task
490
1627
  */
491
1628
  export interface CreateMediaBuyResponse {
492
- /**
493
- * AdCP schema version used for this response
494
- */
495
- adcp_version: string;
496
- status: TaskStatus;
497
- /**
498
- * Unique identifier for tracking this async operation (present for submitted/working status)
499
- */
500
- task_id?: string;
501
1629
  /**
502
1630
  * Publisher's unique identifier for the created media buy
503
1631
  */
@@ -532,13 +1660,9 @@ export interface CreateMediaBuyResponse {
532
1660
  * Standard error structure for task-specific errors and warnings
533
1661
  */
534
1662
  /**
535
- * Creative asset for upload to library - supports both hosted assets and third-party snippets
1663
+ * VAST (Video Ad Serving Template) tag for third-party video ad serving
536
1664
  */
537
1665
  export interface SyncCreativesRequest {
538
- /**
539
- * AdCP schema version for this request
540
- */
541
- adcp_version?: string;
542
1666
  /**
543
1667
  * Array of creative assets to sync (create or update)
544
1668
  *
@@ -573,69 +1697,23 @@ export interface SyncCreativesRequest {
573
1697
  * Validation strictness. 'strict' fails entire sync on any validation error. 'lenient' processes valid creatives and reports errors.
574
1698
  */
575
1699
  validation_mode?: 'strict' | 'lenient';
1700
+ push_notification_config?: PushNotificationConfig;
576
1701
  }
577
1702
  /**
578
- * Current task state - 'completed' for immediate success, 'working' for operations under 120s, 'submitted' for long-running operations
1703
+ * Creative asset for upload to library - supports static assets, generative formats, and third-party snippets
579
1704
  */
580
- export type CreativeStatus = 'processing' | 'approved' | 'rejected' | 'pending_review';
581
1705
  /**
582
- * Response from creative sync operation with detailed results and bulk operation summary
1706
+ * Response from creative sync operation with results for each creative
583
1707
  */
584
1708
  export interface SyncCreativesResponse {
585
- /**
586
- * AdCP schema version used for this response
587
- */
588
- adcp_version: string;
589
- /**
590
- * Human-readable result message summarizing the sync operation
591
- */
592
- message: string;
593
- /**
594
- * Context ID for tracking async operations
595
- */
596
- context_id?: string;
597
- status: TaskStatus;
598
- /**
599
- * Unique identifier for tracking this async operation (present for submitted/working status)
600
- */
601
- task_id?: string;
602
1709
  /**
603
1710
  * Whether this was a dry run (no actual changes made)
604
1711
  */
605
1712
  dry_run?: boolean;
606
1713
  /**
607
- * High-level summary of sync operation results
1714
+ * Results for each creative processed
608
1715
  */
609
- summary?: {
610
- /**
611
- * Total number of creatives processed
612
- */
613
- total_processed: number;
614
- /**
615
- * Number of new creatives created
616
- */
617
- created: number;
618
- /**
619
- * Number of existing creatives updated
620
- */
621
- updated: number;
622
- /**
623
- * Number of creatives that were already up-to-date
624
- */
625
- unchanged: number;
626
- /**
627
- * Number of creatives that failed validation or processing
628
- */
629
- failed: number;
630
- /**
631
- * Number of creatives deleted/archived (when delete_missing=true)
632
- */
633
- deleted?: number;
634
- };
635
- /**
636
- * Detailed results for each creative processed
637
- */
638
- results?: {
1716
+ creatives: {
639
1717
  /**
640
1718
  * Creative ID from the request
641
1719
  */
@@ -644,17 +1722,16 @@ export interface SyncCreativesResponse {
644
1722
  * Action taken for this creative
645
1723
  */
646
1724
  action: 'created' | 'updated' | 'unchanged' | 'failed' | 'deleted';
647
- status?: CreativeStatus;
648
1725
  /**
649
1726
  * Platform-specific ID assigned to the creative
650
1727
  */
651
1728
  platform_id?: string;
652
1729
  /**
653
- * List of field names that were modified (for 'updated' action)
1730
+ * Field names that were modified (only present when action='updated')
654
1731
  */
655
1732
  changes?: string[];
656
1733
  /**
657
- * Validation or processing errors (for 'failed' action)
1734
+ * Validation or processing errors (only present when action='failed')
658
1735
  */
659
1736
  errors?: string[];
660
1737
  /**
@@ -662,99 +1739,43 @@ export interface SyncCreativesResponse {
662
1739
  */
663
1740
  warnings?: string[];
664
1741
  /**
665
- * Feedback from platform review process
666
- */
667
- review_feedback?: string;
668
- /**
669
- * Recommended creative adaptations for better performance
670
- */
671
- suggested_adaptations?: {
672
- /**
673
- * Unique identifier for this adaptation
674
- */
675
- adaptation_id: string;
676
- /**
677
- * Target format ID for the adaptation
678
- */
679
- format_id: string;
680
- /**
681
- * Suggested name for the adapted creative
682
- */
683
- name: string;
684
- /**
685
- * What this adaptation does
686
- */
687
- description: string;
688
- /**
689
- * Expected performance improvement (percentage)
690
- */
691
- estimated_performance_lift?: number;
692
- }[];
693
- }[];
694
- /**
695
- * Summary of assignment operations (when assignments were included in request)
696
- */
697
- assignments_summary?: {
698
- /**
699
- * Total number of creative-package assignment operations processed
700
- */
701
- total_assignments_processed: number;
702
- /**
703
- * Number of successful creative-package assignments
704
- */
705
- assigned: number;
706
- /**
707
- * Number of creative-package unassignments
708
- */
709
- unassigned: number;
710
- /**
711
- * Number of assignment operations that failed
712
- */
713
- failed: number;
714
- };
715
- /**
716
- * Detailed assignment results (when assignments were included in request)
717
- */
718
- assignment_results?: {
719
- /**
720
- * Creative that was assigned/unassigned
1742
+ * Preview URL for generative creatives (only present for generative formats)
721
1743
  */
722
- creative_id: string;
1744
+ preview_url?: string;
723
1745
  /**
724
- * Packages successfully assigned to this creative
1746
+ * ISO 8601 timestamp when preview link expires (only present when preview_url exists)
725
1747
  */
726
- assigned_packages?: string[];
1748
+ expires_at?: string;
727
1749
  /**
728
- * Packages successfully unassigned from this creative
1750
+ * Package IDs this creative was successfully assigned to (only present when assignments were requested)
729
1751
  */
730
- unassigned_packages?: string[];
1752
+ assigned_to?: string[];
731
1753
  /**
732
- * Packages that failed to assign/unassign
1754
+ * Assignment errors by package ID (only present when assignment failures occurred)
733
1755
  */
734
- failed_packages?: {
735
- /**
736
- * Package ID that failed
737
- */
738
- package_id: string;
1756
+ assignment_errors?: {
739
1757
  /**
740
- * Error message for the failed assignment
1758
+ * Error message for this package assignment
1759
+ *
1760
+ * This interface was referenced by `undefined`'s JSON-Schema definition
1761
+ * via the `patternProperty` "^[a-zA-Z0-9_-]+$".
741
1762
  */
742
- error: string;
743
- }[];
1763
+ [k: string]: string;
1764
+ };
744
1765
  }[];
745
1766
  }
746
1767
  /**
747
1768
  * Filter by creative approval status
748
1769
  */
1770
+ export type CreativeStatus = 'processing' | 'approved' | 'rejected' | 'pending_review';
1771
+ /**
1772
+ * Status of a creative asset
1773
+ */
749
1774
  export type CreativeStatus1 = 'processing' | 'approved' | 'rejected' | 'pending_review';
750
1775
  /**
751
- * Filter by third-party snippet type
1776
+ * Request parameters for querying creative assets from the centralized library with filtering, sorting, and pagination
752
1777
  */
753
1778
  export interface ListCreativesRequest {
754
- /**
755
- * AdCP schema version for this request
756
- */
757
- adcp_version?: string;
758
1779
  /**
759
1780
  * Filter criteria for querying creatives
760
1781
  */
@@ -818,7 +1839,6 @@ export interface ListCreativesRequest {
818
1839
  * Filter for unassigned creatives when true, assigned creatives when false
819
1840
  */
820
1841
  unassigned?: boolean;
821
- snippet_type?: SnippetType;
822
1842
  /**
823
1843
  * Filter creatives that have performance data when true
824
1844
  */
@@ -870,19 +1890,16 @@ export interface ListCreativesRequest {
870
1890
  /**
871
1891
  * Current approval status of the creative
872
1892
  */
1893
+ export type SubAsset = SubAsset1 & SubAsset2;
1894
+ export type SubAsset2 = {
1895
+ [k: string]: unknown;
1896
+ } | {
1897
+ [k: string]: unknown;
1898
+ };
1899
+ /**
1900
+ * Response from creative library query with filtered results, metadata, and optional enriched data
1901
+ */
873
1902
  export interface ListCreativesResponse {
874
- /**
875
- * AdCP schema version used for this response
876
- */
877
- adcp_version: string;
878
- /**
879
- * Human-readable result message
880
- */
881
- message: string;
882
- /**
883
- * Context ID for tracking related operations
884
- */
885
- context_id?: string;
886
1903
  /**
887
1904
  * Summary of the query that was executed
888
1905
  */
@@ -945,10 +1962,7 @@ export interface ListCreativesResponse {
945
1962
  * Human-readable creative name
946
1963
  */
947
1964
  name: string;
948
- /**
949
- * Creative format type
950
- */
951
- format: string;
1965
+ format_id: FormatID;
952
1966
  status: CreativeStatus;
953
1967
  /**
954
1968
  * When the creative was uploaded to the library
@@ -963,10 +1977,15 @@ export interface ListCreativesResponse {
963
1977
  */
964
1978
  media_url?: string;
965
1979
  /**
966
- * Third-party tag, VAST XML, or code snippet (for third-party assets)
1980
+ * Assets for this creative, keyed by asset_role
967
1981
  */
968
- snippet?: string;
969
- snippet_type?: SnippetType;
1982
+ assets?: {
1983
+ /**
1984
+ * This interface was referenced by `undefined`'s JSON-Schema definition
1985
+ * via the `patternProperty` "^[a-zA-Z0-9_-]+$".
1986
+ */
1987
+ [k: string]: ImageAsset | VideoAsset | AudioAsset | TextAsset | HTMLAsset | CSSAsset | JavaScriptAsset | VASTAsset | DAASTAsset | PromotedOfferingsAsset | URLAsset;
1988
+ };
970
1989
  /**
971
1990
  * Landing page URL for the creative
972
1991
  */
@@ -1085,21 +2104,38 @@ export interface ListCreativesResponse {
1085
2104
  archived?: number;
1086
2105
  };
1087
2106
  }
2107
+ /**
2108
+ * Format identifier specifying which format this creative conforms to
2109
+ */
2110
+ export interface SubAsset1 {
2111
+ /**
2112
+ * Type of asset. Common types: headline, body_text, thumbnail_image, product_image, featured_image, logo, cta_text, price_text, sponsor_name, author_name, click_url
2113
+ */
2114
+ asset_type?: string;
2115
+ /**
2116
+ * Unique identifier for the asset within the creative
2117
+ */
2118
+ asset_id?: string;
2119
+ /**
2120
+ * URL for media assets (images, videos, etc.)
2121
+ */
2122
+ content_uri?: string;
2123
+ /**
2124
+ * Text content for text-based assets like headlines, body text, CTA text, etc.
2125
+ */
2126
+ content?: string | string[];
2127
+ }
1088
2128
  /**
1089
2129
  * Request parameters for updating campaign and package settings
1090
2130
  */
1091
2131
  export type UpdateMediaBuyRequest = UpdateMediaBuyRequest1 & UpdateMediaBuyRequest2;
1092
2132
  /**
1093
- * Budget pacing strategy
2133
+ * Campaign start timing: 'asap' or ISO 8601 date-time
1094
2134
  */
1095
2135
  export type UpdateMediaBuyRequest2 = {
1096
2136
  [k: string]: unknown;
1097
2137
  };
1098
2138
  export interface UpdateMediaBuyRequest1 {
1099
- /**
1100
- * AdCP schema version for this request
1101
- */
1102
- adcp_version?: string;
1103
2139
  /**
1104
2140
  * Publisher's ID of the media buy to update
1105
2141
  */
@@ -1112,15 +2148,15 @@ export interface UpdateMediaBuyRequest1 {
1112
2148
  * Pause/resume the entire media buy
1113
2149
  */
1114
2150
  active?: boolean;
1115
- /**
1116
- * New start date/time in ISO 8601 format
1117
- */
1118
- start_time?: string;
2151
+ start_time?: StartTiming;
1119
2152
  /**
1120
2153
  * New end date/time in ISO 8601 format
1121
2154
  */
1122
2155
  end_time?: string;
1123
- budget?: Budget;
2156
+ /**
2157
+ * Updated total budget for this media buy. Currency is determined by the pricing_option_id selected in each package.
2158
+ */
2159
+ budget?: number;
1124
2160
  /**
1125
2161
  * Package-specific updates
1126
2162
  */
@@ -1129,23 +2165,15 @@ export interface UpdateMediaBuyRequest1 {
1129
2165
  } | {
1130
2166
  [k: string]: unknown;
1131
2167
  })[];
2168
+ push_notification_config?: PushNotificationConfig;
1132
2169
  }
1133
2170
  /**
1134
- * Budget configuration for a media buy or package
2171
+ * Optional webhook configuration for async update notifications. Publisher will send webhook when update completes if operation takes longer than immediate response time.
1135
2172
  */
1136
2173
  /**
1137
- * Current task state - 'completed' for immediate success, 'working' for operations under 120s, 'submitted' for long-running operations, 'input-required' if approval needed
2174
+ * Response payload for update_media_buy task
1138
2175
  */
1139
2176
  export interface UpdateMediaBuyResponse {
1140
- /**
1141
- * AdCP schema version used for this response
1142
- */
1143
- adcp_version: string;
1144
- status: TaskStatus;
1145
- /**
1146
- * Unique identifier for tracking this async operation (present for submitted/working status)
1147
- */
1148
- task_id?: string;
1149
2177
  /**
1150
2178
  * Publisher's identifier for the media buy
1151
2179
  */
@@ -1183,10 +2211,6 @@ export interface UpdateMediaBuyResponse {
1183
2211
  * Request parameters for retrieving comprehensive delivery metrics
1184
2212
  */
1185
2213
  export interface GetMediaBuyDeliveryRequest {
1186
- /**
1187
- * AdCP schema version for this request
1188
- */
1189
- adcp_version?: string;
1190
2214
  /**
1191
2215
  * Array of publisher media buy IDs to get delivery data for
1192
2216
  */
@@ -1208,24 +2232,44 @@ export interface GetMediaBuyDeliveryRequest {
1208
2232
  */
1209
2233
  end_date?: string;
1210
2234
  }
2235
+ /**
2236
+ * Pricing model used for this media buy
2237
+ */
2238
+ export type PricingModel = 'cpm' | 'vcpm' | 'cpc' | 'cpcv' | 'cpv' | 'cpp' | 'flat_rate';
1211
2239
  /**
1212
2240
  * Response payload for get_media_buy_delivery task
1213
2241
  */
1214
2242
  export interface GetMediaBuyDeliveryResponse {
1215
2243
  /**
1216
- * AdCP schema version used for this response
2244
+ * Type of webhook notification (only present in webhook deliveries): scheduled = regular periodic update, final = campaign completed, delayed = data not yet available, adjusted = resending period with updated data
2245
+ */
2246
+ notification_type?: 'scheduled' | 'final' | 'delayed' | 'adjusted';
2247
+ /**
2248
+ * Indicates if any media buys in this webhook have missing/delayed data (only present in webhook deliveries)
2249
+ */
2250
+ partial_data?: boolean;
2251
+ /**
2252
+ * Number of media buys with reporting_delayed or failed status (only present in webhook deliveries when partial_data is true)
2253
+ */
2254
+ unavailable_count?: number;
2255
+ /**
2256
+ * Sequential notification number (only present in webhook deliveries, starts at 1)
1217
2257
  */
1218
- adcp_version: string;
2258
+ sequence_number?: number;
1219
2259
  /**
1220
- * Date range for the report
2260
+ * ISO 8601 timestamp for next expected notification (only present in webhook deliveries when notification_type is not 'final')
2261
+ */
2262
+ next_expected_at?: string;
2263
+ /**
2264
+ * Date range for the report. All periods use UTC timezone.
1221
2265
  */
1222
2266
  reporting_period: {
1223
2267
  /**
1224
- * ISO 8601 start timestamp
2268
+ * ISO 8601 start timestamp in UTC (e.g., 2024-02-05T00:00:00Z)
1225
2269
  */
1226
2270
  start: string;
1227
2271
  /**
1228
- * ISO 8601 end timestamp
2272
+ * ISO 8601 end timestamp in UTC (e.g., 2024-02-05T23:59:59Z)
1229
2273
  */
1230
2274
  end: string;
1231
2275
  };
@@ -1234,9 +2278,9 @@ export interface GetMediaBuyDeliveryResponse {
1234
2278
  */
1235
2279
  currency: string;
1236
2280
  /**
1237
- * Combined metrics across all returned media buys
2281
+ * Combined metrics across all returned media buys. Only included in API responses (get_media_buy_delivery), not in webhook notifications.
1238
2282
  */
1239
- aggregated_totals: {
2283
+ aggregated_totals?: {
1240
2284
  /**
1241
2285
  * Total impressions delivered across all media buys
1242
2286
  */
@@ -1259,9 +2303,9 @@ export interface GetMediaBuyDeliveryResponse {
1259
2303
  media_buy_count: number;
1260
2304
  };
1261
2305
  /**
1262
- * Array of delivery data for each media buy
2306
+ * Array of delivery data for media buys. When used in webhook notifications, may contain multiple media buys aggregated by publisher. When used in get_media_buy_delivery API responses, typically contains requested media buys.
1263
2307
  */
1264
- deliveries: {
2308
+ media_buy_deliveries: {
1265
2309
  /**
1266
2310
  * Publisher's media buy identifier
1267
2311
  */
@@ -1271,42 +2315,29 @@ export interface GetMediaBuyDeliveryResponse {
1271
2315
  */
1272
2316
  buyer_ref?: string;
1273
2317
  /**
1274
- * Current media buy status
2318
+ * Current media buy status. In webhook context, reporting_delayed indicates data temporarily unavailable.
1275
2319
  */
1276
- status: 'pending' | 'active' | 'paused' | 'completed' | 'failed';
2320
+ status: 'pending' | 'active' | 'paused' | 'completed' | 'failed' | 'reporting_delayed';
1277
2321
  /**
1278
- * Aggregate metrics for this media buy across all packages
2322
+ * When delayed data is expected to be available (only present when status is reporting_delayed)
1279
2323
  */
1280
- totals: {
1281
- /**
1282
- * Total impressions delivered
1283
- */
1284
- impressions: number;
1285
- /**
1286
- * Total amount spent
1287
- */
1288
- spend: number;
1289
- /**
1290
- * Total clicks (if applicable)
1291
- */
1292
- clicks?: number;
1293
- /**
1294
- * Click-through rate (clicks/impressions)
1295
- */
1296
- ctr?: number;
1297
- /**
1298
- * Total video completions (if applicable)
1299
- */
1300
- video_completions?: number;
2324
+ expected_availability?: string;
2325
+ /**
2326
+ * Indicates this delivery contains updated data for a previously reported period. Buyer should replace previous period data with these totals.
2327
+ */
2328
+ is_adjusted?: boolean;
2329
+ pricing_model?: PricingModel;
2330
+ totals: DeliveryMetrics & {
1301
2331
  /**
1302
- * Video completion rate (completions/impressions)
2332
+ * Effective rate paid per unit based on pricing_model (e.g., actual CPM for 'cpm', actual cost per completed view for 'cpcv', actual cost per point for 'cpp')
1303
2333
  */
1304
- completion_rate?: number;
2334
+ effective_rate?: number;
2335
+ [k: string]: unknown;
1305
2336
  };
1306
2337
  /**
1307
2338
  * Metrics broken down by package
1308
2339
  */
1309
- by_package: {
2340
+ by_package: (DeliveryMetrics & {
1310
2341
  /**
1311
2342
  * Publisher's package identifier
1312
2343
  */
@@ -1315,27 +2346,12 @@ export interface GetMediaBuyDeliveryResponse {
1315
2346
  * Buyer's reference identifier for this package
1316
2347
  */
1317
2348
  buyer_ref?: string;
1318
- /**
1319
- * Package impressions
1320
- */
1321
- impressions: number;
1322
- /**
1323
- * Package spend
1324
- */
1325
- spend: number;
1326
- /**
1327
- * Package clicks
1328
- */
1329
- clicks?: number;
1330
- /**
1331
- * Package video completions
1332
- */
1333
- video_completions?: number;
1334
2349
  /**
1335
2350
  * Delivery pace (1.0 = on track, <1.0 = behind, >1.0 = ahead)
1336
2351
  */
1337
2352
  pacing_index?: number;
1338
- }[];
2353
+ [k: string]: unknown;
2354
+ })[];
1339
2355
  /**
1340
2356
  * Day-by-day delivery
1341
2357
  */
@@ -1359,6 +2375,136 @@ export interface GetMediaBuyDeliveryResponse {
1359
2375
  */
1360
2376
  errors?: Error[];
1361
2377
  }
2378
+ /**
2379
+ * Standard delivery metrics that can be reported at media buy, package, or creative level
2380
+ */
2381
+ export interface DeliveryMetrics {
2382
+ /**
2383
+ * Impressions delivered
2384
+ */
2385
+ impressions?: number;
2386
+ /**
2387
+ * Amount spent
2388
+ */
2389
+ spend?: number;
2390
+ /**
2391
+ * Total clicks
2392
+ */
2393
+ clicks?: number;
2394
+ /**
2395
+ * Click-through rate (clicks/impressions)
2396
+ */
2397
+ ctr?: number;
2398
+ /**
2399
+ * Views at threshold (for CPV)
2400
+ */
2401
+ views?: number;
2402
+ /**
2403
+ * 100% completions (for CPCV)
2404
+ */
2405
+ completed_views?: number;
2406
+ /**
2407
+ * Completion rate (completed_views/impressions)
2408
+ */
2409
+ completion_rate?: number;
2410
+ /**
2411
+ * Conversions (reserved for future CPA pricing support)
2412
+ */
2413
+ conversions?: number;
2414
+ /**
2415
+ * Leads generated (reserved for future CPL pricing support)
2416
+ */
2417
+ leads?: number;
2418
+ /**
2419
+ * Gross Rating Points delivered (for CPP)
2420
+ */
2421
+ grps?: number;
2422
+ /**
2423
+ * Unique reach - units depend on measurement provider (e.g., individuals, households, devices, cookies). See delivery_measurement.provider for methodology.
2424
+ */
2425
+ reach?: number;
2426
+ /**
2427
+ * Average frequency per individual (typically measured over campaign duration, but can vary by measurement provider)
2428
+ */
2429
+ frequency?: number;
2430
+ /**
2431
+ * Video quartile completion data
2432
+ */
2433
+ quartile_data?: {
2434
+ /**
2435
+ * 25% completion views
2436
+ */
2437
+ q1_views?: number;
2438
+ /**
2439
+ * 50% completion views
2440
+ */
2441
+ q2_views?: number;
2442
+ /**
2443
+ * 75% completion views
2444
+ */
2445
+ q3_views?: number;
2446
+ /**
2447
+ * 100% completion views
2448
+ */
2449
+ q4_views?: number;
2450
+ [k: string]: unknown;
2451
+ };
2452
+ /**
2453
+ * DOOH-specific metrics (only included for DOOH campaigns)
2454
+ */
2455
+ dooh_metrics?: {
2456
+ /**
2457
+ * Number of times ad played in rotation
2458
+ */
2459
+ loop_plays?: number;
2460
+ /**
2461
+ * Number of unique screens displaying the ad
2462
+ */
2463
+ screens_used?: number;
2464
+ /**
2465
+ * Total display time in seconds
2466
+ */
2467
+ screen_time_seconds?: number;
2468
+ /**
2469
+ * Actual share of voice delivered (0.0 to 1.0)
2470
+ */
2471
+ sov_achieved?: number;
2472
+ /**
2473
+ * Explanation of how DOOH impressions were calculated
2474
+ */
2475
+ calculation_notes?: string;
2476
+ /**
2477
+ * Per-venue performance breakdown
2478
+ */
2479
+ venue_breakdown?: {
2480
+ /**
2481
+ * Venue identifier
2482
+ */
2483
+ venue_id: string;
2484
+ /**
2485
+ * Human-readable venue name
2486
+ */
2487
+ venue_name?: string;
2488
+ /**
2489
+ * Venue type (e.g., 'airport', 'transit', 'retail', 'billboard')
2490
+ */
2491
+ venue_type?: string;
2492
+ /**
2493
+ * Impressions delivered at this venue
2494
+ */
2495
+ impressions: number;
2496
+ /**
2497
+ * Loop plays at this venue
2498
+ */
2499
+ loop_plays?: number;
2500
+ /**
2501
+ * Number of screens used at this venue
2502
+ */
2503
+ screens_used?: number;
2504
+ }[];
2505
+ };
2506
+ [k: string]: unknown;
2507
+ }
1362
2508
  /**
1363
2509
  * Standard error structure for task-specific errors and warnings
1364
2510
  */
@@ -1366,10 +2512,6 @@ export interface GetMediaBuyDeliveryResponse {
1366
2512
  * Request parameters for discovering all properties this agent is authorized to represent
1367
2513
  */
1368
2514
  export interface ListAuthorizedPropertiesRequest {
1369
- /**
1370
- * AdCP schema version for this request
1371
- */
1372
- adcp_version?: string;
1373
2515
  /**
1374
2516
  * Filter properties by specific tags (optional)
1375
2517
  */
@@ -1378,11 +2520,11 @@ export interface ListAuthorizedPropertiesRequest {
1378
2520
  /**
1379
2521
  * Type of identifier for this property
1380
2522
  */
2523
+ export type AdvertisingChannels = 'display' | 'video' | 'audio' | 'native' | 'dooh' | 'ctv' | 'podcast' | 'retail' | 'social';
2524
+ /**
2525
+ * Response payload for list_authorized_properties task
2526
+ */
1381
2527
  export interface ListAuthorizedPropertiesResponse {
1382
- /**
1383
- * AdCP schema version used for this response
1384
- */
1385
- adcp_version: string;
1386
2528
  /**
1387
2529
  * Array of all properties this agent is authorized to represent
1388
2530
  */
@@ -1402,6 +2544,26 @@ export interface ListAuthorizedPropertiesResponse {
1402
2544
  description: string;
1403
2545
  };
1404
2546
  };
2547
+ /**
2548
+ * Primary advertising channels represented in this property portfolio. Helps buying agents quickly filter relevance.
2549
+ *
2550
+ * @minItems 1
2551
+ */
2552
+ primary_channels?: [AdvertisingChannels, ...AdvertisingChannels[]];
2553
+ /**
2554
+ * Primary countries (ISO 3166-1 alpha-2 codes) where properties are concentrated. Helps buying agents quickly filter relevance.
2555
+ *
2556
+ * @minItems 1
2557
+ */
2558
+ primary_countries?: [string, ...string[]];
2559
+ /**
2560
+ * Markdown-formatted description of the property portfolio, including inventory types, audience characteristics, and special features.
2561
+ */
2562
+ portfolio_description?: string;
2563
+ /**
2564
+ * Publisher's advertising content policies, restrictions, and guidelines in natural language. May include prohibited categories, blocked advertisers, restricted tactics, brand safety requirements, or links to full policy documentation.
2565
+ */
2566
+ advertising_policies?: string;
1405
2567
  /**
1406
2568
  * Task-specific errors and warnings (e.g., property availability issues)
1407
2569
  */
@@ -1414,10 +2576,6 @@ export interface ListAuthorizedPropertiesResponse {
1414
2576
  * Request payload for provide_performance_feedback task
1415
2577
  */
1416
2578
  export interface ProvidePerformanceFeedbackRequest {
1417
- /**
1418
- * AdCP schema version for this request
1419
- */
1420
- adcp_version?: string;
1421
2579
  /**
1422
2580
  * Publisher's media buy identifier
1423
2581
  */
@@ -1460,18 +2618,10 @@ export interface ProvidePerformanceFeedbackRequest {
1460
2618
  * Response payload for provide_performance_feedback task
1461
2619
  */
1462
2620
  export interface ProvidePerformanceFeedbackResponse {
1463
- /**
1464
- * AdCP schema version used for this response
1465
- */
1466
- adcp_version: string;
1467
2621
  /**
1468
2622
  * Whether the performance feedback was successfully received
1469
2623
  */
1470
2624
  success: boolean;
1471
- /**
1472
- * Optional human-readable message about the feedback processing
1473
- */
1474
- message?: string;
1475
2625
  /**
1476
2626
  * Task-specific errors and warnings (e.g., invalid measurement period, missing campaign data)
1477
2627
  */
@@ -1484,10 +2634,6 @@ export interface ProvidePerformanceFeedbackResponse {
1484
2634
  * Request parameters for discovering signals based on description
1485
2635
  */
1486
2636
  export interface GetSignalsRequest {
1487
- /**
1488
- * AdCP schema version for this request
1489
- */
1490
- adcp_version?: string;
1491
2637
  /**
1492
2638
  * Natural language description of the desired signals
1493
2639
  */
@@ -1548,10 +2694,6 @@ export interface GetSignalsRequest {
1548
2694
  * Response payload for get_signals task
1549
2695
  */
1550
2696
  export interface GetSignalsResponse {
1551
- /**
1552
- * AdCP schema version used for this response
1553
- */
1554
- adcp_version: string;
1555
2697
  /**
1556
2698
  * Array of matching signals
1557
2699
  */
@@ -1635,10 +2777,6 @@ export interface GetSignalsResponse {
1635
2777
  * Request parameters for activating a signal on a specific platform/account
1636
2778
  */
1637
2779
  export interface ActivateSignalRequest {
1638
- /**
1639
- * AdCP schema version for this request
1640
- */
1641
- adcp_version?: string;
1642
2780
  /**
1643
2781
  * The universal identifier for the signal to activate
1644
2782
  */
@@ -1653,18 +2791,9 @@ export interface ActivateSignalRequest {
1653
2791
  account?: string;
1654
2792
  }
1655
2793
  /**
1656
- * Current activation state: 'submitted' (pending), 'working' (processing), 'completed' (deployed), 'failed', 'input-required' (needs auth), etc.
2794
+ * Response payload for activate_signal task
1657
2795
  */
1658
2796
  export interface ActivateSignalResponse {
1659
- /**
1660
- * AdCP schema version used for this response
1661
- */
1662
- adcp_version: string;
1663
- /**
1664
- * Unique identifier for tracking the activation
1665
- */
1666
- task_id: string;
1667
- status: TaskStatus;
1668
2797
  /**
1669
2798
  * The platform-specific ID to use once activated
1670
2799
  */