soundlink 1.1.1 → 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.
- package/CHANGELOG.md +7 -1
- package/README.md +103 -24
- package/dist/cjs/index.cjs +175 -30
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +254 -41
- package/dist/esm/index.js +175 -30
- package/dist/esm/index.js.map +1 -1
- package/openapi/soundlink-public-api-v1.yaml +1309 -211
- package/package.json +1 -1
|
@@ -3,11 +3,11 @@ info:
|
|
|
3
3
|
title: Soundlink Public API
|
|
4
4
|
version: 0.0.1-draft
|
|
5
5
|
description: |
|
|
6
|
-
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
|
326
|
-
with `startDate` / `endDate`. **Responses are
|
|
327
|
-
|
|
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":"
|
|
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":"
|
|
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
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
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:**
|
|
509
|
-
Re-fetching and re-ingesting on the
|
|
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 (
|
|
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
|
-
|
|
1513
|
+
StopCampaignResponse:
|
|
676
1514
|
type: object
|
|
677
|
-
required: [
|
|
1515
|
+
required: [data, meta]
|
|
678
1516
|
properties:
|
|
679
|
-
|
|
680
|
-
$ref: '#/components/schemas/
|
|
1517
|
+
data:
|
|
1518
|
+
$ref: '#/components/schemas/CampaignStopData'
|
|
681
1519
|
meta:
|
|
682
1520
|
$ref: '#/components/schemas/Meta'
|
|
683
1521
|
|
|
684
|
-
|
|
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
|
-
|
|
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: [
|
|
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
|
-
|
|
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
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
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
|
-
|
|
708
|
-
|
|
709
|
-
|
|
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
|
-
|
|
717
|
-
totalBudget:
|
|
1595
|
+
walletBalance:
|
|
718
1596
|
type: number
|
|
719
|
-
description:
|
|
720
|
-
|
|
721
|
-
type:
|
|
722
|
-
|
|
723
|
-
|
|
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
|
-
|
|
1603
|
+
IncreaseCampaignBudgetResponse:
|
|
742
1604
|
type: object
|
|
743
1605
|
required: [data, meta]
|
|
744
1606
|
properties:
|
|
745
1607
|
data:
|
|
746
|
-
|
|
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
|
-
|
|
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/
|
|
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
|
-
|
|
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
|
-
|
|
1168
|
-
|
|
1169
|
-
|
|
1170
|
-
|
|
1171
|
-
|
|
1172
|
-
|
|
1173
|
-
|
|
1174
|
-
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
1179
|
-
|
|
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: '
|
|
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.
|
|
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
|
|
2345
|
+
description: Campaign not found or belongs to another organization
|
|
1248
2346
|
content:
|
|
1249
2347
|
application/json:
|
|
1250
2348
|
schema:
|