soundlink 1.1.0 → 1.2.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,11 +3,11 @@ 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.
10
+ **Authentication:** `x-api-key` header using a `sk_*` API key created in the Soundlink app (Settings → Developer → API keys).
11
11
  ```
12
12
  x-api-key: sk_abc123_<token>
13
13
  ```
@@ -30,9 +30,11 @@ tags:
30
30
  - name: System
31
31
  description: Connectivity and auth verification
32
32
  - name: Campaigns
33
- description: Campaign listing and detail
33
+ description: Campaign listing, detail, creation, and wallet management (budget, stop, tiers)
34
34
  - name: Metrics
35
35
  description: Campaign performance metrics
36
+ - name: Videos
37
+ description: Partner video library import for Full Control campaigns
36
38
 
37
39
  paths:
38
40
  /v1/ping:
@@ -73,6 +75,45 @@ paths:
73
75
  '429': { $ref: '#/components/responses/RateLimited' }
74
76
  '500': { $ref: '#/components/responses/InternalError' }
75
77
 
78
+ /v1/strategies:
79
+ get:
80
+ operationId: listStrategies
81
+ summary: List campaign strategy types
82
+ description: |
83
+ Returns the static catalog of `strategyType` values accepted by
84
+ `POST /v1/campaigns`. Built-in strategies apply platform default
85
+ tiering internally; only `custom` allows `tierTargeting` on create.
86
+
87
+ Requires the `campaigns:read` scope.
88
+ tags: [Campaigns]
89
+ security:
90
+ - apiKeyAuth: []
91
+ x-required-scope: campaigns:read
92
+ responses:
93
+ '200':
94
+ description: Strategy catalog
95
+ content:
96
+ application/json:
97
+ schema:
98
+ $ref: '#/components/schemas/StrategiesCatalogResponse'
99
+ example:
100
+ data:
101
+ strategies:
102
+ - strategyType: maximum_growth
103
+ tierTargetingAllowed: false
104
+ - strategyType: market_discovery
105
+ tierTargetingAllowed: false
106
+ - strategyType: revenue_maximization
107
+ tierTargetingAllowed: false
108
+ - strategyType: custom
109
+ tierTargetingAllowed: true
110
+ meta:
111
+ requestId: 550e8400-e29b-41d4-a716-446655440000
112
+ '401': { $ref: '#/components/responses/Unauthorized' }
113
+ '403': { $ref: '#/components/responses/Forbidden' }
114
+ '429': { $ref: '#/components/responses/RateLimited' }
115
+ '500': { $ref: '#/components/responses/InternalError' }
116
+
76
117
  /v1/campaigns:
77
118
  get:
78
119
  operationId: listCampaigns
@@ -90,7 +131,7 @@ paths:
90
131
  in: query
91
132
  schema:
92
133
  type: string
93
- enum: [createdAt, status]
134
+ enum: [createdAt]
94
135
  default: createdAt
95
136
  - $ref: '#/components/parameters/sortOrder'
96
137
  responses:
@@ -103,7 +144,7 @@ paths:
103
144
  example:
104
145
  data:
105
146
  items:
106
- - campaignId: camp_abc123
147
+ - campaignId: f1e28d31-c358-4284-9bef-00a2334625fd
107
148
  organizationId: org_xyz
108
149
  status: active
109
150
  socialPlatform: meta
@@ -124,6 +165,106 @@ paths:
124
165
  '429': { $ref: '#/components/responses/RateLimited' }
125
166
  '500': { $ref: '#/components/responses/InternalError' }
126
167
 
168
+ post:
169
+ operationId: createCampaign
170
+ summary: Create a wallet-funded campaign
171
+ description: |
172
+ Creates a campaign funded from the organization's wallet balance.
173
+ Requires the `campaigns:write` scope, and the organization must be
174
+ enabled for wallet billing.
175
+
176
+ This route has a financial side effect (the campaign's budget is
177
+ deducted from the wallet balance), so the `Idempotency-Key` header
178
+ is **required** on every request. See the header description below
179
+ for retry semantics.
180
+ tags: [Campaigns]
181
+ security:
182
+ - apiKeyAuth: []
183
+ x-required-scope: campaigns:write
184
+ parameters:
185
+ - $ref: '#/components/parameters/idempotencyKey'
186
+ requestBody:
187
+ required: true
188
+ content:
189
+ application/json:
190
+ schema:
191
+ $ref: '#/components/schemas/CreateCampaignRequest'
192
+ examples:
193
+ trackCampaign:
194
+ summary: Campaign promoting a single track
195
+ value:
196
+ spotifyUrl: 'https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl'
197
+ dailyBudget: 25
198
+ durationDays: 14
199
+ genre: Pop
200
+ campaignName: 'My Summer Single'
201
+ strategyType: maximum_growth
202
+ creativeDirection:
203
+ type: do_it_for_me
204
+ trackOptions:
205
+ artistIdFollow: 'artist-uuid'
206
+ clonedFromCampaignId: '3f2504e0-4f89-41d3-9a0c-0305e82c3301'
207
+ playlistCampaign:
208
+ summary: Campaign promoting a playlist
209
+ value:
210
+ spotifyUrl: 'https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M'
211
+ dailyBudget: 25
212
+ durationDays: 14
213
+ genre: Pop
214
+ campaignName: 'Summer Vibes Playlist'
215
+ strategyType: maximum_growth
216
+ creativeDirection:
217
+ type: do_it_for_me
218
+ fullControlCampaign:
219
+ summary: Campaign with partner-supplied creative (full control)
220
+ value:
221
+ spotifyUrl: 'https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl'
222
+ dailyBudget: 40
223
+ durationDays: 21
224
+ genre: Hip-Hop/R&B
225
+ campaignName: 'My Summer Single'
226
+ strategyType: custom
227
+ creativeDirection:
228
+ type: full_control
229
+ selectedCreatives:
230
+ - videoId: '8f14e45f-ceea-467e-9de5-e7d0b4d4e6bb'
231
+ - videoId: '3c9b1a2d-1a2f-4a1e-9c3b-0a1b2c3d4e5f'
232
+ tierTargeting:
233
+ customTierIds: [123, 456]
234
+ customTiers:
235
+ - name: 'US/UK'
236
+ countries: ['US', 'GB']
237
+ language: en
238
+ percentBudget: 60
239
+ - name: LatAm
240
+ countries: ['MX', 'AR']
241
+ language: es
242
+ percentBudget: 40
243
+ trackOptions:
244
+ artistIdFollow: 'artist-uuid'
245
+ responses:
246
+ '201':
247
+ description: Campaign created
248
+ content:
249
+ application/json:
250
+ schema:
251
+ $ref: '#/components/schemas/CreateCampaignResponse'
252
+ example:
253
+ data:
254
+ campaignId: campaign-uuid
255
+ status: creating
256
+ meta:
257
+ requestId: 550e8400-e29b-41d4-a716-446655440000
258
+ '400': { $ref: '#/components/responses/CreateCampaignBadRequest' }
259
+ '401': { $ref: '#/components/responses/Unauthorized' }
260
+ '402': { $ref: '#/components/responses/InsufficientCredit' }
261
+ '403': { $ref: '#/components/responses/CreateCampaignForbidden' }
262
+ '404': { $ref: '#/components/responses/NotFound' }
263
+ '409': { $ref: '#/components/responses/IdempotencyKeyConflict' }
264
+ '422': { $ref: '#/components/responses/CreateCampaignUnprocessable' }
265
+ '429': { $ref: '#/components/responses/RateLimited' }
266
+ '500': { $ref: '#/components/responses/InternalError' }
267
+
127
268
  /v1/campaigns/{campaignId}:
