soundlink 2.3.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
@@ -1187,6 +1371,8 @@ paths:
1187
1371
  artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1188
1372
  metaPixelId: '1234567890123456'
1189
1373
  tiktokPixelId: null
1374
+ appleMusicUrl: null
1375
+ youtubeMusicUrl: null
1190
1376
  meta:
1191
1377
  requestId: 550e8400-e29b-41d4-a716-446655440000
1192
1378
  '400': { $ref: '#/components/responses/CreateSoundlinkBadRequest' }
@@ -1234,6 +1420,8 @@ paths:
1234
1420
  artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1235
1421
  metaPixelId: '1234567890123456'
1236
1422
  tiktokPixelId: null
1423
+ appleMusicUrl: null
1424
+ youtubeMusicUrl: null
1237
1425
  meta:
1238
1426
  requestId: 550e8400-e29b-41d4-a716-446655440000
1239
1427
  '401': { $ref: '#/components/responses/Unauthorized' }
@@ -1241,15 +1429,13 @@ paths:
1241
1429
  '404': { $ref: '#/components/responses/NotFound' }
1242
1430
  '429': { $ref: '#/components/responses/RateLimited' }
1243
1431
  '500': { $ref: '#/components/responses/InternalError' }
1244
-
1245
1432
  delete:
1246
1433
  operationId: archiveSoundlink
1247
1434
  summary: Archive a soundlink
1248
1435
  description: |
1249
1436
  Archives a self-serve soundlink (`status: archived`). Same as Archive
1250
- in the app: the public landing page returns 404 after cache expires.
1251
- List and detail still return the row. Cannot be undone via the Public
1252
- API.
1437
+ in the app: the public page stops resolving, and this cannot be undone
1438
+ via the Public API.
1253
1439
 
1254
1440
  Requires `soundlinks:write`. Campaign-linked soundlinks, soundlinks
1255
1441
  that are not `active`, and ids that do not belong to the org return
@@ -1282,6 +1468,8 @@ paths:
1282
1468
  artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1283
1469
  metaPixelId: '1234567890123456'
1284
1470
  tiktokPixelId: null
1471
+ appleMusicUrl: null
1472
+ youtubeMusicUrl: null
1285
1473
  meta:
1286
1474
  requestId: 550e8400-e29b-41d4-a716-446655440000
1287
1475
  '401': { $ref: '#/components/responses/Unauthorized' }
@@ -1290,45 +1478,45 @@ paths:
1290
1478
  '429': { $ref: '#/components/responses/RateLimited' }
1291
1479
  '500': { $ref: '#/components/responses/InternalError' }
1292
1480
 
1293
- /v1/soundlinks/{soundlinkId}/metrics/overview:
1294
- get:
1295
- operationId: getSoundlinkMetricsOverview
1296
- summary: Soundlink metrics overview
1481
+ /v1/soundlinks/{soundlinkId}/test-events:
1482
+ post:
1483
+ operationId: sendSoundlinkTestEvents
1484
+ summary: Send a test conversion event for a soundlink
1297
1485
  description: |
1298
- Soundlink-level totals for a date range: landing page views, outbound
1299
- clicks, listeners, streams, followers, and derived ratios. Totals are
1300
- sums of country-day mart rows (`api_smart_link_country_daily`);
1301
- `listeners` is the sum of daily country `new_listeners` (not
1302
- period-unique). No per-day rows — use `/metrics/timeseries` for those,
1303
- or `/metrics/breakdown` for country-day rows (including new/returning
1304
- splits).
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.
1305
1489
 
1306
- Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
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`).
1307
1502
  tags: [Soundlinks]
1308
1503
  security:
1309
1504
  - apiKeyBearerAuth: []
1310
1505
  - oauthBearer: []
1311
- x-required-scope: soundlinks:read
1506
+ x-required-scope: soundlinks:write
1312
1507
  parameters:
1313
1508
  - $ref: '#/components/parameters/soundlinkId'
1314
- - $ref: '#/components/parameters/soundlinkStartDate'
1315
- - $ref: '#/components/parameters/soundlinkEndDate'
1316
1509
  responses:
1317
1510
  '200':
1318
- description: Soundlink totals
1511
+ description: Test event sent
1319
1512
  content:
1320
1513
  application/json:
1321
1514
  schema:
1322
- $ref: '#/components/schemas/SoundlinkMetricsOverviewResponse'
1515
+ $ref: '#/components/schemas/SendTestEventResponse'
1323
1516
  example:
1324
1517
  data:
1325
- views: 4821
1326
- link_clicks: 890
1327
- streams: 9340
1328
- listeners: 3980
1329
- followers: 312
1330
- streams_per_listener: 2.35
1331
- ctr_lp: 0.185
1518
+ soundlinkId: V1StGXR8_Z5jdHi6B-myT
1519
+ status: sent
1332
1520
  meta:
1333
1521
  requestId: 550e8400-e29b-41d4-a716-446655440000
1334
1522
  '400': { $ref: '#/components/responses/BadRequest' }
@@ -1338,27 +1526,17 @@ paths:
1338
1526
  '429': { $ref: '#/components/responses/RateLimited' }
1339
1527
  '500': { $ref: '#/components/responses/InternalError' }
1340
1528
 
1341
- /v1/soundlinks/{soundlinkId}/metrics/timeseries:
1529
+ /v1/soundlinks/{soundlinkId}/metrics/overview:
1342
1530
  get:
1343
- operationId: getSoundlinkMetricsTimeseries
1344
- summary: Soundlink metrics timeseries
1531
+ operationId: getSoundlinkMetricsOverview
1532
+ summary: Soundlink metrics overview
1345
1533
  description: |
1346
- Per-day metrics for a soundlink. One row per `report_date`. Results
1347
- are paginated.
1348
-
1349
- **Row schema:** `soundlink_daily` v1.0. Rows are idempotent on the
1350
- primary key `(provider, account_id, report_date, soundlink_id)`;
1351
- re-ingesting is safe.
1352
-
1353
- **Mutability window:** rows for a given `report_date` can be revised
1354
- for up to 7 days after the date closes due to delayed Spotify playback
1355
- events. Re-fetch or re-ingest accordingly.
1356
-
1357
- Rows are aggregated across countries (no `country_code`) and
1358
- contain no financial fields. For country-day rows use
1359
- `/metrics/breakdown` (and `/metrics/breakdown/export`).
1360
-
1361
- Maps to the **Trends** tab in the Soundlink Insights UI.
1534
+ Soundlink-level totals for a date range: landing page views, outbound
1535
+ clicks, listeners, streams, followers, and derived ratios. Totals are
1536
+ sums of country-day mart rows (`api_smart_link_country_daily`);
1537
+ `listeners` is the sum of daily country `new_listeners` (not
1538
+ period-unique). No per-day rows — use `/metrics/breakdown` for
1539
+ country-day rows (including new/returning splits).
1362
1540
 
1363
1541
  Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1364
1542
  tags: [Soundlinks]
@@ -1370,54 +1548,22 @@ paths:
1370
1548
  - $ref: '#/components/parameters/soundlinkId'
1371
1549
  - $ref: '#/components/parameters/soundlinkStartDate'
1372
1550
  - $ref: '#/components/parameters/soundlinkEndDate'
1373
- - $ref: '#/components/parameters/page'
1374
- - $ref: '#/components/parameters/pageSize500'
1375
- - name: sortBy
1376
- in: query
1377
- schema:
1378
- type: string
1379
- enum: [report_date]
1380
- default: report_date
1381
- - $ref: '#/components/parameters/sortOrder'
1382
1551
  responses:
1383
1552
  '200':
1384
- description: Paginated per-day rows (`soundlink_daily` schema)
1553
+ description: Soundlink totals
1385
1554
  content:
1386
1555
  application/json:
1387
1556
  schema:
1388
- $ref: '#/components/schemas/SoundlinkTimeseriesResponse'
1557
+ $ref: '#/components/schemas/SoundlinkMetricsOverviewResponse'
1389
1558
  example:
1390
1559
  data:
1391
- schemaVersion: '1.0'
1392
- items:
1393
- - provider: soundlink
1394
- account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
1395
- schema_version: '1.0'
1396
- report_date: '2026-08-01'
1397
- report_date_timezone: UTC
1398
- exported_at: '2026-08-28T03:00:00Z'
1399
- soundlink_id: V1StGXR8_Z5jdHi6B-myT
1400
- soundlink_name: Midnight Drive
1401
- soundlink_target_type: track
1402
- soundlink_target_isrc: DEXW62500259
1403
- soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
1404
- soundlink_target_playlist_id: null
1405
- views: 4821
1406
- link_clicks: 890
1407
- streams: 203
1408
- listeners: 145
1409
- new_listeners: 120
1410
- returning_listeners: 25
1411
- new_listener_streams: 160
1412
- returning_listener_streams: 43
1413
- followers: 12
1414
- streams_per_listener: 1.4
1415
- ctr_lp: 0.185
1416
- pagination:
1417
- page: 1
1418
- pageSize: 50
1419
- totalCount: 90
1420
- totalPages: 2
1560
+ views: 4821
1561
+ link_clicks: 890
1562
+ streams: 9340
1563
+ listeners: 3980
1564
+ followers: 312
1565
+ streams_per_listener: 2.35
1566
+ ctr_lp: 0.185
1421
1567
  meta:
1422
1568
  requestId: 550e8400-e29b-41d4-a716-446655440000
1423
1569
  '400': { $ref: '#/components/responses/BadRequest' }
@@ -1449,7 +1595,6 @@ paths:
1449
1595
  in your own Meta account, so spend is not visible to Soundlink.
1450
1596
 
1451
1597
  Maps to the **Countries** tab in the Soundlink Insights UI.
1452
- Use `/metrics/timeseries` for country-aggregated daily Trends rows.
1453
1598
 
1454
1599
  Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1455
1600
  tags: [Soundlinks]
@@ -1784,10 +1929,14 @@ paths:
1784
1929
  /v1/videos/import:
1785
1930
  post:
1786
1931
  operationId: importVideo
1787
- summary: Import video(s) from public HTTPS MP4 URL(s)
1932
+ summary: Import video(s) from public HTTPS MP4 or QuickTime URL(s)
1788
1933
  description: |
1789
1934
  Accepts a single `url` or a `videos` array (1–5 items). Creates one upload
1790
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.
1791
1940
 
1792
1941
  Requires the `videos:write` scope. Subject to a stricter per-credential rate
1793
1942
  limit than generic public API routes (default 20 imports per hour per API key
@@ -1818,7 +1967,7 @@ paths:
1818
1967
  value:
1819
1968
  videos:
1820
1969
  - url: 'https://cdn.example.com/a.mp4'
1821
- - url: 'https://cdn.example.com/b.mp4'
1970
+ - url: 'https://cdn.example.com/b.mov'
1822
1971
  responses:
1823
1972
  '200':
1824
1973
  description: Duplicate video already in the organization's library (sync legacy path only)
@@ -1913,7 +2062,7 @@ components:
1913
2062
  maxLength: 255
1914
2063
  description: |
1915
2064
  A unique string identifying this request, used to safely retry write
1916
- operations (create, stop, budget increase/decrease) without repeating
2065
+ operations (campaign create/stop/budget, soundlink create) without repeating
1917
2066
  side effects. Required on every request that references this parameter.
1918
2067
  Reusing this key with an unchanged request body replays the original
1919
2068
  response; reusing it with a different body returns
@@ -1963,7 +2112,11 @@ components:
1963
2112
  schema:
1964
2113
  type: string
1965
2114
  format: date
1966
- 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).
1967
2120
 
1968
2121
  endDate:
1969
2122
  name: endDate
@@ -1989,7 +2142,7 @@ components:
1989
2142
  format: date
1990
2143
  description: |
1991
2144
  Inclusive start date (`YYYY-MM-DD`) for soundlink overview and
1992
- timeseries. Defaults to the soundlink creation date when omitted.
2145
+ breakdown. Defaults to the soundlink creation date when omitted.
1993
2146
 
1994
2147
  soundlinkEndDate:
1995
2148
  name: endDate
@@ -2011,6 +2164,33 @@ components:
2011
2164
  format: uuid
2012
2165
  description: Server-generated request ID. Include when contacting support.
2013
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
+
2014
2194
  Pagination:
2015
2195
  type: object
2016
2196
  required: [page, pageSize, totalCount, totalPages]
@@ -2083,7 +2263,19 @@ components:
2083
2263
 
2084
2264
  CampaignStatus:
2085
2265
  type: string
2086
- 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
+ ]
2087
2279
 
2088
2280
  CampaignSummary:
2089
2281
  type: object
@@ -2097,6 +2289,12 @@ components:
2097
2289
  totalBudget,
2098
2290
  campaignDuration,
2099
2291
  generation,
2292
+ artistId,
2293
+ artistName,
2294
+ trackId,
2295
+ playlistId,
2296
+ trackName,
2297
+ campaignUrl,
2100
2298
  createdAt,
2101
2299
  updatedAt,
2102
2300
  ]
@@ -2127,6 +2325,48 @@ components:
2127
2325
  legacy; `2` = Soundlink managed; `3` = wallet. Public API write
2128
2326
  operations (budget changes, stop, tier updates) are supported for
2129
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.
2130
2370
  createdAt:
2131
2371
  type: string
2132
2372
  format: date-time
@@ -2144,6 +2384,11 @@ components:
2144
2384
  description: |
2145
2385
  Growth strategy (e.g. `custom`, `maximum_growth`, `market_discovery`).
2146
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.
2147
2392
 
2148
2393
  CampaignListResponse:
2149
2394
  type: object
@@ -2399,6 +2644,13 @@ components:
2399
2644
  cloned from. Records lineage only — it does not copy settings from
2400
2645
  the source; all other create fields must still be provided. Unknown
2401
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.
2402
2654
 
2403
2655
  CreateCampaignRequestWithoutTiers:
2404
2656
  allOf:
@@ -2445,12 +2697,15 @@ components:
2445
2697
 
2446
2698
  CampaignCreateData:
2447
2699
  type: object
2448
- required: [campaignId, status]
2700
+ required: [campaignId, status, autoRenew]
2449
2701
  properties:
2450
2702
  campaignId:
2451
2703
  type: string
2452
2704
  status:
2453
2705
  $ref: '#/components/schemas/CampaignStatus'
2706
+ autoRenew:
2707
+ type: boolean
2708
+ description: Stored auto-renew flag for this wallet campaign.
2454
2709
 
2455
2710
  CreateCampaignResponse:
2456
2711
  type: object
@@ -2469,7 +2724,10 @@ components:
2469
2724
  type: string
2470
2725
  status:
2471
2726
  $ref: '#/components/schemas/CampaignStatus'
2472
- 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.
2473
2731
 
2474
2732
  StopCampaignResponse:
2475
2733
  type: object
@@ -2480,6 +2738,31 @@ components:
2480
2738
  meta:
2481
2739
  $ref: '#/components/schemas/Meta'
2482
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
+
2483
2766
  StrategyCatalogItem:
2484
2767
  type: object
2485
2768
  required: [strategyType, tierTargetingAllowed]
@@ -2576,10 +2859,12 @@ components:
2576
2859
  properties:
2577
2860
  targetDailyBudget:
2578
2861
  type: number
2579
- minimum: 10
2862
+ minimum: 0
2863
+ exclusiveMinimum: true
2580
2864
  description: |
2581
- New daily budget in USD (gross). Must be at least `$10`/day and
2582
- 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.
2583
2868
  mode:
2584
2869
  $ref: '#/components/schemas/BudgetDecreaseMode'
2585
2870
 
@@ -2689,14 +2974,127 @@ components:
2689
2974
  meta:
2690
2975
  $ref: '#/components/schemas/Meta'
2691
2976
 
2692
- BreakdownRow:
2977
+ CreativeMetricsChild:
2693
2978
  type: object
2694
- description: |
2695
- One row of the `campaign_country_daily` v1.0 schema.
2696
- Primary key: `(provider, account_id, report_date, campaign_id, country_code)`.
2697
- Rows are idempotent — re-ingesting on the primary key is safe.
2698
- Values for a given `report_date` may be revised for up to 7 days after
2699
- the date closes due to delayed events from Meta and Spotify.
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
+
3090
+ BreakdownRow:
3091
+ type: object
3092
+ description: |
3093
+ One row of the `campaign_country_daily` v1.0 schema.
3094
+ Primary key: `(provider, account_id, report_date, campaign_id, country_code)`.
3095
+ Rows are idempotent — re-ingesting on the primary key is safe.
3096
+ Values for a given `report_date` may be revised for up to 7 days after
3097
+ the date closes due to delayed events from Meta and Spotify.
2700
3098
  required:
2701
3099
  - provider
2702
3100
  - account_id
@@ -2781,7 +3179,7 @@ components:
2781
3179
  link_clicks:
2782
3180
  type: integer
2783
3181
  nullable: true
2784
- 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.
2785
3183
  streams:
2786
3184
  type: integer
2787
3185
  description: Spotify streams attributed to this campaign in this country on this day (7-day click-through window). Observed events, not modelled estimates.
@@ -3106,33 +3504,77 @@ components:
3106
3504
  spotifyUrl:
3107
3505
  type: string
3108
3506
  format: uri
3109
- description: HTTPS Spotify track or playlist URL.
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.
3110
3512
  example: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
3111
3513
  autoFollow:
3112
3514
  type: boolean
3113
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.
3114
3521
  artistIdFollow:
3115
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.
3116
3528
  metaPixelId:
3117
3529
  type: string
3530
+ description: |
3531
+ Meta pixel ID. Must be sent together with
3532
+ `metaConversionAccessToken`. Omit both to skip Meta tracking.
3118
3533
  metaConversionAccessToken:
3119
3534
  type: string
3120
3535
  writeOnly: true
3121
3536
  description: |
3122
3537
  Meta Conversions API access token. Write-only: accepted on create,
3123
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
3124
3562
 
3125
3563
  SoundlinkDetail:
3126
3564
  allOf:
3127
3565
  - $ref: '#/components/schemas/SoundlinkSummary'
3128
3566
  - type: object
3129
- required: [autoFollow, artistIdFollow, metaPixelId, tiktokPixelId]
3567
+ required:
3568
+ - autoFollow
3569
+ - artistIdFollow
3570
+ - metaPixelId
3571
+ - tiktokPixelId
3572
+ - appleMusicUrl
3573
+ - youtubeMusicUrl
3130
3574
  properties:
3131
3575
  autoFollow:
3132
3576
  type: boolean
3133
- description: |
3134
- Whether auto-follow is configured for this soundlink. Whether
3135
- it takes effect also depends on the organization's plan.
3577
+ description: Whether auto-follow is enabled on this soundlink.
3136
3578
  artistIdFollow:
3137
3579
  type: string
3138
3580
  nullable: true
@@ -3147,6 +3589,21 @@ components:
3147
3589
  type: string
3148
3590
  nullable: true
3149
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.
3150
3607
 
3151
3608
  SoundlinkDetailResponse:
3152
3609
  type: object
@@ -3157,6 +3614,24 @@ components:
3157
3614
  meta:
3158
3615
  $ref: '#/components/schemas/Meta'
3159
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
+
3160
3635
  SoundlinkMetricsOverview:
3161
3636
  type: object
3162
3637
  description: |
@@ -3171,8 +3646,8 @@ components:
3171
3646
  type: integer
3172
3647
  nullable: true
3173
3648
  description: |
3174
- Clicks on "Continue with Spotify" on the landing page — outbound
3175
- 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.
3176
3651
  streams:
3177
3652
  type: integer
3178
3653
  description: Attributed Spotify streams (sum of country-day rows).
@@ -3206,153 +3681,6 @@ components:
3206
3681
  meta:
3207
3682
  $ref: '#/components/schemas/Meta'
3208
3683
 
3209
- SoundlinkDailyRow:
3210
- type: object
3211
- description: |
3212
- One row of the `soundlink_daily` v1.0 schema.
3213
- Primary key: `(provider, account_id, report_date, soundlink_id)`.
3214
- Rows are idempotent — re-ingesting on the primary key is safe.
3215
- Values for a given `report_date` may be revised for up to 7 days after
3216
- the date closes due to delayed Spotify playback events.
3217
- Rows are aggregated across countries (no `country_code` in v1.0) and
3218
- contain no financial fields.
3219
- required:
3220
- - provider
3221
- - account_id
3222
- - schema_version
3223
- - report_date
3224
- - report_date_timezone
3225
- - exported_at
3226
- - soundlink_id
3227
- - soundlink_name
3228
- - soundlink_target_type
3229
- - views
3230
- - streams
3231
- - listeners
3232
- - followers
3233
- - streams_per_listener
3234
- properties:
3235
- provider:
3236
- type: string
3237
- enum: [soundlink]
3238
- description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
3239
- account_id:
3240
- type: string
3241
- description: Soundlink organization ID (UUID).
3242
- schema_version:
3243
- type: string
3244
- description: Schema version. Pin your ingest pipeline to this value.
3245
- example: '1.0'
3246
- report_date:
3247
- type: string
3248
- format: date
3249
- description: UTC calendar date the metrics belong to (`YYYY-MM-DD`).
3250
- report_date_timezone:
3251
- type: string
3252
- enum: [UTC]
3253
- description: Always `UTC`.
3254
- exported_at:
3255
- type: string
3256
- format: date-time
3257
- description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
3258
- soundlink_id:
3259
- type: string
3260
- description: Unique ID of this soundlink.
3261
- example: V1StGXR8_Z5jdHi6B-myT
3262
- soundlink_name:
3263
- type: string
3264
- description: Human-readable soundlink name.
3265
- soundlink_target_type:
3266
- type: string
3267
- nullable: true
3268
- enum: [track, playlist]
3269
- description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
3270
- soundlink_target_isrc:
3271
- type: string
3272
- nullable: true
3273
- description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
3274
- soundlink_target_spotify_track_id:
3275
- type: string
3276
- nullable: true
3277
- description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
3278
- soundlink_target_playlist_id:
3279
- type: string
3280
- nullable: true
3281
- description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
3282
- views:
3283
- type: integer
3284
- description: Soundlink landing page views on this day.
3285
- link_clicks:
3286
- type: integer
3287
- nullable: true
3288
- description: |
3289
- Clicks on "Continue with Spotify" on the landing page — outbound
3290
- clicks to Spotify. Null if not tracked for this soundlink type.
3291
- streams:
3292
- type: integer
3293
- description: |
3294
- Spotify streams attributed to this soundlink on this day:
3295
- `new_listener_streams + returning_listener_streams`. Observed
3296
- Spotify-side events, not modelled estimates. Safe to sum within a
3297
- day; summing across days counts repeat listens.
3298
- listeners:
3299
- type: integer
3300
- description: |
3301
- Unique Spotify listeners attributed to this soundlink on this day:
3302
- `new_listeners + returning_listeners`. **Do not sum across days** —
3303
- the same listener can appear on multiple `report_date` rows.
3304
- new_listeners:
3305
- type: integer
3306
- nullable: true
3307
- description: Unique listeners whose first play via this soundlink occurred on `report_date`.
3308
- returning_listeners:
3309
- type: integer
3310
- nullable: true
3311
- description: Unique listeners who played on `report_date` but whose first play was on an earlier date.
3312
- new_listener_streams:
3313
- type: integer
3314
- nullable: true
3315
- description: Stream count from new listeners on `report_date`.
3316
- returning_listener_streams:
3317
- type: integer
3318
- nullable: true
3319
- description: Stream count from returning listeners on `report_date`.
3320
- followers:
3321
- type: integer
3322
- description: Spotify artist follower gains attributed to this soundlink on this day.
3323
- streams_per_listener:
3324
- type: number
3325
- description: streams / listeners for this row. Zero if listeners is zero.
3326
- ctr_lp:
3327
- type: number
3328
- nullable: true
3329
- description: |
3330
- Landing page click-through rate (link_clicks / views). Computed
3331
- against landing page views, not ad impressions — do not combine
3332
- with `ctr_linkclick` from `campaign_country_daily`. Null if views
3333
- is zero or link_clicks is null.
3334
-
3335
- SoundlinkTimeseriesResponse:
3336
- type: object
3337
- required: [data, meta]
3338
- properties:
3339
- data:
3340
- type: object
3341
- required: [schemaVersion, items, pagination]
3342
- properties:
3343
- schemaVersion:
3344
- type: string
3345
- description: Version of the `soundlink_daily` row schema. Pin your ingest pipeline to this.
3346
- example: '1.0'
3347
- items:
3348
- type: array
3349
- items:
3350
- $ref: '#/components/schemas/SoundlinkDailyRow'
3351
- pagination:
3352
- $ref: '#/components/schemas/Pagination'
3353
- meta:
3354
- $ref: '#/components/schemas/Meta'
3355
-
3356
3684
  SoundlinkCountryDailyRow:
3357
3685
  type: object
3358
3686
  description: |
@@ -3436,8 +3764,8 @@ components:
3436
3764
  type: integer
3437
3765
  nullable: true
3438
3766
  description: |
3439
- Clicks on "Continue with Spotify" on the landing page — outbound
3440
- 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.
3441
3769
  streams:
3442
3770
  type: integer
3443
3771
  description: |
@@ -3677,7 +4005,7 @@ components:
3677
4005
  url:
3678
4006
  type: string
3679
4007
  format: uri
3680
- 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`.
3681
4009
  videos:
3682
4010
  type: array
3683
4011
  minItems: 1
@@ -3690,7 +4018,7 @@ components:
3690
4018
  url:
3691
4019
  type: string
3692
4020
  format: uri
3693
- 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).
3694
4022
 
3695
4023
  VideoImportStatus:
3696
4024
  type: string
@@ -3927,6 +4255,68 @@ components:
3927
4255
  meta:
3928
4256
  requestId: 550e8400-e29b-41d4-a716-446655440000
3929
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
+
3930
4320
  InsufficientCredit:
3931
4321
  description: Wallet balance is too low to cover `dailyBudget * durationDays`
3932
4322
  content:
@@ -4001,69 +4391,6 @@ components:
4001
4391
  meta:
4002
4392
  requestId: 550e8400-e29b-41d4-a716-446655440000
4003
4393
 
4004
- CreateSoundlinkBadRequest:
4005
- description: |
4006
- Missing or malformed request body, or a missing/empty
4007
- `Idempotency-Key` header.
4008
- content:
4009
- application/json:
4010
- schema:
4011
- $ref: '#/components/schemas/ErrorResponse'
4012
- examples:
4013
- missing_field:
4014
- value:
4015
- error:
4016
- code: invalid_request
4017
- message: 'Missing required field: name.'
4018
- meta:
4019
- requestId: 550e8400-e29b-41d4-a716-446655440000
4020
- missing_idempotency_key:
4021
- value:
4022
- error:
4023
- code: invalid_request
4024
- message: 'Idempotency-Key header is required and must not be empty.'
4025
- meta:
4026
- requestId: 550e8400-e29b-41d4-a716-446655440000
4027
- pixel_pair:
4028
- value:
4029
- error:
4030
- code: invalid_request
4031
- message: 'metaPixelId and metaConversionAccessToken must both be provided, or both omitted.'
4032
- meta:
4033
- requestId: 550e8400-e29b-41d4-a716-446655440000
4034
-
4035
- CreateSoundlinkForbidden:
4036
- description: |
4037
- Valid credentials but missing the `soundlinks:write` scope.
4038
- content:
4039
- application/json:
4040
- schema:
4041
- $ref: '#/components/schemas/ErrorResponse'
4042
- examples:
4043
- insufficient_scope:
4044
- value:
4045
- error:
4046
- code: insufficient_scope
4047
- message: 'This key does not have the soundlinks:write scope.'
4048
- meta:
4049
- requestId: 550e8400-e29b-41d4-a716-446655440000
4050
-
4051
- CreateSoundlinkUnprocessable:
4052
- description: Request body is well-formed but the Spotify URL is invalid.
4053
- content:
4054
- application/json:
4055
- schema:
4056
- $ref: '#/components/schemas/ErrorResponse'
4057
- examples:
4058
- invalid_spotify_url:
4059
- summary: Malformed URL, unsupported type, or Spotify resource does not exist
4060
- value:
4061
- error:
4062
- code: invalid_spotify_url
4063
- message: 'Spotify track not found.'
4064
- meta:
4065
- requestId: 550e8400-e29b-41d4-a716-446655440000
4066
-
4067
4394
  IdempotencyKeyConflict:
4068
4395
  description: |
4069
4396
  The `Idempotency-Key` was reused with a materially different request