soundlink 1.2.0 → 2.1.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.
@@ -7,10 +7,43 @@ info:
7
7
 
8
8
  **Base URL:** `https://api.getsoundlink.com`
9
9
 
10
- **Authentication:** `x-api-key` header using a `sk_*` API key created in the Soundlink app (Settings → Developer → API keys).
11
- ```
12
- x-api-key: sk_abc123_<token>
13
- ```
10
+ ## Authentication
11
+
12
+ Send `Authorization: Bearer` with one of:
13
+
14
+ 1. **API key (recommended)** — a `sk_*` key from the Soundlink app
15
+ (Settings → Developer → API keys):
16
+ ```
17
+ Authorization: Bearer sk_abc123_<token>
18
+ ```
19
+
20
+ 2. **OAuth Bearer** — an access token from Sign in with Soundlink
21
+ (authorization code or client credentials). Token scopes use the
22
+ same strings as Public API key scopes (for example `campaigns:read`,
23
+ `metrics:read`):
24
+ ```
25
+ Authorization: Bearer <oauth_access_token>
26
+ ```
27
+
28
+ `x-api-key` is no longer accepted and is ignored if sent. Requests
29
+ without `Authorization: Bearer` return `401 invalid_api_key` (or
30
+ `401 invalid_token` when a Bearer value is present but neither a
31
+ recognized `sk_*` key nor a valid OAuth access token).
32
+
33
+ ### Which operations accept OAuth?
34
+
35
+ | Operations | Required scope | Auth |
36
+ | --- | --- | --- |
37
+ | `GET /v1/ping` | any granted Public API scope | API key (Bearer) or OAuth Bearer |
38
+ | Campaign reads (`GET /v1/strategies`, `GET /v1/campaigns`, campaign detail, tiers) | `campaigns:read` | API key (Bearer) or OAuth Bearer |
39
+ | Metrics reads (overview, breakdown, exports) | `metrics:read` | API key (Bearer) or OAuth Bearer |
40
+ | Campaign writes (create, stop, budget, tier updates) | `campaigns:write` | API key (Bearer) or OAuth Bearer |
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 |
43
+
44
+ Per-operation scope requirements are also marked with `x-required-scope`
45
+ (except `GET /v1/ping`, which accepts any valid credential with at least
46
+ one Public API scope granted to the key/token).
14
47
 
15
48
  All responses are wrapped in a standard envelope:
16
49
  ```json
@@ -24,7 +57,8 @@ servers:
24
57
  description: Production
25
58
 
26
59
  security:
27
- - apiKeyAuth: []
60
+ - apiKeyBearerAuth: []
61
+ - oauthBearer: []
28
62
 
29
63
  tags:
30
64
  - name: System
@@ -35,6 +69,8 @@ tags:
35
69
  description: Campaign performance metrics
36
70
  - name: Videos
37
71
  description: Partner video library import for Full Control campaigns
72
+ - name: Soundlinks
73
+ description: Soundlink listing, detail, and performance metrics
38
74
 
39
75
  paths:
40
76
  /v1/ping:
@@ -43,11 +79,13 @@ paths:
43
79
  summary: Verify connectivity and authentication
44
80
  description: |
45
81
  Returns `{ "status": "ok" }` if the request is authenticated and the
46
- API is reachable. Useful for verifying a newly issued key before making
47
- data requests.
82
+ API is reachable. Useful for verifying a newly issued API key or OAuth
83
+ access token before making data requests. Accepts either credential;
84
+ no specific scope is required beyond a valid key/token.
48
85
  tags: [System]
49
86
  security:
50
- - apiKeyAuth: []
87
+ - apiKeyBearerAuth: []
88
+ - oauthBearer: []
51
89
  responses:
52
90
  '200':
53
91
  description: Authenticated and reachable
@@ -84,10 +122,11 @@ paths:
84
122
  `POST /v1/campaigns`. Built-in strategies apply platform default
85
123
  tiering internally; only `custom` allows `tierTargeting` on create.
86
124
 
87
- Requires the `campaigns:read` scope.
125
+ Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
88
126
  tags: [Campaigns]
89
127
  security:
90
- - apiKeyAuth: []
128
+ - apiKeyBearerAuth: []
129
+ - oauthBearer: []
91
130
  x-required-scope: campaigns:read
92
131
  responses:
93
132
  '200':
@@ -121,9 +160,13 @@ paths:
121
160
  description: |
122
161
  Returns all campaigns for the authenticated organization.
123
162
  Intended for reporting and data warehouse sync.
163
+
164
+ Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
124
165
  tags: [Campaigns]
125
166
  security:
126
- - apiKeyAuth: []
167
+ - apiKeyBearerAuth: []
168
+ - oauthBearer: []
169
+ x-required-scope: campaigns:read
127
170
  parameters:
128
171
  - $ref: '#/components/parameters/page'
129
172
  - $ref: '#/components/parameters/pageSize100'
@@ -177,9 +220,12 @@ paths:
177
220
  deducted from the wallet balance), so the `Idempotency-Key` header
178
221
  is **required** on every request. See the header description below
179
222
  for retry semantics.
223
+
224
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
180
225
  tags: [Campaigns]
181
226
  security:
182
- - apiKeyAuth: []
227
+ - apiKeyBearerAuth: []
228
+ - oauthBearer: []
183
229
  x-required-scope: campaigns:write
184
230
  parameters:
185
231
  - $ref: '#/components/parameters/idempotencyKey'
@@ -269,10 +315,15 @@ paths:
269
315
  get:
270
316
  operationId: getCampaign
271
317
  summary: Get campaign
272
- description: Fetch full details for a single campaign.
318
+ description: |
319
+ Fetch full details for a single campaign.
320
+
321
+ Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
273
322
  tags: [Campaigns]
274
323
  security:
275
- - apiKeyAuth: []
324
+ - apiKeyBearerAuth: []
325
+ - oauthBearer: []
326
+ x-required-scope: campaigns:read
276
327
  parameters:
277
328
  - $ref: '#/components/parameters/campaignId'
278
329
  responses:
@@ -316,10 +367,13 @@ paths:
316
367
  already-stopped campaign succeeds without double-refunding. The
317
368
  `Idempotency-Key` header is also **required** so retries of the same
318
369
  request replay the original response without repeating side effects.
370
+
371
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
319
372
  tags: [Campaigns]
320
373
  x-required-scope: campaigns:write
321
374
  security:
322
- - apiKeyAuth: []
375
+ - apiKeyBearerAuth: []
376
+ - oauthBearer: []
323
377
  parameters:
324
378
  - $ref: '#/components/parameters/campaignId'
325
379
  - $ref: '#/components/parameters/idempotencyKey'
@@ -361,10 +415,13 @@ paths:
361
415
  - `current_and_renewals` — applies to the current cycle and future renewals
362
416
 
363
417
  Debits the organization wallet when the current cycle is increased.
418
+
419
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
364
420
  tags: [Campaigns]
365
421
  x-required-scope: campaigns:write
366
422
  security:
367
- - apiKeyAuth: []
423
+ - apiKeyBearerAuth: []
424
+ - oauthBearer: []
368
425
  parameters:
369
426
  - $ref: '#/components/parameters/campaignId'
370
427
  - $ref: '#/components/parameters/idempotencyKey'
@@ -433,10 +490,13 @@ paths:
433
490
  - `targetDailyBudget` must be at least `$10`/day and lower than the
434
491
  current daily budget
435
492
  - more than 3 days must remain in the current cycle
493
+
494
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
436
495
  tags: [Campaigns]
437
496
  x-required-scope: campaigns:write
438
497
  security:
439
- - apiKeyAuth: []
498
+ - apiKeyBearerAuth: []
499
+ - oauthBearer: []
440
500
  parameters:
441
501
  - $ref: '#/components/parameters/campaignId'
442
502
  - $ref: '#/components/parameters/idempotencyKey'
@@ -483,10 +543,13 @@ paths:
483
543
  updated (`lastUpdate`). Use this before `PATCH` to build a valid request.
484
544
 
485
545
  **Wallet campaigns only** (`generation: 3`).
546
+
547
+ Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
486
548
  tags: [Campaigns]
487
549
  x-required-scope: campaigns:read
488
550
  security:
489
- - apiKeyAuth: []
551
+ - apiKeyBearerAuth: []
552
+ - oauthBearer: []
490
553
  parameters:
491
554
  - $ref: '#/components/parameters/campaignId'
492
555
  responses:
@@ -533,10 +596,13 @@ paths:
533
596
 
534
597
  **Cooldown:** after a successful update, further tier changes are
535
598
  blocked for **72 hours** (`409 tier_update_cooldown`).
599
+
600
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
536
601
  tags: [Campaigns]
537
602
  x-required-scope: campaigns:write
538
603
  security:
539
- - apiKeyAuth: []
604
+ - apiKeyBearerAuth: []
605
+ - oauthBearer: []
540
606
  parameters:
541
607
  - $ref: '#/components/parameters/campaignId'
542
608
  requestBody:
@@ -598,9 +664,13 @@ paths:
598
664
  `/metrics/breakdown` for those.
599
665
 
600
666
  Suitable for dashboards and quick syncs.
667
+
668
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
601
669
  tags: [Metrics]
602
670
  security:
603
- - apiKeyAuth: []
671
+ - apiKeyBearerAuth: []
672
+ - oauthBearer: []
673
+ x-required-scope: metrics:read
604
674
  parameters:
605
675
  - $ref: '#/components/parameters/campaignId'
606
676
  - $ref: '#/components/parameters/startDate'
@@ -656,9 +726,13 @@ paths:
656
726
 
657
727
  Maps to the **Countries** tab in the Soundlink Insights UI.
658
728
  Use for daily warehouse loads.
729
+
730
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
659
731
  tags: [Metrics]
660
732
  security:
661
- - apiKeyAuth: []
733
+ - apiKeyBearerAuth: []
734
+ - oauthBearer: []
735
+ x-required-scope: metrics:read
662
736
  parameters:
663
737
  - $ref: '#/components/parameters/campaignId'
664
738
  - $ref: '#/components/parameters/startDate'
@@ -758,9 +832,13 @@ paths:
758
832
  to 7 days after the date closes due to delayed events from Meta and
759
833
  Spotify. Re-fetching and re-ingesting on the primary key is safe
760
834
  (idempotent).
835
+
836
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
761
837
  tags: [Metrics]
762
838
  security:
763
- - apiKeyAuth: []
839
+ - apiKeyBearerAuth: []
840
+ - oauthBearer: []
841
+ x-required-scope: metrics:read
764
842
  parameters:
765
843
  - $ref: '#/components/parameters/campaignId'
766
844
  - $ref: '#/components/parameters/startDate'
@@ -827,9 +905,13 @@ paths:
827
905
  **Mutability:** rows for a given `report_date` can be revised for up to
828
906
  7 days after the date closes. Re-fetching and re-ingesting on the
829
907
  primary key is safe (idempotent).
908
+
909
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
830
910
  tags: [Metrics]
831
911
  security:
832
- - apiKeyAuth: []
912
+ - apiKeyBearerAuth: []
913
+ - oauthBearer: []
914
+ x-required-scope: metrics:read
833
915
  parameters:
834
916
  - $ref: '#/components/parameters/campaignId'
835
917
  - $ref: '#/components/parameters/startDate'
@@ -862,7 +944,317 @@ paths:
862
944
  $ref: '#/components/schemas/EngagementRow'
863
945
  example: |
864
946
  {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112cc9a","schema_version":"1.0","report_date":"2026-04-08","report_date_timezone":"UTC","exported_at":"2026-05-22T10:12:11Z","campaign_id":"8ccd7b88-2591-4b94-848f-f142f5c6bba1","campaign_name":"9 To 5","campaign_target_type":"track","campaign_target_isrc":"DEXW62500272","campaign_target_spotify_track_id":"2RkZ5WPkKyBf0u8vN3dNgb","campaign_target_playlist_id":null,"status":"ended","engagement_context":"catalog","country_code":"US","engaged_track_isrc":"DEXW62500001","engaged_spotify_track_id":"4cOdK2wGLETKBW3PvgPWqT","engaged_track_name":"Till The Sunrise","playlist_position":null,"new_listeners":42,"returning_listeners":18,"listeners":60,"new_listener_streams":58,"returning_listener_streams":31,"streams":89,"spl":1.48}
865
- {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112cc9a","schema_version":"1.0","report_date":"2026-04-08","report_date_timezone":"UTC","exported_at":"2026-05-22T10:12:11Z","campaign_id":"8ccd7b88-2591-4b94-848f-f142f5c6bba1","campaign_name":"9 To 5","campaign_target_type":"track","campaign_target_isrc":"DEXW62500272","campaign_target_spotify_track_id":"2RkZ5WPkKyBf0u8vN3dNgb","campaign_target_playlist_id":null,"status":"ended","engagement_context":"catalog","country_code":"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}
947
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-04-08","report_date_timezone":"UTC","exported_at":"2026-05-22T10:12:11Z","campaign_id":"f1e28d31-c358-4284-9bef-00a2334625fd","campaign_name":"Sleep Playlist","campaign_target_type":"playlist","campaign_target_isrc":null,"campaign_target_spotify_track_id":null,"campaign_target_playlist_id":"37i9dQZF1DXcBWIGoYBM5M","status":"active","engagement_context":"playlist","country_code":"DE","engaged_track_isrc":"DEXW62500001","engaged_spotify_track_id":"4cOdK2wGLETKBW3PvgPWqT","engaged_track_name":"Till The Sunrise","playlist_position":14,"new_listeners":19,"returning_listeners":7,"listeners":26,"new_listener_streams":24,"returning_listener_streams":11,"streams":35,"spl":1.35}
948
+ '400': { $ref: '#/components/responses/BadRequest' }
949
+ '401': { $ref: '#/components/responses/Unauthorized' }
950
+ '403': { $ref: '#/components/responses/Forbidden' }
951
+ '404': { $ref: '#/components/responses/NotFound' }
952
+ '429': { $ref: '#/components/responses/RateLimited' }
953
+ '500': { $ref: '#/components/responses/InternalError' }
954
+
955
+ /v1/soundlinks:
956
+ get:
957
+ operationId: listSoundlinks
958
+ summary: List soundlinks
959
+ description: |
960
+ Returns the organization's self-serve soundlinks. Soundlinks linked
961
+ to a campaign are the campaign's underlying resource and are served
962
+ by the Campaigns endpoints instead.
963
+
964
+ Soundlink schemas contain no financial fields: ads for self-serve
965
+ soundlinks run in your own Meta account, so spend is not visible to
966
+ Soundlink.
967
+
968
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
969
+ tags: [Soundlinks]
970
+ security:
971
+ - apiKeyBearerAuth: []
972
+ - oauthBearer: []
973
+ x-required-scope: soundlinks:read
974
+ parameters:
975
+ - $ref: '#/components/parameters/page'
976
+ - $ref: '#/components/parameters/pageSize100'
977
+ - name: sortBy
978
+ in: query
979
+ schema:
980
+ type: string
981
+ enum: [createdAt]
982
+ default: createdAt
983
+ - $ref: '#/components/parameters/sortOrder'
984
+ responses:
985
+ '200':
986
+ description: Paginated list of soundlinks
987
+ content:
988
+ application/json:
989
+ schema:
990
+ $ref: '#/components/schemas/SoundlinkListResponse'
991
+ example:
992
+ data:
993
+ items:
994
+ - soundlinkId: V1StGXR8_Z5jdHi6B-myT
995
+ organizationId: a7ac3173-2f71-4e79-921f-d15d7112dd11
996
+ name: Midnight Drive
997
+ url: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
998
+ targetType: track
999
+ spotifyUrl: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
1000
+ status: active
1001
+ createdAt: '2026-04-01T10:00:00Z'
1002
+ pagination:
1003
+ page: 1
1004
+ pageSize: 10
1005
+ totalCount: 42
1006
+ totalPages: 5
1007
+ meta:
1008
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1009
+ '401': { $ref: '#/components/responses/Unauthorized' }
1010
+ '403': { $ref: '#/components/responses/Forbidden' }
1011
+ '429': { $ref: '#/components/responses/RateLimited' }
1012
+ '500': { $ref: '#/components/responses/InternalError' }
1013
+
1014
+ /v1/soundlinks/{soundlinkId}:
1015
+ get:
1016
+ operationId: getSoundlink
1017
+ summary: Get soundlink
1018
+ description: |
1019
+ Fetch details for a single self-serve soundlink. Soundlinks linked
1020
+ to a campaign are not addressable here and return `404`.
1021
+
1022
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1023
+ tags: [Soundlinks]
1024
+ security:
1025
+ - apiKeyBearerAuth: []
1026
+ - oauthBearer: []
1027
+ x-required-scope: soundlinks:read
1028
+ parameters:
1029
+ - $ref: '#/components/parameters/soundlinkId'
1030
+ responses:
1031
+ '200':
1032
+ description: Soundlink detail
1033
+ content:
1034
+ application/json:
1035
+ schema:
1036
+ $ref: '#/components/schemas/SoundlinkDetailResponse'
1037
+ example:
1038
+ data:
1039
+ soundlinkId: V1StGXR8_Z5jdHi6B-myT
1040
+ organizationId: a7ac3173-2f71-4e79-921f-d15d7112dd11
1041
+ name: Midnight Drive
1042
+ url: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
1043
+ targetType: track
1044
+ spotifyUrl: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
1045
+ status: active
1046
+ createdAt: '2026-04-01T10:00:00Z'
1047
+ autoFollow: true
1048
+ metaPixelId: '1234567890123456'
1049
+ tiktokPixelId: null
1050
+ meta:
1051
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1052
+ '401': { $ref: '#/components/responses/Unauthorized' }
1053
+ '403': { $ref: '#/components/responses/Forbidden' }
1054
+ '404': { $ref: '#/components/responses/NotFound' }
1055
+ '429': { $ref: '#/components/responses/RateLimited' }
1056
+ '500': { $ref: '#/components/responses/InternalError' }
1057
+
1058
+ /v1/soundlinks/{soundlinkId}/metrics/overview:
1059
+ get:
1060
+ operationId: getSoundlinkMetricsOverview
1061
+ summary: Soundlink metrics overview
1062
+ description: |
1063
+ 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.
1068
+
1069
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1070
+ tags: [Soundlinks]
1071
+ security:
1072
+ - apiKeyBearerAuth: []
1073
+ - oauthBearer: []
1074
+ x-required-scope: soundlinks:read
1075
+ parameters:
1076
+ - $ref: '#/components/parameters/soundlinkId'
1077
+ - $ref: '#/components/parameters/soundlinkStartDate'
1078
+ - $ref: '#/components/parameters/soundlinkEndDate'
1079
+ responses:
1080
+ '200':
1081
+ description: Soundlink totals
1082
+ content:
1083
+ application/json:
1084
+ schema:
1085
+ $ref: '#/components/schemas/SoundlinkMetricsOverviewResponse'
1086
+ example:
1087
+ data:
1088
+ views: 4821
1089
+ link_clicks: 890
1090
+ streams: 9340
1091
+ listeners: 4821
1092
+ new_listeners: 3980
1093
+ returning_listeners: 841
1094
+ new_listener_streams: 7104
1095
+ returning_listener_streams: 2236
1096
+ followers: 312
1097
+ streams_per_listener: 1.94
1098
+ ctr_lp: 0.185
1099
+ meta:
1100
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1101
+ '400': { $ref: '#/components/responses/BadRequest' }
1102
+ '401': { $ref: '#/components/responses/Unauthorized' }
1103
+ '403': { $ref: '#/components/responses/Forbidden' }
1104
+ '404': { $ref: '#/components/responses/NotFound' }
1105
+ '429': { $ref: '#/components/responses/RateLimited' }
1106
+ '500': { $ref: '#/components/responses/InternalError' }
1107
+
1108
+ /v1/soundlinks/{soundlinkId}/metrics/timeseries:
1109
+ get:
1110
+ operationId: getSoundlinkMetricsTimeseries
1111
+ summary: Soundlink metrics timeseries
1112
+ description: |
1113
+ Per-day metrics for a soundlink. One row per `report_date`. Results
1114
+ are paginated.
1115
+
1116
+ **Row schema:** `soundlink_daily` v1.0. Rows are idempotent on the
1117
+ primary key `(provider, account_id, report_date, soundlink_id)`;
1118
+ re-ingesting is safe.
1119
+
1120
+ **Mutability window:** rows for a given `report_date` can be revised
1121
+ for up to 7 days after the date closes due to delayed Spotify playback
1122
+ events. Re-fetch or re-ingest accordingly.
1123
+
1124
+ Rows are aggregated across countries (no `country_code` in v1.0) and
1125
+ contain no financial fields.
1126
+
1127
+ Maps to the **Trends** tab in the Soundlink Insights UI.
1128
+ Use for daily warehouse loads.
1129
+
1130
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1131
+ tags: [Soundlinks]
1132
+ security:
1133
+ - apiKeyBearerAuth: []
1134
+ - oauthBearer: []
1135
+ x-required-scope: soundlinks:read
1136
+ parameters:
1137
+ - $ref: '#/components/parameters/soundlinkId'
1138
+ - $ref: '#/components/parameters/soundlinkStartDate'
1139
+ - $ref: '#/components/parameters/soundlinkEndDate'
1140
+ - $ref: '#/components/parameters/page'
1141
+ - $ref: '#/components/parameters/pageSize500'
1142
+ - name: sortBy
1143
+ in: query
1144
+ schema:
1145
+ type: string
1146
+ enum: [report_date]
1147
+ default: report_date
1148
+ - $ref: '#/components/parameters/sortOrder'
1149
+ responses:
1150
+ '200':
1151
+ description: Paginated per-day rows (`soundlink_daily` schema)
1152
+ content:
1153
+ application/json:
1154
+ schema:
1155
+ $ref: '#/components/schemas/SoundlinkTimeseriesResponse'
1156
+ example:
1157
+ data:
1158
+ schemaVersion: '1.0'
1159
+ items:
1160
+ - provider: soundlink
1161
+ account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
1162
+ schema_version: '1.0'
1163
+ report_date: '2026-08-01'
1164
+ report_date_timezone: UTC
1165
+ exported_at: '2026-08-28T03:00:00Z'
1166
+ soundlink_id: V1StGXR8_Z5jdHi6B-myT
1167
+ soundlink_name: Midnight Drive
1168
+ soundlink_target_type: track
1169
+ soundlink_target_isrc: DEXW62500259
1170
+ soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
1171
+ 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
1183
+ pagination:
1184
+ page: 1
1185
+ pageSize: 50
1186
+ totalCount: 90
1187
+ totalPages: 2
1188
+ meta:
1189
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1190
+ '400': { $ref: '#/components/responses/BadRequest' }
1191
+ '401': { $ref: '#/components/responses/Unauthorized' }
1192
+ '403': { $ref: '#/components/responses/Forbidden' }
1193
+ '404': { $ref: '#/components/responses/NotFound' }
1194
+ '429': { $ref: '#/components/responses/RateLimited' }
1195
+ '500': { $ref: '#/components/responses/InternalError' }
1196
+
1197
+ /v1/soundlinks/{soundlinkId}/metrics/engagement:
1198
+ get:
1199
+ operationId: getSoundlinkEngagement
1200
+ summary: Soundlink engagement (top tracks)
1201
+ 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.
1205
+
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).
1211
+
1212
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1213
+ tags: [Soundlinks]
1214
+ security:
1215
+ - apiKeyBearerAuth: []
1216
+ - oauthBearer: []
1217
+ x-required-scope: soundlinks:read
1218
+ parameters:
1219
+ - $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
1225
+ in: query
1226
+ schema:
1227
+ type: string
1228
+ enum: [totalStreams, totalListeners]
1229
+ default: totalStreams
1230
+ - $ref: '#/components/parameters/sortOrder'
1231
+ responses:
1232
+ '200':
1233
+ description: Paginated aggregated top tracks
1234
+ content:
1235
+ application/json:
1236
+ 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
866
1258
  '400': { $ref: '#/components/responses/BadRequest' }
867
1259
  '401': { $ref: '#/components/responses/Unauthorized' }
868
1260
  '403': { $ref: '#/components/responses/Forbidden' }
@@ -873,21 +1265,23 @@ paths:
873
1265
  /v1/videos/import:
874
1266
  post:
875
1267
  operationId: importVideo
876
- summary: Import a video from a public HTTPS MP4 URL
1268
+ summary: Import video(s) from public HTTPS MP4 URL(s)
877
1269
  description: |
878
- Downloads a single public HTTPS MP4, stages it for ingestion, and starts
879
- the background video pipeline. Returns `202` while processing, or `200`
880
- with `videoId` immediately when the organization already has the same video
881
- (content duplicate).
1270
+ Accepts a single `url` or a `videos` array (1–5 items). Creates one upload
1271
+ session, enqueues async download/staging, and returns `202` with `sessionId`.
882
1272
 
883
- Requires the `videos:write` scope. Subject to a stricter per-key rate limit
884
- than generic public API routes (default 5 imports per hour per API key).
1273
+ Requires the `videos:write` scope. Subject to a stricter per-credential rate
1274
+ limit than generic public API routes (default 20 imports per hour per API key
1275
+ or OAuth grant). This caps how many import requests are accepted per hour,
1276
+ not how long ingestion takes.
885
1277
 
886
- Poll `GET /v1/videos/import/{sessionId}` until `status` is `ready` or `failed`.
887
- Use the returned `videoId` in Full Control campaign `creativeDirection.selectedCreatives`.
1278
+ Poll `GET /v1/videos/import/{sessionId}` until `status` is `ready`, `partial`,
1279
+ or `failed`. For single-URL imports, use `videoId` when ready. For batches
1280
+ (`count > 1`), use `videoIds`.
888
1281
  tags: [Videos]
889
1282
  security:
890
- - apiKeyAuth: []
1283
+ - apiKeyBearerAuth: []
1284
+ - oauthBearer: []
891
1285
  x-required-scope: videos:write
892
1286
  requestBody:
893
1287
  required: true
@@ -895,11 +1289,20 @@ paths:
895
1289
  application/json:
896
1290
  schema:
897
1291
  $ref: '#/components/schemas/VideoImportRequest'
898
- example:
899
- url: 'https://cdn.example.com/promo.mp4'
1292
+ examples:
1293
+ single:
1294
+ summary: Single URL (legacy)
1295
+ value:
1296
+ url: 'https://cdn.example.com/promo.mp4'
1297
+ batch:
1298
+ summary: Batch of URLs
1299
+ value:
1300
+ videos:
1301
+ - url: 'https://cdn.example.com/a.mp4'
1302
+ - url: 'https://cdn.example.com/b.mp4'
900
1303
  responses:
901
1304
  '200':
902
- description: Duplicate video already in the organization's library
1305
+ description: Duplicate video already in the organization's library (sync legacy path only)
903
1306
  content:
904
1307
  application/json:
905
1308
  schema:
@@ -921,11 +1324,13 @@ paths:
921
1324
  operationId: getVideoImportStatus
922
1325
  summary: Get video import session status
923
1326
  description: |
924
- Returns processing status and the resulting `videoId` when ingestion completes.
1327
+ Returns processing status. For single-URL sessions, includes `videoId` when ready.
1328
+ For batch sessions (`count > 1`), includes `videoIds` and `counts`.
925
1329
  Requires the `videos:write` scope.
926
1330
  tags: [Videos]
927
1331
  security:
928
- - apiKeyAuth: []
1332
+ - apiKeyBearerAuth: []
1333
+ - oauthBearer: []
929
1334
  x-required-scope: videos:write
930
1335
  parameters:
931
1336
  - name: sessionId
@@ -950,13 +1355,25 @@ paths:
950
1355
 
951
1356
  components:
952
1357
  securitySchemes:
953
- apiKeyAuth:
954
- type: apiKey
955
- in: header
956
- name: x-api-key
1358
+ apiKeyBearerAuth:
1359
+ type: http
1360
+ scheme: bearer
1361
+ description: |
1362
+ Pass your Soundlink `sk_*` API key as a Bearer token:
1363
+ `Authorization: Bearer sk_<prefix>_<token>` (not an OAuth token; see
1364
+ `oauthBearer` for that). Accepted on all Public API operations. Send
1365
+ only one `Authorization` header per request.
1366
+
1367
+ oauthBearer:
1368
+ type: http
1369
+ scheme: bearer
1370
+ bearerFormat: JWT
957
1371
  description: |
958
- Pass your Soundlink `sk_*` API key in the `x-api-key` header.
959
- Keys can carry explicit scopes (for example `campaigns:read`, `metrics:read`, `videos:write`) enforced by the backend.
1372
+ OAuth 2.0 access token from Sign in with Soundlink
1373
+ (`Authorization: Bearer <oauth_access_token>`).
1374
+ Token scopes must include the operation's required scope
1375
+ (see `x-required-scope` and the Authentication section).
1376
+ Accepted on all Public API operations (reads and writes).
960
1377
 
961
1378
  parameters:
962
1379
  campaignId:
@@ -1037,6 +1454,44 @@ components:
1037
1454
  format: date
1038
1455
  description: Inclusive end date (`YYYY-MM-DD`). Defaults to today.
1039
1456
 
1457
+ soundlinkId:
1458
+ name: soundlinkId
1459
+ in: path
1460
+ required: true
1461
+ schema:
1462
+ type: string
1463
+ description: Soundlink identifier (URL-safe string, same ID used in the public sndl.ink URL)
1464
+
1465
+ soundlinkStartDate:
1466
+ name: startDate
1467
+ in: query
1468
+ schema:
1469
+ type: string
1470
+ format: date
1471
+ description: |
1472
+ Inclusive start date (`YYYY-MM-DD`) for soundlink overview and
1473
+ timeseries. Defaults to the soundlink creation date when omitted.
1474
+
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
+ soundlinkEndDate:
1488
+ name: endDate
1489
+ in: query
1490
+ schema:
1491
+ type: string
1492
+ format: date
1493
+ description: Inclusive end date (`YYYY-MM-DD`). Defaults to today.
1494
+
1040
1495
  schemas:
1041
1496
  # --- Shared ---
1042
1497
 
@@ -1073,8 +1528,9 @@ components:
1073
1528
  - invalid_api_key
1074
1529
  - api_key_revoked
1075
1530
  - api_key_expired
1076
- - mixed_credentials
1531
+ - invalid_token
1077
1532
  - insufficient_scope
1533
+ - access_denied
1078
1534
  - not_found
1079
1535
  - campaign_not_found
1080
1536
  - invalid_query_parameter
@@ -2014,9 +2470,11 @@ components:
2014
2470
  nullable: true
2015
2471
  minimum: 1
2016
2472
  description: |
2017
- 1-based slot index of the engaged track in the promoted playlist on `report_date`.
2018
- Populated for `engagement_context = playlist` when playlist snapshot data is available.
2019
- `null` for catalog rows and until position data is delivered (reserved for future delivery in v1.0).
2473
+ 1-based slot of the engaged track on the promoted playlist for `report_date` (1 = top).
2474
+ Populated only when `engagement_context = playlist` and that day's playlist crawl listed the track.
2475
+ `null` for catalog rows; before the day's crawl completes (current UTC day is often null until later morning UTC);
2476
+ when the track was not listed or could not be matched to that day's crawl; or while historical backfill is still catching up.
2477
+ Field is beta until historical backfill finishes. Treat `null` as unavailable — not an error.
2020
2478
  new_listeners:
2021
2479
  type: integer
2022
2480
  minimum: 0
@@ -2049,20 +2507,389 @@ components:
2049
2507
  type: number
2050
2508
  description: Streams per listener (`streams / listeners`). Zero if `listeners` is zero.
2051
2509
 
2510
+ # --- Soundlinks ---
2511
+
2512
+ SoundlinkStatus:
2513
+ type: string
2514
+ enum: [draft, active, archived]
2515
+
2516
+ SoundlinkSummary:
2517
+ type: object
2518
+ required: [soundlinkId, organizationId, name, url, targetType, status, createdAt]
2519
+ properties:
2520
+ soundlinkId:
2521
+ type: string
2522
+ description: |
2523
+ Unique ID of this soundlink (URL-safe string, same ID used in the
2524
+ public sndl.ink URL).
2525
+ example: V1StGXR8_Z5jdHi6B-myT
2526
+ organizationId:
2527
+ type: string
2528
+ description: Soundlink organization ID (UUID).
2529
+ name:
2530
+ type: string
2531
+ description: Human-readable soundlink name.
2532
+ url:
2533
+ type: string
2534
+ format: uri
2535
+ description: Public soundlink landing page URL.
2536
+ example: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
2537
+ targetType:
2538
+ type: string
2539
+ nullable: true
2540
+ enum: [track, album, playlist]
2541
+ description: |
2542
+ Type of Spotify resource this soundlink promotes. `null` if the
2543
+ target could not be determined.
2544
+ spotifyUrl:
2545
+ type: string
2546
+ format: uri
2547
+ nullable: true
2548
+ description: Spotify URL of the promoted resource.
2549
+ status:
2550
+ $ref: '#/components/schemas/SoundlinkStatus'
2551
+ createdAt:
2552
+ type: string
2553
+ format: date-time
2554
+
2555
+ SoundlinkListResponse:
2556
+ type: object
2557
+ required: [data, meta]
2558
+ properties:
2559
+ data:
2560
+ type: object
2561
+ required: [items, pagination]
2562
+ properties:
2563
+ items:
2564
+ type: array
2565
+ items:
2566
+ $ref: '#/components/schemas/SoundlinkSummary'
2567
+ pagination:
2568
+ $ref: '#/components/schemas/Pagination'
2569
+ meta:
2570
+ $ref: '#/components/schemas/Meta'
2571
+
2572
+ SoundlinkDetail:
2573
+ allOf:
2574
+ - $ref: '#/components/schemas/SoundlinkSummary'
2575
+ - type: object
2576
+ required: [autoFollow, metaPixelId, tiktokPixelId]
2577
+ properties:
2578
+ autoFollow:
2579
+ type: boolean
2580
+ description: |
2581
+ Whether auto-follow is configured for this soundlink. Whether
2582
+ it takes effect also depends on the organization's plan.
2583
+ metaPixelId:
2584
+ type: string
2585
+ nullable: true
2586
+ description: Meta pixel ID configured on this soundlink. `null` if not set.
2587
+ tiktokPixelId:
2588
+ type: string
2589
+ nullable: true
2590
+ description: TikTok pixel ID configured on this soundlink. `null` if not set.
2591
+
2592
+ SoundlinkDetailResponse:
2593
+ type: object
2594
+ required: [data, meta]
2595
+ properties:
2596
+ data:
2597
+ $ref: '#/components/schemas/SoundlinkDetail'
2598
+ meta:
2599
+ $ref: '#/components/schemas/Meta'
2600
+
2601
+ SoundlinkMetricsOverview:
2602
+ type: object
2603
+ description: Soundlink-level totals for the requested date range.
2604
+ required: [views, streams, listeners, followers, streams_per_listener]
2605
+ properties:
2606
+ views:
2607
+ type: integer
2608
+ description: Soundlink landing page views in the period.
2609
+ link_clicks:
2610
+ type: integer
2611
+ nullable: true
2612
+ description: |
2613
+ Clicks on "Continue with Spotify" on the landing page — outbound
2614
+ clicks to Spotify. Null if not tracked for this soundlink type.
2615
+ streams:
2616
+ type: integer
2617
+ description: Attributed Spotify streams (sum of daily rows).
2618
+ listeners:
2619
+ type: integer
2620
+ description: Unique attributed Spotify listeners in the period.
2621
+ new_listeners:
2622
+ type: integer
2623
+ nullable: true
2624
+ description: Unique listeners whose first play via this soundlink occurred in the period.
2625
+ returning_listeners:
2626
+ type: integer
2627
+ nullable: true
2628
+ description: Unique listeners who played in the period but whose first play was earlier.
2629
+ new_listener_streams:
2630
+ type: integer
2631
+ nullable: true
2632
+ description: Stream count from new listeners in the period.
2633
+ returning_listener_streams:
2634
+ type: integer
2635
+ nullable: true
2636
+ description: Stream count from returning listeners in the period.
2637
+ followers:
2638
+ type: integer
2639
+ description: Attributed Spotify artist follower gains in the period.
2640
+ streams_per_listener:
2641
+ type: number
2642
+ description: streams / listeners. Zero if listeners is zero.
2643
+ ctr_lp:
2644
+ type: number
2645
+ nullable: true
2646
+ description: |
2647
+ Landing page click-through rate (link_clicks / views). Computed
2648
+ 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.
2651
+
2652
+ SoundlinkMetricsOverviewResponse:
2653
+ type: object
2654
+ required: [data, meta]
2655
+ properties:
2656
+ data:
2657
+ $ref: '#/components/schemas/SoundlinkMetricsOverview'
2658
+ meta:
2659
+ $ref: '#/components/schemas/Meta'
2660
+
2661
+ SoundlinkDailyRow:
2662
+ type: object
2663
+ description: |
2664
+ One row of the `soundlink_daily` v1.0 schema.
2665
+ Primary key: `(provider, account_id, report_date, soundlink_id)`.
2666
+ Rows are idempotent — re-ingesting on the primary key is safe.
2667
+ Values for a given `report_date` may be revised for up to 7 days after
2668
+ 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.
2671
+ required:
2672
+ - provider
2673
+ - account_id
2674
+ - schema_version
2675
+ - report_date
2676
+ - report_date_timezone
2677
+ - exported_at
2678
+ - soundlink_id
2679
+ - soundlink_name
2680
+ - soundlink_target_type
2681
+ - views
2682
+ - streams
2683
+ - listeners
2684
+ - followers
2685
+ - streams_per_listener
2686
+ properties:
2687
+ provider:
2688
+ type: string
2689
+ enum: [soundlink]
2690
+ description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
2691
+ account_id:
2692
+ type: string
2693
+ description: Soundlink organization ID (UUID).
2694
+ schema_version:
2695
+ type: string
2696
+ description: Schema version. Pin your ingest pipeline to this value.
2697
+ example: '1.0'
2698
+ report_date:
2699
+ type: string
2700
+ format: date
2701
+ description: UTC calendar date the metrics belong to (`YYYY-MM-DD`).
2702
+ report_date_timezone:
2703
+ type: string
2704
+ enum: [UTC]
2705
+ description: Always `UTC`.
2706
+ exported_at:
2707
+ type: string
2708
+ format: date-time
2709
+ description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
2710
+ soundlink_id:
2711
+ type: string
2712
+ description: Unique ID of this soundlink.
2713
+ example: V1StGXR8_Z5jdHi6B-myT
2714
+ soundlink_name:
2715
+ type: string
2716
+ description: Human-readable soundlink name.
2717
+ soundlink_target_type:
2718
+ type: string
2719
+ nullable: true
2720
+ enum: [track, playlist]
2721
+ description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
2722
+ soundlink_target_isrc:
2723
+ type: string
2724
+ nullable: true
2725
+ description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
2726
+ soundlink_target_spotify_track_id:
2727
+ type: string
2728
+ nullable: true
2729
+ description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
2730
+ soundlink_target_playlist_id:
2731
+ type: string
2732
+ nullable: true
2733
+ description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
2734
+ views:
2735
+ type: integer
2736
+ description: Soundlink landing page views on this day.
2737
+ link_clicks:
2738
+ type: integer
2739
+ nullable: true
2740
+ description: |
2741
+ Clicks on "Continue with Spotify" on the landing page — outbound
2742
+ clicks to Spotify. Null if not tracked for this soundlink type.
2743
+ streams:
2744
+ type: integer
2745
+ description: |
2746
+ Spotify streams attributed to this soundlink on this day:
2747
+ `new_listener_streams + returning_listener_streams`. Observed
2748
+ Spotify-side events, not modelled estimates. Safe to sum within a
2749
+ day; summing across days counts repeat listens.
2750
+ listeners:
2751
+ type: integer
2752
+ 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.
2756
+ new_listeners:
2757
+ type: integer
2758
+ nullable: true
2759
+ description: Unique listeners whose first play via this soundlink occurred on `report_date`.
2760
+ returning_listeners:
2761
+ type: integer
2762
+ nullable: true
2763
+ description: Unique listeners who played on `report_date` but whose first play was on an earlier date.
2764
+ new_listener_streams:
2765
+ type: integer
2766
+ nullable: true
2767
+ description: Stream count from new listeners on `report_date`.
2768
+ returning_listener_streams:
2769
+ type: integer
2770
+ nullable: true
2771
+ description: Stream count from returning listeners on `report_date`.
2772
+ followers:
2773
+ type: integer
2774
+ description: Spotify artist follower gains attributed to this soundlink on this day.
2775
+ streams_per_listener:
2776
+ type: number
2777
+ description: streams / listeners for this row. Zero if listeners is zero.
2778
+ ctr_lp:
2779
+ type: number
2780
+ nullable: true
2781
+ description: |
2782
+ Landing page click-through rate (link_clicks / views). Computed
2783
+ against landing page views, not ad impressions — do not combine
2784
+ with `ctr_linkclick` from `campaign_country_daily`. Null if views
2785
+ is zero or link_clicks is null.
2786
+
2787
+ SoundlinkTimeseriesResponse:
2788
+ type: object
2789
+ required: [data, meta]
2790
+ properties:
2791
+ data:
2792
+ type: object
2793
+ required: [schemaVersion, items, pagination]
2794
+ properties:
2795
+ schemaVersion:
2796
+ type: string
2797
+ description: Version of the `soundlink_daily` row schema. Pin your ingest pipeline to this.
2798
+ example: '1.0'
2799
+ items:
2800
+ type: array
2801
+ items:
2802
+ $ref: '#/components/schemas/SoundlinkDailyRow'
2803
+ pagination:
2804
+ $ref: '#/components/schemas/Pagination'
2805
+ meta:
2806
+ $ref: '#/components/schemas/Meta'
2807
+
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
+ SoundlinkEngagementResponse:
2835
+ type: object
2836
+ required: [data, meta]
2837
+ properties:
2838
+ data:
2839
+ type: object
2840
+ required: [items, pagination]
2841
+ properties:
2842
+ items:
2843
+ type: array
2844
+ items:
2845
+ $ref: '#/components/schemas/SoundlinkEngagementItem'
2846
+ pagination:
2847
+ $ref: '#/components/schemas/Pagination'
2848
+ meta:
2849
+ $ref: '#/components/schemas/Meta'
2850
+
2052
2851
  # --- Videos ---
2053
2852
 
2054
2853
  VideoImportRequest:
2055
2854
  type: object
2056
- required: [url]
2855
+ description: |
2856
+ Provide either `url` (single) or `videos` (batch of 1–5). Do not send both.
2057
2857
  properties:
2058
2858
  url:
2059
2859
  type: string
2060
2860
  format: uri
2061
- description: Public HTTPS URL to an MP4 file (max 50 MB).
2861
+ description: Public HTTPS URL to an MP4 file (max 50 MB). Mutually exclusive with `videos`.
2862
+ videos:
2863
+ type: array
2864
+ minItems: 1
2865
+ maxItems: 5
2866
+ description: Batch of video URLs. Mutually exclusive with `url`.
2867
+ items:
2868
+ type: object
2869
+ required: [url]
2870
+ properties:
2871
+ url:
2872
+ type: string
2873
+ format: uri
2874
+ description: Public HTTPS URL to an MP4 file (max 50 MB).
2062
2875
 
2063
2876
  VideoImportStatus:
2064
2877
  type: string
2065
- enum: [processing, ready, failed]
2878
+ enum: [processing, ready, failed, partial]
2879
+
2880
+ VideoImportCounts:
2881
+ type: object
2882
+ required: [total, ready, failed]
2883
+ properties:
2884
+ total:
2885
+ type: integer
2886
+ description: Videos admitted in the session
2887
+ ready:
2888
+ type: integer
2889
+ description: Ingested successfully
2890
+ failed:
2891
+ type: integer
2892
+ description: Ingestion failures (download failures fail the whole session in this phase)
2066
2893
 
2067
2894
  VideoImportStartData:
2068
2895
  type: object
@@ -2074,6 +2901,9 @@ components:
2074
2901
  description: Upload session ID for status polling
2075
2902
  status:
2076
2903
  $ref: '#/components/schemas/VideoImportStatus'
2904
+ count:
2905
+ type: integer
2906
+ description: Number of videos accepted for import
2077
2907
  videoId:
2078
2908
  type: string
2079
2909
  format: uuid
@@ -2102,11 +2932,40 @@ components:
2102
2932
  type: string
2103
2933
  format: uuid
2104
2934
  nullable: true
2105
- description: Background video ID when `status` is `ready`
2935
+ description: Present for single-URL sessions when ready or failed after ingest
2936
+ videoIds:
2937
+ type: array
2938
+ items:
2939
+ type: string
2940
+ format: uuid
2941
+ description: Ready video IDs for batch sessions (`count > 1`)
2942
+ counts:
2943
+ $ref: '#/components/schemas/VideoImportCounts'
2106
2944
  error:
2107
- type: string
2945
+ allOf:
2946
+ - $ref: '#/components/schemas/VideoImportStatusError'
2108
2947
  nullable: true
2109
- description: Failure reason when `status` is `failed`
2948
+ description: Present when status is failed
2949
+
2950
+ VideoImportStatusError:
2951
+ type: object
2952
+ required: [code, message]
2953
+ properties:
2954
+ code:
2955
+ type: string
2956
+ enum:
2957
+ - video_too_large
2958
+ - invalid_video_content_type
2959
+ - storage_limit_exceeded
2960
+ - no_videos_imported
2961
+ - duplicate_videos
2962
+ - import_failed
2963
+ description: >
2964
+ Machine-readable failure code. Legacy sessions without a stored
2965
+ code fall back to import_failed.
2966
+ message:
2967
+ type: string
2968
+ description: Human-readable failure message
2110
2969
 
2111
2970
  VideoImportStatusResponse:
2112
2971
  type: object
@@ -2165,7 +3024,10 @@ components:
2165
3024
  requestId: 550e8400-e29b-41d4-a716-446655440000
2166
3025
 
2167
3026
  Unauthorized:
2168
- description: Missing, malformed, revoked, or expired API key
3027
+ description: |
3028
+ Missing or invalid credentials. Covers missing/malformed API keys,
3029
+ invalid or expired OAuth access tokens, and revoked API keys.
3030
+ `x-api-key` is not accepted and is ignored if sent.
2169
3031
  headers:
2170
3032
  Retry-After:
2171
3033
  schema:
@@ -2180,7 +3042,14 @@ components:
2180
3042
  value:
2181
3043
  error:
2182
3044
  code: invalid_api_key
2183
- message: 'Missing or malformed x-api-key header.'
3045
+ message: 'Missing credentials. Send Authorization: Bearer.'
3046
+ meta:
3047
+ requestId: 550e8400-e29b-41d4-a716-446655440000
3048
+ invalid_token:
3049
+ value:
3050
+ error:
3051
+ code: invalid_token
3052
+ message: 'OAuth access token is invalid or expired.'
2184
3053
  meta:
2185
3054
  requestId: 550e8400-e29b-41d4-a716-446655440000
2186
3055
  api_key_revoked:
@@ -2192,17 +3061,28 @@ components:
2192
3061
  requestId: 550e8400-e29b-41d4-a716-446655440000
2193
3062
 
2194
3063
  Forbidden:
2195
- description: Valid key but missing required scope
3064
+ description: |
3065
+ Authenticated but not allowed: missing required scope, or OAuth access
3066
+ disabled for the organization (`access_denied`).
2196
3067
  content:
2197
3068
  application/json:
2198
3069
  schema:
2199
3070
  $ref: '#/components/schemas/ErrorResponse'
2200
- example:
2201
- error:
2202
- code: insufficient_scope
2203
- message: 'This key does not have the metrics:read scope.'
2204
- meta:
2205
- requestId: 550e8400-e29b-41d4-a716-446655440000
3071
+ examples:
3072
+ insufficient_scope:
3073
+ value:
3074
+ error:
3075
+ code: insufficient_scope
3076
+ message: 'This token does not have the metrics:read scope.'
3077
+ meta:
3078
+ requestId: 550e8400-e29b-41d4-a716-446655440000
3079
+ access_denied:
3080
+ value:
3081
+ error:
3082
+ code: access_denied
3083
+ message: 'OAuth access is not enabled for this organization.'
3084
+ meta:
3085
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2206
3086
 
2207
3087
  CreateCampaignForbidden:
2208
3088
  description: |