128
269
  get:
129
270
  operationId: getCampaign
@@ -143,7 +284,7 @@ paths:
143
284
  $ref: '#/components/schemas/CampaignDetailResponse'
144
285
  example:
145
286
  data:
146
- campaignId: camp_abc123
287
+ campaignId: f1e28d31-c358-4284-9bef-00a2334625fd
147
288
  organizationId: org_xyz
148
289
  status: active
149
290
  socialPlatform: meta
@@ -161,6 +302,292 @@ paths:
161
302
  '429': { $ref: '#/components/responses/RateLimited' }
162
303
  '500': { $ref: '#/components/responses/InternalError' }
163
304
 
305
+ /v1/campaigns/{campaignId}/stop:
306
+ post:
307
+ operationId: stopCampaign
308
+ summary: Stop a wallet campaign and refund unspent budget
309
+ description: |
310
+ Stops delivery for a wallet-funded campaign and refunds unspent budget
311
+ to the organization wallet. Requires the `campaigns:write` scope.
312
+
313
+ **Wallet campaigns only** (`generation: 3`).
314
+
315
+ Stopping is idempotent at the campaign level: a second stop on an
316
+ already-stopped campaign succeeds without double-refunding. The
317
+ `Idempotency-Key` header is also **required** so retries of the same
318
+ request replay the original response without repeating side effects.
319
+ tags: [Campaigns]
320
+ x-required-scope: campaigns:write
321
+ security:
322
+ - apiKeyAuth: []
323
+ parameters:
324
+ - $ref: '#/components/parameters/campaignId'
325
+ - $ref: '#/components/parameters/idempotencyKey'
326
+ responses:
327
+ '200':
328
+ description: Campaign stopped (or already stopped)
329
+ content:
330
+ application/json:
331
+ schema:
332
+ $ref: '#/components/schemas/StopCampaignResponse'
333
+ example:
334
+ data:
335
+ campaignId: campaign-uuid
336
+ status: stopped
337
+ meta:
338
+ requestId: 550e8400-e29b-41d4-a716-446655440000
339
+ '400': { $ref: '#/components/responses/BadRequest' }
340
+ '401': { $ref: '#/components/responses/Unauthorized' }
341
+ '403': { $ref: '#/components/responses/Forbidden' }
342
+ '404': { $ref: '#/components/responses/NotFound' }
343
+ '409': { $ref: '#/components/responses/IdempotencyKeyConflict' }
344
+ '429': { $ref: '#/components/responses/RateLimited' }
345
+ '500': { $ref: '#/components/responses/InternalError' }
346
+
347
+ /v1/campaigns/{campaignId}/budget/increase:
348
+ post:
349
+ operationId: increaseCampaignBudget
350
+ summary: Increase wallet campaign budget
351
+ description: |
352
+ Raises budget for a wallet-funded campaign. Requires the
353
+ `campaigns:write` scope and an `Idempotency-Key` header.
354
+
355
+ **Wallet campaigns only** (`generation: 3`).
356
+
357
+ **Modes** (default `current_and_renewals`):
358
+ - `current_cycle` — applies to the current billing cycle only
359
+ - `next_renewal` — adjusts the next-cycle daily budget (may use
360
+ `amount: 0` with `targetDailyBudget` to set an absolute next-cycle target)
361
+ - `current_and_renewals` — applies to the current cycle and future renewals
362
+
363
+ Debits the organization wallet when the current cycle is increased.
364
+ tags: [Campaigns]
365
+ x-required-scope: campaigns:write
366
+ security:
367
+ - apiKeyAuth: []
368
+ parameters:
369
+ - $ref: '#/components/parameters/campaignId'
370
+ - $ref: '#/components/parameters/idempotencyKey'
371
+ requestBody:
372
+ required: true
373
+ content:
374
+ application/json:
375
+ schema:
376
+ $ref: '#/components/schemas/IncreaseCampaignBudgetRequest'
377
+ examples:
378
+ currentAndRenewals:
379
+ summary: Top up current cycle and renewals
380
+ value:
381
+ amount: 70
382
+ mode: current_and_renewals
383
+ nextRenewalTarget:
384
+ summary: Set next-cycle daily budget without current-cycle debit
385
+ value:
386
+ amount: 0
387
+ mode: next_renewal
388
+ targetDailyBudget: 40
389
+ responses:
390
+ '200':
391
+ description: Budget increase accepted
392
+ content:
393
+ application/json:
394
+ schema:
395
+ $ref: '#/components/schemas/IncreaseCampaignBudgetResponse'
396
+ example:
397
+ data:
398
+ campaignId: campaign-uuid
399
+ mode: current_and_renewals
400
+ amount: 70
401
+ walletBalance: 430
402
+ walletNextCycleDailyBudget: 30
403
+ meta:
404
+ requestId: 550e8400-e29b-41d4-a716-446655440000
405
+ '400': { $ref: '#/components/responses/BadRequest' }
406
+ '401': { $ref: '#/components/responses/Unauthorized' }
407
+ '402': { $ref: '#/components/responses/InsufficientCredit' }
408
+ '403': { $ref: '#/components/responses/Forbidden' }
409
+ '404': { $ref: '#/components/responses/NotFound' }
410
+ '409': { $ref: '#/components/responses/IdempotencyKeyConflict' }
411
+ '429': { $ref: '#/components/responses/RateLimited' }
412
+ '500': { $ref: '#/components/responses/InternalError' }
413
+
414
+ /v1/campaigns/{campaignId}/budget/decrease:
415
+ post:
416
+ operationId: decreaseCampaignBudget
417
+ summary: Decrease wallet campaign daily budget
418
+ description: |
419
+ Lowers the daily budget for a wallet-funded campaign to
420
+ `targetDailyBudget`. Requires the `campaigns:write` scope and an
421
+ `Idempotency-Key` header.
422
+
423
+ **Wallet campaigns only** (`generation: 3`).
424
+
425
+ **Modes** (default `current_and_renewals`):
426
+ - `current_cycle` — lowers current-cycle spend only
427
+ - `current_and_renewals` — also sets the next-cycle daily budget
428
+
429
+ `next_renewal` is not supported for decreases. Refund of unused budget
430
+ is applied asynchronously after acceptance (`accepted: true`).
431
+
432
+ Domain rules (also returned as `invalid_request` when violated):
433
+ - `targetDailyBudget` must be at least `$10`/day and lower than the
434
+ current daily budget
435
+ - more than 3 days must remain in the current cycle
436
+ tags: [Campaigns]
437
+ x-required-scope: campaigns:write
438
+ security:
439
+ - apiKeyAuth: []
440
+ parameters:
441
+ - $ref: '#/components/parameters/campaignId'
442
+ - $ref: '#/components/parameters/idempotencyKey'
443
+ requestBody:
444
+ required: true
445
+ content:
446
+ application/json:
447
+ schema:
448
+ $ref: '#/components/schemas/DecreaseCampaignBudgetRequest'
449
+ example:
450
+ targetDailyBudget: 60
451
+ mode: current_and_renewals
452
+ responses:
453
+ '200':
454
+ description: Budget decrease accepted (refund may complete asynchronously)
455
+ content:
456
+ application/json:
457
+ schema:
458
+ $ref: '#/components/schemas/DecreaseCampaignBudgetResponse'
459
+ example:
460
+ data:
461
+ campaignId: campaign-uuid
462
+ mode: current_and_renewals
463
+ targetDailyBudget: 60
464
+ accepted: true
465
+ walletNextCycleDailyBudget: 60
466
+ meta:
467
+ requestId: 550e8400-e29b-41d4-a716-446655440000
468
+ '400': { $ref: '#/components/responses/BadRequest' }
469
+ '401': { $ref: '#/components/responses/Unauthorized' }
470
+ '403': { $ref: '#/components/responses/Forbidden' }
471
+ '404': { $ref: '#/components/responses/NotFound' }
472
+ '409': { $ref: '#/components/responses/IdempotencyKeyConflict' }
473
+ '429': { $ref: '#/components/responses/RateLimited' }
474
+ '500': { $ref: '#/components/responses/InternalError' }
475
+
476
+ /v1/campaigns/{campaignId}/tiers:
477
+ get:
478
+ operationId: getCampaignTiers
479
+ summary: Get campaign tier allocation
480
+ description: |
481
+ Returns the current geographic tier allocation for a wallet campaign:
482
+ which tiers are enabled, their budget share, and when tiers were last
483
+ updated (`lastUpdate`). Use this before `PATCH` to build a valid request.
484
+
485
+ **Wallet campaigns only** (`generation: 3`).
486
+ tags: [Campaigns]
487
+ x-required-scope: campaigns:read
488
+ security:
489
+ - apiKeyAuth: []
490
+ parameters:
491
+ - $ref: '#/components/parameters/campaignId'
492
+ responses:
493
+ '200':
494
+ description: Campaign tier allocation
495
+ content:
496
+ application/json:
497
+ schema:
498
+ $ref: '#/components/schemas/CampaignTiersResponse'
499
+ example:
500
+ data:
501
+ lastUpdate: '2026-01-01T00:00:00Z'
502
+ tiers:
503
+ - tierId: 1
504
+ tierName: US
505
+ isEnabled: true
506
+ allocationPercent: 60
507
+ - tierId: 2
508
+ tierName: UK
509
+ isEnabled: false
510
+ allocationPercent: 40
511
+ meta:
512
+ requestId: 550e8400-e29b-41d4-a716-446655440000
513
+ '400': { $ref: '#/components/responses/BadRequest' }
514
+ '401': { $ref: '#/components/responses/Unauthorized' }
515
+ '403': { $ref: '#/components/responses/Forbidden' }
516
+ '404': { $ref: '#/components/responses/NotFound' }
517
+ '429': { $ref: '#/components/responses/RateLimited' }
518
+ '500': { $ref: '#/components/responses/InternalError' }
519
+
520
+ patch:
521
+ operationId: updateCampaignTiers
522
+ summary: Update campaign tier allocation
523
+ description: |
524
+ Enable or disable geographic tiers and optionally reallocate budget
525
+ shares for a wallet campaign.
526
+
527
+ **Wallet campaigns only** (`generation: 3`).
528
+
529
+ **Request rules:**
530
+ - Include **all** tiers on the campaign in `items`
531
+ - `newAllocationPercent` values must sum to **100**
532
+ - At least one tier must have `isEnabled: true`
533
+
534
+ **Cooldown:** after a successful update, further tier changes are
535
+ blocked for **72 hours** (`409 tier_update_cooldown`).
536
+ tags: [Campaigns]
537
+ x-required-scope: campaigns:write
538
+ security:
539
+ - apiKeyAuth: []
540
+ parameters:
541
+ - $ref: '#/components/parameters/campaignId'
542
+ requestBody:
543
+ required: true
544
+ content:
545
+ application/json:
546
+ schema:
547
+ $ref: '#/components/schemas/UpdateCampaignTiersRequest'
548
+ example:
549
+ items:
550
+ - targetingTierId: 1
551
+ isEnabled: true
552
+ newAllocationPercent: 70
553
+ - targetingTierId: 2
554
+ isEnabled: true
555
+ newAllocationPercent: 30
556
+ responses:
557
+ '200':
558
+ description: Updated tier allocation
559
+ content:
560
+ application/json:
561
+ schema:
562
+ $ref: '#/components/schemas/CampaignTiersResponse'
563
+ '400':
564
+ description: Invalid request or tier status
565
+ content:
566
+ application/json:
567
+ schema:
568
+ $ref: '#/components/schemas/ErrorResponse'
569
+ examples:
570
+ invalid_request:
571
+ value:
572
+ error:
573
+ code: invalid_request
574
+ message: 'Tier updates are only supported for wallet campaigns.'
575
+ meta:
576
+ requestId: 550e8400-e29b-41d4-a716-446655440000
577
+ invalid_tier_status:
578
+ value:
579
+ error:
580
+ code: invalid_tier_status
581
+ message: 'At least one tier must be enabled'
582
+ meta:
583
+ requestId: 550e8400-e29b-41d4-a716-446655440000
584
+ '401': { $ref: '#/components/responses/Unauthorized' }
585
+ '403': { $ref: '#/components/responses/Forbidden' }
586
+ '404': { $ref: '#/components/responses/NotFound' }
587
+ '409': { $ref: '#/components/responses/TierUpdateCooldown' }
588
+ '429': { $ref: '#/components/responses/RateLimited' }
589
+ '500': { $ref: '#/components/responses/InternalError' }
590
+
164
591
  /v1/campaigns/{campaignId}/metrics/overview:
165
592
  get:
166
593
  operationId: getCampaignMetricsOverview
@@ -266,7 +693,7 @@ paths:
266
693
  campaign_name: Sleep Playlist
267
694
  campaign_target_type: track
268
695
  campaign_target_isrc: DEXW62500259
269
- campaign_target_spotify_track_id: 6habFhsOp2NvndAvgiJ01P
696
+ campaign_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
270
697
  campaign_target_playlist_id: null
271
698
  country_code: US
272
699
  impressions: 4821
@@ -322,9 +749,10 @@ paths:
322
749
  Accept: application/x-ndjson
323
750
  ```
324
751
 
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.
752
+ **Date range:** if you omit both dates, defaults to the last **90 days**
753
+ ending today. Override with `startDate` / `endDate`. **Responses are
754
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
755
+ Page longer histories in 90-day slices.
328
756
 
329
757
  **Mutability:** rows for a given `report_date` can be revised for up
330
758
  to 7 days after the date closes due to delayed events from Meta and
@@ -358,113 +786,8 @@ paths:
358
786
  schema:
359
787
  $ref: '#/components/schemas/BreakdownRow'
360
788
  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
789
+ {"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"}
790
+ {"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
791
  '400': { $ref: '#/components/responses/BadRequest' }
469
792
  '401': { $ref: '#/components/responses/Unauthorized' }
470
793
  '403': { $ref: '#/components/responses/Forbidden' }
@@ -479,9 +802,7 @@ paths:
479
802
  description: |
480
803
  Streams the full engagement dataset for a campaign as
481
804
  **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.
805
+ JSON object conforming to the `campaign_engagement_daily` v1.0 schema.
485
806
 
486
807
  Designed for data pipeline consumers: load directly into BigQuery,
487
808
  Snowflake, or any JSONL-aware ingest tool without cursor logic.
@@ -498,15 +819,14 @@ paths:
498
819
  {"provider":"soundlink","report_date":"2026-04-02","streams":104,...}
499
820
  ```
500
821
 
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.
822
+ **Date range:** if you omit both dates, defaults to the last **90 days**
823
+ ending today. Override with `startDate` / `endDate`. **Responses are
824
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
825
+ Page longer histories in 90-day slices.
507
826
 
508
- **Mutability:** same 7-day revision window as the paginated endpoint.
509
- Re-fetching and re-ingesting on the primary key is safe (idempotent).
827
+ **Mutability:** rows for a given `report_date` can be revised for up to
828
+ 7 days after the date closes. Re-fetching and re-ingesting on the
829
+ primary key is safe (idempotent).
510
830
  tags: [Metrics]
511
831
  security:
512
832
  - apiKeyAuth: []
@@ -550,6 +870,84 @@ paths:
550
870
  '429': { $ref: '#/components/responses/RateLimited' }
551
871
  '500': { $ref: '#/components/responses/InternalError' }
552
872
 
873
+ /v1/videos/import:
874
+ post:
875
+ operationId: importVideo
876
+ summary: Import a video from a public HTTPS MP4 URL
877
+ description: |
878
+ Downloads a single public HTTPS MP4, stages it for ingestion, and starts
879
+ the background video pipeline. Returns `202` while processing, or `200`
880
+ with `videoId` immediately when the organization already has the same video
881
+ (content duplicate).
882
+
883
+ Requires the `videos:write` scope. Subject to a stricter per-key rate limit
884
+ than generic public API routes (default 5 imports per hour per API key).
885
+
886
+ Poll `GET /v1/videos/import/{sessionId}` until `status` is `ready` or `failed`.
887
+ Use the returned `videoId` in Full Control campaign `creativeDirection.selectedCreatives`.
888
+ tags: [Videos]
889
+ security:
890
+ - apiKeyAuth: []
891
+ x-required-scope: videos:write
892
+ requestBody:
893
+ required: true
894
+ content:
895
+ application/json:
896
+ schema:
897
+ $ref: '#/components/schemas/VideoImportRequest'
898
+ example:
899
+ url: 'https://cdn.example.com/promo.mp4'
900
+ responses:
901
+ '200':
902
+ description: Duplicate video already in the organization's library
903
+ content:
904
+ application/json:
905
+ schema:
906
+ $ref: '#/components/schemas/VideoImportStartResponse'
907
+ '202':
908
+ description: Import accepted; ingestion in progress
909
+ content:
910
+ application/json:
911
+ schema:
912
+ $ref: '#/components/schemas/VideoImportStartResponse'
913
+ '400': { $ref: '#/components/responses/BadRequest' }
914
+ '401': { $ref: '#/components/responses/Unauthorized' }
915
+ '403': { $ref: '#/components/responses/Forbidden' }
916
+ '429': { $ref: '#/components/responses/RateLimited' }
917
+ '500': { $ref: '#/components/responses/InternalError' }
918
+
919
+ /v1/videos/import/{sessionId}:
920
+ get:
921
+ operationId: getVideoImportStatus
922
+ summary: Get video import session status
923
+ description: |
924
+ Returns processing status and the resulting `videoId` when ingestion completes.
925
+ Requires the `videos:write` scope.
926
+ tags: [Videos]
927
+ security:
928
+ - apiKeyAuth: []
929
+ x-required-scope: videos:write
930
+ parameters:
931
+ - name: sessionId
932
+ in: path
933
+ required: true
934
+ schema:
935
+ type: string
936
+ format: uuid
937
+ description: Upload session ID returned by `POST /v1/videos/import`
938
+ responses:
939
+ '200':
940
+ description: Import session status
941
+ content:
942
+ application/json:
943
+ schema:
944
+ $ref: '#/components/schemas/VideoImportStatusResponse'
945
+ '401': { $ref: '#/components/responses/Unauthorized' }
946
+ '403': { $ref: '#/components/responses/Forbidden' }
947
+ '404': { $ref: '#/components/responses/NotFound' }
948
+ '429': { $ref: '#/components/responses/RateLimited' }
949
+ '500': { $ref: '#/components/responses/InternalError' }
950
+
553
951
  components:
554
952
  securitySchemes:
555
953
  apiKeyAuth:
@@ -558,7 +956,7 @@ components:
558
956
  name: x-api-key
559
957
  description: |
560
958
  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.
959
+ Keys can carry explicit scopes (for example `campaigns:read`, `metrics:read`, `videos:write`) enforced by the backend.
562
960
 
563
961
  parameters:
564
962
  campaignId:
@@ -567,7 +965,23 @@ components:
567
965
  required: true
568
966
  schema:
569
967
  type: string
570
- description: Campaign identifier (e.g. `camp_abc123`)
968
+ description: Campaign identifier (UUID)
969
+
970
+ idempotencyKey:
971
+ name: Idempotency-Key
972
+ in: header
973
+ required: true
974
+ schema:
975
+ type: string
976
+ minLength: 1
977
+ maxLength: 255
978
+ description: |
979
+ A unique string identifying this request, used to safely retry write
980
+ operations (create, stop, budget increase/decrease) without repeating
981
+ side effects. Required on every request that references this parameter.
982
+ Reusing this key with an unchanged request body replays the original
983
+ response; reusing it with a different body returns
984
+ `409 idempotency_key_conflict`. Keys are honored for 24 hours.
571
985
 
572
986
  page:
573
987
  name: page
@@ -666,101 +1080,577 @@ components:
666
1080
  - invalid_query_parameter
667
1081
  - invalid_date_range
668
1082
  - page_size_exceeded
1083
+ - invalid_request
1084
+ - invalid_genre
1085
+ - invalid_duration_or_budget
1086
+ - invalid_daily_budget
1087
+ - invalid_duration_days
1088
+ - invalid_spotify_url
1089
+ - invalid_tier_budget_allocation
1090
+ - invalid_tier_status
1091
+ - tier_update_cooldown
1092
+ - wallet_not_enabled
1093
+ - insufficient_credit
1094
+ - idempotency_key_conflict
669
1095
  - rate_limit_exceeded
1096
+ - invalid_video_url
1097
+ - video_import_limit_exceeded
1098
+ - video_import_session_not_found
670
1099
  - internal_error
671
1100
  message:
672
1101
  type: string
673
- description: Human-readable error description. Do not parse programmatically.
1102
+ description: Human-readable error description. Do not parse programmatically.
1103
+ details:
1104
+ type: object
1105
+ nullable: true
1106
+ description: |
1107
+ Additive, error-code-specific context (e.g. `available`/`required`
1108
+ on `insufficient_credit`). Absent or `null` for error codes that
1109
+ carry no extra data.
1110
+ additionalProperties: true
1111
+
1112
+ ErrorResponse:
1113
+ type: object
1114
+ required: [error, meta]
1115
+ properties:
1116
+ error:
1117
+ $ref: '#/components/schemas/Error'
1118
+ meta:
1119
+ $ref: '#/components/schemas/Meta'
1120
+
1121
+ # --- Campaign ---
1122
+
1123
+ CampaignStatus:
1124
+ type: string
1125
+ enum: [creating, active, paused, stopped, completed, failed, ended]
1126
+
1127
+ CampaignSummary:
1128
+ type: object
1129
+ required:
1130
+ [
1131
+ campaignId,
1132
+ organizationId,
1133
+ status,
1134
+ socialPlatform,
1135
+ dailyBudget,
1136
+ totalBudget,
1137
+ campaignDuration,
1138
+ generation,
1139
+ createdAt,
1140
+ updatedAt,
1141
+ ]
1142
+ properties:
1143
+ campaignId:
1144
+ type: string
1145
+ organizationId:
1146
+ type: string
1147
+ status:
1148
+ $ref: '#/components/schemas/CampaignStatus'
1149
+ socialPlatform:
1150
+ type: string
1151
+ enum: [meta]
1152
+ dailyBudget:
1153
+ type: number
1154
+ description: USD
1155
+ totalBudget:
1156
+ type: number
1157
+ description: USD
1158
+ campaignDuration:
1159
+ type: integer
1160
+ description: Duration in days
1161
+ generation:
1162
+ type: integer
1163
+ enum: [1, 2, 3]
1164
+ description: |
1165
+ Campaign resource generation. `1` = Stripe / one-time / subscription /
1166
+ legacy; `2` = Soundlink managed; `3` = wallet. Public API write
1167
+ operations (budget changes, stop, tier updates) are supported for
1168
+ generation `3` only.
1169
+ createdAt:
1170
+ type: string
1171
+ format: date-time
1172
+ updatedAt:
1173
+ type: string
1174
+ format: date-time
1175
+
1176
+ CampaignDetail:
1177
+ allOf:
1178
+ - $ref: '#/components/schemas/CampaignSummary'
1179
+ - type: object
1180
+ properties:
1181
+ strategyType:
1182
+ type: string
1183
+ description: |
1184
+ Growth strategy (e.g. `custom`, `maximum_growth`, `market_discovery`).
1185
+ Set at campaign creation.
1186
+
1187
+ CampaignListResponse:
1188
+ type: object
1189
+ required: [data, meta]
1190
+ properties:
1191
+ data:
1192
+ type: object
1193
+ required: [items, pagination]
1194
+ properties:
1195
+ items:
1196
+ type: array
1197
+ items:
1198
+ $ref: '#/components/schemas/CampaignSummary'
1199
+ pagination:
1200
+ $ref: '#/components/schemas/Pagination'
1201
+ meta:
1202
+ $ref: '#/components/schemas/Meta'
1203
+
1204
+ CampaignDetailResponse:
1205
+ type: object
1206
+ required: [data, meta]
1207
+ properties:
1208
+ data:
1209
+ $ref: '#/components/schemas/CampaignDetail'
1210
+ meta:
1211
+ $ref: '#/components/schemas/Meta'
1212
+
1213
+ CampaignTier:
1214
+ type: object
1215
+ required: [tierId, tierName, isEnabled, allocationPercent]
1216
+ properties:
1217
+ tierId:
1218
+ type: integer
1219
+ description: Targeting tier identifier.
1220
+ tierName:
1221
+ type: string
1222
+ description: Human-readable tier name.
1223
+ isEnabled:
1224
+ type: boolean
1225
+ description: Whether this tier is currently active.
1226
+ allocationPercent:
1227
+ type: number
1228
+ minimum: 0
1229
+ maximum: 100
1230
+ description: Share of campaign budget allocated to this tier.
1231
+
1232
+ CampaignTiersData:
1233
+ type: object
1234
+ required: [lastUpdate, tiers]
1235
+ properties:
1236
+ lastUpdate:
1237
+ type: string
1238
+ format: date-time
1239
+ nullable: true
1240
+ description: |
1241
+ ISO-8601 timestamp of the last manual tier status update, or null
1242
+ if tiers have never been updated.
1243
+ tiers:
1244
+ type: array
1245
+ items:
1246
+ $ref: '#/components/schemas/CampaignTier'
1247
+
1248
+ CampaignTiersResponse:
1249
+ type: object
1250
+ required: [data, meta]
1251
+ properties:
1252
+ data:
1253
+ $ref: '#/components/schemas/CampaignTiersData'
1254
+ meta:
1255
+ $ref: '#/components/schemas/Meta'
1256
+
1257
+ TierStatusUpdateItem:
1258
+ type: object
1259
+ required: [targetingTierId, isEnabled, newAllocationPercent]
1260
+ properties:
1261
+ targetingTierId:
1262
+ type: integer
1263
+ minimum: 1
1264
+ description: Targeting tier identifier.
1265
+ isEnabled:
1266
+ type: boolean
1267
+ description: Whether to enable or disable this tier.
1268
+ newAllocationPercent:
1269
+ type: number
1270
+ minimum: 0
1271
+ maximum: 100
1272
+ description: New budget share for this tier (all items must sum to 100).
1273
+
1274
+ UpdateCampaignTiersRequest:
1275
+ type: object
1276
+ required: [items]
1277
+ properties:
1278
+ items:
1279
+ type: array
1280
+ minItems: 1
1281
+ items:
1282
+ $ref: '#/components/schemas/TierStatusUpdateItem'
1283
+
1284
+ Genre:
1285
+ type: string
1286
+ description: Strictly validated against the platform's genre list.
1287
+ enum:
1288
+ - Alternative/Indie
1289
+ - Ambient/Sleep
1290
+ - Chill/Background
1291
+ - Classical
1292
+ - Country
1293
+ - Electronic/Dance
1294
+ - Hip-Hop/R&B
1295
+ - Latin/Reggaeton
1296
+ - Pop
1297
+ - Rock
1298
+ - Christmas
1299
+
1300
+ StrategyType:
1301
+ type: string
1302
+ enum:
1303
+ - maximum_growth
1304
+ - market_discovery
1305
+ - revenue_maximization
1306
+ - custom
1307
+
1308
+ CreativeDirection:
1309
+ description: |
1310
+ How the campaign's ad creative is produced. Omit entirely to use the
1311
+ platform's default (`do_it_for_me`).
1312
+ oneOf:
1313
+ - $ref: '#/components/schemas/DoItForMeCreativeDirection'
1314
+ - $ref: '#/components/schemas/FullControlCreativeDirection'
1315
+ discriminator:
1316
+ propertyName: type
1317
+ mapping:
1318
+ do_it_for_me: '#/components/schemas/DoItForMeCreativeDirection'
1319
+ full_control: '#/components/schemas/FullControlCreativeDirection'
1320
+
1321
+ DoItForMeCreativeDirection:
1322
+ type: object
1323
+ required: [type]
1324
+ properties:
1325
+ type:
1326
+ type: string
1327
+ enum: [do_it_for_me]
1328
+ description: Soundlink selects and produces the ad creative.
1329
+
1330
+ FullControlCreativeDirection:
1331
+ type: object
1332
+ required: [type, selectedCreatives]
1333
+ properties:
1334
+ type:
1335
+ type: string
1336
+ enum: [full_control]
1337
+ selectedCreatives:
1338
+ type: array
1339
+ minItems: 1
1340
+ items:
1341
+ $ref: '#/components/schemas/SelectedCreative'
1342
+ description: One or more previously imported video creatives to use for the ad. Required for full control.
1343
+
1344
+ SelectedCreative:
1345
+ type: object
1346
+ required: [videoId]
1347
+ properties:
1348
+ videoId:
1349
+ type: string
1350
+ format: uuid
1351
+ description: |
1352
+ ID of a video previously imported into your video library. Import
1353
+ videos via the video import endpoint before referencing them here.
1354
+
1355
+ CustomTier:
1356
+ type: object
1357
+ required: [name, percentBudget]
1358
+ properties:
1359
+ name:
1360
+ type: string
1361
+ countries:
1362
+ type: array
1363
+ items:
1364
+ type: string
1365
+ description: ISO 3166-1 alpha-2 country codes.
1366
+ language:
1367
+ type: string
1368
+ description: ISO 639-1 language code.
1369
+ percentBudget:
1370
+ type: number
1371
+ description: Share of the campaign budget allocated to this tier. All tiers in a request must sum to 100.
1372
+
1373
+ TierTargeting:
1374
+ type: object
1375
+ description: |
1376
+ Custom tier targeting. Required when `strategyType` is `custom`: provide a
1377
+ non-empty `customTierIds` and/or `customTiers` array. Omit entirely for
1378
+ non-custom strategies (platform default tiering applies).
1379
+ properties:
1380
+ customTierIds:
1381
+ type: array
1382
+ items:
1383
+ type: integer
1384
+ customTiers:
1385
+ type: array
1386
+ description: |
1387
+ Inline custom tiers to create with the campaign. At most 5 active
1388
+ tiers (percentBudget > 0) are allowed; inactive (0%) entries do not
1389
+ count toward that limit. Each active tier must receive at least
1390
+ $1.50 of dailyBudget (gross). percentBudget values must sum to 100.
1391
+ items:
1392
+ $ref: '#/components/schemas/CustomTier'
1393
+
1394
+ CreateCampaignRequestShared:
1395
+ type: object
1396
+ required: [spotifyUrl, dailyBudget, durationDays, genre]
1397
+ properties:
1398
+ spotifyUrl:
1399
+ type: string
1400
+ format: uri
1401
+ description: |
1402
+ Spotify track or playlist URL to promote. Must be a valid track or
1403
+ playlist link to a resource that currently exists on Spotify.
1404
+ dailyBudget:
1405
+ type: number
1406
+ minimum: 10
1407
+ description: |
1408
+ USD, per day. Must be at least 10 (same floor as the Soundlink UI).
1409
+ durationDays:
1410
+ description: |
1411
+ Campaign duration in days. Must be an integer from 7 to 30 (UI custom
1412
+ range), or 60, or 90 (UI dropdown extras).
1413
+ oneOf:
1414
+ - type: integer
1415
+ minimum: 7
1416
+ maximum: 30
1417
+ - type: integer
1418
+ enum: [60, 90]
1419
+ genre:
1420
+ $ref: '#/components/schemas/Genre'
1421
+ campaignName:
1422
+ type: string
1423
+ description: Optional. Server generates a default (track title + short random suffix) when omitted.
1424
+ creativeDirection:
1425
+ $ref: '#/components/schemas/CreativeDirection'
1426
+ trackOptions:
1427
+ type: object
1428
+ description: Options that only apply when `spotifyUrl` is a track link. Ignored when `spotifyUrl` is a playlist link.
1429
+ properties:
1430
+ artistIdFollow:
1431
+ type: string
1432
+ description: Pass-through artist identifier.
1433
+ clonedFromCampaignId:
1434
+ type: string
1435
+ format: uuid
1436
+ description: >-
1437
+ Optional UUID of a campaign in your organization this create is
1438
+ cloned from. Records lineage only — it does not copy settings from
1439
+ the source; all other create fields must still be provided. Unknown
1440
+ or other-organization IDs return `400 invalid_request`.
1441
+
1442
+ CreateCampaignRequestWithoutTiers:
1443
+ allOf:
1444
+ - $ref: '#/components/schemas/CreateCampaignRequestShared'
1445
+ - type: object
1446
+ required: [strategyType]
1447
+ properties:
1448
+ strategyType:
1449
+ type: string
1450
+ enum:
1451
+ - maximum_growth
1452
+ - market_discovery
1453
+ - revenue_maximization
1454
+ description: |
1455
+ Non-custom growth strategy. Do not send `tierTargeting` with these
1456
+ values; the platform applies default tiering.
1457
+ not:
1458
+ required: [tierTargeting]
1459
+
1460
+ CreateCampaignRequestCustom:
1461
+ allOf:
1462
+ - $ref: '#/components/schemas/CreateCampaignRequestShared'
1463
+ - type: object
1464
+ required: [strategyType, tierTargeting]
1465
+ properties:
1466
+ strategyType:
1467
+ type: string
1468
+ enum: [custom]
1469
+ description: |
1470
+ Custom growth strategy. Requires `tierTargeting` with a non-empty
1471
+ `customTierIds` and/or `customTiers` array.
1472
+ tierTargeting:
1473
+ $ref: '#/components/schemas/TierTargeting'
1474
+
1475
+ CreateCampaignRequest:
1476
+ description: |
1477
+ Create a wallet-funded campaign. When `strategyType` is `custom`,
1478
+ `tierTargeting` is required. For `maximum_growth`, `market_discovery`,
1479
+ or `revenue_maximization`, do not send `tierTargeting` (platform default
1480
+ tiering applies).
1481
+ oneOf:
1482
+ - $ref: '#/components/schemas/CreateCampaignRequestWithoutTiers'
1483
+ - $ref: '#/components/schemas/CreateCampaignRequestCustom'
1484
+
1485
+ CampaignCreateData:
1486
+ type: object
1487
+ required: [campaignId, status]
1488
+ properties:
1489
+ campaignId:
1490
+ type: string
1491
+ status:
1492
+ $ref: '#/components/schemas/CampaignStatus'
1493
+
1494
+ CreateCampaignResponse:
1495
+ type: object
1496
+ required: [data, meta]
1497
+ properties:
1498
+ data:
1499
+ $ref: '#/components/schemas/CampaignCreateData'
1500
+ meta:
1501
+ $ref: '#/components/schemas/Meta'
1502
+
1503
+ CampaignStopData:
1504
+ type: object
1505
+ required: [campaignId, status]
1506
+ properties:
1507
+ campaignId:
1508
+ type: string
1509
+ status:
1510
+ $ref: '#/components/schemas/CampaignStatus'
1511
+ description: Campaign status after stop (typically `stopped`).
674
1512
 
675
- ErrorResponse:
1513
+ StopCampaignResponse:
676
1514
  type: object
677
- required: [error, meta]
1515
+ required: [data, meta]
678
1516
  properties:
679
- error:
680
- $ref: '#/components/schemas/Error'
1517
+ data:
1518
+ $ref: '#/components/schemas/CampaignStopData'
681
1519
  meta:
682
1520
  $ref: '#/components/schemas/Meta'
683
1521
 
684
- # --- Campaign ---
1522
+ StrategyCatalogItem:
1523
+ type: object
1524
+ required: [strategyType, tierTargetingAllowed]
1525
+ properties:
1526
+ strategyType:
1527
+ $ref: '#/components/schemas/StrategyType'
1528
+ tierTargetingAllowed:
1529
+ type: boolean
1530
+ description: |
1531
+ When `false`, omit `tierTargeting` on create (platform default
1532
+ tiering applies). Only `custom` allows `tierTargeting`.
685
1533
 
686
- CampaignStatus:
1534
+ StrategiesCatalogData:
1535
+ type: object
1536
+ required: [strategies]
1537
+ properties:
1538
+ strategies:
1539
+ type: array
1540
+ items:
1541
+ $ref: '#/components/schemas/StrategyCatalogItem'
1542
+
1543
+ StrategiesCatalogResponse:
1544
+ type: object
1545
+ required: [data, meta]
1546
+ properties:
1547
+ data:
1548
+ $ref: '#/components/schemas/StrategiesCatalogData'
1549
+ meta:
1550
+ $ref: '#/components/schemas/Meta'
1551
+
1552
+ BudgetIncreaseMode:
687
1553
  type: string
688
- enum: [creating, active, paused, completed, failed]
1554
+ enum: [current_cycle, next_renewal, current_and_renewals]
1555
+ description: |
1556
+ Defaults to `current_and_renewals` when omitted on increase requests.
689
1557
 
690
- CampaignSummary:
1558
+ BudgetDecreaseMode:
1559
+ type: string
1560
+ enum: [current_cycle, current_and_renewals]
1561
+ description: |
1562
+ Defaults to `current_and_renewals` when omitted on decrease requests.
1563
+ `next_renewal` is not supported for decreases.
1564
+
1565
+ IncreaseCampaignBudgetRequest:
691
1566
  type: object
692
- required:
693
- [
694
- campaignId,
695
- organizationId,
696
- status,
697
- socialPlatform,
698
- dailyBudget,
699
- totalBudget,
700
- campaignDuration,
701
- createdAt,
702
- updatedAt,
703
- ]
1567
+ required: [amount]
1568
+ properties:
1569
+ amount:
1570
+ type: number
1571
+ description: |
1572
+ Wallet debit / top-up amount in USD. Must be positive, except
1573
+ `mode: next_renewal` with `targetDailyBudget` where `amount` may
1574
+ be `0`.
1575
+ mode:
1576
+ $ref: '#/components/schemas/BudgetIncreaseMode'
1577
+ targetDailyBudget:
1578
+ type: number
1579
+ minimum: 0
1580
+ exclusiveMinimum: true
1581
+ description: |
1582
+ Optional absolute next-cycle daily budget (USD). Most useful with
1583
+ `mode: next_renewal`.
1584
+
1585
+ IncreaseCampaignBudgetData:
1586
+ type: object
1587
+ required: [campaignId, mode, amount, walletBalance]
704
1588
  properties:
705
1589
  campaignId:
706
1590
  type: string
707
- organizationId:
708
- type: string
709
- status:
710
- $ref: '#/components/schemas/CampaignStatus'
711
- socialPlatform:
712
- type: string
713
- enum: [meta]
714
- dailyBudget:
1591
+ mode:
1592
+ $ref: '#/components/schemas/BudgetIncreaseMode'
1593
+ amount:
715
1594
  type: number
716
- description: USD
717
- totalBudget:
1595
+ walletBalance:
718
1596
  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.
1597
+ description: Organization wallet balance after the increase.
1598
+ walletNextCycleDailyBudget:
1599
+ type: number
1600
+ nullable: true
1601
+ description: Next-cycle daily budget when set by this request.
740
1602
 
741
- CampaignListResponse:
1603
+ IncreaseCampaignBudgetResponse:
742
1604
  type: object
743
1605
  required: [data, meta]
744
1606
  properties:
745
1607
  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'
1608
+ $ref: '#/components/schemas/IncreaseCampaignBudgetData'
755
1609
  meta:
756
1610
  $ref: '#/components/schemas/Meta'
757
1611
 
758
- CampaignDetailResponse:
1612
+ DecreaseCampaignBudgetRequest:
1613
+ type: object
1614
+ required: [targetDailyBudget]
1615
+ properties:
1616
+ targetDailyBudget:
1617
+ type: number
1618
+ minimum: 10
1619
+ description: |
1620
+ New daily budget in USD (gross). Must be at least `$10`/day and
1621
+ lower than the campaign's current daily budget.
1622
+ mode:
1623
+ $ref: '#/components/schemas/BudgetDecreaseMode'
1624
+
1625
+ DecreaseCampaignBudgetData:
1626
+ type: object
1627
+ required: [campaignId, mode, targetDailyBudget, accepted]
1628
+ properties:
1629
+ campaignId:
1630
+ type: string
1631
+ mode:
1632
+ $ref: '#/components/schemas/BudgetDecreaseMode'
1633
+ targetDailyBudget:
1634
+ type: number
1635
+ accepted:
1636
+ type: boolean
1637
+ enum: [true]
1638
+ description: |
1639
+ Always `true` on success. Unused budget refund is applied
1640
+ asynchronously after acceptance.
1641
+ walletNextCycleDailyBudget:
1642
+ type: number
1643
+ nullable: true
1644
+ description: |
1645
+ Present for `current_and_renewals` when the next-cycle daily
1646
+ budget was updated. Omitted for `current_cycle`.
1647
+
1648
+ DecreaseCampaignBudgetResponse:
759
1649
  type: object
760
1650
  required: [data, meta]
761
1651
  properties:
762
1652
  data:
763
- $ref: '#/components/schemas/CampaignDetail'
1653
+ $ref: '#/components/schemas/DecreaseCampaignBudgetData'
764
1654
  meta:
765
1655
  $ref: '#/components/schemas/Meta'
766
1656
 
@@ -1159,24 +2049,71 @@ components:
1159
2049
  type: number
1160
2050
  description: Streams per listener (`streams / listeners`). Zero if `listeners` is zero.
1161
2051
 
1162
- EngagementBreakdownResponse:
2052
+ # --- Videos ---
2053
+
2054
+ VideoImportRequest:
2055
+ type: object
2056
+ required: [url]
2057
+ properties:
2058
+ url:
2059
+ type: string
2060
+ format: uri
2061
+ description: Public HTTPS URL to an MP4 file (max 50 MB).
2062
+
2063
+ VideoImportStatus:
2064
+ type: string
2065
+ enum: [processing, ready, failed]
2066
+
2067
+ VideoImportStartData:
2068
+ type: object
2069
+ required: [sessionId, status]
2070
+ properties:
2071
+ sessionId:
2072
+ type: string
2073
+ format: uuid
2074
+ description: Upload session ID for status polling
2075
+ status:
2076
+ $ref: '#/components/schemas/VideoImportStatus'
2077
+ videoId:
2078
+ type: string
2079
+ format: uuid
2080
+ nullable: true
2081
+ description: Present when `status` is `ready` (new or duplicate video)
2082
+
2083
+ VideoImportStartResponse:
1163
2084
  type: object
1164
2085
  required: [data, meta]
1165
2086
  properties:
1166
2087
  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'
2088
+ $ref: '#/components/schemas/VideoImportStartData'
2089
+ meta:
2090
+ $ref: '#/components/schemas/Meta'
2091
+
2092
+ VideoImportStatusData:
2093
+ type: object
2094
+ required: [sessionId, status]
2095
+ properties:
2096
+ sessionId:
2097
+ type: string
2098
+ format: uuid
2099
+ status:
2100
+ $ref: '#/components/schemas/VideoImportStatus'
2101
+ videoId:
2102
+ type: string
2103
+ format: uuid
2104
+ nullable: true
2105
+ description: Background video ID when `status` is `ready`
2106
+ error:
2107
+ type: string
2108
+ nullable: true
2109
+ description: Failure reason when `status` is `failed`
2110
+
2111
+ VideoImportStatusResponse:
2112
+ type: object
2113
+ required: [data, meta]
2114
+ properties:
2115
+ data:
2116
+ $ref: '#/components/schemas/VideoImportStatusData'
1180
2117
  meta:
1181
2118
  $ref: '#/components/schemas/Meta'
1182
2119
 
@@ -1203,6 +2140,30 @@ components:
1203
2140
  meta:
1204
2141
  requestId: 550e8400-e29b-41d4-a716-446655440000
1205
2142
 
2143
+ CreateCampaignBadRequest:
2144
+ description: |
2145
+ Missing or malformed request body, or a missing/empty
2146
+ `Idempotency-Key` header.
2147
+ content:
2148
+ application/json:
2149
+ schema:
2150
+ $ref: '#/components/schemas/ErrorResponse'
2151
+ examples:
2152
+ missing_field:
2153
+ value:
2154
+ error:
2155
+ code: invalid_request
2156
+ message: 'Missing required field: spotifyUrl.'
2157
+ meta:
2158
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2159
+ missing_idempotency_key:
2160
+ value:
2161
+ error:
2162
+ code: invalid_request
2163
+ message: 'Idempotency-Key header is required and must not be empty.'
2164
+ meta:
2165
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2166
+
1206
2167
  Unauthorized:
1207
2168
  description: Missing, malformed, revoked, or expired API key
1208
2169
  headers:
@@ -1219,14 +2180,14 @@ components:
1219
2180
  value:
1220
2181
  error:
1221
2182
  code: invalid_api_key
1222
- message: 'Authorization header is missing or malformed.'
2183
+ message: 'Missing or malformed x-api-key header.'
1223
2184
  meta:
1224
2185
  requestId: 550e8400-e29b-41d4-a716-446655440000
1225
2186
  api_key_revoked:
1226
2187
  value:
1227
2188
  error:
1228
2189
  code: api_key_revoked
1229
- message: 'This API key has been revoked. Contact Soundlink Engineering to mint a new key.'
2190
+ message: 'This API key has been revoked. Create a new key in Settings → Developer → API keys.'
1230
2191
  meta:
1231
2192
  requestId: 550e8400-e29b-41d4-a716-446655440000
1232
2193
 
@@ -1243,8 +2204,145 @@ components:
1243
2204
  meta:
1244
2205
  requestId: 550e8400-e29b-41d4-a716-446655440000
1245
2206
 
2207
+ CreateCampaignForbidden:
2208
+ description: |
2209
+ Valid key but missing the `campaigns:write` scope, or the calling
2210
+ organization is not enabled for wallet billing.
2211
+ content:
2212
+ application/json:
2213
+ schema:
2214
+ $ref: '#/components/schemas/ErrorResponse'
2215
+ examples:
2216
+ insufficient_scope:
2217
+ value:
2218
+ error:
2219
+ code: insufficient_scope
2220
+ message: 'This key does not have the campaigns:write scope.'
2221
+ meta:
2222
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2223
+ wallet_not_enabled:
2224
+ value:
2225
+ error:
2226
+ code: wallet_not_enabled
2227
+ message: 'This organization does not have wallet billing enabled.'
2228
+ meta:
2229
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2230
+
2231
+ InsufficientCredit:
2232
+ description: Wallet balance is too low to cover `dailyBudget * durationDays`
2233
+ content:
2234
+ application/json:
2235
+ schema:
2236
+ $ref: '#/components/schemas/ErrorResponse'
2237
+ example:
2238
+ error:
2239
+ code: insufficient_credit
2240
+ message: 'Insufficient wallet balance for this campaign.'
2241
+ details:
2242
+ available: 120.00
2243
+ required: 350.00
2244
+ meta:
2245
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2246
+
2247
+ CreateCampaignUnprocessable:
2248
+ description: Request body is well-formed but semantically invalid
2249
+ content:
2250
+ application/json:
2251
+ schema:
2252
+ $ref: '#/components/schemas/ErrorResponse'
2253
+ examples:
2254
+ invalid_genre:
2255
+ value:
2256
+ error:
2257
+ code: invalid_genre
2258
+ message: 'genre must be one of the supported values.'
2259
+ meta:
2260
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2261
+ invalid_duration_or_budget:
2262
+ value:
2263
+ error:
2264
+ code: invalid_duration_or_budget
2265
+ message: 'dailyBudget and durationDays must be greater than 0.'
2266
+ meta:
2267
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2268
+ invalid_daily_budget:
2269
+ value:
2270
+ error:
2271
+ code: invalid_daily_budget
2272
+ message: 'dailyBudget must be at least 10 (USD per day).'
2273
+ meta:
2274
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2275
+ invalid_duration_days:
2276
+ value:
2277
+ error:
2278
+ code: invalid_duration_days
2279
+ message: 'durationDays must be an integer from 7 to 30, or 60, or 90.'
2280
+ meta:
2281
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2282
+ invalid_spotify_url:
2283
+ summary: Malformed URL or Spotify track/playlist does not exist
2284
+ value:
2285
+ error:
2286
+ code: invalid_spotify_url
2287
+ message: 'Spotify track not found.'
2288
+ meta:
2289
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2290
+ invalid_tier_budget_allocation:
2291
+ value:
2292
+ error:
2293
+ code: invalid_tier_budget_allocation
2294
+ message: 'tierTargeting.customTiers[].percentBudget must sum to 100.'
2295
+ meta:
2296
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2297
+ invalid_request_tier_targeting:
2298
+ value:
2299
+ error:
2300
+ code: invalid_request
2301
+ message: 'tierTargeting is only allowed when strategyType is custom.'
2302
+ meta:
2303
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2304
+
2305
+ IdempotencyKeyConflict:
2306
+ description: |
2307
+ The `Idempotency-Key` was reused with a materially different request
2308
+ body, or a request with the same key is still in progress.
2309
+ content:
2310
+ application/json:
2311
+ schema:
2312
+ $ref: '#/components/schemas/ErrorResponse'
2313
+ examples:
2314
+ conflicting_body:
2315
+ value:
2316
+ error:
2317
+ code: idempotency_key_conflict
2318
+ message: 'This Idempotency-Key was already used with a different request body.'
2319
+ meta:
2320
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2321
+ in_progress:
2322
+ value:
2323
+ error:
2324
+ code: idempotency_key_conflict
2325
+ message: 'A request with this Idempotency-Key is still processing. Retry after a short delay.'
2326
+ meta:
2327
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2328
+
2329
+ TierUpdateCooldown:
2330
+ description: |
2331
+ Campaign tiers were updated in the last 72 hours. Wait for the cooldown
2332
+ to end before updating again.
2333
+ content:
2334
+ application/json:
2335
+ schema:
2336
+ $ref: '#/components/schemas/ErrorResponse'
2337
+ example:
2338
+ error:
2339
+ code: tier_update_cooldown
2340
+ message: 'Campaign tiers were updated in the last 72 hours. Wait for the cooldown to end before updating again.'
2341
+ meta:
2342
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2343
+
1246
2344
  NotFound:
1247
- description: Campaign not found, belongs to another org, or feature flag is off
2345
+ description: Campaign not found or belongs to another organization
1248
2346
  content:
1249
2347
  application/json:
1250
2348
  schema: