soundlink 2.1.0 → 2.3.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,7 @@ 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/engagement) | `soundlinks:read` | 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 |
43
43
 
44
44
  Per-operation scope requirements are also marked with `x-required-scope`
45
45
  (except `GET /v1/ping`, which accepts any valid credential with at least
@@ -873,6 +873,116 @@ paths:
873
873
  '429': { $ref: '#/components/responses/RateLimited' }
874
874
  '500': { $ref: '#/components/responses/InternalError' }
875
875
 
876
+ /v1/campaigns/{campaignId}/metrics/engagement:
877
+ get:
878
+ operationId: getCampaignEngagement
879
+ summary: Campaign engagement breakdown
880
+ description: |
881
+ Per-day, per-track engagement metrics for a campaign. One row per
882
+ `(report_date, campaign_id, engagement_context, country_code, engaged_spotify_track_id)`.
883
+ Results are paginated.
884
+
885
+ **Row schema:** `campaign_engagement_daily` v1.0 — the same schema used
886
+ in JSONL bulk exports. Rows are idempotent on the primary key; re-ingesting
887
+ is safe.
888
+
889
+ **Key difference from `/metrics/breakdown`:** this endpoint covers the
890
+ full engagement window — including post-campaign streaming activity —
891
+ not just dates when the campaign was actively running.
892
+
893
+ **`engagement_context` values:**
894
+ - `catalog` — same-artist spillover (and direct promoted-track plays)
895
+ on track campaigns.
896
+ - `playlist` — per-track performance inside the promoted playlist on
897
+ playlist campaigns.
898
+
899
+ **`listeners` is deduplicated within each row only.** Do not sum
900
+ `listeners` across days to get a campaign total.
901
+
902
+ **Date range:** if you omit both dates, defaults to the last **90 days**
903
+ ending today. Override with `startDate` / `endDate`. **Responses are
904
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
905
+
906
+ **Mutability window:** rows for a given `report_date` can be revised
907
+ for up to 7 days after the date closes due to delayed Spotify
908
+ playback events.
909
+
910
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
911
+ tags: [Metrics]
912
+ security:
913
+ - apiKeyBearerAuth: []
914
+ - oauthBearer: []
915
+ x-required-scope: metrics:read
916
+ parameters:
917
+ - $ref: '#/components/parameters/campaignId'
918
+ - $ref: '#/components/parameters/startDate'
919
+ - $ref: '#/components/parameters/endDate'
920
+ - name: engagementContext
921
+ in: query
922
+ schema:
923
+ type: string
924
+ enum: [catalog, playlist]
925
+ description: Filter to a single engagement context. Omit to return both.
926
+ - $ref: '#/components/parameters/page'
927
+ - $ref: '#/components/parameters/pageSize500'
928
+ - name: sortBy
929
+ in: query
930
+ schema:
931
+ type: string
932
+ enum: [report_date]
933
+ default: report_date
934
+ - $ref: '#/components/parameters/sortOrder'
935
+ responses:
936
+ '200':
937
+ description: Paginated engagement rows (`campaign_engagement_daily` schema)
938
+ content:
939
+ application/json:
940
+ schema:
941
+ $ref: '#/components/schemas/MetricsEngagementResponse'
942
+ example:
943
+ data:
944
+ schemaVersion: '1.0'
945
+ items:
946
+ - provider: soundlink
947
+ account_id: a7ac3173-2f71-4e79-921f-d15d7112cc9a
948
+ schema_version: '1.0'
949
+ report_date: '2026-04-08'
950
+ report_date_timezone: UTC
951
+ exported_at: '2026-05-22T10:12:11Z'
952
+ campaign_id: 8ccd7b88-2591-4b94-848f-f142f5c6bba1
953
+ campaign_name: 9 To 5
954
+ campaign_target_type: track
955
+ campaign_target_isrc: DEXW62500272
956
+ campaign_target_spotify_track_id: 2RkZ5WPkKyBf0u8vN3dNgb
957
+ campaign_target_playlist_id: null
958
+ status: ended
959
+ engagement_context: catalog
960
+ country_code: US
961
+ engaged_track_isrc: DEXW62500001
962
+ engaged_spotify_track_id: 4cOdK2wGLETKBW3PvgPWqT
963
+ engaged_track_name: Till The Sunrise
964
+ playlist_position: null
965
+ new_listeners: 42
966
+ returning_listeners: 18
967
+ listeners: 60
968
+ new_listener_streams: 58
969
+ returning_listener_streams: 31
970
+ streams: 89
971
+ spl: 1.48
972
+ pagination:
973
+ page: 1
974
+ pageSize: 50
975
+ totalCount: 120
976
+ totalPages: 3
977
+ meta:
978
+ requestId: 550e8400-e29b-41d4-a716-446655440000
979
+ '400': { $ref: '#/components/responses/BadRequest' }
980
+ '401': { $ref: '#/components/responses/Unauthorized' }
981
+ '403': { $ref: '#/components/responses/Forbidden' }
982
+ '404': { $ref: '#/components/responses/NotFound' }
983
+ '429': { $ref: '#/components/responses/RateLimited' }
984
+ '500': { $ref: '#/components/responses/InternalError' }
985
+
876
986
  /v1/campaigns/{campaignId}/metrics/engagement/export:
877
987
  get:
878
988
  operationId: exportCampaignEngagement
@@ -880,7 +990,9 @@ paths:
880
990
  description: |
881
991
  Streams the full engagement dataset for a campaign as
882
992
  **newline-delimited JSON (JSONL)**. Every line is a complete, valid
883
- JSON object conforming to the `campaign_engagement_daily` v1.0 schema.
993
+ JSON object conforming to the `campaign_engagement_daily` v1.0 schema
994
+ — identical to the rows returned by `GET /metrics/engagement` but
995
+ without pagination or an envelope wrapper.
884
996
 
885
997
  Designed for data pipeline consumers: load directly into BigQuery,
886
998
  Snowflake, or any JSONL-aware ingest tool without cursor logic.
@@ -1011,6 +1123,80 @@ paths:
1011
1123
  '429': { $ref: '#/components/responses/RateLimited' }
1012
1124
  '500': { $ref: '#/components/responses/InternalError' }
1013
1125
 
1126
+ post:
1127
+ operationId: createSoundlink
1128
+ summary: Create a self-serve soundlink
1129
+ description: |
1130
+ Creates a self-serve soundlink in the organization. This is the Public
1131
+ API equivalent of the in-app create flow. It does not create a wallet
1132
+ campaign and does not appear on `GET /v1/campaigns`.
1133
+
1134
+ Requires the `soundlinks:write` scope.
1135
+
1136
+ `Idempotency-Key` is **required**. Reusing the key with an unchanged
1137
+ body replays the original `201`; a different body returns
1138
+ `409 idempotency_key_conflict`. Keys are honored for 24 hours.
1139
+
1140
+ **Auth:** Accepts API key or OAuth Bearer (`soundlinks:write`).
1141
+ tags: [Soundlinks]
1142
+ security:
1143
+ - apiKeyBearerAuth: []
1144
+ - oauthBearer: []
1145
+ x-required-scope: soundlinks:write
1146
+ parameters:
1147
+ - $ref: '#/components/parameters/idempotencyKey'
1148
+ requestBody:
1149
+ required: true
1150
+ content:
1151
+ application/json:
1152
+ schema:
1153
+ $ref: '#/components/schemas/CreateSoundlinkRequest'
1154
+ examples:
1155
+ track:
1156
+ summary: Track soundlink
1157
+ value:
1158
+ name: Midnight Drive
1159
+ spotifyUrl: 'https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl'
1160
+ autoFollow: true
1161
+ artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1162
+ metaPixelId: '1234567890123456'
1163
+ metaConversionAccessToken: 'EAAB...'
1164
+ playlist:
1165
+ summary: Playlist soundlink
1166
+ value:
1167
+ name: Late Night Mix
1168
+ spotifyUrl: 'https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M'
1169
+ responses:
1170
+ '201':
1171
+ description: Soundlink created
1172
+ content:
1173
+ application/json:
1174
+ schema:
1175
+ $ref: '#/components/schemas/SoundlinkDetailResponse'
1176
+ example:
1177
+ data:
1178
+ soundlinkId: V1StGXR8_Z5jdHi6B-myT
1179
+ organizationId: a7ac3173-2f71-4e79-921f-d15d7112dd11
1180
+ name: Midnight Drive
1181
+ url: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
1182
+ targetType: track
1183
+ spotifyUrl: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
1184
+ status: active
1185
+ createdAt: '2026-04-01T10:00:00Z'
1186
+ autoFollow: true
1187
+ artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1188
+ metaPixelId: '1234567890123456'
1189
+ tiktokPixelId: null
1190
+ meta:
1191
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1192
+ '400': { $ref: '#/components/responses/CreateSoundlinkBadRequest' }
1193
+ '401': { $ref: '#/components/responses/Unauthorized' }
1194
+ '403': { $ref: '#/components/responses/CreateSoundlinkForbidden' }
1195
+ '409': { $ref: '#/components/responses/IdempotencyKeyConflict' }
1196
+ '422': { $ref: '#/components/responses/CreateSoundlinkUnprocessable' }
1197
+ '429': { $ref: '#/components/responses/RateLimited' }
1198
+ '500': { $ref: '#/components/responses/InternalError' }
1199
+
1014
1200
  /v1/soundlinks/{soundlinkId}:
1015
1201
  get:
1016
1202
  operationId: getSoundlink
@@ -1045,6 +1231,55 @@ paths:
1045
1231
  status: active
1046
1232
  createdAt: '2026-04-01T10:00:00Z'
1047
1233
  autoFollow: true
1234
+ artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1235
+ metaPixelId: '1234567890123456'
1236
+ tiktokPixelId: null
1237
+ meta:
1238
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1239
+ '401': { $ref: '#/components/responses/Unauthorized' }
1240
+ '403': { $ref: '#/components/responses/Forbidden' }
1241
+ '404': { $ref: '#/components/responses/NotFound' }
1242
+ '429': { $ref: '#/components/responses/RateLimited' }
1243
+ '500': { $ref: '#/components/responses/InternalError' }
1244
+
1245
+ delete:
1246
+ operationId: archiveSoundlink
1247
+ summary: Archive a soundlink
1248
+ description: |
1249
+ 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.
1253
+
1254
+ Requires `soundlinks:write`. Campaign-linked soundlinks, soundlinks
1255
+ that are not `active`, and ids that do not belong to the org return
1256
+ `404`. Does not require `Idempotency-Key`.
1257
+ tags: [Soundlinks]
1258
+ security:
1259
+ - apiKeyBearerAuth: []
1260
+ - oauthBearer: []
1261
+ x-required-scope: soundlinks:write
1262
+ parameters:
1263
+ - $ref: '#/components/parameters/soundlinkId'
1264
+ responses:
1265
+ '200':
1266
+ description: Soundlink archived
1267
+ content:
1268
+ application/json:
1269
+ schema:
1270
+ $ref: '#/components/schemas/SoundlinkDetailResponse'
1271
+ example:
1272
+ data:
1273
+ soundlinkId: V1StGXR8_Z5jdHi6B-myT
1274
+ organizationId: a7ac3173-2f71-4e79-921f-d15d7112dd11
1275
+ name: Midnight Drive
1276
+ url: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
1277
+ targetType: track
1278
+ spotifyUrl: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
1279
+ status: archived
1280
+ createdAt: '2026-04-01T10:00:00Z'
1281
+ autoFollow: true
1282
+ artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1048
1283
  metaPixelId: '1234567890123456'
1049
1284
  tiktokPixelId: null
1050
1285
  meta:
@@ -1061,10 +1296,12 @@ paths:
1061
1296
  summary: Soundlink metrics overview
1062
1297
  description: |
1063
1298
  Soundlink-level totals for a date range: landing page views, outbound
1064
- clicks, listeners (with new/returning splits), streams, followers, and
1065
- derived ratios. No per-day rows — use `/metrics/timeseries` for those.
1066
-
1067
- Maps to the **Overview** tab in the Soundlink Insights UI.
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).
1068
1305
 
1069
1306
  Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1070
1307
  tags: [Soundlinks]
@@ -1088,13 +1325,9 @@ paths:
1088
1325
  views: 4821
1089
1326
  link_clicks: 890
1090
1327
  streams: 9340
1091
- listeners: 4821
1092
- new_listeners: 3980
1093
- returning_listeners: 841
1094
- new_listener_streams: 7104
1095
- returning_listener_streams: 2236
1328
+ listeners: 3980
1096
1329
  followers: 312
1097
- streams_per_listener: 1.94
1330
+ streams_per_listener: 2.35
1098
1331
  ctr_lp: 0.185
1099
1332
  meta:
1100
1333
  requestId: 550e8400-e29b-41d4-a716-446655440000
@@ -1121,11 +1354,276 @@ paths:
1121
1354
  for up to 7 days after the date closes due to delayed Spotify playback
1122
1355
  events. Re-fetch or re-ingest accordingly.
1123
1356
 
1124
- Rows are aggregated across countries (no `country_code` in v1.0) and
1125
- contain no financial fields.
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.
1362
+
1363
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1364
+ tags: [Soundlinks]
1365
+ security:
1366
+ - apiKeyBearerAuth: []
1367
+ - oauthBearer: []
1368
+ x-required-scope: soundlinks:read
1369
+ parameters:
1370
+ - $ref: '#/components/parameters/soundlinkId'
1371
+ - $ref: '#/components/parameters/soundlinkStartDate'
1372
+ - $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
+ responses:
1383
+ '200':
1384
+ description: Paginated per-day rows (`soundlink_daily` schema)
1385
+ content:
1386
+ application/json:
1387
+ schema:
1388
+ $ref: '#/components/schemas/SoundlinkTimeseriesResponse'
1389
+ example:
1390
+ 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
1421
+ meta:
1422
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1423
+ '400': { $ref: '#/components/responses/BadRequest' }
1424
+ '401': { $ref: '#/components/responses/Unauthorized' }
1425
+ '403': { $ref: '#/components/responses/Forbidden' }
1426
+ '404': { $ref: '#/components/responses/NotFound' }
1427
+ '429': { $ref: '#/components/responses/RateLimited' }
1428
+ '500': { $ref: '#/components/responses/InternalError' }
1429
+
1430
+ /v1/soundlinks/{soundlinkId}/metrics/breakdown:
1431
+ get:
1432
+ operationId: getSoundlinkMetricsBreakdown
1433
+ summary: Soundlink metrics breakdown
1434
+ description: |
1435
+ Per-day metrics broken down by country. One row per
1436
+ `(report_date, soundlink_id, country_code)`. Can be large, so results
1437
+ are paginated.
1438
+
1439
+ **Row schema:** `soundlink_country_daily` v1.0 — the same schema used
1440
+ in JSONL bulk exports. Rows are idempotent on the primary key
1441
+ `(provider, account_id, report_date, soundlink_id, country_code)`;
1442
+ re-ingesting is safe.
1443
+
1444
+ **Mutability window:** rows for a given `report_date` can be revised
1445
+ for up to 7 days after the date closes due to delayed Spotify playback
1446
+ events. Re-fetch or re-ingest accordingly.
1447
+
1448
+ Rows contain no financial fields: ads for self-serve soundlinks run
1449
+ in your own Meta account, so spend is not visible to Soundlink.
1450
+
1451
+ Maps to the **Countries** tab in the Soundlink Insights UI.
1452
+ Use `/metrics/timeseries` for country-aggregated daily Trends rows.
1453
+
1454
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1455
+ tags: [Soundlinks]
1456
+ security:
1457
+ - apiKeyBearerAuth: []
1458
+ - oauthBearer: []
1459
+ x-required-scope: soundlinks:read
1460
+ parameters:
1461
+ - $ref: '#/components/parameters/soundlinkId'
1462
+ - $ref: '#/components/parameters/soundlinkStartDate'
1463
+ - $ref: '#/components/parameters/soundlinkEndDate'
1464
+ - $ref: '#/components/parameters/page'
1465
+ - $ref: '#/components/parameters/pageSize500'
1466
+ - name: sortBy
1467
+ in: query
1468
+ schema:
1469
+ type: string
1470
+ enum: [report_date, country_code]
1471
+ default: report_date
1472
+ - $ref: '#/components/parameters/sortOrder'
1473
+ responses:
1474
+ '200':
1475
+ description: Paginated per-day country rows (`soundlink_country_daily` schema)
1476
+ content:
1477
+ application/json:
1478
+ schema:
1479
+ $ref: '#/components/schemas/SoundlinkBreakdownResponse'
1480
+ example:
1481
+ data:
1482
+ schemaVersion: '1.0'
1483
+ items:
1484
+ - provider: soundlink
1485
+ account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
1486
+ schema_version: '1.0'
1487
+ report_date: '2026-08-01'
1488
+ report_date_timezone: UTC
1489
+ exported_at: '2026-08-28T03:00:00Z'
1490
+ soundlink_id: V1StGXR8_Z5jdHi6B-myT
1491
+ soundlink_name: Midnight Drive
1492
+ soundlink_target_type: track
1493
+ soundlink_target_isrc: DEXW62500259
1494
+ soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
1495
+ soundlink_target_playlist_id: null
1496
+ country_code: US
1497
+ views: 4821
1498
+ link_clicks: 890
1499
+ streams: 203
1500
+ listeners: 145
1501
+ new_listeners: 120
1502
+ returning_listeners: 25
1503
+ new_listener_streams: 160
1504
+ returning_listener_streams: 43
1505
+ followers: 12
1506
+ streams_per_listener: 1.4
1507
+ ctr_lp: 0.185
1508
+ pagination:
1509
+ page: 1
1510
+ pageSize: 50
1511
+ totalCount: 340
1512
+ totalPages: 7
1513
+ meta:
1514
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1515
+ '400': { $ref: '#/components/responses/BadRequest' }
1516
+ '401': { $ref: '#/components/responses/Unauthorized' }
1517
+ '403': { $ref: '#/components/responses/Forbidden' }
1518
+ '404': { $ref: '#/components/responses/NotFound' }
1519
+ '429': { $ref: '#/components/responses/RateLimited' }
1520
+ '500': { $ref: '#/components/responses/InternalError' }
1521
+
1522
+ /v1/soundlinks/{soundlinkId}/metrics/breakdown/export:
1523
+ get:
1524
+ operationId: exportSoundlinkMetricsBreakdown
1525
+ summary: Soundlink metrics breakdown export (JSONL)
1526
+ description: |
1527
+ Streams the full country-level metrics dataset for a soundlink as
1528
+ **newline-delimited JSON (JSONL)**. Every line is a complete, valid
1529
+ JSON object conforming to the `soundlink_country_daily` v1.0 schema
1530
+ — identical to the rows returned by `GET /metrics/breakdown` but
1531
+ without pagination or an envelope wrapper.
1532
+
1533
+ Designed for data pipeline consumers: load directly into BigQuery,
1534
+ Snowflake, or any JSONL-aware ingest tool without cursor logic.
1535
+
1536
+ **Usage:**
1537
+ ```
1538
+ GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export
1539
+ Accept: application/x-ndjson
1540
+ ```
1541
+
1542
+ **Date range:** if you omit both dates, defaults to the last **90 days**
1543
+ ending today. Override with `startDate` / `endDate`. **Responses are
1544
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
1545
+ Page longer histories in 90-day slices.
1546
+
1547
+ **Mutability:** rows for a given `report_date` can be revised for up
1548
+ to 7 days after the date closes due to delayed Spotify playback
1549
+ events. Re-fetching and re-ingesting on the primary key is safe
1550
+ (idempotent).
1551
+
1552
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1553
+ tags: [Soundlinks]
1554
+ security:
1555
+ - apiKeyBearerAuth: []
1556
+ - oauthBearer: []
1557
+ x-required-scope: soundlinks:read
1558
+ parameters:
1559
+ - $ref: '#/components/parameters/soundlinkId'
1560
+ - $ref: '#/components/parameters/startDate'
1561
+ - $ref: '#/components/parameters/endDate'
1562
+ responses:
1563
+ '200':
1564
+ description: |
1565
+ JSONL stream. Each line is a `soundlink_country_daily` v1.0 row.
1566
+ Lines are sorted by `(report_date asc, country_code)`.
1567
+ headers:
1568
+ Content-Disposition:
1569
+ schema:
1570
+ type: string
1571
+ description: |
1572
+ `attachment; filename="breakdown_{soundlinkId}_{startDate}_{endDate}.jsonl"`
1573
+ example: 'attachment; filename="breakdown_V1StGXR8_Z5jdHi6B-myT_2026-08-01_2026-08-31.jsonl"'
1574
+ X-Row-Count:
1575
+ schema:
1576
+ type: integer
1577
+ description: Total number of rows in the response.
1578
+ content:
1579
+ application/x-ndjson:
1580
+ schema:
1581
+ $ref: '#/components/schemas/SoundlinkCountryDailyRow'
1582
+ example: |
1583
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"country_code":"US","views":4821,"link_clicks":890,"streams":203,"listeners":145,"new_listeners":120,"returning_listeners":25,"new_listener_streams":160,"returning_listener_streams":43,"followers":12,"streams_per_listener":1.4,"ctr_lp":0.185}
1584
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"country_code":"DE","views":2103,"link_clicks":31,"streams":87,"listeners":61,"new_listeners":48,"returning_listeners":13,"new_listener_streams":64,"returning_listener_streams":23,"followers":4,"streams_per_listener":1.43,"ctr_lp":0.0147}
1585
+ '400': { $ref: '#/components/responses/BadRequest' }
1586
+ '401': { $ref: '#/components/responses/Unauthorized' }
1587
+ '403': { $ref: '#/components/responses/Forbidden' }
1588
+ '404': { $ref: '#/components/responses/NotFound' }
1589
+ '429': { $ref: '#/components/responses/RateLimited' }
1590
+ '500': { $ref: '#/components/responses/InternalError' }
1591
+
1592
+ /v1/soundlinks/{soundlinkId}/metrics/engagement:
1593
+ get:
1594
+ operationId: getSoundlinkEngagement
1595
+ summary: Soundlink engagement breakdown
1596
+ description: |
1597
+ Per-day, per-track engagement metrics for a soundlink. One row per
1598
+ `(report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id)`.
1599
+ Results are paginated.
1600
+
1601
+ **Row schema:** `soundlink_engagement_daily` v1.0 — the same schema used
1602
+ in JSONL bulk exports. Rows are idempotent on the primary key; re-ingesting
1603
+ is safe.
1604
+
1605
+ **Key difference from `/metrics/breakdown`:** breakdown aggregates
1606
+ views, streams, and listeners by **country** (`soundlink_country_daily`);
1607
+ engagement breaks down **which tracks** listeners played, including
1608
+ catalog spillover and playlist slot performance (`engagement_context`,
1609
+ `engaged_spotify_track_id`).
1610
+
1611
+ **`engagement_context` values:**
1612
+ - `catalog` — same-artist spillover (and direct promoted-track plays)
1613
+ on track soundlinks.
1614
+ - `playlist` — per-track performance inside the promoted playlist on
1615
+ playlist soundlinks.
1616
+
1617
+ **`listeners` is deduplicated within each row only.** Do not sum
1618
+ `listeners` across days to get a soundlink total.
1126
1619
 
1127
- Maps to the **Trends** tab in the Soundlink Insights UI.
1128
- Use for daily warehouse loads.
1620
+ **Date range:** if you omit both dates, defaults to the last **90 days**
1621
+ ending today. Override with `startDate` / `endDate`. **Responses are
1622
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
1623
+
1624
+ **Mutability window:** rows for a given `report_date` can be revised
1625
+ for up to 7 days after the date closes due to delayed Spotify
1626
+ playback events.
1129
1627
 
1130
1628
  Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1131
1629
  tags: [Soundlinks]
@@ -1135,8 +1633,14 @@ paths:
1135
1633
  x-required-scope: soundlinks:read
1136
1634
  parameters:
1137
1635
  - $ref: '#/components/parameters/soundlinkId'
1138
- - $ref: '#/components/parameters/soundlinkStartDate'
1139
- - $ref: '#/components/parameters/soundlinkEndDate'
1636
+ - $ref: '#/components/parameters/startDate'
1637
+ - $ref: '#/components/parameters/endDate'
1638
+ - name: engagementContext
1639
+ in: query
1640
+ schema:
1641
+ type: string
1642
+ enum: [catalog, playlist]
1643
+ description: Filter to a single engagement context. Omit to return both.
1140
1644
  - $ref: '#/components/parameters/page'
1141
1645
  - $ref: '#/components/parameters/pageSize500'
1142
1646
  - name: sortBy
@@ -1148,11 +1652,11 @@ paths:
1148
1652
  - $ref: '#/components/parameters/sortOrder'
1149
1653
  responses:
1150
1654
  '200':
1151
- description: Paginated per-day rows (`soundlink_daily` schema)
1655
+ description: Paginated engagement rows (`soundlink_engagement_daily` schema)
1152
1656
  content:
1153
1657
  application/json:
1154
1658
  schema:
1155
- $ref: '#/components/schemas/SoundlinkTimeseriesResponse'
1659
+ $ref: '#/components/schemas/SoundlinkEngagementResponse'
1156
1660
  example:
1157
1661
  data:
1158
1662
  schemaVersion: '1.0'
@@ -1169,22 +1673,24 @@ paths:
1169
1673
  soundlink_target_isrc: DEXW62500259
1170
1674
  soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
1171
1675
  soundlink_target_playlist_id: null
1172
- views: 4821
1173
- link_clicks: 890
1174
- streams: 203
1175
- listeners: 145
1176
- new_listeners: 120
1177
- returning_listeners: 25
1178
- new_listener_streams: 160
1179
- returning_listener_streams: 43
1180
- followers: 12
1181
- streams_per_listener: 1.4
1182
- ctr_lp: 0.185
1676
+ engagement_context: catalog
1677
+ country_code: US
1678
+ engaged_track_isrc: DEXW62500001
1679
+ engaged_spotify_track_id: 4cOdK2wGLETKBW3PvgPWqT
1680
+ engaged_track_name: Till The Sunrise
1681
+ playlist_position: null
1682
+ new_listeners: 42
1683
+ returning_listeners: 18
1684
+ listeners: 60
1685
+ new_listener_streams: 58
1686
+ returning_listener_streams: 31
1687
+ streams: 89
1688
+ spl: 1.48
1183
1689
  pagination:
1184
1690
  page: 1
1185
1691
  pageSize: 50
1186
- totalCount: 90
1187
- totalPages: 2
1692
+ totalCount: 120
1693
+ totalPages: 3
1188
1694
  meta:
1189
1695
  requestId: 550e8400-e29b-41d4-a716-446655440000
1190
1696
  '400': { $ref: '#/components/responses/BadRequest' }
@@ -1194,20 +1700,40 @@ paths:
1194
1700
  '429': { $ref: '#/components/responses/RateLimited' }
1195
1701
  '500': { $ref: '#/components/responses/InternalError' }
1196
1702
 
1197
- /v1/soundlinks/{soundlinkId}/metrics/engagement:
1703
+ /v1/soundlinks/{soundlinkId}/metrics/engagement/export:
1198
1704
  get:
1199
- operationId: getSoundlinkEngagement
1200
- summary: Soundlink engagement (top tracks)
1705
+ operationId: exportSoundlinkEngagement
1706
+ summary: Soundlink engagement export (JSONL)
1201
1707
  description: |
1202
- Top tracks for a soundlink, aggregated over the requested date range.
1203
- One item per track, sorted by streams by default. Results are
1204
- paginated.
1708
+ Streams the full engagement dataset for a soundlink as
1709
+ **newline-delimited JSON (JSONL)**. Every line is a complete, valid
1710
+ JSON object conforming to the `soundlink_engagement_daily` v1.0 schema
1711
+ — identical to the rows returned by `GET /metrics/engagement` but
1712
+ without pagination or an envelope wrapper.
1713
+
1714
+ Designed for data pipeline consumers: load directly into BigQuery,
1715
+ Snowflake, or any JSONL-aware ingest tool without cursor logic.
1716
+
1717
+ **Usage:**
1718
+ ```
1719
+ GET /v1/soundlinks/{soundlinkId}/metrics/engagement/export
1720
+ Accept: application/x-ndjson
1721
+ ```
1722
+
1723
+ **Response body (one JSON object per line, no trailing comma):**
1724
+ ```
1725
+ {"provider":"soundlink","report_date":"2026-08-01","streams":89,...}
1726
+ {"provider":"soundlink","report_date":"2026-08-02","streams":104,...}
1727
+ ```
1728
+
1729
+ **Date range:** if you omit both dates, defaults to the last **90 days**
1730
+ ending today. Override with `startDate` / `endDate`. **Responses are
1731
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
1732
+ Page longer histories in 90-day slices.
1205
1733
 
1206
- Returns period totals per track (not daily rows). Maps to the top
1207
- tracks section of the **Overview** tab in the Soundlink Insights UI.
1208
- `startDate`/`endDate` snap to the same Insights windows: yesterday,
1209
- last 7 days (inclusive span ending today), or all-time. Omitting
1210
- `startDate` always uses all-time (it is not inferred from createdAt).
1734
+ **Mutability:** rows for a given `report_date` can be revised for up to
1735
+ 7 days after the date closes. Re-fetching and re-ingesting on the
1736
+ primary key is safe (idempotent).
1211
1737
 
1212
1738
  Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1213
1739
  tags: [Soundlinks]
@@ -1217,44 +1743,37 @@ paths:
1217
1743
  x-required-scope: soundlinks:read
1218
1744
  parameters:
1219
1745
  - $ref: '#/components/parameters/soundlinkId'
1220
- - $ref: '#/components/parameters/soundlinkEngagementStartDate'
1221
- - $ref: '#/components/parameters/soundlinkEndDate'
1222
- - $ref: '#/components/parameters/page'
1223
- - $ref: '#/components/parameters/pageSize100'
1224
- - name: sortBy
1746
+ - $ref: '#/components/parameters/startDate'
1747
+ - $ref: '#/components/parameters/endDate'
1748
+ - name: engagementContext
1225
1749
  in: query
1226
1750
  schema:
1227
1751
  type: string
1228
- enum: [totalStreams, totalListeners]
1229
- default: totalStreams
1230
- - $ref: '#/components/parameters/sortOrder'
1752
+ enum: [catalog, playlist]
1753
+ description: Filter to a single engagement context. Omit to return both.
1231
1754
  responses:
1232
1755
  '200':
1233
- description: Paginated aggregated top tracks
1756
+ description: |
1757
+ JSONL stream. Each line is a `soundlink_engagement_daily` v1.0 row.
1758
+ Lines are sorted by `(report_date asc, engagement_context, country_code, engaged_spotify_track_id)`.
1759
+ headers:
1760
+ Content-Disposition:
1761
+ schema:
1762
+ type: string
1763
+ description: |
1764
+ `attachment; filename="engagement_{soundlinkId}_{startDate}_{endDate}.jsonl"`
1765
+ example: 'attachment; filename="engagement_V1StGXR8_Z5jdHi6B-myT_2026-08-01_2026-08-31.jsonl"'
1766
+ X-Row-Count:
1767
+ schema:
1768
+ type: integer
1769
+ description: Total number of rows in the response. Useful for progress tracking when streaming.
1234
1770
  content:
1235
- application/json:
1771
+ application/x-ndjson:
1236
1772
  schema:
1237
- $ref: '#/components/schemas/SoundlinkEngagementResponse'
1238
- example:
1239
- data:
1240
- items:
1241
- - trackId: 11dFghVXANMlKmJXsNCbNl
1242
- trackName: Midnight Drive
1243
- totalStreams: 892
1244
- totalListeners: 603
1245
- streamsPerListener: 1.48
1246
- - trackId: 4cOdK2wGLETKBW3PvgPWqT
1247
- trackName: Till The Sunrise
1248
- totalStreams: 411
1249
- totalListeners: 322
1250
- streamsPerListener: 1.28
1251
- pagination:
1252
- page: 1
1253
- pageSize: 10
1254
- totalCount: 24
1255
- totalPages: 3
1256
- meta:
1257
- requestId: 550e8400-e29b-41d4-a716-446655440000
1773
+ $ref: '#/components/schemas/SoundlinkEngagementDailyRow'
1774
+ example: |
1775
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"engagement_context":"catalog","country_code":"US","engaged_track_isrc":"DEXW62500001","engaged_spotify_track_id":"4cOdK2wGLETKBW3PvgPWqT","engaged_track_name":"Till The Sunrise","playlist_position":null,"new_listeners":42,"returning_listeners":18,"listeners":60,"new_listener_streams":58,"returning_listener_streams":31,"streams":89,"spl":1.48}
1776
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"playlist","soundlink_target_isrc":null,"soundlink_target_spotify_track_id":null,"soundlink_target_playlist_id":"37i9dQZF1Epwit2GR54N9P","engagement_context":"playlist","country_code":"DE","engaged_track_isrc":"DEXW62500001","engaged_spotify_track_id":"4cOdK2wGLETKBW3PvgPWqT","engaged_track_name":"Till The Sunrise","playlist_position":14,"new_listeners":19,"returning_listeners":7,"listeners":26,"new_listener_streams":24,"returning_listener_streams":11,"streams":35,"spl":1.35}
1258
1777
  '400': { $ref: '#/components/responses/BadRequest' }
1259
1778
  '401': { $ref: '#/components/responses/Unauthorized' }
1260
1779
  '403': { $ref: '#/components/responses/Forbidden' }
@@ -1472,18 +1991,6 @@ components:
1472
1991
  Inclusive start date (`YYYY-MM-DD`) for soundlink overview and
1473
1992
  timeseries. Defaults to the soundlink creation date when omitted.
1474
1993
 
1475
- soundlinkEngagementStartDate:
1476
- name: startDate
1477
- in: query
1478
- schema:
1479
- type: string
1480
- format: date
1481
- description: |
1482
- Inclusive start date (`YYYY-MM-DD`) for soundlink engagement
1483
- (top tracks). Omit for all-time (not createdAt). When set, snaps
1484
- to Insights windows (yesterday / last 7 days ending today /
1485
- all-time); other ranges resolve to all-time.
1486
-
1487
1994
  soundlinkEndDate:
1488
1995
  name: endDate
1489
1996
  in: query
@@ -1528,9 +2035,7 @@ components:
1528
2035
  - invalid_api_key
1529
2036
  - api_key_revoked
1530
2037
  - api_key_expired
1531
- - invalid_token
1532
2038
  - insufficient_scope
1533
- - access_denied
1534
2039
  - not_found
1535
2040
  - campaign_not_found
1536
2041
  - invalid_query_parameter
@@ -2352,6 +2857,27 @@ components:
2352
2857
  meta:
2353
2858
  $ref: '#/components/schemas/Meta'
2354
2859
 
2860
+ MetricsEngagementResponse:
2861
+ type: object
2862
+ required: [data, meta]
2863
+ properties:
2864
+ data:
2865
+ type: object
2866
+ required: [schemaVersion, items, pagination]
2867
+ properties:
2868
+ schemaVersion:
2869
+ type: string
2870
+ description: Version of the `campaign_engagement_daily` row schema. Pin your ingest pipeline to this.
2871
+ example: '1.0'
2872
+ items:
2873
+ type: array
2874
+ items:
2875
+ $ref: '#/components/schemas/EngagementRow'
2876
+ pagination:
2877
+ $ref: '#/components/schemas/Pagination'
2878
+ meta:
2879
+ $ref: '#/components/schemas/Meta'
2880
+
2355
2881
  # --- Engagement ---
2356
2882
 
2357
2883
  EngagementRow:
@@ -2569,17 +3095,50 @@ components:
2569
3095
  meta:
2570
3096
  $ref: '#/components/schemas/Meta'
2571
3097
 
3098
+ CreateSoundlinkRequest:
3099
+ type: object
3100
+ required: [name, spotifyUrl]
3101
+ properties:
3102
+ name:
3103
+ type: string
3104
+ minLength: 1
3105
+ description: Human-readable soundlink name.
3106
+ spotifyUrl:
3107
+ type: string
3108
+ format: uri
3109
+ description: HTTPS Spotify track or playlist URL.
3110
+ example: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
3111
+ autoFollow:
3112
+ type: boolean
3113
+ default: false
3114
+ artistIdFollow:
3115
+ type: string
3116
+ metaPixelId:
3117
+ type: string
3118
+ metaConversionAccessToken:
3119
+ type: string
3120
+ writeOnly: true
3121
+ description: |
3122
+ Meta Conversions API access token. Write-only: accepted on create,
3123
+ never returned on GET. Must be sent together with `metaPixelId`.
3124
+
2572
3125
  SoundlinkDetail:
2573
3126
  allOf:
2574
3127
  - $ref: '#/components/schemas/SoundlinkSummary'
2575
3128
  - type: object
2576
- required: [autoFollow, metaPixelId, tiktokPixelId]
3129
+ required: [autoFollow, artistIdFollow, metaPixelId, tiktokPixelId]
2577
3130
  properties:
2578
3131
  autoFollow:
2579
3132
  type: boolean
2580
3133
  description: |
2581
3134
  Whether auto-follow is configured for this soundlink. Whether
2582
3135
  it takes effect also depends on the organization's plan.
3136
+ artistIdFollow:
3137
+ type: string
3138
+ nullable: true
3139
+ description: |
3140
+ Spotify artist ID configured for auto-follow on track links.
3141
+ Unused for playlists. `null` if not set.
2583
3142
  metaPixelId:
2584
3143
  type: string
2585
3144
  nullable: true
@@ -2600,12 +3159,129 @@ components:
2600
3159
 
2601
3160
  SoundlinkMetricsOverview:
2602
3161
  type: object
2603
- description: Soundlink-level totals for the requested date range.
3162
+ description: |
3163
+ Soundlink-level totals for the requested date range. Additive fields
3164
+ are sums of `api_smart_link_country_daily` country-day rows.
2604
3165
  required: [views, streams, listeners, followers, streams_per_listener]
2605
3166
  properties:
2606
3167
  views:
2607
3168
  type: integer
2608
- description: Soundlink landing page views in the period.
3169
+ description: Soundlink landing page views in the period (sum of country-day rows).
3170
+ link_clicks:
3171
+ type: integer
3172
+ nullable: true
3173
+ description: |
3174
+ Clicks on "Continue with Spotify" on the landing page — outbound
3175
+ clicks to Spotify. Null if not tracked for this soundlink type.
3176
+ streams:
3177
+ type: integer
3178
+ description: Attributed Spotify streams (sum of country-day rows).
3179
+ listeners:
3180
+ type: integer
3181
+ description: |
3182
+ Sum of country-day `new_listeners` from the mart (first-play
3183
+ attributed listeners). Not period-unique across days/countries,
3184
+ and not equal to summing breakdown `listeners` (new + returning).
3185
+ followers:
3186
+ type: integer
3187
+ description: Attributed Spotify artist follower gains in the period.
3188
+ streams_per_listener:
3189
+ type: number
3190
+ description: streams / listeners. Zero if listeners is zero.
3191
+ ctr_lp:
3192
+ type: number
3193
+ nullable: true
3194
+ description: |
3195
+ Landing page click-through rate (link_clicks / views). Computed
3196
+ against landing page views, not ad impressions — do not combine
3197
+ with `ctr_linkclick` from campaign metrics. Null if views is zero
3198
+ or link_clicks is null.
3199
+
3200
+ SoundlinkMetricsOverviewResponse:
3201
+ type: object
3202
+ required: [data, meta]
3203
+ properties:
3204
+ data:
3205
+ $ref: '#/components/schemas/SoundlinkMetricsOverview'
3206
+ meta:
3207
+ $ref: '#/components/schemas/Meta'
3208
+
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.
2609
3285
  link_clicks:
2610
3286
  type: integer
2611
3287
  nullable: true
@@ -2614,60 +3290,78 @@ components:
2614
3290
  clicks to Spotify. Null if not tracked for this soundlink type.
2615
3291
  streams:
2616
3292
  type: integer
2617
- description: Attributed Spotify streams (sum of daily rows).
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.
2618
3298
  listeners:
2619
3299
  type: integer
2620
- description: Unique attributed Spotify listeners in the period.
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.
2621
3304
  new_listeners:
2622
3305
  type: integer
2623
3306
  nullable: true
2624
- description: Unique listeners whose first play via this soundlink occurred in the period.
3307
+ description: Unique listeners whose first play via this soundlink occurred on `report_date`.
2625
3308
  returning_listeners:
2626
3309
  type: integer
2627
3310
  nullable: true
2628
- description: Unique listeners who played in the period but whose first play was earlier.
3311
+ description: Unique listeners who played on `report_date` but whose first play was on an earlier date.
2629
3312
  new_listener_streams:
2630
3313
  type: integer
2631
3314
  nullable: true
2632
- description: Stream count from new listeners in the period.
3315
+ description: Stream count from new listeners on `report_date`.
2633
3316
  returning_listener_streams:
2634
3317
  type: integer
2635
3318
  nullable: true
2636
- description: Stream count from returning listeners in the period.
3319
+ description: Stream count from returning listeners on `report_date`.
2637
3320
  followers:
2638
3321
  type: integer
2639
- description: Attributed Spotify artist follower gains in the period.
3322
+ description: Spotify artist follower gains attributed to this soundlink on this day.
2640
3323
  streams_per_listener:
2641
3324
  type: number
2642
- description: streams / listeners. Zero if listeners is zero.
3325
+ description: streams / listeners for this row. Zero if listeners is zero.
2643
3326
  ctr_lp:
2644
3327
  type: number
2645
3328
  nullable: true
2646
3329
  description: |
2647
3330
  Landing page click-through rate (link_clicks / views). Computed
2648
3331
  against landing page views, not ad impressions — do not combine
2649
- with `ctr_linkclick` from campaign metrics. Null if views is zero
2650
- or link_clicks is null.
3332
+ with `ctr_linkclick` from `campaign_country_daily`. Null if views
3333
+ is zero or link_clicks is null.
2651
3334
 
2652
- SoundlinkMetricsOverviewResponse:
3335
+ SoundlinkTimeseriesResponse:
2653
3336
  type: object
2654
3337
  required: [data, meta]
2655
3338
  properties:
2656
3339
  data:
2657
- $ref: '#/components/schemas/SoundlinkMetricsOverview'
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'
2658
3353
  meta:
2659
3354
  $ref: '#/components/schemas/Meta'
2660
3355
 
2661
- SoundlinkDailyRow:
3356
+ SoundlinkCountryDailyRow:
2662
3357
  type: object
2663
3358
  description: |
2664
- One row of the `soundlink_daily` v1.0 schema.
2665
- Primary key: `(provider, account_id, report_date, soundlink_id)`.
3359
+ One row of the `soundlink_country_daily` v1.0 schema.
3360
+ Primary key: `(provider, account_id, report_date, soundlink_id, country_code)`.
2666
3361
  Rows are idempotent — re-ingesting on the primary key is safe.
2667
3362
  Values for a given `report_date` may be revised for up to 7 days after
2668
3363
  the date closes due to delayed Spotify playback events.
2669
- Rows are aggregated across countries (no `country_code` in v1.0) and
2670
- contain no financial fields.
3364
+ Rows contain no financial fields.
2671
3365
  required:
2672
3366
  - provider
2673
3367
  - account_id
@@ -2678,6 +3372,7 @@ components:
2678
3372
  - soundlink_id
2679
3373
  - soundlink_name
2680
3374
  - soundlink_target_type
3375
+ - country_code
2681
3376
  - views
2682
3377
  - streams
2683
3378
  - listeners
@@ -2731,9 +3426,12 @@ components:
2731
3426
  type: string
2732
3427
  nullable: true
2733
3428
  description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
3429
+ country_code:
3430
+ type: string
3431
+ description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
2734
3432
  views:
2735
3433
  type: integer
2736
- description: Soundlink landing page views on this day.
3434
+ description: Soundlink landing page views in this country on this day.
2737
3435
  link_clicks:
2738
3436
  type: integer
2739
3437
  nullable: true
@@ -2743,35 +3441,36 @@ components:
2743
3441
  streams:
2744
3442
  type: integer
2745
3443
  description: |
2746
- Spotify streams attributed to this soundlink on this day:
2747
- `new_listener_streams + returning_listener_streams`. Observed
3444
+ Spotify streams attributed to this soundlink in this country on this
3445
+ day: `new_listener_streams + returning_listener_streams`. Observed
2748
3446
  Spotify-side events, not modelled estimates. Safe to sum within a
2749
3447
  day; summing across days counts repeat listens.
2750
3448
  listeners:
2751
3449
  type: integer
2752
3450
  description: |
2753
- Unique Spotify listeners attributed to this soundlink on this day:
2754
- `new_listeners + returning_listeners`. **Do not sum across days** —
2755
- the same listener can appear on multiple `report_date` rows.
3451
+ Unique Spotify listeners attributed to this soundlink in this
3452
+ country on this day: `new_listeners + returning_listeners`.
3453
+ **Do not sum across days** — the same listener can appear on
3454
+ multiple `report_date` rows.
2756
3455
  new_listeners:
2757
3456
  type: integer
2758
3457
  nullable: true
2759
- description: Unique listeners whose first play via this soundlink occurred on `report_date`.
3458
+ description: Unique listeners whose first play via this soundlink occurred on `report_date` in this country.
2760
3459
  returning_listeners:
2761
3460
  type: integer
2762
3461
  nullable: true
2763
- description: Unique listeners who played on `report_date` but whose first play was on an earlier date.
3462
+ description: Unique listeners who played on `report_date` in this country but whose first play was on an earlier date.
2764
3463
  new_listener_streams:
2765
3464
  type: integer
2766
3465
  nullable: true
2767
- description: Stream count from new listeners on `report_date`.
3466
+ description: Stream count from new listeners on `report_date` in this country.
2768
3467
  returning_listener_streams:
2769
3468
  type: integer
2770
3469
  nullable: true
2771
- description: Stream count from returning listeners on `report_date`.
3470
+ description: Stream count from returning listeners on `report_date` in this country.
2772
3471
  followers:
2773
3472
  type: integer
2774
- description: Spotify artist follower gains attributed to this soundlink on this day.
3473
+ description: Spotify artist follower gains attributed to this soundlink in this country on this day.
2775
3474
  streams_per_listener:
2776
3475
  type: number
2777
3476
  description: streams / listeners for this row. Zero if listeners is zero.
@@ -2784,7 +3483,7 @@ components:
2784
3483
  with `ctr_linkclick` from `campaign_country_daily`. Null if views
2785
3484
  is zero or link_clicks is null.
2786
3485
 
2787
- SoundlinkTimeseriesResponse:
3486
+ SoundlinkBreakdownResponse:
2788
3487
  type: object
2789
3488
  required: [data, meta]
2790
3489
  properties:
@@ -2794,60 +3493,180 @@ components:
2794
3493
  properties:
2795
3494
  schemaVersion:
2796
3495
  type: string
2797
- description: Version of the `soundlink_daily` row schema. Pin your ingest pipeline to this.
3496
+ description: Version of the `soundlink_country_daily` row schema. Pin your ingest pipeline to this.
2798
3497
  example: '1.0'
2799
3498
  items:
2800
3499
  type: array
2801
3500
  items:
2802
- $ref: '#/components/schemas/SoundlinkDailyRow'
3501
+ $ref: '#/components/schemas/SoundlinkCountryDailyRow'
2803
3502
  pagination:
2804
3503
  $ref: '#/components/schemas/Pagination'
2805
3504
  meta:
2806
3505
  $ref: '#/components/schemas/Meta'
2807
3506
 
2808
- SoundlinkEngagementItem:
2809
- type: object
2810
- description: |
2811
- One track aggregated over the requested date range (period totals,
2812
- not daily rows).
2813
- required: [trackId, trackName, totalStreams, totalListeners, streamsPerListener]
2814
- properties:
2815
- trackId:
2816
- type: string
2817
- description: Spotify track ID of the engaged track.
2818
- example: 4cOdK2wGLETKBW3PvgPWqT
2819
- trackName:
2820
- type: string
2821
- description: Display name of the engaged track.
2822
- totalStreams:
2823
- type: integer
2824
- minimum: 0
2825
- description: Total streams of this track in the period.
2826
- totalListeners:
2827
- type: integer
2828
- minimum: 0
2829
- description: Unique listeners of this track in the period.
2830
- streamsPerListener:
2831
- type: number
2832
- description: totalStreams / totalListeners. Zero if totalListeners is zero.
2833
-
2834
3507
  SoundlinkEngagementResponse:
2835
3508
  type: object
2836
3509
  required: [data, meta]
2837
3510
  properties:
2838
3511
  data:
2839
3512
  type: object
2840
- required: [items, pagination]
3513
+ required: [schemaVersion, items, pagination]
2841
3514
  properties:
3515
+ schemaVersion:
3516
+ type: string
3517
+ description: Version of the `soundlink_engagement_daily` row schema. Pin your ingest pipeline to this.
3518
+ example: '1.0'
2842
3519
  items:
2843
3520
  type: array
2844
3521
  items:
2845
- $ref: '#/components/schemas/SoundlinkEngagementItem'
3522
+ $ref: '#/components/schemas/SoundlinkEngagementDailyRow'
2846
3523
  pagination:
2847
3524
  $ref: '#/components/schemas/Pagination'
2848
3525
  meta:
2849
3526
  $ref: '#/components/schemas/Meta'
2850
3527
 
3528
+ SoundlinkEngagementDailyRow:
3529
+ type: object
3530
+ description: |
3531
+ One row of the `soundlink_engagement_daily` v1.0 schema.
3532
+ Primary key: `(provider, account_id, report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id)`.
3533
+ Rows are idempotent — re-ingesting on the primary key is safe.
3534
+ Values for a given `report_date` may be revised for up to 7 days after
3535
+ the date closes due to delayed Spotify playback events.
3536
+ No `status` field: soundlinks do not store per-day lifecycle history.
3537
+ No financial fields.
3538
+ required:
3539
+ - provider
3540
+ - account_id
3541
+ - schema_version
3542
+ - report_date
3543
+ - report_date_timezone
3544
+ - exported_at
3545
+ - soundlink_id
3546
+ - soundlink_name
3547
+ - soundlink_target_type
3548
+ - engagement_context
3549
+ - country_code
3550
+ - engaged_spotify_track_id
3551
+ - engaged_track_name
3552
+ - new_listeners
3553
+ - returning_listeners
3554
+ - listeners
3555
+ - new_listener_streams
3556
+ - returning_listener_streams
3557
+ - streams
3558
+ - spl
3559
+ properties:
3560
+ provider:
3561
+ type: string
3562
+ enum: [soundlink]
3563
+ description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
3564
+ account_id:
3565
+ type: string
3566
+ description: Soundlink organization ID (UUID).
3567
+ schema_version:
3568
+ type: string
3569
+ description: Schema version string. Pin your ingest pipeline to this value.
3570
+ example: '1.0'
3571
+ report_date:
3572
+ type: string
3573
+ format: date
3574
+ description: UTC calendar date the metrics belong to (`YYYY-MM-DD`). Rows can change for up to 7 days after close.
3575
+ report_date_timezone:
3576
+ type: string
3577
+ enum: [UTC]
3578
+ description: Always `UTC`.
3579
+ exported_at:
3580
+ type: string
3581
+ format: date-time
3582
+ description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
3583
+ soundlink_id:
3584
+ type: string
3585
+ description: Unique ID of this soundlink.
3586
+ example: V1StGXR8_Z5jdHi6B-myT
3587
+ soundlink_name:
3588
+ type: string
3589
+ description: Human-readable soundlink name.
3590
+ soundlink_target_type:
3591
+ type: string
3592
+ nullable: true
3593
+ enum: [track, playlist]
3594
+ description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
3595
+ soundlink_target_isrc:
3596
+ type: string
3597
+ nullable: true
3598
+ description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
3599
+ soundlink_target_spotify_track_id:
3600
+ type: string
3601
+ nullable: true
3602
+ description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
3603
+ soundlink_target_playlist_id:
3604
+ type: string
3605
+ nullable: true
3606
+ description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
3607
+ engagement_context:
3608
+ type: string
3609
+ enum: [catalog, playlist]
3610
+ description: |
3611
+ Which section this row belongs to.
3612
+ `catalog`: plays of the promoted track and same-artist catalog tracks (track soundlinks).
3613
+ `playlist`: per-track performance inside the promoted playlist (playlist soundlinks).
3614
+ country_code:
3615
+ type: string
3616
+ description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
3617
+ example: US
3618
+ engaged_track_isrc:
3619
+ type: string
3620
+ nullable: true
3621
+ description: |
3622
+ ISRC of the track that received listens. May differ from `soundlink_target_isrc`
3623
+ for catalog spillover rows. `null` if ISRC could not be resolved.
3624
+ engaged_spotify_track_id:
3625
+ type: string
3626
+ description: Spotify track ID of the engaged track. Part of the primary key.
3627
+ example: 4cOdK2wGLETKBW3PvgPWqT
3628
+ engaged_track_name:
3629
+ type: string
3630
+ description: Display name of the engaged track.
3631
+ playlist_position:
3632
+ type: integer
3633
+ nullable: true
3634
+ minimum: 1
3635
+ description: |
3636
+ 1-based slot of the engaged track on the promoted playlist for `report_date` (1 = top).
3637
+ Populated only when `engagement_context = playlist`. Treat `null` as unavailable, not an error.
3638
+ new_listeners:
3639
+ type: integer
3640
+ minimum: 0
3641
+ description: Unique listeners whose first play of this track via this soundlink occurred on `report_date`.
3642
+ returning_listeners:
3643
+ type: integer
3644
+ minimum: 0
3645
+ description: Unique listeners who played this track on `report_date` but whose first play was on an earlier date.
3646
+ listeners:
3647
+ type: integer
3648
+ minimum: 0
3649
+ description: |
3650
+ Total unique listeners on `report_date`: `new_listeners + returning_listeners`.
3651
+ **Do not sum across days** — the same listener can appear on multiple `report_date` rows.
3652
+ new_listener_streams:
3653
+ type: integer
3654
+ minimum: 0
3655
+ description: Stream count from new listeners on `report_date`.
3656
+ returning_listener_streams:
3657
+ type: integer
3658
+ minimum: 0
3659
+ description: Stream count from returning listeners on `report_date`.
3660
+ streams:
3661
+ type: integer
3662
+ minimum: 0
3663
+ description: |
3664
+ Total streams on `report_date`: `new_listener_streams + returning_listener_streams`.
3665
+ Safe to sum within a day; summing across days counts repeat listens.
3666
+ spl:
3667
+ type: number
3668
+ description: Streams per listener (`streams / listeners`). Zero if `listeners` is zero.
3669
+
2851
3670
  # --- Videos ---
2852
3671
 
2853
3672
  VideoImportRequest:
@@ -3182,6 +4001,69 @@ components:
3182
4001
  meta:
3183
4002
  requestId: 550e8400-e29b-41d4-a716-446655440000
3184
4003
 
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
+
3185
4067
  IdempotencyKeyConflict:
3186
4068
  description: |
3187
4069
  The `Idempotency-Key` was reused with a materially different request