soundlink 1.1.1 → 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.
@@ -3,14 +3,23 @@ info:
3
3
  title: Soundlink Public API
4
4
  version: 0.0.1-draft
5
5
  description: |
6
- Read-only campaign and metrics API for Soundlink partner organizations.
6
+ Campaign listing, metrics, and write operations for Soundlink partner organizations.
7
7
 
8
8
  **Base URL:** `https://api.getsoundlink.com`
9
9
 
10
- **Authentication:** `x-api-key` header using a `sk_*` API key issued by Soundlink Engineering.
11
- ```
12
- x-api-key: sk_abc123_<token>
13
- ```
10
+ **Authentication:** send a `sk_*` API key created in the Soundlink app (Settings → Developer → API keys) using one of:
11
+
12
+ 1. **`Authorization: Bearer` (recommended)**:
13
+ ```
14
+ Authorization: Bearer sk_abc123_<token>
15
+ ```
16
+
17
+ 2. **`x-api-key` header (deprecated, retiring 2026-08-17)** — migrate to Bearer above before then:
18
+ ```
19
+ x-api-key: sk_abc123_<token>
20
+ ```
21
+
22
+ Sending both headers returns `401 mixed_credentials`.
14
23
 
15
24
  All responses are wrapped in a standard envelope:
16
25
  ```json
@@ -25,14 +34,17 @@ servers:
25
34
 
26
35
  security:
27
36
  - apiKeyAuth: []
37
+ - apiKeyBearerAuth: []
28
38
 
29
39
  tags:
30
40
  - name: System
31
41
  description: Connectivity and auth verification
32
42
  - name: Campaigns
33
- description: Campaign listing and detail
43
+ description: Campaign listing, detail, creation, and wallet management (budget, stop, tiers)
34
44
  - name: Metrics
35
45
  description: Campaign performance metrics
46
+ - name: Videos
47
+ description: Partner video library import for Full Control campaigns
36
48
 
37
49
  paths:
38
50
  /v1/ping:
@@ -46,6 +58,7 @@ paths:
46
58
  tags: [System]
47
59
  security:
48
60
  - apiKeyAuth: []
61
+ - apiKeyBearerAuth: []
49
62
  responses:
50
63
  '200':
51
64
  description: Authenticated and reachable
@@ -73,6 +86,46 @@ paths:
73
86
  '429': { $ref: '#/components/responses/RateLimited' }
74
87
  '500': { $ref: '#/components/responses/InternalError' }
75
88
 
89
+ /v1/strategies:
90
+ get:
91
+ operationId: listStrategies
92
+ summary: List campaign strategy types
93
+ description: |
94
+ Returns the static catalog of `strategyType` values accepted by
95
+ `POST /v1/campaigns`. Built-in strategies apply platform default
96
+ tiering internally; only `custom` allows `tierTargeting` on create.
97
+
98
+ Requires the `campaigns:read` scope.
99
+ tags: [Campaigns]
100
+ security:
101
+ - apiKeyAuth: []
102
+ - apiKeyBearerAuth: []
103
+ x-required-scope: campaigns:read
104
+ responses:
105
+ '200':
106
+ description: Strategy catalog
107
+ content:
108
+ application/json:
109
+ schema:
110
+ $ref: '#/components/schemas/StrategiesCatalogResponse'
111
+ example:
112
+ data:
113
+ strategies:
114
+ - strategyType: maximum_growth
115
+ tierTargetingAllowed: false
116
+ - strategyType: market_discovery
117
+ tierTargetingAllowed: false
118
+ - strategyType: revenue_maximization
119
+ tierTargetingAllowed: false
120
+ - strategyType: custom
121
+ tierTargetingAllowed: true
122
+ meta:
123
+ requestId: 550e8400-e29b-41d4-a716-446655440000
124
+ '401': { $ref: '#/components/responses/Unauthorized' }
125
+ '403': { $ref: '#/components/responses/Forbidden' }
126
+ '429': { $ref: '#/components/responses/RateLimited' }
127
+ '500': { $ref: '#/components/responses/InternalError' }
128
+
76
129
  /v1/campaigns:
77
130
  get:
78
131
  operationId: listCampaigns
@@ -83,6 +136,7 @@ paths:
83
136
  tags: [Campaigns]
84
137
  security:
85
138
  - apiKeyAuth: []
139
+ - apiKeyBearerAuth: []
86
140
  parameters:
87
141
  - $ref: '#/components/parameters/page'
88
142
  - $ref: '#/components/parameters/pageSize100'
@@ -90,7 +144,7 @@ paths:
90
144
  in: query
91
145
  schema:
92
146
  type: string
93
- enum: [createdAt, status]
147
+ enum: [createdAt]
94
148
  default: createdAt
95
149
  - $ref: '#/components/parameters/sortOrder'
96
150
  responses:
@@ -103,7 +157,7 @@ paths:
103
157
  example:
104
158
  data:
105
159
  items:
106
- - campaignId: camp_abc123
160
+ - campaignId: f1e28d31-c358-4284-9bef-00a2334625fd
107
161
  organizationId: org_xyz
108
162
  status: active
109
163
  socialPlatform: meta
@@ -124,6 +178,107 @@ paths:
124
178
  '429': { $ref: '#/components/responses/RateLimited' }
125
179
  '500': { $ref: '#/components/responses/InternalError' }
126
180
 
181
+ post:
182
+ operationId: createCampaign
183
+ summary: Create a wallet-funded campaign
184
+ description: |
185
+ Creates a campaign funded from the organization's wallet balance.
186
+ Requires the `campaigns:write` scope, and the organization must be
187
+ enabled for wallet billing.
188
+
189
+ This route has a financial side effect (the campaign's budget is
190
+ deducted from the wallet balance), so the `Idempotency-Key` header
191
+ is **required** on every request. See the header description below
192
+ for retry semantics.
193
+ tags: [Campaigns]
194
+ security:
195
+ - apiKeyAuth: []
196
+ - apiKeyBearerAuth: []
197
+ x-required-scope: campaigns:write
198
+ parameters:
199
+ - $ref: '#/components/parameters/idempotencyKey'
200
+ requestBody:
201
+ required: true
202
+ content:
203
+ application/json:
204
+ schema:
205
+ $ref: '#/components/schemas/CreateCampaignRequest'
206
+ examples:
207
+ trackCampaign:
208
+ summary: Campaign promoting a single track
209
+ value:
210
+ spotifyUrl: 'https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl'
211
+ dailyBudget: 25
212
+ durationDays: 14
213
+ genre: Pop
214
+ campaignName: 'My Summer Single'
215
+ strategyType: maximum_growth
216
+ creativeDirection:
217
+ type: do_it_for_me
218
+ trackOptions:
219
+ artistIdFollow: 'artist-uuid'
220
+ clonedFromCampaignId: '3f2504e0-4f89-41d3-9a0c-0305e82c3301'
221
+ playlistCampaign:
222
+ summary: Campaign promoting a playlist
223
+ value:
224
+ spotifyUrl: 'https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M'
225
+ dailyBudget: 25
226
+ durationDays: 14
227
+ genre: Pop
228
+ campaignName: 'Summer Vibes Playlist'
229
+ strategyType: maximum_growth
230
+ creativeDirection:
231
+ type: do_it_for_me
232
+ fullControlCampaign:
233
+ summary: Campaign with partner-supplied creative (full control)
234
+ value:
235
+ spotifyUrl: 'https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl'
236
+ dailyBudget: 40
237
+ durationDays: 21
238
+ genre: Hip-Hop/R&B
239
+ campaignName: 'My Summer Single'
240
+ strategyType: custom
241
+ creativeDirection:
242
+ type: full_control
243
+ selectedCreatives:
244
+ - videoId: '8f14e45f-ceea-467e-9de5-e7d0b4d4e6bb'
245
+ - videoId: '3c9b1a2d-1a2f-4a1e-9c3b-0a1b2c3d4e5f'
246
+ tierTargeting:
247
+ customTierIds: [123, 456]
248
+ customTiers:
249
+ - name: 'US/UK'
250
+ countries: ['US', 'GB']
251
+ language: en
252
+ percentBudget: 60
253
+ - name: LatAm
254
+ countries: ['MX', 'AR']
255
+ language: es
256
+ percentBudget: 40
257
+ trackOptions:
258
+ artistIdFollow: 'artist-uuid'
259
+ responses:
260
+ '201':
261
+ description: Campaign created
262
+ content:
263
+ application/json:
264
+ schema:
265
+ $ref: '#/components/schemas/CreateCampaignResponse'
266
+ example:
267
+ data:
268
+ campaignId: campaign-uuid
269
+ status: creating
270
+ meta:
271
+ requestId: 550e8400-e29b-41d4-a716-446655440000
272
+ '400': { $ref: '#/components/responses/CreateCampaignBadRequest' }
273
+ '401': { $ref: '#/components/responses/Unauthorized' }
274
+ '402': { $ref: '#/components/responses/InsufficientCredit' }
275
+ '403': { $ref: '#/components/responses/CreateCampaignForbidden' }
276
+ '404': { $ref: '#/components/responses/NotFound' }
277
+ '409': { $ref: '#/components/responses/IdempotencyKeyConflict' }
278
+ '422': { $ref: '#/components/responses/CreateCampaignUnprocessable' }
279
+ '429': { $ref: '#/components/responses/RateLimited' }
280
+ '500': { $ref: '#/components/responses/InternalError' }
281
+
127
282
  /v1/campaigns/{campaignId}:
128
283
  get:
129
284
  operationId: getCampaign
@@ -132,6 +287,7 @@ paths:
132
287
  tags: [Campaigns]
133
288
  security:
134
289
  - apiKeyAuth: []
290
+ - apiKeyBearerAuth: []
135
291
  parameters:
136
292
  - $ref: '#/components/parameters/campaignId'
137
293
  responses:
@@ -143,7 +299,7 @@ paths:
143
299
  $ref: '#/components/schemas/CampaignDetailResponse'
144
300
  example:
145
301
  data:
146
- campaignId: camp_abc123
302
+ campaignId: f1e28d31-c358-4284-9bef-00a2334625fd
147
303
  organizationId: org_xyz
148
304
  status: active
149
305
  socialPlatform: meta
@@ -161,6 +317,297 @@ paths:
161
317
  '429': { $ref: '#/components/responses/RateLimited' }
162
318
  '500': { $ref: '#/components/responses/InternalError' }
163
319
 
320
+ /v1/campaigns/{campaignId}/stop:
321
+ post:
322
+ operationId: stopCampaign
323
+ summary: Stop a wallet campaign and refund unspent budget
324
+ description: |
325
+ Stops delivery for a wallet-funded campaign and refunds unspent budget
326
+ to the organization wallet. Requires the `campaigns:write` scope.
327
+
328
+ **Wallet campaigns only** (`generation: 3`).
329
+
330
+ Stopping is idempotent at the campaign level: a second stop on an
331
+ already-stopped campaign succeeds without double-refunding. The
332
+ `Idempotency-Key` header is also **required** so retries of the same
333
+ request replay the original response without repeating side effects.
334
+ tags: [Campaigns]
335
+ x-required-scope: campaigns:write
336
+ security:
337
+ - apiKeyAuth: []
338
+ - apiKeyBearerAuth: []
339
+ parameters:
340
+ - $ref: '#/components/parameters/campaignId'
341
+ - $ref: '#/components/parameters/idempotencyKey'
342
+ responses:
343
+ '200':
344
+ description: Campaign stopped (or already stopped)
345
+ content:
346
+ application/json:
347
+ schema:
348
+ $ref: '#/components/schemas/StopCampaignResponse'
349
+ example:
350
+ data:
351
+ campaignId: campaign-uuid
352
+ status: stopped
353
+ meta:
354
+ requestId: 550e8400-e29b-41d4-a716-446655440000
355
+ '400': { $ref: '#/components/responses/BadRequest' }
356
+ '401': { $ref: '#/components/responses/Unauthorized' }
357
+ '403': { $ref: '#/components/responses/Forbidden' }
358
+ '404': { $ref: '#/components/responses/NotFound' }
359
+ '409': { $ref: '#/components/responses/IdempotencyKeyConflict' }
360
+ '429': { $ref: '#/components/responses/RateLimited' }
361
+ '500': { $ref: '#/components/responses/InternalError' }
362
+
363
+ /v1/campaigns/{campaignId}/budget/increase:
364
+ post:
365
+ operationId: increaseCampaignBudget
366
+ summary: Increase wallet campaign budget
367
+ description: |
368
+ Raises budget for a wallet-funded campaign. Requires the
369
+ `campaigns:write` scope and an `Idempotency-Key` header.
370
+
371
+ **Wallet campaigns only** (`generation: 3`).
372
+
373
+ **Modes** (default `current_and_renewals`):
374
+ - `current_cycle` — applies to the current billing cycle only
375
+ - `next_renewal` — adjusts the next-cycle daily budget (may use
376
+ `amount: 0` with `targetDailyBudget` to set an absolute next-cycle target)
377
+ - `current_and_renewals` — applies to the current cycle and future renewals
378
+
379
+ Debits the organization wallet when the current cycle is increased.
380
+ tags: [Campaigns]
381
+ x-required-scope: campaigns:write
382
+ security:
383
+ - apiKeyAuth: []
384
+ - apiKeyBearerAuth: []
385
+ parameters:
386
+ - $ref: '#/components/parameters/campaignId'
387
+ - $ref: '#/components/parameters/idempotencyKey'
388
+ requestBody:
389
+ required: true
390
+ content:
391
+ application/json:
392
+ schema:
393
+ $ref: '#/components/schemas/IncreaseCampaignBudgetRequest'
394
+ examples:
395
+ currentAndRenewals:
396
+ summary: Top up current cycle and renewals
397
+ value:
398
+ amount: 70
399
+ mode: current_and_renewals
400
+ nextRenewalTarget:
401
+ summary: Set next-cycle daily budget without current-cycle debit
402
+ value:
403
+ amount: 0
404
+ mode: next_renewal
405
+ targetDailyBudget: 40
406
+ responses:
407
+ '200':
408
+ description: Budget increase accepted
409
+ content:
410
+ application/json:
411
+ schema:
412
+ $ref: '#/components/schemas/IncreaseCampaignBudgetResponse'
413
+ example:
414
+ data:
415
+ campaignId: campaign-uuid
416
+ mode: current_and_renewals
417
+ amount: 70
418
+ walletBalance: 430
419
+ walletNextCycleDailyBudget: 30
420
+ meta:
421
+ requestId: 550e8400-e29b-41d4-a716-446655440000
422
+ '400': { $ref: '#/components/responses/BadRequest' }
423
+ '401': { $ref: '#/components/responses/Unauthorized' }
424
+ '402': { $ref: '#/components/responses/InsufficientCredit' }
425
+ '403': { $ref: '#/components/responses/Forbidden' }
426
+ '404': { $ref: '#/components/responses/NotFound' }
427
+ '409': { $ref: '#/components/responses/IdempotencyKeyConflict' }
428
+ '429': { $ref: '#/components/responses/RateLimited' }
429
+ '500': { $ref: '#/components/responses/InternalError' }
430
+
431
+ /v1/campaigns/{campaignId}/budget/decrease:
432
+ post:
433
+ operationId: decreaseCampaignBudget
434
+ summary: Decrease wallet campaign daily budget
435
+ description: |
436
+ Lowers the daily budget for a wallet-funded campaign to
437
+ `targetDailyBudget`. Requires the `campaigns:write` scope and an
438
+ `Idempotency-Key` header.
439
+
440
+ **Wallet campaigns only** (`generation: 3`).
441
+
442
+ **Modes** (default `current_and_renewals`):
443
+ - `current_cycle` — lowers current-cycle spend only
444
+ - `current_and_renewals` — also sets the next-cycle daily budget
445
+
446
+ `next_renewal` is not supported for decreases. Refund of unused budget
447
+ is applied asynchronously after acceptance (`accepted: true`).
448
+
449
+ Domain rules (also returned as `invalid_request` when violated):
450
+ - `targetDailyBudget` must be at least `$10`/day and lower than the
451
+ current daily budget
452
+ - more than 3 days must remain in the current cycle
453
+ tags: [Campaigns]
454
+ x-required-scope: campaigns:write
455
+ security:
456
+ - apiKeyAuth: []
457
+ - apiKeyBearerAuth: []
458
+ parameters:
459
+ - $ref: '#/components/parameters/campaignId'
460
+ - $ref: '#/components/parameters/idempotencyKey'
461
+ requestBody:
462
+ required: true
463
+ content:
464
+ application/json:
465
+ schema:
466
+ $ref: '#/components/schemas/DecreaseCampaignBudgetRequest'
467
+ example:
468
+ targetDailyBudget: 60
469
+ mode: current_and_renewals
470
+ responses:
471
+ '200':
472
+ description: Budget decrease accepted (refund may complete asynchronously)
473
+ content:
474
+ application/json:
475
+ schema:
476
+ $ref: '#/components/schemas/DecreaseCampaignBudgetResponse'
477
+ example:
478
+ data:
479
+ campaignId: campaign-uuid
480
+ mode: current_and_renewals
481
+ targetDailyBudget: 60
482
+ accepted: true
483
+ walletNextCycleDailyBudget: 60
484
+ meta:
485
+ requestId: 550e8400-e29b-41d4-a716-446655440000
486
+ '400': { $ref: '#/components/responses/BadRequest' }
487
+ '401': { $ref: '#/components/responses/Unauthorized' }
488
+ '403': { $ref: '#/components/responses/Forbidden' }
489
+ '404': { $ref: '#/components/responses/NotFound' }
490
+ '409': { $ref: '#/components/responses/IdempotencyKeyConflict' }
491
+ '429': { $ref: '#/components/responses/RateLimited' }
492
+ '500': { $ref: '#/components/responses/InternalError' }
493
+
494
+ /v1/campaigns/{campaignId}/tiers:
495
+ get:
496
+ operationId: getCampaignTiers
497
+ summary: Get campaign tier allocation
498
+ description: |
499
+ Returns the current geographic tier allocation for a wallet campaign:
500
+ which tiers are enabled, their budget share, and when tiers were last
501
+ updated (`lastUpdate`). Use this before `PATCH` to build a valid request.
502
+
503
+ **Wallet campaigns only** (`generation: 3`).
504
+ tags: [Campaigns]
505
+ x-required-scope: campaigns:read
506
+ security:
507
+ - apiKeyAuth: []
508
+ - apiKeyBearerAuth: []
509
+ parameters:
510
+ - $ref: '#/components/parameters/campaignId'
511
+ responses:
512
+ '200':
513
+ description: Campaign tier allocation
514
+ content:
515
+ application/json:
516
+ schema:
517
+ $ref: '#/components/schemas/CampaignTiersResponse'
518
+ example:
519
+ data:
520
+ lastUpdate: '2026-01-01T00:00:00Z'
521
+ tiers:
522
+ - tierId: 1
523
+ tierName: US
524
+ isEnabled: true
525
+ allocationPercent: 60
526
+ - tierId: 2
527
+ tierName: UK
528
+ isEnabled: false
529
+ allocationPercent: 40
530
+ meta:
531
+ requestId: 550e8400-e29b-41d4-a716-446655440000
532
+ '400': { $ref: '#/components/responses/BadRequest' }
533
+ '401': { $ref: '#/components/responses/Unauthorized' }
534
+ '403': { $ref: '#/components/responses/Forbidden' }
535
+ '404': { $ref: '#/components/responses/NotFound' }
536
+ '429': { $ref: '#/components/responses/RateLimited' }
537
+ '500': { $ref: '#/components/responses/InternalError' }
538
+
539
+ patch:
540
+ operationId: updateCampaignTiers
541
+ summary: Update campaign tier allocation
542
+ description: |
543
+ Enable or disable geographic tiers and optionally reallocate budget
544
+ shares for a wallet campaign.
545
+
546
+ **Wallet campaigns only** (`generation: 3`).
547
+
548
+ **Request rules:**
549
+ - Include **all** tiers on the campaign in `items`
550
+ - `newAllocationPercent` values must sum to **100**
551
+ - At least one tier must have `isEnabled: true`
552
+
553
+ **Cooldown:** after a successful update, further tier changes are
554
+ blocked for **72 hours** (`409 tier_update_cooldown`).
555
+ tags: [Campaigns]
556
+ x-required-scope: campaigns:write
557
+ security:
558
+ - apiKeyAuth: []
559
+ - apiKeyBearerAuth: []
560
+ parameters:
561
+ - $ref: '#/components/parameters/campaignId'
562
+ requestBody:
563
+ required: true
564
+ content:
565
+ application/json:
566
+ schema:
567
+ $ref: '#/components/schemas/UpdateCampaignTiersRequest'
568
+ example:
569
+ items:
570
+ - targetingTierId: 1
571
+ isEnabled: true
572
+ newAllocationPercent: 70
573
+ - targetingTierId: 2
574
+ isEnabled: true
575
+ newAllocationPercent: 30
576
+ responses:
577
+ '200':
578
+ description: Updated tier allocation
579
+ content:
580
+ application/json:
581
+ schema:
582
+ $ref: '#/components/schemas/CampaignTiersResponse'
583
+ '400':
584
+ description: Invalid request or tier status
585
+ content:
586
+ application/json:
587
+ schema:
588
+ $ref: '#/components/schemas/ErrorResponse'
589
+ examples:
590
+ invalid_request:
591
+ value:
592
+ error:
593
+ code: invalid_request
594
+ message: 'Tier updates are only supported for wallet campaigns.'
595
+ meta:
596
+ requestId: 550e8400-e29b-41d4-a716-446655440000
597
+ invalid_tier_status:
598
+ value:
599
+ error:
600
+ code: invalid_tier_status
601
+ message: 'At least one tier must be enabled'
602
+ meta:
603
+ requestId: 550e8400-e29b-41d4-a716-446655440000
604
+ '401': { $ref: '#/components/responses/Unauthorized' }
605
+ '403': { $ref: '#/components/responses/Forbidden' }
606
+ '404': { $ref: '#/components/responses/NotFound' }
607
+ '409': { $ref: '#/components/responses/TierUpdateCooldown' }
608
+ '429': { $ref: '#/components/responses/RateLimited' }
609
+ '500': { $ref: '#/components/responses/InternalError' }
610
+
164
611
  /v1/campaigns/{campaignId}/metrics/overview:
165
612
  get:
166
613
  operationId: getCampaignMetricsOverview
@@ -174,6 +621,7 @@ paths:
174
621
  tags: [Metrics]
175
622
  security:
176
623
  - apiKeyAuth: []
624
+ - apiKeyBearerAuth: []
177
625
  parameters:
178
626
  - $ref: '#/components/parameters/campaignId'
179
627
  - $ref: '#/components/parameters/startDate'
@@ -232,6 +680,7 @@ paths:
232
680
  tags: [Metrics]
233
681
  security:
234
682
  - apiKeyAuth: []
683
+ - apiKeyBearerAuth: []
235
684
  parameters:
236
685
  - $ref: '#/components/parameters/campaignId'
237
686
  - $ref: '#/components/parameters/startDate'
@@ -266,7 +715,7 @@ paths:
266
715
  campaign_name: Sleep Playlist
267
716
  campaign_target_type: track
268
717
  campaign_target_isrc: DEXW62500259
269
- campaign_target_spotify_track_id: 6habFhsOp2NvndAvgiJ01P
718
+ campaign_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
270
719
  campaign_target_playlist_id: null
271
720
  country_code: US
272
721
  impressions: 4821
@@ -322,9 +771,10 @@ paths:
322
771
  Accept: application/x-ndjson
323
772
  ```
