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.
@@ -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/timeseries/breakdown/engagement, JSONL exports) | `soundlinks:read` | API key (Bearer) or OAuth Bearer |
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
- Stopping is idempotent at the campaign level: a second stop on an
367
- already-stopped campaign succeeds without double-refunding. The
368
- `Idempotency-Key` header is also **required** so retries of the same
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 `$10`/day and lower than the
491
- current daily budget
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/timeseries` for those,
1180
- or `/metrics/breakdown` for country-day rows (including new/returning
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/timeseries:
1576
+ /v1/soundlinks/{soundlinkId}/metrics/breakdown:
1219
1577
  get:
1220
- operationId: getSoundlinkMetricsTimeseries
1221
- summary: Soundlink metrics timeseries
1578
+ operationId: getSoundlinkMetricsBreakdown
1579
+ summary: Soundlink metrics breakdown
1222
1580
  description: |
1223
- Per-day metrics for a soundlink. One row per `report_date`. Results
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:** `soundlink_daily` v1.0. Rows are idempotent on the
1227
- primary key `(provider, account_id, report_date, soundlink_id)`;
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 are aggregated across countries (no `country_code`) and
1235
- contain no financial fields. For country-day rows use
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 **Trends** tab in the Soundlink Insights UI.
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 (`soundlink_daily` schema)
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/SoundlinkTimeseriesResponse'
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: 90
1297
- totalPages: 2
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: getSoundlinkMetricsBreakdown
1310
- summary: Soundlink metrics breakdown
1669
+ operationId: exportSoundlinkMetricsBreakdown
1670
+ summary: Soundlink metrics breakdown export (JSONL)
1311
1671
  description: |
1312
- Per-day metrics broken down by country. One row per
1313
- `(report_date, soundlink_id, country_code)`. Can be large, so results
1314
- are paginated.
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
- **Row schema:** `soundlink_country_daily` v1.0 — the same schema used
1317
- in JSONL bulk exports. Rows are idempotent on the primary key
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
- **Mutability window:** rows for a given `report_date` can be revised
1322
- for up to 7 days after the date closes due to delayed Spotify playback
1323
- events. Re-fetch or re-ingest accordingly.
1681
+ **Usage:**
1682
+ ```
1683
+ GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export
1684
+ Accept: application/x-ndjson
1685
+ ```
1324
1686
 
1325
- Rows contain no financial fields: ads for self-serve soundlinks run
1326
- in your own Meta account, so spend is not visible to Soundlink.
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
- Maps to the **Countries** tab in the Soundlink Insights UI.
1329
- Use `/metrics/timeseries` for country-aggregated daily Trends rows.
1330
-
1331
- Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
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.mp4'
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, stop, budget increase/decrease) without repeating
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: Inclusive start date (`YYYY-MM-DD`). Defaults to campaign start date.
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
- timeseries. Defaults to the soundlink creation date when omitted.
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: [creating, active, paused, stopped, completed, failed, ended]
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: Campaign status after stop (typically `stopped`).
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: 10
2862
+ minimum: 0
2863
+ exclusiveMinimum: true
2457
2864
  description: |
2458
- New daily budget in USD (gross). Must be at least `$10`/day and
2459
- lower than the campaign's current daily budget.
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: Clicks on "Continue with Spotify" on the Soundlink landing page. Use `cpc_linkclick` / `ctr_linkclick` for outbound CPC/CTR.
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: [autoFollow, metaPixelId, tiktokPixelId]
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
- Whether auto-follow is configured for this soundlink. Whether
2985
- it takes effect also depends on the organization's plan.
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
- Clicks on "Continue with Spotify" on the landing page — outbound
3019
- clicks to Spotify. Null if not tracked for this soundlink type.
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
- Clicks on "Continue with Spotify" on the landing page — outbound
3284
- clicks to Spotify. Null if not tracked for this soundlink type.
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: