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