soundlink 2.2.0 → 2.4.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 +16 -0
- package/README.md +26 -3
- package/dist/cjs/index.cjs +112 -1
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +169 -14
- package/dist/esm/index.js +112 -1
- package/dist/esm/index.js.map +1 -1
- package/openapi/soundlink-public-api-v1.yaml +854 -308
- package/package.json +2 -2
|
@@ -39,7 +39,9 @@ info:
|
|
|
39
39
|
| Metrics reads (overview, breakdown, exports) | `metrics:read` | API key (Bearer) or OAuth Bearer |
|
|
40
40
|
| Campaign writes (create, stop, budget, tier updates) | `campaigns:write` | API key (Bearer) or OAuth Bearer |
|
|
41
41
|
| Video import / import status | `videos:write` | API key (Bearer) or OAuth Bearer |
|
|
42
|
-
| Soundlink reads (list, detail, metrics overview/
|
|
42
|
+
| Soundlink reads (list, detail, metrics overview/breakdown/engagement, JSONL exports) | `soundlinks:read` | API key (Bearer) or OAuth Bearer |
|
|
43
|
+
| Soundlink writes (create, archive, test events) | `soundlinks:write` | API key (Bearer) or OAuth Bearer |
|
|
44
|
+
| Wallet read (`GET /v1/wallet`) | `wallet:read` | API key (Bearer) or OAuth Bearer |
|
|
43
45
|
|
|
44
46
|
Per-operation scope requirements are also marked with `x-required-scope`
|
|
45
47
|
(except `GET /v1/ping`, which accepts any valid credential with at least
|
|
@@ -63,6 +65,8 @@ security:
|
|
|
63
65
|
tags:
|
|
64
66
|
- name: System
|
|
65
67
|
description: Connectivity and auth verification
|
|
68
|
+
- name: Wallet
|
|
69
|
+
description: Organization wallet balance
|
|
66
70
|
- name: Campaigns
|
|
67
71
|
description: Campaign listing, detail, creation, and wallet management (budget, stop, tiers)
|
|
68
72
|
- name: Metrics
|
|
@@ -70,7 +74,7 @@ tags:
|
|
|
70
74
|
- name: Videos
|
|
71
75
|
description: Partner video library import for Full Control campaigns
|
|
72
76
|
- name: Soundlinks
|
|
73
|
-
description: Soundlink listing, detail, and performance metrics
|
|
77
|
+
description: Soundlink listing, detail, creation, archive, and performance metrics
|
|
74
78
|
|
|
75
79
|
paths:
|
|
76
80
|
/v1/ping:
|
|
@@ -113,6 +117,45 @@ paths:
|
|
|
113
117
|
'429': { $ref: '#/components/responses/RateLimited' }
|
|
114
118
|
'500': { $ref: '#/components/responses/InternalError' }
|
|
115
119
|
|
|
120
|
+
/v1/wallet:
|
|
121
|
+
get:
|
|
122
|
+
operationId: getWallet
|
|
123
|
+
summary: Get organization wallet balance
|
|
124
|
+
description: |
|
|
125
|
+
Returns the organization wallet on the API key. Requires `wallet:read`.
|
|
126
|
+
Existing keys do not have this scope until it is granted.
|
|
127
|
+
|
|
128
|
+
`available` is the amount `POST /v1/campaigns` checks before reserving.
|
|
129
|
+
When create returns `402 insufficient_credit`, `error.details.available`
|
|
130
|
+
matches this field. `reserved` is the sum of active reservations.
|
|
131
|
+
|
|
132
|
+
An organization with no credits row returns zeros and `updatedAt: null`.
|
|
133
|
+
tags: [Wallet]
|
|
134
|
+
x-required-scope: wallet:read
|
|
135
|
+
security:
|
|
136
|
+
- apiKeyBearerAuth: []
|
|
137
|
+
- oauthBearer: []
|
|
138
|
+
responses:
|
|
139
|
+
'200':
|
|
140
|
+
description: Wallet snapshot
|
|
141
|
+
content:
|
|
142
|
+
application/json:
|
|
143
|
+
schema:
|
|
144
|
+
$ref: '#/components/schemas/GetWalletResponse'
|
|
145
|
+
example:
|
|
146
|
+
data:
|
|
147
|
+
balance: 500
|
|
148
|
+
available: 350
|
|
149
|
+
reserved: 150
|
|
150
|
+
currency: USD
|
|
151
|
+
updatedAt: '2026-04-01T10:00:00Z'
|
|
152
|
+
meta:
|
|
153
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
154
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
155
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
156
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
157
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
158
|
+
|
|
116
159
|
/v1/strategies:
|
|
117
160
|
get:
|
|
118
161
|
operationId: listStrategies
|
|
@@ -194,6 +237,12 @@ paths:
|
|
|
194
237
|
dailyBudget: 20.0
|
|
195
238
|
totalBudget: 140.0
|
|
196
239
|
campaignDuration: 7
|
|
240
|
+
artistId: 4gzpq5DPGxSnKTe4SA8HAU
|
|
241
|
+
artistName: Coldplay
|
|
242
|
+
trackId: 3AJwUDP919kvQ9QcozQPxg
|
|
243
|
+
playlistId: null
|
|
244
|
+
trackName: Yellow
|
|
245
|
+
campaignUrl: https://getsoundlink.com/orgs/org_xyz/insights/V1StGXR8_Z5jdHi6B-myT
|
|
197
246
|
createdAt: '2026-04-01T10:00:00Z'
|
|
198
247
|
updatedAt: '2026-04-08T12:00:00Z'
|
|
199
248
|
pagination:
|
|
@@ -343,6 +392,12 @@ paths:
|
|
|
343
392
|
totalBudget: 140.0
|
|
344
393
|
campaignDuration: 7
|
|
345
394
|
strategyType: custom
|
|
395
|
+
artistId: 4gzpq5DPGxSnKTe4SA8HAU
|
|
396
|
+
artistName: Coldplay
|
|
397
|
+
trackId: 3AJwUDP919kvQ9QcozQPxg
|
|
398
|
+
playlistId: null
|
|
399
|
+
trackName: Yellow
|
|
400
|
+
campaignUrl: https://getsoundlink.com/orgs/org_xyz/insights/V1StGXR8_Z5jdHi6B-myT
|
|
346
401
|
createdAt: '2026-04-01T10:00:00Z'
|
|
347
402
|
updatedAt: '2026-04-08T12:00:00Z'
|
|
348
403
|
meta:
|
|
@@ -363,9 +418,17 @@ paths:
|
|
|
363
418
|
|
|
364
419
|
**Wallet campaigns only** (`generation: 3`).
|
|
365
420
|
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
`
|
|
421
|
+
**Statuses that accept stop** and return `stopped`: `active`,
|
|
422
|
+
`inactive`, `restarting`, `restart_failed`, `renew_failed`, and
|
|
423
|
+
`renew_awaiting_charge`.
|
|
424
|
+
|
|
425
|
+
**Already terminal:** `stopped` and `ended` succeed without changing
|
|
426
|
+
status. The response `status` stays `stopped` or `ended`. A second
|
|
427
|
+
stop does not double-refund.
|
|
428
|
+
|
|
429
|
+
**Retry later (`400 invalid_request`):** `creating` and `renewing`.
|
|
430
|
+
|
|
431
|
+
The `Idempotency-Key` header is **required** so retries of the same
|
|
369
432
|
request replay the original response without repeating side effects.
|
|
370
433
|
|
|
371
434
|
**Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
|
|
@@ -398,6 +461,56 @@ paths:
|
|
|
398
461
|
'429': { $ref: '#/components/responses/RateLimited' }
|
|
399
462
|
'500': { $ref: '#/components/responses/InternalError' }
|
|
400
463
|
|
|
464
|
+
/v1/campaigns/{campaignId}/auto-renew:
|
|
465
|
+
put:
|
|
466
|
+
operationId: updateCampaignAutoRenew
|
|
467
|
+
summary: Toggle wallet campaign auto-renew
|
|
468
|
+
description: |
|
|
469
|
+
Sets auto-renew for a wallet-funded campaign. Requires the
|
|
470
|
+
`campaigns:write` scope and an `Idempotency-Key` header.
|
|
471
|
+
|
|
472
|
+
**Wallet campaigns only** (`generation: 3`). Non-wallet campaigns
|
|
473
|
+
return `400`. Allowed when the campaign status is `active` or
|
|
474
|
+
`renew_failed`. A matching stored value is a no-op success.
|
|
475
|
+
|
|
476
|
+
**Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
|
|
477
|
+
tags: [Campaigns]
|
|
478
|
+
x-required-scope: campaigns:write
|
|
479
|
+
security:
|
|
480
|
+
- apiKeyBearerAuth: []
|
|
481
|
+
- oauthBearer: []
|
|
482
|
+
parameters:
|
|
483
|
+
- $ref: '#/components/parameters/campaignId'
|
|
484
|
+
- $ref: '#/components/parameters/idempotencyKey'
|
|
485
|
+
requestBody:
|
|
486
|
+
required: true
|
|
487
|
+
content:
|
|
488
|
+
application/json:
|
|
489
|
+
schema:
|
|
490
|
+
$ref: '#/components/schemas/UpdateCampaignAutoRenewRequest'
|
|
491
|
+
example:
|
|
492
|
+
autoRenew: true
|
|
493
|
+
responses:
|
|
494
|
+
'200':
|
|
495
|
+
description: Auto-renew updated
|
|
496
|
+
content:
|
|
497
|
+
application/json:
|
|
498
|
+
schema:
|
|
499
|
+
$ref: '#/components/schemas/UpdateCampaignAutoRenewResponse'
|
|
500
|
+
example:
|
|
501
|
+
data:
|
|
502
|
+
campaignId: campaign-uuid
|
|
503
|
+
autoRenew: true
|
|
504
|
+
meta:
|
|
505
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
506
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
507
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
508
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
509
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
510
|
+
'409': { $ref: '#/components/responses/IdempotencyKeyConflict' }
|
|
511
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
512
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
513
|
+
|
|
401
514
|
/v1/campaigns/{campaignId}/budget/increase:
|
|
402
515
|
post:
|
|
403
516
|
operationId: increaseCampaignBudget
|
|
@@ -487,8 +600,10 @@ paths:
|
|
|
487
600
|
is applied asynchronously after acceptance (`accepted: true`).
|
|
488
601
|
|
|
489
602
|
Domain rules (also returned as `invalid_request` when violated):
|
|
490
|
-
- `targetDailyBudget` must be at least
|
|
491
|
-
|
|
603
|
+
- `targetDailyBudget` must be at least the campaign's enabled-ad-set
|
|
604
|
+
minimum gross (`minLowerDailyBudgetGrossCurrent`, or the max of
|
|
605
|
+
current and next when `mode` is `current_and_renewals`) and lower
|
|
606
|
+
than the current daily budget
|
|
492
607
|
- more than 3 days must remain in the current cycle
|
|
493
608
|
|
|
494
609
|
**Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
|
|
@@ -706,6 +821,75 @@ paths:
|
|
|
706
821
|
'429': { $ref: '#/components/responses/RateLimited' }
|
|
707
822
|
'500': { $ref: '#/components/responses/InternalError' }
|
|
708
823
|
|
|
824
|
+
/v1/campaigns/{campaignId}/metrics/creatives:
|
|
825
|
+
get:
|
|
826
|
+
operationId: getCampaignCreativeMetrics
|
|
827
|
+
summary: Campaign creative metrics
|
|
828
|
+
description: |
|
|
829
|
+
Lifetime creative performance for one campaign, grouped by background
|
|
830
|
+
video. Each child is one ad creative. This is a
|
|
831
|
+
snapshot, not a date range. `startDate` and `endDate` are rejected.
|
|
832
|
+
|
|
833
|
+
Spend is omitted until media spend and fees can be split. Ratios use
|
|
834
|
+
the same lifetime basis as the Creatives tab.
|
|
835
|
+
|
|
836
|
+
Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
|
|
837
|
+
tags: [Metrics]
|
|
838
|
+
security:
|
|
839
|
+
- apiKeyBearerAuth: []
|
|
840
|
+
- oauthBearer: []
|
|
841
|
+
x-required-scope: metrics:read
|
|
842
|
+
parameters:
|
|
843
|
+
- $ref: '#/components/parameters/campaignId'
|
|
844
|
+
responses:
|
|
845
|
+
'200':
|
|
846
|
+
description: Creative groups for the campaign
|
|
847
|
+
content:
|
|
848
|
+
application/json:
|
|
849
|
+
schema:
|
|
850
|
+
$ref: '#/components/schemas/CreativeMetricsResponse'
|
|
851
|
+
example:
|
|
852
|
+
data:
|
|
853
|
+
creatives:
|
|
854
|
+
- video_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
|
|
855
|
+
caption: Late night version
|
|
856
|
+
listeners: 400
|
|
857
|
+
followers: 80
|
|
858
|
+
link_clicks: 280
|
|
859
|
+
cpl: 0.25
|
|
860
|
+
cpf: 1.25
|
|
861
|
+
cpc_linkclick: 0.357
|
|
862
|
+
frequency: 1.8
|
|
863
|
+
children:
|
|
864
|
+
- caption: Late night version
|
|
865
|
+
language: en
|
|
866
|
+
spotify_track_id: 11dFghVXANMlKmJXsNCbNl
|
|
867
|
+
listeners: 200
|
|
868
|
+
followers: 40
|
|
869
|
+
link_clicks: 120
|
|
870
|
+
cpl: 0.3
|
|
871
|
+
cpf: 1.5
|
|
872
|
+
cpc_linkclick: 0.5
|
|
873
|
+
frequency: 2
|
|
874
|
+
- caption: Daytime version
|
|
875
|
+
language: en
|
|
876
|
+
spotify_track_id: 11dFghVXANMlKmJXsNCbNl
|
|
877
|
+
listeners: 200
|
|
878
|
+
followers: 40
|
|
879
|
+
link_clicks: 160
|
|
880
|
+
cpl: 0.2
|
|
881
|
+
cpf: 1
|
|
882
|
+
cpc_linkclick: 0.25
|
|
883
|
+
frequency: 1.5
|
|
884
|
+
meta:
|
|
885
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
886
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
887
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
888
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
889
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
890
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
891
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
892
|
+
|
|
709
893
|
/v1/campaigns/{campaignId}/metrics/breakdown:
|
|
710
894
|
get:
|
|
711
895
|
operationId: getCampaignMetricsBreakdown
|
|
@@ -1123,6 +1307,82 @@ paths:
|
|
|
1123
1307
|
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1124
1308
|
'500': { $ref: '#/components/responses/InternalError' }
|
|
1125
1309
|
|
|
1310
|
+
post:
|
|
1311
|
+
operationId: createSoundlink
|
|
1312
|
+
summary: Create a self-serve soundlink
|
|
1313
|
+
description: |
|
|
1314
|
+
Creates a self-serve soundlink in the organization. This is the Public
|
|
1315
|
+
API equivalent of the in-app create flow. It does not create a wallet
|
|
1316
|
+
campaign and does not appear on `GET /v1/campaigns`.
|
|
1317
|
+
|
|
1318
|
+
Requires the `soundlinks:write` scope.
|
|
1319
|
+
|
|
1320
|
+
`Idempotency-Key` is **required**. Reusing the key with an unchanged
|
|
1321
|
+
body replays the original `201`; a different body returns
|
|
1322
|
+
`409 idempotency_key_conflict`. Keys are honored for 24 hours.
|
|
1323
|
+
|
|
1324
|
+
**Auth:** Accepts API key or OAuth Bearer (`soundlinks:write`).
|
|
1325
|
+
tags: [Soundlinks]
|
|
1326
|
+
security:
|
|
1327
|
+
- apiKeyBearerAuth: []
|
|
1328
|
+
- oauthBearer: []
|
|
1329
|
+
x-required-scope: soundlinks:write
|
|
1330
|
+
parameters:
|
|
1331
|
+
- $ref: '#/components/parameters/idempotencyKey'
|
|
1332
|
+
requestBody:
|
|
1333
|
+
required: true
|
|
1334
|
+
content:
|
|
1335
|
+
application/json:
|
|
1336
|
+
schema:
|
|
1337
|
+
$ref: '#/components/schemas/CreateSoundlinkRequest'
|
|
1338
|
+
examples:
|
|
1339
|
+
track:
|
|
1340
|
+
summary: Track soundlink
|
|
1341
|
+
value:
|
|
1342
|
+
name: Midnight Drive
|
|
1343
|
+
spotifyUrl: 'https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl'
|
|
1344
|
+
autoFollow: true
|
|
1345
|
+
artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
|
|
1346
|
+
metaPixelId: '1234567890123456'
|
|
1347
|
+
metaConversionAccessToken: 'EAAB...'
|
|
1348
|
+
playlist:
|
|
1349
|
+
summary: Playlist soundlink
|
|
1350
|
+
value:
|
|
1351
|
+
name: Late Night Mix
|
|
1352
|
+
spotifyUrl: 'https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M'
|
|
1353
|
+
responses:
|
|
1354
|
+
'201':
|
|
1355
|
+
description: Soundlink created
|
|
1356
|
+
content:
|
|
1357
|
+
application/json:
|
|
1358
|
+
schema:
|
|
1359
|
+
$ref: '#/components/schemas/SoundlinkDetailResponse'
|
|
1360
|
+
example:
|
|
1361
|
+
data:
|
|
1362
|
+
soundlinkId: V1StGXR8_Z5jdHi6B-myT
|
|
1363
|
+
organizationId: a7ac3173-2f71-4e79-921f-d15d7112dd11
|
|
1364
|
+
name: Midnight Drive
|
|
1365
|
+
url: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
|
|
1366
|
+
targetType: track
|
|
1367
|
+
spotifyUrl: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
|
|
1368
|
+
status: active
|
|
1369
|
+
createdAt: '2026-04-01T10:00:00Z'
|
|
1370
|
+
autoFollow: true
|
|
1371
|
+
artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
|
|
1372
|
+
metaPixelId: '1234567890123456'
|
|
1373
|
+
tiktokPixelId: null
|
|
1374
|
+
appleMusicUrl: null
|
|
1375
|
+
youtubeMusicUrl: null
|
|
1376
|
+
meta:
|
|
1377
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1378
|
+
'400': { $ref: '#/components/responses/CreateSoundlinkBadRequest' }
|
|
1379
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1380
|
+
'403': { $ref: '#/components/responses/CreateSoundlinkForbidden' }
|
|
1381
|
+
'409': { $ref: '#/components/responses/IdempotencyKeyConflict' }
|
|
1382
|
+
'422': { $ref: '#/components/responses/CreateSoundlinkUnprocessable' }
|
|
1383
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1384
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1385
|
+
|
|
1126
1386
|
/v1/soundlinks/{soundlinkId}:
|
|
1127
1387
|
get:
|
|
1128
1388
|
operationId: getSoundlink
|
|
@@ -1157,10 +1417,109 @@ paths:
|
|
|
1157
1417
|
status: active
|
|
1158
1418
|
createdAt: '2026-04-01T10:00:00Z'
|
|
1159
1419
|
autoFollow: true
|
|
1420
|
+
artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
|
|
1421
|
+
metaPixelId: '1234567890123456'
|
|
1422
|
+
tiktokPixelId: null
|
|
1423
|
+
appleMusicUrl: null
|
|
1424
|
+
youtubeMusicUrl: null
|
|
1425
|
+
meta:
|
|
1426
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1427
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1428
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1429
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
1430
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1431
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1432
|
+
delete:
|
|
1433
|
+
operationId: archiveSoundlink
|
|
1434
|
+
summary: Archive a soundlink
|
|
1435
|
+
description: |
|
|
1436
|
+
Archives a self-serve soundlink (`status: archived`). Same as Archive
|
|
1437
|
+
in the app: the public page stops resolving, and this cannot be undone
|
|
1438
|
+
via the Public API.
|
|
1439
|
+
|
|
1440
|
+
Requires `soundlinks:write`. Campaign-linked soundlinks, soundlinks
|
|
1441
|
+
that are not `active`, and ids that do not belong to the org return
|
|
1442
|
+
`404`. Does not require `Idempotency-Key`.
|
|
1443
|
+
tags: [Soundlinks]
|
|
1444
|
+
security:
|
|
1445
|
+
- apiKeyBearerAuth: []
|
|
1446
|
+
- oauthBearer: []
|
|
1447
|
+
x-required-scope: soundlinks:write
|
|
1448
|
+
parameters:
|
|
1449
|
+
- $ref: '#/components/parameters/soundlinkId'
|
|
1450
|
+
responses:
|
|
1451
|
+
'200':
|
|
1452
|
+
description: Soundlink archived
|
|
1453
|
+
content:
|
|
1454
|
+
application/json:
|
|
1455
|
+
schema:
|
|
1456
|
+
$ref: '#/components/schemas/SoundlinkDetailResponse'
|
|
1457
|
+
example:
|
|
1458
|
+
data:
|
|
1459
|
+
soundlinkId: V1StGXR8_Z5jdHi6B-myT
|
|
1460
|
+
organizationId: a7ac3173-2f71-4e79-921f-d15d7112dd11
|
|
1461
|
+
name: Midnight Drive
|
|
1462
|
+
url: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
|
|
1463
|
+
targetType: track
|
|
1464
|
+
spotifyUrl: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
|
|
1465
|
+
status: archived
|
|
1466
|
+
createdAt: '2026-04-01T10:00:00Z'
|
|
1467
|
+
autoFollow: true
|
|
1468
|
+
artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
|
|
1160
1469
|
metaPixelId: '1234567890123456'
|
|
1161
1470
|
tiktokPixelId: null
|
|
1471
|
+
appleMusicUrl: null
|
|
1472
|
+
youtubeMusicUrl: null
|
|
1473
|
+
meta:
|
|
1474
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1475
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1476
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1477
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
1478
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1479
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1480
|
+
|
|
1481
|
+
/v1/soundlinks/{soundlinkId}/test-events:
|
|
1482
|
+
post:
|
|
1483
|
+
operationId: sendSoundlinkTestEvents
|
|
1484
|
+
summary: Send a test conversion event for a soundlink
|
|
1485
|
+
description: |
|
|
1486
|
+
Sends the same test conversion event as the in-app "send test event"
|
|
1487
|
+
action. Pixels and tokens are read from the soundlink. This request
|
|
1488
|
+
has no body.
|
|
1489
|
+
|
|
1490
|
+
When the soundlink has a Meta pixel, a live Meta Conversions API event
|
|
1491
|
+
named `Soundlink Stream` is sent to that pixel. When it has a TikTok
|
|
1492
|
+
pixel, a live TikTok `ViewContent` event is sent as well. These are
|
|
1493
|
+
not sandbox events: they appear in the ad platform's events manager.
|
|
1494
|
+
|
|
1495
|
+
Requires `soundlinks:write`. Unknown ids, another organization's
|
|
1496
|
+
soundlink, and campaign-linked soundlinks return `404`. Archived
|
|
1497
|
+
self-serve soundlinks are allowed. A soundlink with neither pixel
|
|
1498
|
+
returns `400`. Does not require `Idempotency-Key`; each call sends a
|
|
1499
|
+
new event.
|
|
1500
|
+
|
|
1501
|
+
**Auth:** Accepts API key or OAuth Bearer (`soundlinks:write`).
|
|
1502
|
+
tags: [Soundlinks]
|
|
1503
|
+
security:
|
|
1504
|
+
- apiKeyBearerAuth: []
|
|
1505
|
+
- oauthBearer: []
|
|
1506
|
+
x-required-scope: soundlinks:write
|
|
1507
|
+
parameters:
|
|
1508
|
+
- $ref: '#/components/parameters/soundlinkId'
|
|
1509
|
+
responses:
|
|
1510
|
+
'200':
|
|
1511
|
+
description: Test event sent
|
|
1512
|
+
content:
|
|
1513
|
+
application/json:
|
|
1514
|
+
schema:
|
|
1515
|
+
$ref: '#/components/schemas/SendTestEventResponse'
|
|
1516
|
+
example:
|
|
1517
|
+
data:
|
|
1518
|
+
soundlinkId: V1StGXR8_Z5jdHi6B-myT
|
|
1519
|
+
status: sent
|
|
1162
1520
|
meta:
|
|
1163
1521
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1522
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
1164
1523
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1165
1524
|
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1166
1525
|
'404': { $ref: '#/components/responses/NotFound' }
|
|
@@ -1176,9 +1535,8 @@ paths:
|
|
|
1176
1535
|
clicks, listeners, streams, followers, and derived ratios. Totals are
|
|
1177
1536
|
sums of country-day mart rows (`api_smart_link_country_daily`);
|
|
1178
1537
|
`listeners` is the sum of daily country `new_listeners` (not
|
|
1179
|
-
period-unique). No per-day rows — use `/metrics/
|
|
1180
|
-
|
|
1181
|
-
splits).
|
|
1538
|
+
period-unique). No per-day rows — use `/metrics/breakdown` for
|
|
1539
|
+
country-day rows (including new/returning splits).
|
|
1182
1540
|
|
|
1183
1541
|
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1184
1542
|
tags: [Soundlinks]
|
|
@@ -1215,27 +1573,28 @@ paths:
|
|
|
1215
1573
|
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1216
1574
|
'500': { $ref: '#/components/responses/InternalError' }
|
|
1217
1575
|
|
|
1218
|
-
/v1/soundlinks/{soundlinkId}/metrics/
|
|
1576
|
+
/v1/soundlinks/{soundlinkId}/metrics/breakdown:
|
|
1219
1577
|
get:
|
|
1220
|
-
operationId:
|
|
1221
|
-
summary: Soundlink metrics
|
|
1578
|
+
operationId: getSoundlinkMetricsBreakdown
|
|
1579
|
+
summary: Soundlink metrics breakdown
|
|
1222
1580
|
description: |
|
|
1223
|
-
Per-day metrics
|
|
1581
|
+
Per-day metrics broken down by country. One row per
|
|
1582
|
+
`(report_date, soundlink_id, country_code)`. Can be large, so results
|
|
1224
1583
|
are paginated.
|
|
1225
1584
|
|
|
1226
|
-
**Row schema:** `
|
|
1227
|
-
|
|
1585
|
+
**Row schema:** `soundlink_country_daily` v1.0 — the same schema used
|
|
1586
|
+
in JSONL bulk exports. Rows are idempotent on the primary key
|
|
1587
|
+
`(provider, account_id, report_date, soundlink_id, country_code)`;
|
|
1228
1588
|
re-ingesting is safe.
|
|
1229
1589
|
|
|
1230
1590
|
**Mutability window:** rows for a given `report_date` can be revised
|
|
1231
1591
|
for up to 7 days after the date closes due to delayed Spotify playback
|
|
1232
1592
|
events. Re-fetch or re-ingest accordingly.
|
|
1233
1593
|
|
|
1234
|
-
Rows
|
|
1235
|
-
|
|
1236
|
-
`/metrics/breakdown` (and `/metrics/breakdown/export`).
|
|
1594
|
+
Rows contain no financial fields: ads for self-serve soundlinks run
|
|
1595
|
+
in your own Meta account, so spend is not visible to Soundlink.
|
|
1237
1596
|
|
|
1238
|
-
Maps to the **
|
|
1597
|
+
Maps to the **Countries** tab in the Soundlink Insights UI.
|
|
1239
1598
|
|
|
1240
1599
|
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1241
1600
|
tags: [Soundlinks]
|
|
@@ -1253,16 +1612,16 @@ paths:
|
|
|
1253
1612
|
in: query
|
|
1254
1613
|
schema:
|
|
1255
1614
|
type: string
|
|
1256
|
-
enum: [report_date]
|
|
1615
|
+
enum: [report_date, country_code]
|
|
1257
1616
|
default: report_date
|
|
1258
1617
|
- $ref: '#/components/parameters/sortOrder'
|
|
1259
1618
|
responses:
|
|
1260
1619
|
'200':
|
|
1261
|
-
description: Paginated per-day rows (`
|
|
1620
|
+
description: Paginated per-day country rows (`soundlink_country_daily` schema)
|
|
1262
1621
|
content:
|
|
1263
1622
|
application/json:
|
|
1264
1623
|
schema:
|
|
1265
|
-
$ref: '#/components/schemas/
|
|
1624
|
+
$ref: '#/components/schemas/SoundlinkBreakdownResponse'
|
|
1266
1625
|
example:
|
|
1267
1626
|
data:
|
|
1268
1627
|
schemaVersion: '1.0'
|
|
@@ -1279,6 +1638,7 @@ paths:
|
|
|
1279
1638
|
soundlink_target_isrc: DEXW62500259
|
|
1280
1639
|
soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
|
|
1281
1640
|
soundlink_target_playlist_id: null
|
|
1641
|
+
country_code: US
|
|
1282
1642
|
views: 4821
|
|
1283
1643
|
link_clicks: 890
|
|
1284
1644
|
streams: 203
|
|
@@ -1293,8 +1653,8 @@ paths:
|
|
|
1293
1653
|
pagination:
|
|
1294
1654
|
page: 1
|
|
1295
1655
|
pageSize: 50
|
|
1296
|
-
totalCount:
|
|
1297
|
-
totalPages:
|
|
1656
|
+
totalCount: 340
|
|
1657
|
+
totalPages: 7
|
|
1298
1658
|
meta:
|
|
1299
1659
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1300
1660
|
'400': { $ref: '#/components/responses/BadRequest' }
|
|
@@ -1304,127 +1664,35 @@ paths:
|
|
|
1304
1664
|
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1305
1665
|
'500': { $ref: '#/components/responses/InternalError' }
|
|
1306
1666
|
|
|
1307
|
-
/v1/soundlinks/{soundlinkId}/metrics/breakdown:
|
|
1667
|
+
/v1/soundlinks/{soundlinkId}/metrics/breakdown/export:
|
|
1308
1668
|
get:
|
|
1309
|
-
operationId:
|
|
1310
|
-
summary: Soundlink metrics breakdown
|
|
1669
|
+
operationId: exportSoundlinkMetricsBreakdown
|
|
1670
|
+
summary: Soundlink metrics breakdown export (JSONL)
|
|
1311
1671
|
description: |
|
|
1312
|
-
|
|
1313
|
-
|
|
1314
|
-
|
|
1672
|
+
Streams the full country-level metrics dataset for a soundlink as
|
|
1673
|
+
**newline-delimited JSON (JSONL)**. Every line is a complete, valid
|
|
1674
|
+
JSON object conforming to the `soundlink_country_daily` v1.0 schema
|
|
1675
|
+
— identical to the rows returned by `GET /metrics/breakdown` but
|
|
1676
|
+
without pagination or an envelope wrapper.
|
|
1315
1677
|
|
|
1316
|
-
|
|
1317
|
-
|
|
1318
|
-
`(provider, account_id, report_date, soundlink_id, country_code)`;
|
|
1319
|
-
re-ingesting is safe.
|
|
1678
|
+
Designed for data pipeline consumers: load directly into BigQuery,
|
|
1679
|
+
Snowflake, or any JSONL-aware ingest tool without cursor logic.
|
|
1320
1680
|
|
|
1321
|
-
**
|
|
1322
|
-
|
|
1323
|
-
|
|
1681
|
+
**Usage:**
|
|
1682
|
+
```
|
|
1683
|
+
GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export
|
|
1684
|
+
Accept: application/x-ndjson
|
|
1685
|
+
```
|
|
1324
1686
|
|
|
1325
|
-
|
|
1326
|
-
|
|
1687
|
+
**Date range:** if you omit both dates, defaults to the last **90 days**
|
|
1688
|
+
ending today. Override with `startDate` / `endDate`. **Responses are
|
|
1689
|
+
capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
|
|
1690
|
+
Page longer histories in 90-day slices.
|
|
1327
1691
|
|
|
1328
|
-
|
|
1329
|
-
|
|
1330
|
-
|
|
1331
|
-
|
|
1332
|
-
tags: [Soundlinks]
|
|
1333
|
-
security:
|
|
1334
|
-
- apiKeyBearerAuth: []
|
|
1335
|
-
- oauthBearer: []
|
|
1336
|
-
x-required-scope: soundlinks:read
|
|
1337
|
-
parameters:
|
|
1338
|
-
- $ref: '#/components/parameters/soundlinkId'
|
|
1339
|
-
- $ref: '#/components/parameters/soundlinkStartDate'
|
|
1340
|
-
- $ref: '#/components/parameters/soundlinkEndDate'
|
|
1341
|
-
- $ref: '#/components/parameters/page'
|
|
1342
|
-
- $ref: '#/components/parameters/pageSize500'
|
|
1343
|
-
- name: sortBy
|
|
1344
|
-
in: query
|
|
1345
|
-
schema:
|
|
1346
|
-
type: string
|
|
1347
|
-
enum: [report_date, country_code]
|
|
1348
|
-
default: report_date
|
|
1349
|
-
- $ref: '#/components/parameters/sortOrder'
|
|
1350
|
-
responses:
|
|
1351
|
-
'200':
|
|
1352
|
-
description: Paginated per-day country rows (`soundlink_country_daily` schema)
|
|
1353
|
-
content:
|
|
1354
|
-
application/json:
|
|
1355
|
-
schema:
|
|
1356
|
-
$ref: '#/components/schemas/SoundlinkBreakdownResponse'
|
|
1357
|
-
example:
|
|
1358
|
-
data:
|
|
1359
|
-
schemaVersion: '1.0'
|
|
1360
|
-
items:
|
|
1361
|
-
- provider: soundlink
|
|
1362
|
-
account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
|
|
1363
|
-
schema_version: '1.0'
|
|
1364
|
-
report_date: '2026-08-01'
|
|
1365
|
-
report_date_timezone: UTC
|
|
1366
|
-
exported_at: '2026-08-28T03:00:00Z'
|
|
1367
|
-
soundlink_id: V1StGXR8_Z5jdHi6B-myT
|
|
1368
|
-
soundlink_name: Midnight Drive
|
|
1369
|
-
soundlink_target_type: track
|
|
1370
|
-
soundlink_target_isrc: DEXW62500259
|
|
1371
|
-
soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
|
|
1372
|
-
soundlink_target_playlist_id: null
|
|
1373
|
-
country_code: US
|
|
1374
|
-
views: 4821
|
|
1375
|
-
link_clicks: 890
|
|
1376
|
-
streams: 203
|
|
1377
|
-
listeners: 145
|
|
1378
|
-
new_listeners: 120
|
|
1379
|
-
returning_listeners: 25
|
|
1380
|
-
new_listener_streams: 160
|
|
1381
|
-
returning_listener_streams: 43
|
|
1382
|
-
followers: 12
|
|
1383
|
-
streams_per_listener: 1.4
|
|
1384
|
-
ctr_lp: 0.185
|
|
1385
|
-
pagination:
|
|
1386
|
-
page: 1
|
|
1387
|
-
pageSize: 50
|
|
1388
|
-
totalCount: 340
|
|
1389
|
-
totalPages: 7
|
|
1390
|
-
meta:
|
|
1391
|
-
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1392
|
-
'400': { $ref: '#/components/responses/BadRequest' }
|
|
1393
|
-
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1394
|
-
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1395
|
-
'404': { $ref: '#/components/responses/NotFound' }
|
|
1396
|
-
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1397
|
-
'500': { $ref: '#/components/responses/InternalError' }
|
|
1398
|
-
|
|
1399
|
-
/v1/soundlinks/{soundlinkId}/metrics/breakdown/export:
|
|
1400
|
-
get:
|
|
1401
|
-
operationId: exportSoundlinkMetricsBreakdown
|
|
1402
|
-
summary: Soundlink metrics breakdown export (JSONL)
|
|
1403
|
-
description: |
|
|
1404
|
-
Streams the full country-level metrics dataset for a soundlink as
|
|
1405
|
-
**newline-delimited JSON (JSONL)**. Every line is a complete, valid
|
|
1406
|
-
JSON object conforming to the `soundlink_country_daily` v1.0 schema
|
|
1407
|
-
— identical to the rows returned by `GET /metrics/breakdown` but
|
|
1408
|
-
without pagination or an envelope wrapper.
|
|
1409
|
-
|
|
1410
|
-
Designed for data pipeline consumers: load directly into BigQuery,
|
|
1411
|
-
Snowflake, or any JSONL-aware ingest tool without cursor logic.
|
|
1412
|
-
|
|
1413
|
-
**Usage:**
|
|
1414
|
-
```
|
|
1415
|
-
GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export
|
|
1416
|
-
Accept: application/x-ndjson
|
|
1417
|
-
```
|
|
1418
|
-
|
|
1419
|
-
**Date range:** if you omit both dates, defaults to the last **90 days**
|
|
1420
|
-
ending today. Override with `startDate` / `endDate`. **Responses are
|
|
1421
|
-
capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
|
|
1422
|
-
Page longer histories in 90-day slices.
|
|
1423
|
-
|
|
1424
|
-
**Mutability:** rows for a given `report_date` can be revised for up
|
|
1425
|
-
to 7 days after the date closes due to delayed Spotify playback
|
|
1426
|
-
events. Re-fetching and re-ingesting on the primary key is safe
|
|
1427
|
-
(idempotent).
|
|
1692
|
+
**Mutability:** rows for a given `report_date` can be revised for up
|
|
1693
|
+
to 7 days after the date closes due to delayed Spotify playback
|
|
1694
|
+
events. Re-fetching and re-ingesting on the primary key is safe
|
|
1695
|
+
(idempotent).
|
|
1428
1696
|
|
|
1429
1697
|
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1430
1698
|
tags: [Soundlinks]
|
|
@@ -1661,10 +1929,14 @@ paths:
|
|
|
1661
1929
|
/v1/videos/import:
|
|
1662
1930
|
post:
|
|
1663
1931
|
operationId: importVideo
|
|
1664
|
-
summary: Import video(s) from public HTTPS MP4 URL(s)
|
|
1932
|
+
summary: Import video(s) from public HTTPS MP4 or QuickTime URL(s)
|
|
1665
1933
|
description: |
|
|
1666
1934
|
Accepts a single `url` or a `videos` array (1–5 items). Creates one upload
|
|
1667
1935
|
session, enqueues async download/staging, and returns `202` with `sessionId`.
|
|
1936
|
+
URLs may be MP4 (`video/mp4`) or QuickTime (`.mov` / `video/quicktime`).
|
|
1937
|
+
Unsupported types return `invalid_video_content_type`.
|
|
1938
|
+
QuickTime imports stay `processing` while they transcode to MP4, then
|
|
1939
|
+
follow the same ingest path as native MP4.
|
|
1668
1940
|
|
|
1669
1941
|
Requires the `videos:write` scope. Subject to a stricter per-credential rate
|
|
1670
1942
|
limit than generic public API routes (default 20 imports per hour per API key
|
|
@@ -1695,7 +1967,7 @@ paths:
|
|
|
1695
1967
|
value:
|
|
1696
1968
|
videos:
|
|
1697
1969
|
- url: 'https://cdn.example.com/a.mp4'
|
|
1698
|
-
- url: 'https://cdn.example.com/b.
|
|
1970
|
+
- url: 'https://cdn.example.com/b.mov'
|
|
1699
1971
|
responses:
|
|
1700
1972
|
'200':
|
|
1701
1973
|
description: Duplicate video already in the organization's library (sync legacy path only)
|
|
@@ -1790,7 +2062,7 @@ components:
|
|
|
1790
2062
|
maxLength: 255
|
|
1791
2063
|
description: |
|
|
1792
2064
|
A unique string identifying this request, used to safely retry write
|
|
1793
|
-
operations (create
|
|
2065
|
+
operations (campaign create/stop/budget, soundlink create) without repeating
|
|
1794
2066
|
side effects. Required on every request that references this parameter.
|
|
1795
2067
|
Reusing this key with an unchanged request body replays the original
|
|
1796
2068
|
response; reusing it with a different body returns
|
|
@@ -1840,7 +2112,11 @@ components:
|
|
|
1840
2112
|
schema:
|
|
1841
2113
|
type: string
|
|
1842
2114
|
format: date
|
|
1843
|
-
description:
|
|
2115
|
+
description: |
|
|
2116
|
+
Inclusive start date (`YYYY-MM-DD`). When omitted, the default depends
|
|
2117
|
+
on the endpoint: campaign overview and paginated breakdown use the
|
|
2118
|
+
campaign start date; engagement and JSONL export endpoints use the
|
|
2119
|
+
last 90 days ending today (see each operation).
|
|
1844
2120
|
|
|
1845
2121
|
endDate:
|
|
1846
2122
|
name: endDate
|
|
@@ -1866,7 +2142,7 @@ components:
|
|
|
1866
2142
|
format: date
|
|
1867
2143
|
description: |
|
|
1868
2144
|
Inclusive start date (`YYYY-MM-DD`) for soundlink overview and
|
|
1869
|
-
|
|
2145
|
+
breakdown. Defaults to the soundlink creation date when omitted.
|
|
1870
2146
|
|
|
1871
2147
|
soundlinkEndDate:
|
|
1872
2148
|
name: endDate
|
|
@@ -1888,6 +2164,33 @@ components:
|
|
|
1888
2164
|
format: uuid
|
|
1889
2165
|
description: Server-generated request ID. Include when contacting support.
|
|
1890
2166
|
|
|
2167
|
+
WalletData:
|
|
2168
|
+
type: object
|
|
2169
|
+
required: [balance, available, reserved, currency, updatedAt]
|
|
2170
|
+
properties:
|
|
2171
|
+
balance:
|
|
2172
|
+
type: number
|
|
2173
|
+
available:
|
|
2174
|
+
type: number
|
|
2175
|
+
reserved:
|
|
2176
|
+
type: number
|
|
2177
|
+
currency:
|
|
2178
|
+
type: string
|
|
2179
|
+
enum: [USD]
|
|
2180
|
+
updatedAt:
|
|
2181
|
+
type: string
|
|
2182
|
+
format: date-time
|
|
2183
|
+
nullable: true
|
|
2184
|
+
|
|
2185
|
+
GetWalletResponse:
|
|
2186
|
+
type: object
|
|
2187
|
+
required: [data, meta]
|
|
2188
|
+
properties:
|
|
2189
|
+
data:
|
|
2190
|
+
$ref: '#/components/schemas/WalletData'
|
|
2191
|
+
meta:
|
|
2192
|
+
$ref: '#/components/schemas/Meta'
|
|
2193
|
+
|
|
1891
2194
|
Pagination:
|
|
1892
2195
|
type: object
|
|
1893
2196
|
required: [page, pageSize, totalCount, totalPages]
|
|
@@ -1960,7 +2263,19 @@ components:
|
|
|
1960
2263
|
|
|
1961
2264
|
CampaignStatus:
|
|
1962
2265
|
type: string
|
|
1963
|
-
enum:
|
|
2266
|
+
enum:
|
|
2267
|
+
[
|
|
2268
|
+
creating,
|
|
2269
|
+
active,
|
|
2270
|
+
inactive,
|
|
2271
|
+
ended,
|
|
2272
|
+
renewing,
|
|
2273
|
+
restarting,
|
|
2274
|
+
restart_failed,
|
|
2275
|
+
renew_awaiting_charge,
|
|
2276
|
+
renew_failed,
|
|
2277
|
+
stopped,
|
|
2278
|
+
]
|
|
1964
2279
|
|
|
1965
2280
|
CampaignSummary:
|
|
1966
2281
|
type: object
|
|
@@ -1974,6 +2289,12 @@ components:
|
|
|
1974
2289
|
totalBudget,
|
|
1975
2290
|
campaignDuration,
|
|
1976
2291
|
generation,
|
|
2292
|
+
artistId,
|
|
2293
|
+
artistName,
|
|
2294
|
+
trackId,
|
|
2295
|
+
playlistId,
|
|
2296
|
+
trackName,
|
|
2297
|
+
campaignUrl,
|
|
1977
2298
|
createdAt,
|
|
1978
2299
|
updatedAt,
|
|
1979
2300
|
]
|
|
@@ -2004,6 +2325,48 @@ components:
|
|
|
2004
2325
|
legacy; `2` = Soundlink managed; `3` = wallet. Public API write
|
|
2005
2326
|
operations (budget changes, stop, tier updates) are supported for
|
|
2006
2327
|
generation `3` only.
|
|
2328
|
+
artistId:
|
|
2329
|
+
type: string
|
|
2330
|
+
nullable: true
|
|
2331
|
+
description: |
|
|
2332
|
+
Follow-attribution Spotify artist ID (`artist_id_follow`).
|
|
2333
|
+
This is the artist campaign follows are credited to, not the
|
|
2334
|
+
track's credit list (collabs/features are omitted). Use this
|
|
2335
|
+
to group campaigns for one artist. `null` when unset.
|
|
2336
|
+
artistName:
|
|
2337
|
+
type: string
|
|
2338
|
+
nullable: true
|
|
2339
|
+
description: |
|
|
2340
|
+
Cached display name for `artistId` only — not derived from the
|
|
2341
|
+
track's artists. `null` when unknown or unset.
|
|
2342
|
+
trackId:
|
|
2343
|
+
type: string
|
|
2344
|
+
nullable: true
|
|
2345
|
+
description: |
|
|
2346
|
+
Promoted Spotify track ID, parsed from the smart link URL.
|
|
2347
|
+
`null` for playlist campaigns or when the URL is not a track.
|
|
2348
|
+
Stable join key for the song; same grain as
|
|
2349
|
+
`campaign_target_spotify_track_id` on metrics breakdown.
|
|
2350
|
+
playlistId:
|
|
2351
|
+
type: string
|
|
2352
|
+
nullable: true
|
|
2353
|
+
description: |
|
|
2354
|
+
Promoted Spotify playlist ID, parsed from the smart link URL.
|
|
2355
|
+
`null` for track campaigns or when the URL is not a playlist.
|
|
2356
|
+
Same grain as `campaign_target_playlist_id` on metrics breakdown.
|
|
2357
|
+
trackName:
|
|
2358
|
+
type: string
|
|
2359
|
+
nullable: true
|
|
2360
|
+
description: |
|
|
2361
|
+
Promoted track title. `null` for playlist campaigns or when unknown.
|
|
2362
|
+
campaignUrl:
|
|
2363
|
+
type: string
|
|
2364
|
+
format: uri
|
|
2365
|
+
description: |
|
|
2366
|
+
Logged-in campaign insights URL in the Soundlink product
|
|
2367
|
+
(`/orgs/{organizationId}/insights/{smartLinkId}`). Uses the smart
|
|
2368
|
+
link id, not the campaign id. Requires a Soundlink account in this
|
|
2369
|
+
organization. This is not a public share link.
|
|
2007
2370
|
createdAt:
|
|
2008
2371
|
type: string
|
|
2009
2372
|
format: date-time
|
|
@@ -2021,6 +2384,11 @@ components:
|
|
|
2021
2384
|
description: |
|
|
2022
2385
|
Growth strategy (e.g. `custom`, `maximum_growth`, `market_discovery`).
|
|
2023
2386
|
Set at campaign creation.
|
|
2387
|
+
autoRenew:
|
|
2388
|
+
type: boolean
|
|
2389
|
+
description: |
|
|
2390
|
+
Whether this wallet campaign renews at the end of each cycle.
|
|
2391
|
+
`false` when auto-renew is off or the campaign has no stored value.
|
|
2024
2392
|
|
|
2025
2393
|
CampaignListResponse:
|
|
2026
2394
|
type: object
|
|
@@ -2276,6 +2644,13 @@ components:
|
|
|
2276
2644
|
cloned from. Records lineage only — it does not copy settings from
|
|
2277
2645
|
the source; all other create fields must still be provided. Unknown
|
|
2278
2646
|
or other-organization IDs return `400 invalid_request`.
|
|
2647
|
+
autoRenew:
|
|
2648
|
+
type: boolean
|
|
2649
|
+
default: false
|
|
2650
|
+
description: >-
|
|
2651
|
+
When true, the wallet campaign renews at the end of each cycle if
|
|
2652
|
+
credit remains. When false or omitted, auto-renew stays off. A
|
|
2653
|
+
renewal can cost more than create because of ad fees.
|
|
2279
2654
|
|
|
2280
2655
|
CreateCampaignRequestWithoutTiers:
|
|
2281
2656
|
allOf:
|
|
@@ -2322,12 +2697,15 @@ components:
|
|
|
2322
2697
|
|
|
2323
2698
|
CampaignCreateData:
|
|
2324
2699
|
type: object
|
|
2325
|
-
required: [campaignId, status]
|
|
2700
|
+
required: [campaignId, status, autoRenew]
|
|
2326
2701
|
properties:
|
|
2327
2702
|
campaignId:
|
|
2328
2703
|
type: string
|
|
2329
2704
|
status:
|
|
2330
2705
|
$ref: '#/components/schemas/CampaignStatus'
|
|
2706
|
+
autoRenew:
|
|
2707
|
+
type: boolean
|
|
2708
|
+
description: Stored auto-renew flag for this wallet campaign.
|
|
2331
2709
|
|
|
2332
2710
|
CreateCampaignResponse:
|
|
2333
2711
|
type: object
|
|
@@ -2346,7 +2724,10 @@ components:
|
|
|
2346
2724
|
type: string
|
|
2347
2725
|
status:
|
|
2348
2726
|
$ref: '#/components/schemas/CampaignStatus'
|
|
2349
|
-
description:
|
|
2727
|
+
description: |
|
|
2728
|
+
Campaign status after stop. `stopped` when stop applied or the
|
|
2729
|
+
campaign was already stopped. `ended` when the campaign had
|
|
2730
|
+
already ended.
|
|
2350
2731
|
|
|
2351
2732
|
StopCampaignResponse:
|
|
2352
2733
|
type: object
|
|
@@ -2357,6 +2738,31 @@ components:
|
|
|
2357
2738
|
meta:
|
|
2358
2739
|
$ref: '#/components/schemas/Meta'
|
|
2359
2740
|
|
|
2741
|
+
UpdateCampaignAutoRenewRequest:
|
|
2742
|
+
type: object
|
|
2743
|
+
required: [autoRenew]
|
|
2744
|
+
properties:
|
|
2745
|
+
autoRenew:
|
|
2746
|
+
type: boolean
|
|
2747
|
+
|
|
2748
|
+
CampaignAutoRenewData:
|
|
2749
|
+
type: object
|
|
2750
|
+
required: [campaignId, autoRenew]
|
|
2751
|
+
properties:
|
|
2752
|
+
campaignId:
|
|
2753
|
+
type: string
|
|
2754
|
+
autoRenew:
|
|
2755
|
+
type: boolean
|
|
2756
|
+
|
|
2757
|
+
UpdateCampaignAutoRenewResponse:
|
|
2758
|
+
type: object
|
|
2759
|
+
required: [data, meta]
|
|
2760
|
+
properties:
|
|
2761
|
+
data:
|
|
2762
|
+
$ref: '#/components/schemas/CampaignAutoRenewData'
|
|
2763
|
+
meta:
|
|
2764
|
+
$ref: '#/components/schemas/Meta'
|
|
2765
|
+
|
|
2360
2766
|
StrategyCatalogItem:
|
|
2361
2767
|
type: object
|
|
2362
2768
|
required: [strategyType, tierTargetingAllowed]
|
|
@@ -2453,10 +2859,12 @@ components:
|
|
|
2453
2859
|
properties:
|
|
2454
2860
|
targetDailyBudget:
|
|
2455
2861
|
type: number
|
|
2456
|
-
minimum:
|
|
2862
|
+
minimum: 0
|
|
2863
|
+
exclusiveMinimum: true
|
|
2457
2864
|
description: |
|
|
2458
|
-
New daily budget in USD (gross). Must be at least
|
|
2459
|
-
lower than the campaign's current
|
|
2865
|
+
New daily budget in USD (gross). Must be at least the campaign's
|
|
2866
|
+
enabled-ad-set minimum gross and lower than the campaign's current
|
|
2867
|
+
daily budget.
|
|
2460
2868
|
mode:
|
|
2461
2869
|
$ref: '#/components/schemas/BudgetDecreaseMode'
|
|
2462
2870
|
|
|
@@ -2566,6 +2974,119 @@ components:
|
|
|
2566
2974
|
meta:
|
|
2567
2975
|
$ref: '#/components/schemas/Meta'
|
|
2568
2976
|
|
|
2977
|
+
CreativeMetricsChild:
|
|
2978
|
+
type: object
|
|
2979
|
+
required:
|
|
2980
|
+
- caption
|
|
2981
|
+
- language
|
|
2982
|
+
- spotify_track_id
|
|
2983
|
+
- listeners
|
|
2984
|
+
- followers
|
|
2985
|
+
- link_clicks
|
|
2986
|
+
- cpl
|
|
2987
|
+
- cpf
|
|
2988
|
+
- cpc_linkclick
|
|
2989
|
+
- frequency
|
|
2990
|
+
properties:
|
|
2991
|
+
caption:
|
|
2992
|
+
type: string
|
|
2993
|
+
nullable: true
|
|
2994
|
+
language:
|
|
2995
|
+
type: string
|
|
2996
|
+
nullable: true
|
|
2997
|
+
description: Render language. Null when the render has no language.
|
|
2998
|
+
spotify_track_id:
|
|
2999
|
+
type: string
|
|
3000
|
+
description: Spotify track id stored on the render. Not a lookup.
|
|
3001
|
+
listeners:
|
|
3002
|
+
type: integer
|
|
3003
|
+
nullable: true
|
|
3004
|
+
description: Lifetime listeners. Null when the variant has no performance row.
|
|
3005
|
+
followers:
|
|
3006
|
+
type: integer
|
|
3007
|
+
nullable: true
|
|
3008
|
+
link_clicks:
|
|
3009
|
+
type: integer
|
|
3010
|
+
nullable: true
|
|
3011
|
+
cpl:
|
|
3012
|
+
type: number
|
|
3013
|
+
nullable: true
|
|
3014
|
+
cpf:
|
|
3015
|
+
type: number
|
|
3016
|
+
nullable: true
|
|
3017
|
+
cpc_linkclick:
|
|
3018
|
+
type: number
|
|
3019
|
+
nullable: true
|
|
3020
|
+
frequency:
|
|
3021
|
+
type: number
|
|
3022
|
+
nullable: true
|
|
3023
|
+
|
|
3024
|
+
CreativeMetricsGroup:
|
|
3025
|
+
type: object
|
|
3026
|
+
required:
|
|
3027
|
+
- video_id
|
|
3028
|
+
- caption
|
|
3029
|
+
- listeners
|
|
3030
|
+
- followers
|
|
3031
|
+
- link_clicks
|
|
3032
|
+
- cpl
|
|
3033
|
+
- cpf
|
|
3034
|
+
- cpc_linkclick
|
|
3035
|
+
- frequency
|
|
3036
|
+
- children
|
|
3037
|
+
properties:
|
|
3038
|
+
video_id:
|
|
3039
|
+
type: string
|
|
3040
|
+
description: Background video id. Groups with no video id are omitted.
|
|
3041
|
+
caption:
|
|
3042
|
+
type: string
|
|
3043
|
+
nullable: true
|
|
3044
|
+
description: Caption of the highest-spend child.
|
|
3045
|
+
listeners:
|
|
3046
|
+
type: integer
|
|
3047
|
+
nullable: true
|
|
3048
|
+
followers:
|
|
3049
|
+
type: integer
|
|
3050
|
+
nullable: true
|
|
3051
|
+
link_clicks:
|
|
3052
|
+
type: integer
|
|
3053
|
+
nullable: true
|
|
3054
|
+
cpl:
|
|
3055
|
+
type: number
|
|
3056
|
+
nullable: true
|
|
3057
|
+
cpf:
|
|
3058
|
+
type: number
|
|
3059
|
+
nullable: true
|
|
3060
|
+
cpc_linkclick:
|
|
3061
|
+
type: number
|
|
3062
|
+
nullable: true
|
|
3063
|
+
frequency:
|
|
3064
|
+
type: number
|
|
3065
|
+
nullable: true
|
|
3066
|
+
children:
|
|
3067
|
+
type: array
|
|
3068
|
+
minItems: 1
|
|
3069
|
+
items:
|
|
3070
|
+
$ref: '#/components/schemas/CreativeMetricsChild'
|
|
3071
|
+
|
|
3072
|
+
CreativeMetrics:
|
|
3073
|
+
type: object
|
|
3074
|
+
required: [creatives]
|
|
3075
|
+
properties:
|
|
3076
|
+
creatives:
|
|
3077
|
+
type: array
|
|
3078
|
+
items:
|
|
3079
|
+
$ref: '#/components/schemas/CreativeMetricsGroup'
|
|
3080
|
+
|
|
3081
|
+
CreativeMetricsResponse:
|
|
3082
|
+
type: object
|
|
3083
|
+
required: [data, meta]
|
|
3084
|
+
properties:
|
|
3085
|
+
data:
|
|
3086
|
+
$ref: '#/components/schemas/CreativeMetrics'
|
|
3087
|
+
meta:
|
|
3088
|
+
$ref: '#/components/schemas/Meta'
|
|
3089
|
+
|
|
2569
3090
|
BreakdownRow:
|
|
2570
3091
|
type: object
|
|
2571
3092
|
description: |
|
|
@@ -2658,7 +3179,7 @@ components:
|
|
|
2658
3179
|
link_clicks:
|
|
2659
3180
|
type: integer
|
|
2660
3181
|
nullable: true
|
|
2661
|
-
description:
|
|
3182
|
+
description: CTA clicks across all DSPs on the Soundlink landing page. Use `cpc_linkclick` / `ctr_linkclick` for outbound CPC/CTR.
|
|
2662
3183
|
streams:
|
|
2663
3184
|
type: integer
|
|
2664
3185
|
description: Spotify streams attributed to this campaign in this country on this day (7-day click-through window). Observed events, not modelled estimates.
|
|
@@ -2972,17 +3493,94 @@ components:
|
|
|
2972
3493
|
meta:
|
|
2973
3494
|
$ref: '#/components/schemas/Meta'
|
|
2974
3495
|
|
|
3496
|
+
CreateSoundlinkRequest:
|
|
3497
|
+
type: object
|
|
3498
|
+
required: [name, spotifyUrl]
|
|
3499
|
+
properties:
|
|
3500
|
+
name:
|
|
3501
|
+
type: string
|
|
3502
|
+
minLength: 1
|
|
3503
|
+
description: Human-readable soundlink name.
|
|
3504
|
+
spotifyUrl:
|
|
3505
|
+
type: string
|
|
3506
|
+
format: uri
|
|
3507
|
+
description: |
|
|
3508
|
+
HTTPS Spotify track or playlist URL. Album, artist, and URI
|
|
3509
|
+
(`spotify:track:...`) forms are rejected. An optional `intl-xx`
|
|
3510
|
+
path segment is accepted. Query strings are stripped before
|
|
3511
|
+
lookup. The resource must currently exist on Spotify.
|
|
3512
|
+
example: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
|
|
3513
|
+
autoFollow:
|
|
3514
|
+
type: boolean
|
|
3515
|
+
default: false
|
|
3516
|
+
description: |
|
|
3517
|
+
When true, fans who connect Spotify from the landing page are
|
|
3518
|
+
asked to follow the track artist (`artistIdFollow`, or the
|
|
3519
|
+
track's primary artist when omitted), or the playlist itself
|
|
3520
|
+
when `spotifyUrl` is a playlist. Defaults to false.
|
|
3521
|
+
artistIdFollow:
|
|
3522
|
+
type: string
|
|
3523
|
+
description: |
|
|
3524
|
+
Spotify artist ID used for auto-follow on track links.
|
|
3525
|
+
Optional. Persisted even when `autoFollow` is false. For
|
|
3526
|
+
multi-artist tracks, pass the artist that should be followed.
|
|
3527
|
+
Ignored when `spotifyUrl` is a playlist.
|
|
3528
|
+
metaPixelId:
|
|
3529
|
+
type: string
|
|
3530
|
+
description: |
|
|
3531
|
+
Meta pixel ID. Must be sent together with
|
|
3532
|
+
`metaConversionAccessToken`. Omit both to skip Meta tracking.
|
|
3533
|
+
metaConversionAccessToken:
|
|
3534
|
+
type: string
|
|
3535
|
+
writeOnly: true
|
|
3536
|
+
description: |
|
|
3537
|
+
Meta Conversions API access token. Write-only: accepted on create,
|
|
3538
|
+
never returned on GET. Must be sent together with `metaPixelId`.
|
|
3539
|
+
appleMusicUrl:
|
|
3540
|
+
type: string
|
|
3541
|
+
format: uri
|
|
3542
|
+
description: |
|
|
3543
|
+
Optional HTTPS Apple Music URL. Accepted shapes: a song
|
|
3544
|
+
(`/song/{slug}/{id}`), a catalog playlist (`pl.`), a library
|
|
3545
|
+
playlist (`pl.u-`), or an album share-sheet link with `?i={songId}`
|
|
3546
|
+
(stored as the canonical song URL). Host must be `music.apple.com`
|
|
3547
|
+
with a two-letter storefront. URL shape is checked only; the
|
|
3548
|
+
Apple catalog is not looked up. Omit to create a Spotify-only
|
|
3549
|
+
soundlink.
|
|
3550
|
+
example: https://music.apple.com/us/song/anti-hero/1645937493
|
|
3551
|
+
youtubeMusicUrl:
|
|
3552
|
+
type: string
|
|
3553
|
+
format: uri
|
|
3554
|
+
description: |
|
|
3555
|
+
Optional HTTPS YouTube Music URL. Accepted shapes: a song
|
|
3556
|
+
(`music.youtube.com/watch?v=…`, `youtube.com/watch?v=…`, or
|
|
3557
|
+
`youtu.be/…`) or a playlist (`…/playlist?list=…`). Shorts,
|
|
3558
|
+
live, channel, and browse links are rejected. A video or
|
|
3559
|
+
playlist that does not exist on YouTube returns
|
|
3560
|
+
`400 invalid_request`. Omit to leave YouTube Music unset.
|
|
3561
|
+
example: https://music.youtube.com/watch?v=dQw4w9WgXcQ
|
|
3562
|
+
|
|
2975
3563
|
SoundlinkDetail:
|
|
2976
3564
|
allOf:
|
|
2977
3565
|
- $ref: '#/components/schemas/SoundlinkSummary'
|
|
2978
3566
|
- type: object
|
|
2979
|
-
required:
|
|
3567
|
+
required:
|
|
3568
|
+
- autoFollow
|
|
3569
|
+
- artistIdFollow
|
|
3570
|
+
- metaPixelId
|
|
3571
|
+
- tiktokPixelId
|
|
3572
|
+
- appleMusicUrl
|
|
3573
|
+
- youtubeMusicUrl
|
|
2980
3574
|
properties:
|
|
2981
3575
|
autoFollow:
|
|
2982
3576
|
type: boolean
|
|
3577
|
+
description: Whether auto-follow is enabled on this soundlink.
|
|
3578
|
+
artistIdFollow:
|
|
3579
|
+
type: string
|
|
3580
|
+
nullable: true
|
|
2983
3581
|
description: |
|
|
2984
|
-
|
|
2985
|
-
|
|
3582
|
+
Spotify artist ID configured for auto-follow on track links.
|
|
3583
|
+
Unused for playlists. `null` if not set.
|
|
2986
3584
|
metaPixelId:
|
|
2987
3585
|
type: string
|
|
2988
3586
|
nullable: true
|
|
@@ -2991,6 +3589,21 @@ components:
|
|
|
2991
3589
|
type: string
|
|
2992
3590
|
nullable: true
|
|
2993
3591
|
description: TikTok pixel ID configured on this soundlink. `null` if not set.
|
|
3592
|
+
appleMusicUrl:
|
|
3593
|
+
type: string
|
|
3594
|
+
format: uri
|
|
3595
|
+
nullable: true
|
|
3596
|
+
description: |
|
|
3597
|
+
Apple Music URL stored on this soundlink. `null` if not set.
|
|
3598
|
+
Share-sheet album links are returned as the canonical song URL.
|
|
3599
|
+
youtubeMusicUrl:
|
|
3600
|
+
type: string
|
|
3601
|
+
format: uri
|
|
3602
|
+
nullable: true
|
|
3603
|
+
description: |
|
|
3604
|
+
YouTube Music URL stored on this soundlink. `null` if not set.
|
|
3605
|
+
Input hosts such as `youtu.be` are returned as the canonical
|
|
3606
|
+
`music.youtube.com` song or playlist URL.
|
|
2994
3607
|
|
|
2995
3608
|
SoundlinkDetailResponse:
|
|
2996
3609
|
type: object
|
|
@@ -3001,6 +3614,24 @@ components:
|
|
|
3001
3614
|
meta:
|
|
3002
3615
|
$ref: '#/components/schemas/Meta'
|
|
3003
3616
|
|
|
3617
|
+
SendTestEventResponse:
|
|
3618
|
+
type: object
|
|
3619
|
+
required: [data, meta]
|
|
3620
|
+
properties:
|
|
3621
|
+
data:
|
|
3622
|
+
type: object
|
|
3623
|
+
required: [soundlinkId, status]
|
|
3624
|
+
properties:
|
|
3625
|
+
soundlinkId:
|
|
3626
|
+
type: string
|
|
3627
|
+
description: Soundlink that received the test event.
|
|
3628
|
+
status:
|
|
3629
|
+
type: string
|
|
3630
|
+
enum: [sent]
|
|
3631
|
+
description: Present when the stored pixel test event was sent.
|
|
3632
|
+
meta:
|
|
3633
|
+
$ref: '#/components/schemas/Meta'
|
|
3634
|
+
|
|
3004
3635
|
SoundlinkMetricsOverview:
|
|
3005
3636
|
type: object
|
|
3006
3637
|
description: |
|
|
@@ -3015,8 +3646,8 @@ components:
|
|
|
3015
3646
|
type: integer
|
|
3016
3647
|
nullable: true
|
|
3017
3648
|
description: |
|
|
3018
|
-
|
|
3019
|
-
|
|
3649
|
+
CTA clicks across all DSPs on the landing page. Null if not tracked
|
|
3650
|
+
for this soundlink type.
|
|
3020
3651
|
streams:
|
|
3021
3652
|
type: integer
|
|
3022
3653
|
description: Attributed Spotify streams (sum of country-day rows).
|
|
@@ -3050,153 +3681,6 @@ components:
|
|
|
3050
3681
|
meta:
|
|
3051
3682
|
$ref: '#/components/schemas/Meta'
|
|
3052
3683
|
|
|
3053
|
-
SoundlinkDailyRow:
|
|
3054
|
-
type: object
|
|
3055
|
-
description: |
|
|
3056
|
-
One row of the `soundlink_daily` v1.0 schema.
|
|
3057
|
-
Primary key: `(provider, account_id, report_date, soundlink_id)`.
|
|
3058
|
-
Rows are idempotent — re-ingesting on the primary key is safe.
|
|
3059
|
-
Values for a given `report_date` may be revised for up to 7 days after
|
|
3060
|
-
the date closes due to delayed Spotify playback events.
|
|
3061
|
-
Rows are aggregated across countries (no `country_code` in v1.0) and
|
|
3062
|
-
contain no financial fields.
|
|
3063
|
-
required:
|
|
3064
|
-
- provider
|
|
3065
|
-
- account_id
|
|
3066
|
-
- schema_version
|
|
3067
|
-
- report_date
|
|
3068
|
-
- report_date_timezone
|
|
3069
|
-
- exported_at
|
|
3070
|
-
- soundlink_id
|
|
3071
|
-
- soundlink_name
|
|
3072
|
-
- soundlink_target_type
|
|
3073
|
-
- views
|
|
3074
|
-
- streams
|
|
3075
|
-
- listeners
|
|
3076
|
-
- followers
|
|
3077
|
-
- streams_per_listener
|
|
3078
|
-
properties:
|
|
3079
|
-
provider:
|
|
3080
|
-
type: string
|
|
3081
|
-
enum: [soundlink]
|
|
3082
|
-
description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
|
|
3083
|
-
account_id:
|
|
3084
|
-
type: string
|
|
3085
|
-
description: Soundlink organization ID (UUID).
|
|
3086
|
-
schema_version:
|
|
3087
|
-
type: string
|
|
3088
|
-
description: Schema version. Pin your ingest pipeline to this value.
|
|
3089
|
-
example: '1.0'
|
|
3090
|
-
report_date:
|
|
3091
|
-
type: string
|
|
3092
|
-
format: date
|
|
3093
|
-
description: UTC calendar date the metrics belong to (`YYYY-MM-DD`).
|
|
3094
|
-
report_date_timezone:
|
|
3095
|
-
type: string
|
|
3096
|
-
enum: [UTC]
|
|
3097
|
-
description: Always `UTC`.
|
|
3098
|
-
exported_at:
|
|
3099
|
-
type: string
|
|
3100
|
-
format: date-time
|
|
3101
|
-
description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
|
|
3102
|
-
soundlink_id:
|
|
3103
|
-
type: string
|
|
3104
|
-
description: Unique ID of this soundlink.
|
|
3105
|
-
example: V1StGXR8_Z5jdHi6B-myT
|
|
3106
|
-
soundlink_name:
|
|
3107
|
-
type: string
|
|
3108
|
-
description: Human-readable soundlink name.
|
|
3109
|
-
soundlink_target_type:
|
|
3110
|
-
type: string
|
|
3111
|
-
nullable: true
|
|
3112
|
-
enum: [track, playlist]
|
|
3113
|
-
description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
|
|
3114
|
-
soundlink_target_isrc:
|
|
3115
|
-
type: string
|
|
3116
|
-
nullable: true
|
|
3117
|
-
description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
|
|
3118
|
-
soundlink_target_spotify_track_id:
|
|
3119
|
-
type: string
|
|
3120
|
-
nullable: true
|
|
3121
|
-
description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
|
|
3122
|
-
soundlink_target_playlist_id:
|
|
3123
|
-
type: string
|
|
3124
|
-
nullable: true
|
|
3125
|
-
description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
|
|
3126
|
-
views:
|
|
3127
|
-
type: integer
|
|
3128
|
-
description: Soundlink landing page views on this day.
|
|
3129
|
-
link_clicks:
|
|
3130
|
-
type: integer
|
|
3131
|
-
nullable: true
|
|
3132
|
-
description: |
|
|
3133
|
-
Clicks on "Continue with Spotify" on the landing page — outbound
|
|
3134
|
-
clicks to Spotify. Null if not tracked for this soundlink type.
|
|
3135
|
-
streams:
|
|
3136
|
-
type: integer
|
|
3137
|
-
description: |
|
|
3138
|
-
Spotify streams attributed to this soundlink on this day:
|
|
3139
|
-
`new_listener_streams + returning_listener_streams`. Observed
|
|
3140
|
-
Spotify-side events, not modelled estimates. Safe to sum within a
|
|
3141
|
-
day; summing across days counts repeat listens.
|
|
3142
|
-
listeners:
|
|
3143
|
-
type: integer
|
|
3144
|
-
description: |
|
|
3145
|
-
Unique Spotify listeners attributed to this soundlink on this day:
|
|
3146
|
-
`new_listeners + returning_listeners`. **Do not sum across days** —
|
|
3147
|
-
the same listener can appear on multiple `report_date` rows.
|
|
3148
|
-
new_listeners:
|
|
3149
|
-
type: integer
|
|
3150
|
-
nullable: true
|
|
3151
|
-
description: Unique listeners whose first play via this soundlink occurred on `report_date`.
|
|
3152
|
-
returning_listeners:
|
|
3153
|
-
type: integer
|
|
3154
|
-
nullable: true
|
|
3155
|
-
description: Unique listeners who played on `report_date` but whose first play was on an earlier date.
|
|
3156
|
-
new_listener_streams:
|
|
3157
|
-
type: integer
|
|
3158
|
-
nullable: true
|
|
3159
|
-
description: Stream count from new listeners on `report_date`.
|
|
3160
|
-
returning_listener_streams:
|
|
3161
|
-
type: integer
|
|
3162
|
-
nullable: true
|
|
3163
|
-
description: Stream count from returning listeners on `report_date`.
|
|
3164
|
-
followers:
|
|
3165
|
-
type: integer
|
|
3166
|
-
description: Spotify artist follower gains attributed to this soundlink on this day.
|
|
3167
|
-
streams_per_listener:
|
|
3168
|
-
type: number
|
|
3169
|
-
description: streams / listeners for this row. Zero if listeners is zero.
|
|
3170
|
-
ctr_lp:
|
|
3171
|
-
type: number
|
|
3172
|
-
nullable: true
|
|
3173
|
-
description: |
|
|
3174
|
-
Landing page click-through rate (link_clicks / views). Computed
|
|
3175
|
-
against landing page views, not ad impressions — do not combine
|
|
3176
|
-
with `ctr_linkclick` from `campaign_country_daily`. Null if views
|
|
3177
|
-
is zero or link_clicks is null.
|
|
3178
|
-
|
|
3179
|
-
SoundlinkTimeseriesResponse:
|
|
3180
|
-
type: object
|
|
3181
|
-
required: [data, meta]
|
|
3182
|
-
properties:
|
|
3183
|
-
data:
|
|
3184
|
-
type: object
|
|
3185
|
-
required: [schemaVersion, items, pagination]
|
|
3186
|
-
properties:
|
|
3187
|
-
schemaVersion:
|
|
3188
|
-
type: string
|
|
3189
|
-
description: Version of the `soundlink_daily` row schema. Pin your ingest pipeline to this.
|
|
3190
|
-
example: '1.0'
|
|
3191
|
-
items:
|
|
3192
|
-
type: array
|
|
3193
|
-
items:
|
|
3194
|
-
$ref: '#/components/schemas/SoundlinkDailyRow'
|
|
3195
|
-
pagination:
|
|
3196
|
-
$ref: '#/components/schemas/Pagination'
|
|
3197
|
-
meta:
|
|
3198
|
-
$ref: '#/components/schemas/Meta'
|
|
3199
|
-
|
|
3200
3684
|
SoundlinkCountryDailyRow:
|
|
3201
3685
|
type: object
|
|
3202
3686
|
description: |
|
|
@@ -3280,8 +3764,8 @@ components:
|
|
|
3280
3764
|
type: integer
|
|
3281
3765
|
nullable: true
|
|
3282
3766
|
description: |
|
|
3283
|
-
|
|
3284
|
-
|
|
3767
|
+
CTA clicks across all DSPs on the landing page. Null if not tracked
|
|
3768
|
+
for this soundlink type.
|
|
3285
3769
|
streams:
|
|
3286
3770
|
type: integer
|
|
3287
3771
|
description: |
|
|
@@ -3521,7 +4005,7 @@ components:
|
|
|
3521
4005
|
url:
|
|
3522
4006
|
type: string
|
|
3523
4007
|
format: uri
|
|
3524
|
-
description: Public HTTPS URL to an MP4 file (max 50 MB). Mutually exclusive with `videos`.
|
|
4008
|
+
description: Public HTTPS URL to an MP4 or QuickTime (.mov) file (max 50 MB). Mutually exclusive with `videos`.
|
|
3525
4009
|
videos:
|
|
3526
4010
|
type: array
|
|
3527
4011
|
minItems: 1
|
|
@@ -3534,7 +4018,7 @@ components:
|
|
|
3534
4018
|
url:
|
|
3535
4019
|
type: string
|
|
3536
4020
|
format: uri
|
|
3537
|
-
description: Public HTTPS URL to an MP4 file (max 50 MB).
|
|
4021
|
+
description: Public HTTPS URL to an MP4 or QuickTime (.mov) file (max 50 MB).
|
|
3538
4022
|
|
|
3539
4023
|
VideoImportStatus:
|
|
3540
4024
|
type: string
|
|
@@ -3771,6 +4255,68 @@ components:
|
|
|
3771
4255
|
meta:
|
|
3772
4256
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
3773
4257
|
|
|
4258
|
+
CreateSoundlinkBadRequest:
|
|
4259
|
+
description: |
|
|
4260
|
+
Missing or malformed request body, or a missing/empty
|
|
4261
|
+
`Idempotency-Key` header.
|
|
4262
|
+
content:
|
|
4263
|
+
application/json:
|
|
4264
|
+
schema:
|
|
4265
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
4266
|
+
examples:
|
|
4267
|
+
missing_field:
|
|
4268
|
+
value:
|
|
4269
|
+
error:
|
|
4270
|
+
code: invalid_request
|
|
4271
|
+
message: 'Missing required field: name.'
|
|
4272
|
+
meta:
|
|
4273
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
4274
|
+
missing_idempotency_key:
|
|
4275
|
+
value:
|
|
4276
|
+
error:
|
|
4277
|
+
code: invalid_request
|
|
4278
|
+
message: 'Idempotency-Key header is required and must not be empty.'
|
|
4279
|
+
meta:
|
|
4280
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
4281
|
+
pixel_pair:
|
|
4282
|
+
value:
|
|
4283
|
+
error:
|
|
4284
|
+
code: invalid_request
|
|
4285
|
+
message: 'metaPixelId and metaConversionAccessToken must both be provided, or both omitted.'
|
|
4286
|
+
meta:
|
|
4287
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
4288
|
+
|
|
4289
|
+
CreateSoundlinkForbidden:
|
|
4290
|
+
description: |
|
|
4291
|
+
Valid credentials but missing the `soundlinks:write` scope.
|
|
4292
|
+
content:
|
|
4293
|
+
application/json:
|
|
4294
|
+
schema:
|
|
4295
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
4296
|
+
examples:
|
|
4297
|
+
insufficient_scope:
|
|
4298
|
+
value:
|
|
4299
|
+
error:
|
|
4300
|
+
code: insufficient_scope
|
|
4301
|
+
message: 'This key does not have the soundlinks:write scope.'
|
|
4302
|
+
meta:
|
|
4303
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
4304
|
+
CreateSoundlinkUnprocessable:
|
|
4305
|
+
description: Request body is well-formed but the Spotify URL is invalid.
|
|
4306
|
+
content:
|
|
4307
|
+
application/json:
|
|
4308
|
+
schema:
|
|
4309
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
4310
|
+
examples:
|
|
4311
|
+
invalid_spotify_url:
|
|
4312
|
+
summary: Malformed URL, unsupported type, or Spotify resource does not exist
|
|
4313
|
+
value:
|
|
4314
|
+
error:
|
|
4315
|
+
code: invalid_spotify_url
|
|
4316
|
+
message: 'Spotify track not found.'
|
|
4317
|
+
meta:
|
|
4318
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
4319
|
+
|
|
3774
4320
|
InsufficientCredit:
|
|
3775
4321
|
description: Wallet balance is too low to cover `dailyBudget * durationDays`
|
|
3776
4322
|
content:
|