324
773
 
325
- **Date range:** defaults to the full campaign active period. Override
326
- with `startDate` / `endDate`. **Responses are capped at 90 days** —
327
- use `startDate` / `endDate` to slice through longer windows manually.
774
+ **Date range:** if you omit both dates, defaults to the last **90 days**
775
+ ending today. Override with `startDate` / `endDate`. **Responses are
776
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
777
+ Page longer histories in 90-day slices.
328
778
 
329
779
  **Mutability:** rows for a given `report_date` can be revised for up
330
780
  to 7 days after the date closes due to delayed events from Meta and
@@ -333,6 +783,7 @@ paths:
333
783
  tags: [Metrics]
334
784
  security:
335
785
  - apiKeyAuth: []
786
+ - apiKeyBearerAuth: []
336
787
  parameters:
337
788
  - $ref: '#/components/parameters/campaignId'
338
789
  - $ref: '#/components/parameters/startDate'
@@ -358,113 +809,8 @@ paths:
358
809
  schema:
359
810
  $ref: '#/components/schemas/BreakdownRow'
360
811
  example: |
361
- {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-04-01","report_date_timezone":"UTC","exported_at":"2026-05-20T03:00:00Z","campaign_id":"f1e28d31-c358-4284-9bef-00a2334625fd","campaign_name":"Sleep Playlist","campaign_target_type":"track","campaign_target_isrc":"DEXW62500259","campaign_target_spotify_track_id":"6habFhsOp2NvndAvgiJ01P","campaign_target_playlist_id":null,"country_code":"US","impressions":4821,"ad_clicks":112,"link_clicks":89,"streams":203,"listeners":145,"followers":12,"streams_per_listener":1.4,"spend_media":42.50,"spend_total":53.13,"fees":10.63,"currency":"USD","currency_account":"USD","cpl":0.293,"cpf":3.542,"cpc_linkclick":0.478,"ctr_linkclick":0.0185,"ctr_adclick":0.0232,"cost_per_result":3.542,"result_type":"follow"}
362
- {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-04-01","report_date_timezone":"UTC","exported_at":"2026-05-20T03:00:00Z","campaign_id":"f1e28d31-c358-4284-9bef-00a2334625fd","campaign_name":"Sleep Playlist","campaign_target_type":"track","campaign_target_isrc":"DEXW62500259","campaign_target_spotify_track_id":"6habFhsOp2NvndAvgiJ01P","campaign_target_playlist_id":null,"country_code":"DE","impressions":2103,"ad_clicks":48,"link_clicks":31,"streams":87,"listeners":61,"followers":4,"streams_per_listener":1.43,"spend_media":18.20,"spend_total":22.75,"fees":4.55,"currency":"USD","currency_account":"USD","cpl":0.298,"cpf":4.55,"cpc_linkclick":0.587,"ctr_linkclick":0.0148,"ctr_adclick":0.0228,"cost_per_result":4.55,"result_type":"follow"}
363
- '400': { $ref: '#/components/responses/BadRequest' }
364
- '401': { $ref: '#/components/responses/Unauthorized' }
365
- '403': { $ref: '#/components/responses/Forbidden' }
366
- '404': { $ref: '#/components/responses/NotFound' }
367
- '429': { $ref: '#/components/responses/RateLimited' }
368
- '500': { $ref: '#/components/responses/InternalError' }
369
-
370
- /v1/campaigns/{campaignId}/metrics/engagement:
371
- get:
372
- operationId: getCampaignEngagement
373
- summary: Campaign engagement breakdown
374
- description: |
375
- Per-day, per-track engagement metrics for a campaign. One row per
376
- `(report_date, campaign_id, engagement_context, engaged_spotify_track_id)`.
377
-
378
- **Key difference from `/metrics/breakdown`:** this endpoint covers the
379
- full engagement window — including post-campaign streaming activity —
380
- not just dates when the campaign was actively running. Use this for
381
- catalog spillover analysis and long-tail retention.
382
-
383
- **`engagement_context` values:**
384
- - `catalog` — same-artist spillover (and direct promoted-track plays)
385
- on track campaigns. `engaged_track_isrc` may equal
386
- `campaign_target_isrc` (the promoted track itself) or differ
387
- (spillover tracks).
388
- - `playlist` — per-track performance inside the promoted playlist on
389
- playlist campaigns. One row per track in the playlist per day.
390
-
391
- **`listeners` is deduplicated within each row only.** Do not sum
392
- `listeners` across days to get a campaign total — the same listener
393
- can appear on multiple `report_date` rows.
394
-
395
- Row schema: `campaign_engagement_daily` v1.0. Rows are idempotent on
396
- the primary key; re-ingesting is safe.
397
-
398
- **Mutability window:** rows for a given `report_date` can be revised
399
- for up to 7 days after the date closes due to delayed Spotify
400
- playback events.
401
- tags: [Metrics]
402
- security:
403
- - apiKeyAuth: []
404
- parameters:
405
- - $ref: '#/components/parameters/campaignId'
406
- - $ref: '#/components/parameters/startDate'
407
- - $ref: '#/components/parameters/endDate'
408
- - name: engagementContext
409
- in: query
410
- schema:
411
- type: string
412
- enum: [catalog, playlist]
413
- description: |
414
- Filter to a single engagement context. Omit to return both.
415
- - $ref: '#/components/parameters/page'
416
- - $ref: '#/components/parameters/pageSize500'
417
- - name: sortBy
418
- in: query
419
- schema:
420
- type: string
421
- enum: [report_date, streams, listeners]
422
- default: report_date
423
- - $ref: '#/components/parameters/sortOrder'
424
- responses:
425
- '200':
426
- description: Paginated per-day per-track engagement rows (`campaign_engagement_daily` schema)
427
- content:
428
- application/json:
429
- schema:
430
- $ref: '#/components/schemas/EngagementBreakdownResponse'
431
- example:
432
- data:
433
- schemaVersion: '1.0'
434
- items:
435
- - provider: soundlink
436
- account_id: a7ac3173-2f71-4e79-921f-d15d7112cc9a
437
- schema_version: '1.0'
438
- report_date: '2026-04-08'
439
- report_date_timezone: UTC
440
- exported_at: '2026-05-22T10:12:11Z'
441
- campaign_id: 8ccd7b88-2591-4b94-848f-f142f5c6bba1
442
- campaign_name: 9 To 5
443
- campaign_target_type: track
444
- campaign_target_isrc: DEXW62500272
445
- campaign_target_spotify_track_id: 2RkZ5WPkKyBf0u8vN3dNgb
446
- campaign_target_playlist_id: null
447
- status: ended
448
- engagement_context: catalog
449
- country_code: US
450
- engaged_track_isrc: DEXW62500001
451
- engaged_spotify_track_id: 4cOdK2wGLETKBW3PvgPWqT
452
- engaged_track_name: Till The Sunrise
453
- playlist_position: null
454
- new_listeners: 42
455
- returning_listeners: 18
456
- listeners: 60
457
- new_listener_streams: 58
458
- returning_listener_streams: 31
459
- streams: 89
460
- spl: 1.48
461
- pagination:
462
- page: 1
463
- pageSize: 50
464
- totalCount: 210
465
- totalPages: 5
466
- meta:
467
- requestId: 550e8400-e29b-41d4-a716-446655440000
812
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-04-01","report_date_timezone":"UTC","exported_at":"2026-05-20T03:00:00Z","campaign_id":"f1e28d31-c358-4284-9bef-00a2334625fd","campaign_name":"Sleep Playlist","campaign_target_type":"track","campaign_target_isrc":"DEXW62500259","campaign_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","campaign_target_playlist_id":null,"country_code":"US","impressions":4821,"ad_clicks":112,"link_clicks":89,"streams":203,"listeners":145,"followers":12,"streams_per_listener":1.4,"spend_media":42.50,"spend_total":53.13,"fees":10.63,"currency":"USD","currency_account":"USD","cpl":0.293,"cpf":3.542,"cpc_linkclick":0.478,"ctr_linkclick":0.0185,"ctr_adclick":0.0232,"cost_per_result":3.542,"result_type":"follow"}
813
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-04-01","report_date_timezone":"UTC","exported_at":"2026-05-20T03:00:00Z","campaign_id":"f1e28d31-c358-4284-9bef-00a2334625fd","campaign_name":"Sleep Playlist","campaign_target_type":"track","campaign_target_isrc":"DEXW62500259","campaign_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","campaign_target_playlist_id":null,"country_code":"DE","impressions":2103,"ad_clicks":48,"link_clicks":31,"streams":87,"listeners":61,"followers":4,"streams_per_listener":1.43,"spend_media":18.20,"spend_total":22.75,"fees":4.55,"currency":"USD","currency_account":"USD","cpl":0.298,"cpf":4.55,"cpc_linkclick":0.587,"ctr_linkclick":0.0148,"ctr_adclick":0.0228,"cost_per_result":4.55,"result_type":"follow"}
468
814
  '400': { $ref: '#/components/responses/BadRequest' }
469
815
  '401': { $ref: '#/components/responses/Unauthorized' }
470
816
  '403': { $ref: '#/components/responses/Forbidden' }
@@ -479,9 +825,7 @@ paths:
479
825
  description: |
480
826
  Streams the full engagement dataset for a campaign as
481
827
  **newline-delimited JSON (JSONL)**. Every line is a complete, valid
482
- JSON object conforming to the `campaign_engagement_daily` v1.0 schema
483
- — identical to the rows returned by `GET /metrics/engagement` but
484
- without pagination or an envelope wrapper.
828
+ JSON object conforming to the `campaign_engagement_daily` v1.0 schema.
485
829
 
486
830
  Designed for data pipeline consumers: load directly into BigQuery,
487
831
  Snowflake, or any JSONL-aware ingest tool without cursor logic.
@@ -498,18 +842,18 @@ paths:
498
842
  {"provider":"soundlink","report_date":"2026-04-02","streams":104,...}
499
843
  ```
500
844
 
501
- **Date range:** defaults to the full campaign lifetime plus 30 days
502
- post-end to capture tail engagement. Override with `startDate` /
503
- `endDate`. **Responses are capped at 90 days** — if the requested
504
- range exceeds 90 days, the most recent 90 days are returned. Use
505
- `startDate` / `endDate` to page through longer windows in 90-day
506
- slices.
845
+ **Date range:** if you omit both dates, defaults to the last **90 days**
846
+ ending today. Override with `startDate` / `endDate`. **Responses are
847
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
848
+ Page longer histories in 90-day slices.
507
849
 
508
- **Mutability:** same 7-day revision window as the paginated endpoint.
509
- Re-fetching and re-ingesting on the primary key is safe (idempotent).
850
+ **Mutability:** rows for a given `report_date` can be revised for up to
851
+ 7 days after the date closes. Re-fetching and re-ingesting on the
852
+ primary key is safe (idempotent).
510
853
  tags: [Metrics]
511
854
  security:
512
855
  - apiKeyAuth: []
856
+ - apiKeyBearerAuth: []
513
857
  parameters:
514
858
  - $ref: '#/components/parameters/campaignId'
515
859
  - $ref: '#/components/parameters/startDate'
@@ -542,7 +886,7 @@ paths:
542
886
  $ref: '#/components/schemas/EngagementRow'
543
887
  example: |
544
888
  {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112cc9a","schema_version":"1.0","report_date":"2026-04-08","report_date_timezone":"UTC","exported_at":"2026-05-22T10:12:11Z","campaign_id":"8ccd7b88-2591-4b94-848f-f142f5c6bba1","campaign_name":"9 To 5","campaign_target_type":"track","campaign_target_isrc":"DEXW62500272","campaign_target_spotify_track_id":"2RkZ5WPkKyBf0u8vN3dNgb","campaign_target_playlist_id":null,"status":"ended","engagement_context":"catalog","country_code":"US","engaged_track_isrc":"DEXW62500001","engaged_spotify_track_id":"4cOdK2wGLETKBW3PvgPWqT","engaged_track_name":"Till The Sunrise","playlist_position":null,"new_listeners":42,"returning_listeners":18,"listeners":60,"new_listener_streams":58,"returning_listener_streams":31,"streams":89,"spl":1.48}
545
- {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112cc9a","schema_version":"1.0","report_date":"2026-04-08","report_date_timezone":"UTC","exported_at":"2026-05-22T10:12:11Z","campaign_id":"8ccd7b88-2591-4b94-848f-f142f5c6bba1","campaign_name":"9 To 5","campaign_target_type":"track","campaign_target_isrc":"DEXW62500272","campaign_target_spotify_track_id":"2RkZ5WPkKyBf0u8vN3dNgb","campaign_target_playlist_id":null,"status":"ended","engagement_context":"catalog","country_code":"DE","engaged_track_isrc":"DEXW62500001","engaged_spotify_track_id":"4cOdK2wGLETKBW3PvgPWqT","engaged_track_name":"Till The Sunrise","playlist_position":14,"new_listeners":19,"returning_listeners":7,"listeners":26,"new_listener_streams":24,"returning_listener_streams":11,"streams":35,"spl":1.35}
889
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-04-08","report_date_timezone":"UTC","exported_at":"2026-05-22T10:12:11Z","campaign_id":"f1e28d31-c358-4284-9bef-00a2334625fd","campaign_name":"Sleep Playlist","campaign_target_type":"playlist","campaign_target_isrc":null,"campaign_target_spotify_track_id":null,"campaign_target_playlist_id":"37i9dQZF1DXcBWIGoYBM5M","status":"active","engagement_context":"playlist","country_code":"DE","engaged_track_isrc":"DEXW62500001","engaged_spotify_track_id":"4cOdK2wGLETKBW3PvgPWqT","engaged_track_name":"Till The Sunrise","playlist_position":14,"new_listeners":19,"returning_listeners":7,"listeners":26,"new_listener_streams":24,"returning_listener_streams":11,"streams":35,"spl":1.35}
546
890
  '400': { $ref: '#/components/responses/BadRequest' }
547
891
  '401': { $ref: '#/components/responses/Unauthorized' }
548
892
  '403': { $ref: '#/components/responses/Forbidden' }
@@ -550,6 +894,86 @@ paths:
550
894
  '429': { $ref: '#/components/responses/RateLimited' }
551
895
  '500': { $ref: '#/components/responses/InternalError' }
552
896
 
897
+ /v1/videos/import:
898
+ post:
899
+ operationId: importVideo
900
+ summary: Import a video from a public HTTPS MP4 URL
901
+ description: |
902
+ Downloads a single public HTTPS MP4, stages it for ingestion, and starts
903
+ the background video pipeline. Returns `202` while processing, or `200`
904
+ with `videoId` immediately when the organization already has the same video
905
+ (content duplicate).
906
+
907
+ Requires the `videos:write` scope. Subject to a stricter per-key rate limit
908
+ than generic public API routes (default 5 imports per hour per API key).
909
+
910
+ Poll `GET /v1/videos/import/{sessionId}` until `status` is `ready` or `failed`.
911
+ Use the returned `videoId` in Full Control campaign `creativeDirection.selectedCreatives`.
912
+ tags: [Videos]
913
+ security:
914
+ - apiKeyAuth: []
915
+ - apiKeyBearerAuth: []
916
+ x-required-scope: videos:write
917
+ requestBody:
918
+ required: true
919
+ content:
920
+ application/json:
921
+ schema:
922
+ $ref: '#/components/schemas/VideoImportRequest'
923
+ example:
924
+ url: 'https://cdn.example.com/promo.mp4'
925
+ responses:
926
+ '200':
927
+ description: Duplicate video already in the organization's library
928
+ content:
929
+ application/json:
930
+ schema:
931
+ $ref: '#/components/schemas/VideoImportStartResponse'
932
+ '202':
933
+ description: Import accepted; ingestion in progress
934
+ content:
935
+ application/json:
936
+ schema:
937
+ $ref: '#/components/schemas/VideoImportStartResponse'
938
+ '400': { $ref: '#/components/responses/BadRequest' }
939
+ '401': { $ref: '#/components/responses/Unauthorized' }
940
+ '403': { $ref: '#/components/responses/Forbidden' }
941
+ '429': { $ref: '#/components/responses/RateLimited' }
942
+ '500': { $ref: '#/components/responses/InternalError' }
943
+
944
+ /v1/videos/import/{sessionId}:
945
+ get:
946
+ operationId: getVideoImportStatus
947
+ summary: Get video import session status
948
+ description: |
949
+ Returns processing status and the resulting `videoId` when ingestion completes.
950
+ Requires the `videos:write` scope.
951
+ tags: [Videos]
952
+ security:
953
+ - apiKeyAuth: []
954
+ - apiKeyBearerAuth: []
955
+ x-required-scope: videos:write
956
+ parameters:
957
+ - name: sessionId
958
+ in: path
959
+ required: true
960
+ schema:
961
+ type: string
962
+ format: uuid
963
+ description: Upload session ID returned by `POST /v1/videos/import`
964
+ responses:
965
+ '200':
966
+ description: Import session status
967
+ content:
968
+ application/json:
969
+ schema:
970
+ $ref: '#/components/schemas/VideoImportStatusResponse'
971
+ '401': { $ref: '#/components/responses/Unauthorized' }
972
+ '403': { $ref: '#/components/responses/Forbidden' }
973
+ '404': { $ref: '#/components/responses/NotFound' }
974
+ '429': { $ref: '#/components/responses/RateLimited' }
975
+ '500': { $ref: '#/components/responses/InternalError' }
976
+
553
977
  components:
554
978
  securitySchemes:
555
979
  apiKeyAuth:
@@ -558,7 +982,18 @@ components:
558
982
  name: x-api-key
559
983
  description: |
560
984
  Pass your Soundlink `sk_*` API key in the `x-api-key` header.
561
- Keys can carry explicit scopes (for example `campaigns:read`, `metrics:read`) enforced by the backend.
985
+ Keys can carry explicit scopes (for example `campaigns:read`, `metrics:read`, `videos:write`) enforced by the backend.
986
+
987
+ **Deprecated, retiring 2026-08-17** — migrate to `Authorization: Bearer sk_...` (see `apiKeyBearerAuth`) before then.
988
+
989
+ apiKeyBearerAuth:
990
+ type: http
991
+ scheme: bearer
992
+ description: |
993
+ Pass your Soundlink `sk_*` API key as a Bearer token:
994
+ `Authorization: Bearer sk_<prefix>_<token>`. Verified with the exact
995
+ same key as `apiKeyAuth` — just the recommended header for the same
996
+ `sk_*` credential. Do not combine with `x-api-key`.
562
997
 
563
998
  parameters:
564
999
  campaignId:
@@ -567,7 +1002,23 @@ components:
567
1002
  required: true
568
1003
  schema:
569
1004
  type: string
570
- description: Campaign identifier (e.g. `camp_abc123`)
1005
+ description: Campaign identifier (UUID)
1006
+
1007
+ idempotencyKey:
1008
+ name: Idempotency-Key
1009
+ in: header
1010
+ required: true
1011
+ schema:
1012
+ type: string
1013
+ minLength: 1
1014
+ maxLength: 255
1015
+ description: |
1016
+ A unique string identifying this request, used to safely retry write
1017
+ operations (create, stop, budget increase/decrease) without repeating
1018
+ side effects. Required on every request that references this parameter.
1019
+ Reusing this key with an unchanged request body replays the original
1020
+ response; reusing it with a different body returns
1021
+ `409 idempotency_key_conflict`. Keys are honored for 24 hours.
571
1022
 
572
1023
  page:
573
1024
  name: page
@@ -666,101 +1117,577 @@ components:
666
1117
  - invalid_query_parameter
667
1118
  - invalid_date_range
668
1119
  - page_size_exceeded
1120
+ - invalid_request
1121
+ - invalid_genre
1122
+ - invalid_duration_or_budget
1123
+ - invalid_daily_budget
1124
+ - invalid_duration_days
1125
+ - invalid_spotify_url
1126
+ - invalid_tier_budget_allocation
1127
+ - invalid_tier_status
1128
+ - tier_update_cooldown
1129
+ - wallet_not_enabled
1130
+ - insufficient_credit
1131
+ - idempotency_key_conflict
669
1132
  - rate_limit_exceeded
1133
+ - invalid_video_url
1134
+ - video_import_limit_exceeded
1135
+ - video_import_session_not_found
670
1136
  - internal_error
671
1137
  message:
672
1138
  type: string
673
- description: Human-readable error description. Do not parse programmatically.
1139
+ description: Human-readable error description. Do not parse programmatically.
1140
+ details:
1141
+ type: object
1142
+ nullable: true
1143
+ description: |
1144
+ Additive, error-code-specific context (e.g. `available`/`required`
1145
+ on `insufficient_credit`). Absent or `null` for error codes that
1146
+ carry no extra data.
1147
+ additionalProperties: true
1148
+
1149
+ ErrorResponse:
1150
+ type: object
1151
+ required: [error, meta]
1152
+ properties:
1153
+ error:
1154
+ $ref: '#/components/schemas/Error'
1155
+ meta:
1156
+ $ref: '#/components/schemas/Meta'
1157
+
1158
+ # --- Campaign ---
1159
+
1160
+ CampaignStatus:
1161
+ type: string
1162
+ enum: [creating, active, paused, stopped, completed, failed, ended]
1163
+
1164
+ CampaignSummary:
1165
+ type: object
1166
+ required:
1167
+ [
1168
+ campaignId,
1169
+ organizationId,
1170
+ status,
1171
+ socialPlatform,
1172
+ dailyBudget,
1173
+ totalBudget,
1174
+ campaignDuration,
1175
+ generation,
1176
+ createdAt,
1177
+ updatedAt,
1178
+ ]
1179
+ properties:
1180
+ campaignId:
1181
+ type: string
1182
+ organizationId:
1183
+ type: string
1184
+ status:
1185
+ $ref: '#/components/schemas/CampaignStatus'
1186
+ socialPlatform:
1187
+ type: string
1188
+ enum: [meta]
1189
+ dailyBudget:
1190
+ type: number
1191
+ description: USD
1192
+ totalBudget:
1193
+ type: number
1194
+ description: USD
1195
+ campaignDuration:
1196
+ type: integer
1197
+ description: Duration in days
1198
+ generation:
1199
+ type: integer
1200
+ enum: [1, 2, 3]
1201
+ description: |
1202
+ Campaign resource generation. `1` = Stripe / one-time / subscription /
1203
+ legacy; `2` = Soundlink managed; `3` = wallet. Public API write
1204
+ operations (budget changes, stop, tier updates) are supported for
1205
+ generation `3` only.
1206
+ createdAt:
1207
+ type: string
1208
+ format: date-time
1209
+ updatedAt:
1210
+ type: string
1211
+ format: date-time
1212
+
1213
+ CampaignDetail:
1214
+ allOf:
1215
+ - $ref: '#/components/schemas/CampaignSummary'
1216
+ - type: object
1217
+ properties:
1218
+ strategyType:
1219
+ type: string
1220
+ description: |
1221
+ Growth strategy (e.g. `custom`, `maximum_growth`, `market_discovery`).
1222
+ Set at campaign creation.
1223
+
1224
+ CampaignListResponse:
1225
+ type: object
1226
+ required: [data, meta]
1227
+ properties:
1228
+ data:
1229
+ type: object
1230
+ required: [items, pagination]
1231
+ properties:
1232
+ items:
1233
+ type: array
1234
+ items:
1235
+ $ref: '#/components/schemas/CampaignSummary'
1236
+ pagination:
1237
+ $ref: '#/components/schemas/Pagination'
1238
+ meta:
1239
+ $ref: '#/components/schemas/Meta'
1240
+
1241
+ CampaignDetailResponse:
1242
+ type: object
1243
+ required: [data, meta]
1244
+ properties:
1245
+ data:
1246
+ $ref: '#/components/schemas/CampaignDetail'
1247
+ meta:
1248
+ $ref: '#/components/schemas/Meta'
1249
+
1250
+ CampaignTier:
1251
+ type: object
1252
+ required: [tierId, tierName, isEnabled, allocationPercent]
1253
+ properties:
1254
+ tierId:
1255
+ type: integer
1256
+ description: Targeting tier identifier.
1257
+ tierName:
1258
+ type: string
1259
+ description: Human-readable tier name.
1260
+ isEnabled:
1261
+ type: boolean
1262
+ description: Whether this tier is currently active.
1263
+ allocationPercent:
1264
+ type: number
1265
+ minimum: 0
1266
+ maximum: 100
1267
+ description: Share of campaign budget allocated to this tier.
1268
+
1269
+ CampaignTiersData:
1270
+ type: object
1271
+ required: [lastUpdate, tiers]
1272
+ properties:
1273
+ lastUpdate:
1274
+ type: string
1275
+ format: date-time
1276
+ nullable: true
1277
+ description: |
1278
+ ISO-8601 timestamp of the last manual tier status update, or null
1279
+ if tiers have never been updated.
1280
+ tiers:
1281
+ type: array
1282
+ items:
1283
+ $ref: '#/components/schemas/CampaignTier'
1284
+
1285
+ CampaignTiersResponse:
1286
+ type: object
1287
+ required: [data, meta]
1288
+ properties:
1289
+ data:
1290
+ $ref: '#/components/schemas/CampaignTiersData'
1291
+ meta:
1292
+ $ref: '#/components/schemas/Meta'
1293
+
1294
+ TierStatusUpdateItem:
1295
+ type: object
1296
+ required: [targetingTierId, isEnabled, newAllocationPercent]
1297
+ properties:
1298
+ targetingTierId:
1299
+ type: integer
1300
+ minimum: 1
1301
+ description: Targeting tier identifier.
1302
+ isEnabled:
1303
+ type: boolean
1304
+ description: Whether to enable or disable this tier.
1305
+ newAllocationPercent:
1306
+ type: number
1307
+ minimum: 0
1308
+ maximum: 100
1309
+ description: New budget share for this tier (all items must sum to 100).
1310
+
1311
+ UpdateCampaignTiersRequest:
1312
+ type: object
1313
+ required: [items]
1314
+ properties:
1315
+ items:
1316
+ type: array
1317
+ minItems: 1
1318
+ items:
1319
+ $ref: '#/components/schemas/TierStatusUpdateItem'
1320
+
1321
+ Genre:
1322
+ type: string
1323
+ description: Strictly validated against the platform's genre list.
1324
+ enum:
1325
+ - Alternative/Indie
1326
+ - Ambient/Sleep
1327
+ - Chill/Background
1328
+ - Classical
1329
+ - Country
1330
+ - Electronic/Dance
1331
+ - Hip-Hop/R&B
1332
+ - Latin/Reggaeton
1333
+ - Pop
1334
+ - Rock
1335
+ - Christmas
1336
+
1337
+ StrategyType:
1338
+ type: string
1339
+ enum:
1340
+ - maximum_growth
1341
+ - market_discovery
1342
+ - revenue_maximization
1343
+ - custom
1344
+
1345
+ CreativeDirection:
1346
+ description: |
1347
+ How the campaign's ad creative is produced. Omit entirely to use the
1348
+ platform's default (`do_it_for_me`).
1349
+ oneOf:
1350
+ - $ref: '#/components/schemas/DoItForMeCreativeDirection'
1351
+ - $ref: '#/components/schemas/FullControlCreativeDirection'
1352
+ discriminator:
1353
+ propertyName: type
1354
+ mapping:
1355
+ do_it_for_me: '#/components/schemas/DoItForMeCreativeDirection'
1356
+ full_control: '#/components/schemas/FullControlCreativeDirection'
1357
+
1358
+ DoItForMeCreativeDirection:
1359
+ type: object
1360
+ required: [type]
1361
+ properties:
1362
+ type:
1363
+ type: string
1364
+ enum: [do_it_for_me]
1365
+ description: Soundlink selects and produces the ad creative.
1366
+
1367
+ FullControlCreativeDirection:
1368
+ type: object
1369
+ required: [type, selectedCreatives]
1370
+ properties:
1371
+ type:
1372
+ type: string
1373
+ enum: [full_control]
1374
+ selectedCreatives:
1375
+ type: array
1376
+ minItems: 1
1377
+ items:
1378
+ $ref: '#/components/schemas/SelectedCreative'
1379
+ description: One or more previously imported video creatives to use for the ad. Required for full control.
1380
+
1381
+ SelectedCreative:
1382
+ type: object
1383
+ required: [videoId]
1384
+ properties:
1385
+ videoId:
1386
+ type: string
1387
+ format: uuid
1388
+ description: |
1389
+ ID of a video previously imported into your video library. Import
1390
+ videos via the video import endpoint before referencing them here.
1391
+
1392
+ CustomTier:
1393
+ type: object
1394
+ required: [name, percentBudget]
1395
+ properties:
1396
+ name:
1397
+ type: string
1398
+ countries:
1399
+ type: array
1400
+ items:
1401
+ type: string
1402
+ description: ISO 3166-1 alpha-2 country codes.
1403
+ language:
1404
+ type: string
1405
+ description: ISO 639-1 language code.
1406
+ percentBudget:
1407
+ type: number
1408
+ description: Share of the campaign budget allocated to this tier. All tiers in a request must sum to 100.
1409
+
1410
+ TierTargeting:
1411
+ type: object
1412
+ description: |
1413
+ Custom tier targeting. Required when `strategyType` is `custom`: provide a
1414
+ non-empty `customTierIds` and/or `customTiers` array. Omit entirely for
1415
+ non-custom strategies (platform default tiering applies).
1416
+ properties:
1417
+ customTierIds:
1418
+ type: array
1419
+ items:
1420
+ type: integer
1421
+ customTiers:
1422
+ type: array
1423
+ description: |
1424
+ Inline custom tiers to create with the campaign. At most 5 active
1425
+ tiers (percentBudget > 0) are allowed; inactive (0%) entries do not
1426
+ count toward that limit. Each active tier must receive at least
1427
+ $1.50 of dailyBudget (gross). percentBudget values must sum to 100.
1428
+ items:
1429
+ $ref: '#/components/schemas/CustomTier'
1430
+
1431
+ CreateCampaignRequestShared:
1432
+ type: object
1433
+ required: [spotifyUrl, dailyBudget, durationDays, genre]
1434
+ properties:
1435
+ spotifyUrl:
1436
+ type: string
1437
+ format: uri
1438
+ description: |
1439
+ Spotify track or playlist URL to promote. Must be a valid track or
1440
+ playlist link to a resource that currently exists on Spotify.
1441
+ dailyBudget:
1442
+ type: number
1443
+ minimum: 10
1444
+ description: |
1445
+ USD, per day. Must be at least 10 (same floor as the Soundlink UI).
1446
+ durationDays:
1447
+ description: |
1448
+ Campaign duration in days. Must be an integer from 7 to 30 (UI custom
1449
+ range), or 60, or 90 (UI dropdown extras).
1450
+ oneOf:
1451
+ - type: integer
1452
+ minimum: 7
1453
+ maximum: 30
1454
+ - type: integer
1455
+ enum: [60, 90]
1456
+ genre:
1457
+ $ref: '#/components/schemas/Genre'
1458
+ campaignName:
1459
+ type: string
1460
+ description: Optional. Server generates a default (track title + short random suffix) when omitted.
1461
+ creativeDirection:
1462
+ $ref: '#/components/schemas/CreativeDirection'
1463
+ trackOptions:
1464
+ type: object
1465
+ description: Options that only apply when `spotifyUrl` is a track link. Ignored when `spotifyUrl` is a playlist link.
1466
+ properties:
1467
+ artistIdFollow:
1468
+ type: string
1469
+ description: Pass-through artist identifier.
1470
+ clonedFromCampaignId:
1471
+ type: string
1472
+ format: uuid
1473
+ description: >-
1474
+ Optional UUID of a campaign in your organization this create is
1475
+ cloned from. Records lineage only — it does not copy settings from
1476
+ the source; all other create fields must still be provided. Unknown
1477
+ or other-organization IDs return `400 invalid_request`.
1478
+
1479
+ CreateCampaignRequestWithoutTiers:
1480
+ allOf:
1481
+ - $ref: '#/components/schemas/CreateCampaignRequestShared'
1482
+ - type: object
1483
+ required: [strategyType]
1484
+ properties:
1485
+ strategyType:
1486
+ type: string
1487
+ enum:
1488
+ - maximum_growth
1489
+ - market_discovery
1490
+ - revenue_maximization
1491
+ description: |
1492
+ Non-custom growth strategy. Do not send `tierTargeting` with these
1493
+ values; the platform applies default tiering.
1494
+ not:
1495
+ required: [tierTargeting]
1496
+
1497
+ CreateCampaignRequestCustom:
1498
+ allOf:
1499
+ - $ref: '#/components/schemas/CreateCampaignRequestShared'
1500
+ - type: object
1501
+ required: [strategyType, tierTargeting]
1502
+ properties:
1503
+ strategyType:
1504
+ type: string
1505
+ enum: [custom]
1506
+ description: |
1507
+ Custom growth strategy. Requires `tierTargeting` with a non-empty
1508
+ `customTierIds` and/or `customTiers` array.
1509
+ tierTargeting:
1510
+ $ref: '#/components/schemas/TierTargeting'
1511
+
1512
+ CreateCampaignRequest:
1513
+ description: |
1514
+ Create a wallet-funded campaign. When `strategyType` is `custom`,
1515
+ `tierTargeting` is required. For `maximum_growth`, `market_discovery`,
1516
+ or `revenue_maximization`, do not send `tierTargeting` (platform default
1517
+ tiering applies).
1518
+ oneOf:
1519
+ - $ref: '#/components/schemas/CreateCampaignRequestWithoutTiers'
1520
+ - $ref: '#/components/schemas/CreateCampaignRequestCustom'
1521
+
1522
+ CampaignCreateData:
1523
+ type: object
1524
+ required: [campaignId, status]
1525
+ properties:
1526
+ campaignId:
1527
+ type: string
1528
+ status:
1529
+ $ref: '#/components/schemas/CampaignStatus'
1530
+
1531
+ CreateCampaignResponse:
1532
+ type: object
1533
+ required: [data, meta]
1534
+ properties:
1535
+ data:
1536
+ $ref: '#/components/schemas/CampaignCreateData'
1537
+ meta:
1538
+ $ref: '#/components/schemas/Meta'
1539
+
1540
+ CampaignStopData:
1541
+ type: object
1542
+ required: [campaignId, status]
1543
+ properties:
1544
+ campaignId:
1545
+ type: string
1546
+ status:
1547
+ $ref: '#/components/schemas/CampaignStatus'
1548
+ description: Campaign status after stop (typically `stopped`).
674
1549
 
675
- ErrorResponse:
1550
+ StopCampaignResponse:
676
1551
  type: object
677
- required: [error, meta]
1552
+ required: [data, meta]
678
1553
  properties:
679
- error:
680
- $ref: '#/components/schemas/Error'
1554
+ data:
1555
+ $ref: '#/components/schemas/CampaignStopData'
681
1556
  meta:
682
1557
  $ref: '#/components/schemas/Meta'
683
1558
 
684
- # --- Campaign ---
1559
+ StrategyCatalogItem:
1560
+ type: object
1561
+ required: [strategyType, tierTargetingAllowed]
1562
+ properties:
1563
+ strategyType:
1564
+ $ref: '#/components/schemas/StrategyType'
1565
+ tierTargetingAllowed:
1566
+ type: boolean
1567
+ description: |
1568
+ When `false`, omit `tierTargeting` on create (platform default
1569
+ tiering applies). Only `custom` allows `tierTargeting`.
685
1570
 
686
- CampaignStatus:
1571
+ StrategiesCatalogData:
1572
+ type: object
1573
+ required: [strategies]
1574
+ properties:
1575
+ strategies:
1576
+ type: array
1577
+ items:
1578
+ $ref: '#/components/schemas/StrategyCatalogItem'
1579
+
1580
+ StrategiesCatalogResponse:
1581
+ type: object
1582
+ required: [data, meta]
1583
+ properties:
1584
+ data:
1585
+ $ref: '#/components/schemas/StrategiesCatalogData'
1586
+ meta:
1587
+ $ref: '#/components/schemas/Meta'
1588
+
1589
+ BudgetIncreaseMode:
687
1590
  type: string
688
- enum: [creating, active, paused, completed, failed]
1591
+ enum: [current_cycle, next_renewal, current_and_renewals]
1592
+ description: |
1593
+ Defaults to `current_and_renewals` when omitted on increase requests.
689
1594
 
690
- CampaignSummary:
1595
+ BudgetDecreaseMode:
1596
+ type: string
1597
+ enum: [current_cycle, current_and_renewals]
1598
+ description: |
1599
+ Defaults to `current_and_renewals` when omitted on decrease requests.
1600
+ `next_renewal` is not supported for decreases.
1601
+
1602
+ IncreaseCampaignBudgetRequest:
691
1603
  type: object
692
- required:
693
- [
694
- campaignId,
695
- organizationId,
696
- status,
697
- socialPlatform,
698
- dailyBudget,
699
- totalBudget,
700
- campaignDuration,
701
- createdAt,
702
- updatedAt,
703
- ]
1604
+ required: [amount]
1605
+ properties:
1606
+ amount:
1607
+ type: number
1608
+ description: |
1609
+ Wallet debit / top-up amount in USD. Must be positive, except
1610
+ `mode: next_renewal` with `targetDailyBudget` where `amount` may
1611
+ be `0`.
1612
+ mode:
1613
+ $ref: '#/components/schemas/BudgetIncreaseMode'
1614
+ targetDailyBudget:
1615
+ type: number
1616
+ minimum: 0
1617
+ exclusiveMinimum: true
1618
+ description: |
1619
+ Optional absolute next-cycle daily budget (USD). Most useful with
1620
+ `mode: next_renewal`.
1621
+
1622
+ IncreaseCampaignBudgetData:
1623
+ type: object
1624
+ required: [campaignId, mode, amount, walletBalance]
704
1625
  properties:
705
1626
  campaignId:
706
1627
  type: string
707
- organizationId:
708
- type: string
709
- status:
710
- $ref: '#/components/schemas/CampaignStatus'
711
- socialPlatform:
712
- type: string
713
- enum: [meta]
714
- dailyBudget:
1628
+ mode:
1629
+ $ref: '#/components/schemas/BudgetIncreaseMode'
1630
+ amount:
715
1631
  type: number
716
- description: USD
717
- totalBudget:
1632
+ walletBalance:
718
1633
  type: number
719
- description: USD
720
- campaignDuration:
721
- type: integer
722
- description: Duration in days
723
- createdAt:
724
- type: string
725
- format: date-time
726
- updatedAt:
727
- type: string
728
- format: date-time
729
-
730
- CampaignDetail:
731
- allOf:
732
- - $ref: '#/components/schemas/CampaignSummary'
733
- - type: object
734
- properties:
735
- strategyType:
736
- type: string
737
- description: |
738
- Growth strategy (e.g. `custom`, `maximum_growth`, `market_discovery`).
739
- Set at campaign creation.
1634
+ description: Organization wallet balance after the increase.
1635
+ walletNextCycleDailyBudget:
1636
+ type: number
1637
+ nullable: true
1638
+ description: Next-cycle daily budget when set by this request.
740
1639
 
741
- CampaignListResponse:
1640
+ IncreaseCampaignBudgetResponse:
742
1641
  type: object
743
1642
  required: [data, meta]
744
1643
  properties:
745
1644
  data:
746
- type: object
747
- required: [items, pagination]
748
- properties:
749
- items:
750
- type: array
751
- items:
752
- $ref: '#/components/schemas/CampaignSummary'
753
- pagination:
754
- $ref: '#/components/schemas/Pagination'
1645
+ $ref: '#/components/schemas/IncreaseCampaignBudgetData'
755
1646
  meta:
756
1647
  $ref: '#/components/schemas/Meta'
757
1648
 
758
- CampaignDetailResponse:
1649
+ DecreaseCampaignBudgetRequest:
1650
+ type: object
1651
+ required: [targetDailyBudget]
1652
+ properties:
1653
+ targetDailyBudget:
1654
+ type: number
1655
+ minimum: 10
1656
+ description: |
1657
+ New daily budget in USD (gross). Must be at least `$10`/day and
1658
+ lower than the campaign's current daily budget.
1659
+ mode:
1660
+ $ref: '#/components/schemas/BudgetDecreaseMode'
1661
+
1662
+ DecreaseCampaignBudgetData:
1663
+ type: object
1664
+ required: [campaignId, mode, targetDailyBudget, accepted]
1665
+ properties:
1666
+ campaignId:
1667
+ type: string
1668
+ mode:
1669
+ $ref: '#/components/schemas/BudgetDecreaseMode'
1670
+ targetDailyBudget:
1671
+ type: number
1672
+ accepted:
1673
+ type: boolean
1674
+ enum: [true]
1675
+ description: |
1676
+ Always `true` on success. Unused budget refund is applied
1677
+ asynchronously after acceptance.
1678
+ walletNextCycleDailyBudget:
1679
+ type: number
1680
+ nullable: true
1681
+ description: |
1682
+ Present for `current_and_renewals` when the next-cycle daily
1683
+ budget was updated. Omitted for `current_cycle`.
1684
+
1685
+ DecreaseCampaignBudgetResponse:
759
1686
  type: object
760
1687
  required: [data, meta]
761
1688
  properties:
762
1689
  data:
763
- $ref: '#/components/schemas/CampaignDetail'
1690
+ $ref: '#/components/schemas/DecreaseCampaignBudgetData'
764
1691
  meta:
765
1692
  $ref: '#/components/schemas/Meta'
766
1693
 
@@ -1124,9 +2051,11 @@ components:
1124
2051
  nullable: true
1125
2052
  minimum: 1
1126
2053
  description: |
1127
- 1-based slot index of the engaged track in the promoted playlist on `report_date`.
1128
- Populated for `engagement_context = playlist` when playlist snapshot data is available.
1129
- `null` for catalog rows and until position data is delivered (reserved for future delivery in v1.0).
2054
+ 1-based slot of the engaged track on the promoted playlist for `report_date` (1 = top).
2055
+ Populated only when `engagement_context = playlist` and that day's playlist crawl listed the track.
2056
+ `null` for catalog rows; before the day's crawl completes (current UTC day is often null until later morning UTC);
2057
+ when the track was not listed or could not be matched to that day's crawl; or while historical backfill is still catching up.
2058
+ Field is beta until historical backfill finishes. Treat `null` as unavailable — not an error.
1130
2059
  new_listeners:
1131
2060
  type: integer
1132
2061
  minimum: 0
@@ -1159,24 +2088,71 @@ components:
1159
2088
  type: number
1160
2089
  description: Streams per listener (`streams / listeners`). Zero if `listeners` is zero.
1161
2090
 
1162
- EngagementBreakdownResponse:
2091
+ # --- Videos ---
2092
+
2093
+ VideoImportRequest:
2094
+ type: object
2095
+ required: [url]
2096
+ properties:
2097
+ url:
2098
+ type: string
2099
+ format: uri
2100
+ description: Public HTTPS URL to an MP4 file (max 50 MB).
2101
+
2102
+ VideoImportStatus:
2103
+ type: string
2104
+ enum: [processing, ready, failed]
2105
+
2106
+ VideoImportStartData:
2107
+ type: object
2108
+ required: [sessionId, status]
2109
+ properties:
2110
+ sessionId:
2111
+ type: string
2112
+ format: uuid
2113
+ description: Upload session ID for status polling
2114
+ status:
2115
+ $ref: '#/components/schemas/VideoImportStatus'
2116
+ videoId:
2117
+ type: string
2118
+ format: uuid
2119
+ nullable: true
2120
+ description: Present when `status` is `ready` (new or duplicate video)
2121
+
2122
+ VideoImportStartResponse:
1163
2123
  type: object
1164
2124
  required: [data, meta]
1165
2125
  properties:
1166
2126
  data:
1167
- type: object
1168
- required: [schemaVersion, items, pagination]
1169
- properties:
1170
- schemaVersion:
1171
- type: string
1172
- description: Version of the `campaign_engagement_daily` row schema. Pin your ingest pipeline to this.
1173
- example: '1.0'
1174
- items:
1175
- type: array
1176
- items:
1177
- $ref: '#/components/schemas/EngagementRow'
1178
- pagination:
1179
- $ref: '#/components/schemas/Pagination'
2127
+ $ref: '#/components/schemas/VideoImportStartData'
2128
+ meta:
2129
+ $ref: '#/components/schemas/Meta'
2130
+
2131
+ VideoImportStatusData:
2132
+ type: object
2133
+ required: [sessionId, status]
2134
+ properties:
2135
+ sessionId:
2136
+ type: string
2137
+ format: uuid
2138
+ status:
2139
+ $ref: '#/components/schemas/VideoImportStatus'
2140
+ videoId:
2141
+ type: string
2142
+ format: uuid
2143
+ nullable: true
2144
+ description: Background video ID when `status` is `ready`
2145
+ error:
2146
+ type: string
2147
+ nullable: true
2148
+ description: Failure reason when `status` is `failed`
2149
+
2150
+ VideoImportStatusResponse:
2151
+ type: object
2152
+ required: [data, meta]
2153
+ properties:
2154
+ data:
2155
+ $ref: '#/components/schemas/VideoImportStatusData'
1180
2156
  meta:
1181
2157
  $ref: '#/components/schemas/Meta'
1182
2158
 
@@ -1203,6 +2179,30 @@ components:
1203
2179
  meta:
1204
2180
  requestId: 550e8400-e29b-41d4-a716-446655440000
1205
2181
 
2182
+ CreateCampaignBadRequest:
2183
+ description: |
2184
+ Missing or malformed request body, or a missing/empty
2185
+ `Idempotency-Key` header.
2186
+ content:
2187
+ application/json:
2188
+ schema:
2189
+ $ref: '#/components/schemas/ErrorResponse'
2190
+ examples:
2191
+ missing_field:
2192
+ value:
2193
+ error:
2194
+ code: invalid_request
2195
+ message: 'Missing required field: spotifyUrl.'
2196
+ meta:
2197
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2198
+ missing_idempotency_key:
2199
+ value:
2200
+ error:
2201
+ code: invalid_request
2202
+ message: 'Idempotency-Key header is required and must not be empty.'
2203
+ meta:
2204
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2205
+
1206
2206
  Unauthorized:
1207
2207
  description: Missing, malformed, revoked, or expired API key
1208
2208
  headers:
@@ -1219,14 +2219,14 @@ components:
1219
2219
  value:
1220
2220
  error:
1221
2221
  code: invalid_api_key
1222
- message: 'Authorization header is missing or malformed.'
2222
+ message: 'Missing or malformed API key. Expected: sk_<prefix>_<token> (sent via x-api-key or Authorization: Bearer).'
1223
2223
  meta:
1224
2224
  requestId: 550e8400-e29b-41d4-a716-446655440000
1225
2225
  api_key_revoked:
1226
2226
  value:
1227
2227
  error:
1228
2228
  code: api_key_revoked
1229
- message: 'This API key has been revoked. Contact Soundlink Engineering to mint a new key.'
2229
+ message: 'This API key has been revoked. Create a new key in Settings → Developer → API keys.'
1230
2230
  meta:
1231
2231
  requestId: 550e8400-e29b-41d4-a716-446655440000
1232
2232
 
@@ -1243,8 +2243,145 @@ components:
1243
2243
  meta:
1244
2244
  requestId: 550e8400-e29b-41d4-a716-446655440000
1245
2245
 
2246
+ CreateCampaignForbidden:
2247
+ description: |
2248
+ Valid key but missing the `campaigns:write` scope, or the calling
2249
+ organization is not enabled for wallet billing.
2250
+ content:
2251
+ application/json:
2252
+ schema:
2253
+ $ref: '#/components/schemas/ErrorResponse'
2254
+ examples:
2255
+ insufficient_scope:
2256
+ value:
2257
+ error:
2258
+ code: insufficient_scope
2259
+ message: 'This key does not have the campaigns:write scope.'
2260
+ meta:
2261
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2262
+ wallet_not_enabled:
2263
+ value:
2264
+ error:
2265
+ code: wallet_not_enabled
2266
+ message: 'This organization does not have wallet billing enabled.'
2267
+ meta:
2268
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2269
+
2270
+ InsufficientCredit:
2271
+ description: Wallet balance is too low to cover `dailyBudget * durationDays`
2272
+ content:
2273
+ application/json:
2274
+ schema:
2275
+ $ref: '#/components/schemas/ErrorResponse'
2276
+ example:
2277
+ error:
2278
+ code: insufficient_credit
2279
+ message: 'Insufficient wallet balance for this campaign.'
2280
+ details:
2281
+ available: 120.00
2282
+ required: 350.00
2283
+ meta:
2284
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2285
+
2286
+ CreateCampaignUnprocessable:
2287
+ description: Request body is well-formed but semantically invalid
2288
+ content:
2289
+ application/json:
2290
+ schema:
2291
+ $ref: '#/components/schemas/ErrorResponse'
2292
+ examples:
2293
+ invalid_genre:
2294
+ value:
2295
+ error:
2296
+ code: invalid_genre
2297
+ message: 'genre must be one of the supported values.'
2298
+ meta:
2299
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2300
+ invalid_duration_or_budget:
2301
+ value:
2302
+ error:
2303
+ code: invalid_duration_or_budget
2304
+ message: 'dailyBudget and durationDays must be greater than 0.'
2305
+ meta:
2306
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2307
+ invalid_daily_budget:
2308
+ value:
2309
+ error:
2310
+ code: invalid_daily_budget
2311
+ message: 'dailyBudget must be at least 10 (USD per day).'
2312
+ meta:
2313
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2314
+ invalid_duration_days:
2315
+ value:
2316
+ error:
2317
+ code: invalid_duration_days
2318
+ message: 'durationDays must be an integer from 7 to 30, or 60, or 90.'
2319
+ meta:
2320
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2321
+ invalid_spotify_url:
2322
+ summary: Malformed URL or Spotify track/playlist does not exist
2323
+ value:
2324
+ error:
2325
+ code: invalid_spotify_url
2326
+ message: 'Spotify track not found.'
2327
+ meta:
2328
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2329
+ invalid_tier_budget_allocation:
2330
+ value:
2331
+ error:
2332
+ code: invalid_tier_budget_allocation
2333
+ message: 'tierTargeting.customTiers[].percentBudget must sum to 100.'
2334
+ meta:
2335
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2336
+ invalid_request_tier_targeting:
2337
+ value:
2338
+ error:
2339
+ code: invalid_request
2340
+ message: 'tierTargeting is only allowed when strategyType is custom.'
2341
+ meta:
2342
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2343
+
2344
+ IdempotencyKeyConflict:
2345
+ description: |
2346
+ The `Idempotency-Key` was reused with a materially different request
2347
+ body, or a request with the same key is still in progress.
2348
+ content:
2349
+ application/json:
2350
+ schema:
2351
+ $ref: '#/components/schemas/ErrorResponse'
2352
+ examples:
2353
+ conflicting_body:
2354
+ value:
2355
+ error:
2356
+ code: idempotency_key_conflict
2357
+ message: 'This Idempotency-Key was already used with a different request body.'
2358
+ meta:
2359
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2360
+ in_progress:
2361
+ value:
2362
+ error:
2363
+ code: idempotency_key_conflict
2364
+ message: 'A request with this Idempotency-Key is still processing. Retry after a short delay.'
2365
+ meta:
2366
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2367
+
2368
+ TierUpdateCooldown:
2369
+ description: |
2370
+ Campaign tiers were updated in the last 72 hours. Wait for the cooldown
2371
+ to end before updating again.
2372
+ content:
2373
+ application/json:
2374
+ schema:
2375
+ $ref: '#/components/schemas/ErrorResponse'
2376
+ example:
2377
+ error:
2378
+ code: tier_update_cooldown
2379
+ message: 'Campaign tiers were updated in the last 72 hours. Wait for the cooldown to end before updating again.'
2380
+ meta:
2381
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2382
+
1246
2383
  NotFound:
1247
- description: Campaign not found, belongs to another org, or feature flag is off
2384
+ description: Campaign not found or belongs to another organization
1248
2385
  content:
1249
2386
  application/json:
1250
2387
  schema: