soundlink 2.0.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,19 +7,43 @@ info:
7
7
 
8
8
  **Base URL:** `https://api.getsoundlink.com`
9
9
 
10
- **Authentication:** send a `sk_*` API key created in the Soundlink app (Settings → Developer → API keys) using one of:
10
+ ## Authentication
11
11
 
12
- 1. **`Authorization: Bearer` (recommended)**:
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):
13
16
  ```
14
17
  Authorization: Bearer sk_abc123_<token>
15
18
  ```
16
19
 
17
- 2. **`x-api-key` header (deprecated, retiring 2026-08-17)** — migrate to Bearer above before then:
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`):
18
24
  ```
19
- x-api-key: sk_abc123_<token>
25
+ Authorization: Bearer <oauth_access_token>
20
26
  ```
21
27
 
22
- Sending both headers returns `401 mixed_credentials`.
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).
23
47
 
24
48
  All responses are wrapped in a standard envelope:
25
49
  ```json
@@ -33,8 +57,8 @@ servers:
33
57
  description: Production
34
58
 
35
59
  security:
36
- - apiKeyAuth: []
37
60
  - apiKeyBearerAuth: []
61
+ - oauthBearer: []
38
62
 
39
63
  tags:
40
64
  - name: System
@@ -45,6 +69,8 @@ tags:
45
69
  description: Campaign performance metrics
46
70
  - name: Videos
47
71
  description: Partner video library import for Full Control campaigns
72
+ - name: Soundlinks
73
+ description: Soundlink listing, detail, and performance metrics
48
74
 
49
75
  paths:
50
76
  /v1/ping:
@@ -53,12 +79,13 @@ paths:
53
79
  summary: Verify connectivity and authentication
54
80
  description: |
55
81
  Returns `{ "status": "ok" }` if the request is authenticated and the
56
- API is reachable. Useful for verifying a newly issued key before making
57
- 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.
58
85
  tags: [System]
59
86
  security:
60
- - apiKeyAuth: []
61
87
  - apiKeyBearerAuth: []
88
+ - oauthBearer: []
62
89
  responses:
63
90
  '200':
64
91
  description: Authenticated and reachable
@@ -95,11 +122,11 @@ paths:
95
122
  `POST /v1/campaigns`. Built-in strategies apply platform default
96
123
  tiering internally; only `custom` allows `tierTargeting` on create.
97
124
 
98
- Requires the `campaigns:read` scope.
125
+ Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
99
126
  tags: [Campaigns]
100
127
  security:
101
- - apiKeyAuth: []
102
128
  - apiKeyBearerAuth: []
129
+ - oauthBearer: []
103
130
  x-required-scope: campaigns:read
104
131
  responses:
105
132
  '200':
@@ -133,10 +160,13 @@ paths:
133
160
  description: |
134
161
  Returns all campaigns for the authenticated organization.
135
162
  Intended for reporting and data warehouse sync.
163
+
164
+ Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
136
165
  tags: [Campaigns]
137
166
  security:
138
- - apiKeyAuth: []
139
167
  - apiKeyBearerAuth: []
168
+ - oauthBearer: []
169
+ x-required-scope: campaigns:read
140
170
  parameters:
141
171
  - $ref: '#/components/parameters/page'
142
172
  - $ref: '#/components/parameters/pageSize100'
@@ -190,10 +220,12 @@ paths:
190
220
  deducted from the wallet balance), so the `Idempotency-Key` header
191
221
  is **required** on every request. See the header description below
192
222
  for retry semantics.
223
+
224
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
193
225
  tags: [Campaigns]
194
226
  security:
195
- - apiKeyAuth: []
196
227
  - apiKeyBearerAuth: []
228
+ - oauthBearer: []
197
229
  x-required-scope: campaigns:write
198
230
  parameters:
199
231
  - $ref: '#/components/parameters/idempotencyKey'
@@ -283,11 +315,15 @@ paths:
283
315
  get:
284
316
  operationId: getCampaign
285
317
  summary: Get campaign
286
- 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.
287
322
  tags: [Campaigns]
288
323
  security:
289
- - apiKeyAuth: []
290
324
  - apiKeyBearerAuth: []
325
+ - oauthBearer: []
326
+ x-required-scope: campaigns:read
291
327
  parameters:
292
328
  - $ref: '#/components/parameters/campaignId'
293
329
  responses:
@@ -331,11 +367,13 @@ paths:
331
367
  already-stopped campaign succeeds without double-refunding. The
332
368
  `Idempotency-Key` header is also **required** so retries of the same
333
369
  request replay the original response without repeating side effects.
370
+
371
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
334
372
  tags: [Campaigns]
335
373
  x-required-scope: campaigns:write
336
374
  security:
337
- - apiKeyAuth: []
338
375
  - apiKeyBearerAuth: []
376
+ - oauthBearer: []
339
377
  parameters:
340
378
  - $ref: '#/components/parameters/campaignId'
341
379
  - $ref: '#/components/parameters/idempotencyKey'
@@ -377,11 +415,13 @@ paths:
377
415
  - `current_and_renewals` — applies to the current cycle and future renewals
378
416
 
379
417
  Debits the organization wallet when the current cycle is increased.
418
+
419
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
380
420
  tags: [Campaigns]
381
421
  x-required-scope: campaigns:write
382
422
  security:
383
- - apiKeyAuth: []
384
423
  - apiKeyBearerAuth: []
424
+ - oauthBearer: []
385
425
  parameters:
386
426
  - $ref: '#/components/parameters/campaignId'
387
427
  - $ref: '#/components/parameters/idempotencyKey'
@@ -450,11 +490,13 @@ paths:
450
490
  - `targetDailyBudget` must be at least `$10`/day and lower than the
451
491
  current daily budget
452
492
  - more than 3 days must remain in the current cycle
493
+
494
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
453
495
  tags: [Campaigns]
454
496
  x-required-scope: campaigns:write
455
497
  security:
456
- - apiKeyAuth: []
457
498
  - apiKeyBearerAuth: []
499
+ - oauthBearer: []
458
500
  parameters:
459
501
  - $ref: '#/components/parameters/campaignId'
460
502
  - $ref: '#/components/parameters/idempotencyKey'
@@ -501,11 +543,13 @@ paths:
501
543
  updated (`lastUpdate`). Use this before `PATCH` to build a valid request.
502
544
 
503
545
  **Wallet campaigns only** (`generation: 3`).
546
+
547
+ Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
504
548
  tags: [Campaigns]
505
549
  x-required-scope: campaigns:read
506
550
  security:
507
- - apiKeyAuth: []
508
551
  - apiKeyBearerAuth: []
552
+ - oauthBearer: []
509
553
  parameters:
510
554
  - $ref: '#/components/parameters/campaignId'
511
555
  responses:
@@ -552,11 +596,13 @@ paths:
552
596
 
553
597
  **Cooldown:** after a successful update, further tier changes are
554
598
  blocked for **72 hours** (`409 tier_update_cooldown`).
599
+
600
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
555
601
  tags: [Campaigns]
556
602
  x-required-scope: campaigns:write
557
603
  security:
558
- - apiKeyAuth: []
559
604
  - apiKeyBearerAuth: []
605
+ - oauthBearer: []
560
606
  parameters:
561
607
  - $ref: '#/components/parameters/campaignId'
562
608
  requestBody:
@@ -618,10 +664,13 @@ paths:
618
664
  `/metrics/breakdown` for those.
619
665
 
620
666
  Suitable for dashboards and quick syncs.
667
+
668
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
621
669
  tags: [Metrics]
622
670
  security:
623
- - apiKeyAuth: []
624
671
  - apiKeyBearerAuth: []
672
+ - oauthBearer: []
673
+ x-required-scope: metrics:read
625
674
  parameters:
626
675
  - $ref: '#/components/parameters/campaignId'
627
676
  - $ref: '#/components/parameters/startDate'
@@ -677,10 +726,13 @@ paths:
677
726
 
678
727
  Maps to the **Countries** tab in the Soundlink Insights UI.
679
728
  Use for daily warehouse loads.
729
+
730
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
680
731
  tags: [Metrics]
681
732
  security:
682
- - apiKeyAuth: []
683
733
  - apiKeyBearerAuth: []
734
+ - oauthBearer: []
735
+ x-required-scope: metrics:read
684
736
  parameters:
685
737
  - $ref: '#/components/parameters/campaignId'
686
738
  - $ref: '#/components/parameters/startDate'
@@ -780,10 +832,13 @@ paths:
780
832
  to 7 days after the date closes due to delayed events from Meta and
781
833
  Spotify. Re-fetching and re-ingesting on the primary key is safe
782
834
  (idempotent).
835
+
836
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
783
837
  tags: [Metrics]
784
838
  security:
785
- - apiKeyAuth: []
786
839
  - apiKeyBearerAuth: []
840
+ - oauthBearer: []
841
+ x-required-scope: metrics:read
787
842
  parameters:
788
843
  - $ref: '#/components/parameters/campaignId'
789
844
  - $ref: '#/components/parameters/startDate'
@@ -850,10 +905,13 @@ paths:
850
905
  **Mutability:** rows for a given `report_date` can be revised for up to
851
906
  7 days after the date closes. Re-fetching and re-ingesting on the
852
907
  primary key is safe (idempotent).
908
+
909
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
853
910
  tags: [Metrics]
854
911
  security:
855
- - apiKeyAuth: []
856
912
  - apiKeyBearerAuth: []
913
+ - oauthBearer: []
914
+ x-required-scope: metrics:read
857
915
  parameters:
858
916
  - $ref: '#/components/parameters/campaignId'
859
917
  - $ref: '#/components/parameters/startDate'
@@ -894,25 +952,336 @@ paths:
894
952
  '429': { $ref: '#/components/responses/RateLimited' }
895
953
  '500': { $ref: '#/components/responses/InternalError' }
896
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
1258
+ '400': { $ref: '#/components/responses/BadRequest' }
1259
+ '401': { $ref: '#/components/responses/Unauthorized' }
1260
+ '403': { $ref: '#/components/responses/Forbidden' }
1261
+ '404': { $ref: '#/components/responses/NotFound' }
1262
+ '429': { $ref: '#/components/responses/RateLimited' }
1263
+ '500': { $ref: '#/components/responses/InternalError' }
1264
+
897
1265
  /v1/videos/import:
898
1266
  post:
899
1267
  operationId: importVideo
900
- summary: Import a video from a public HTTPS MP4 URL
1268
+ summary: Import video(s) from public HTTPS MP4 URL(s)
901
1269
  description: |
902
- Downloads a single public HTTPS MP4, stages it for ingestion, and starts
903
- the background video pipeline. Returns `202` while processing, or `200`
904
- with `videoId` immediately when the organization already has the same video
905
- (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`.
906
1272
 
907
- Requires the `videos:write` scope. Subject to a stricter per-key rate limit
908
- 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.
909
1277
 
910
- Poll `GET /v1/videos/import/{sessionId}` until `status` is `ready` or `failed`.
911
- 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`.
912
1281
  tags: [Videos]
913
1282
  security:
914
- - apiKeyAuth: []
915
1283
  - apiKeyBearerAuth: []
1284
+ - oauthBearer: []
916
1285
  x-required-scope: videos:write
917
1286
  requestBody:
918
1287
  required: true
@@ -920,11 +1289,20 @@ paths:
920
1289
  application/json:
921
1290
  schema:
922
1291
  $ref: '#/components/schemas/VideoImportRequest'
923
- example:
924
- 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'
925
1303
  responses:
926
1304
  '200':
927
- description: Duplicate video already in the organization's library
1305
+ description: Duplicate video already in the organization's library (sync legacy path only)
928
1306
  content:
929
1307
  application/json:
930
1308
  schema:
@@ -946,12 +1324,13 @@ paths:
946
1324
  operationId: getVideoImportStatus
947
1325
  summary: Get video import session status
948
1326
  description: |
949
- 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`.
950
1329
  Requires the `videos:write` scope.
951
1330
  tags: [Videos]
952
1331
  security:
953
- - apiKeyAuth: []
954
1332
  - apiKeyBearerAuth: []
1333
+ - oauthBearer: []
955
1334
  x-required-scope: videos:write
956
1335
  parameters:
957
1336
  - name: sessionId
@@ -976,24 +1355,25 @@ paths:
976
1355
 
977
1356
  components:
978
1357
  securitySchemes:
979
- apiKeyAuth:
980
- type: apiKey
981
- in: header
982
- name: x-api-key
983
- description: |
984
- Pass your Soundlink `sk_*` API key in the `x-api-key` header.
985
- Keys can carry explicit scopes (for example `campaigns:read`, `metrics:read`, `videos:write`) enforced by the backend.
986
-
987
- **Deprecated, retiring 2026-08-17** — migrate to `Authorization: Bearer sk_...` (see `apiKeyBearerAuth`) before then.
988
-
989
1358
  apiKeyBearerAuth:
990
1359
  type: http
991
1360
  scheme: bearer
992
1361
  description: |
993
1362
  Pass your Soundlink `sk_*` API key as a Bearer token:
994
- `Authorization: Bearer sk_<prefix>_<token>`. Verified with the exact
995
- same key as `apiKeyAuth` — just the recommended header for the same
996
- `sk_*` credential. Do not combine with `x-api-key`.
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
1371
+ description: |
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).
997
1377
 
998
1378
  parameters:
999
1379
  campaignId:
@@ -1074,6 +1454,44 @@ components:
1074
1454
  format: date
1075
1455
  description: Inclusive end date (`YYYY-MM-DD`). Defaults to today.
1076
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
+
1077
1495
  schemas:
1078
1496
  # --- Shared ---
1079
1497
 
@@ -1110,8 +1528,9 @@ components:
1110
1528
  - invalid_api_key
1111
1529
  - api_key_revoked
1112
1530
  - api_key_expired
1113
- - mixed_credentials
1531
+ - invalid_token
1114
1532
  - insufficient_scope
1533
+ - access_denied
1115
1534
  - not_found
1116
1535
  - campaign_not_found
1117
1536
  - invalid_query_parameter
@@ -2088,20 +2507,389 @@ components:
2088
2507
  type: number
2089
2508
  description: Streams per listener (`streams / listeners`). Zero if `listeners` is zero.
2090
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
+
2091
2851
  # --- Videos ---
2092
2852
 
2093
2853
  VideoImportRequest:
2094
2854
  type: object
2095
- required: [url]
2855
+ description: |
2856
+ Provide either `url` (single) or `videos` (batch of 1–5). Do not send both.
2096
2857
  properties:
2097
2858
  url:
2098
2859
  type: string
2099
2860
  format: uri
2100
- 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).
2101
2875
 
2102
2876
  VideoImportStatus:
2103
2877
  type: string
2104
- 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)
2105
2893
 
2106
2894
  VideoImportStartData:
2107
2895
  type: object
@@ -2113,6 +2901,9 @@ components:
2113
2901
  description: Upload session ID for status polling
2114
2902
  status:
2115
2903
  $ref: '#/components/schemas/VideoImportStatus'
2904
+ count:
2905
+ type: integer
2906
+ description: Number of videos accepted for import
2116
2907
  videoId:
2117
2908
  type: string
2118
2909
  format: uuid
@@ -2141,11 +2932,40 @@ components:
2141
2932
  type: string
2142
2933
  format: uuid
2143
2934
  nullable: true
2144
- 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'
2145
2944
  error:
2146
- type: string
2945
+ allOf:
2946
+ - $ref: '#/components/schemas/VideoImportStatusError'
2147
2947
  nullable: true
2148
- 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
2149
2969
 
2150
2970
  VideoImportStatusResponse:
2151
2971
  type: object
@@ -2204,7 +3024,10 @@ components:
2204
3024
  requestId: 550e8400-e29b-41d4-a716-446655440000
2205
3025
 
2206
3026
  Unauthorized:
2207
- 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.
2208
3031
  headers:
2209
3032
  Retry-After:
2210
3033
  schema:
@@ -2219,7 +3042,14 @@ components:
2219
3042
  value:
2220
3043
  error:
2221
3044
  code: invalid_api_key
2222
- message: 'Missing or malformed API key. Expected: sk_<prefix>_<token> (sent via x-api-key or Authorization: Bearer).'
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.'
2223
3053
  meta:
2224
3054
  requestId: 550e8400-e29b-41d4-a716-446655440000
2225
3055
  api_key_revoked:
@@ -2231,17 +3061,28 @@ components:
2231
3061
  requestId: 550e8400-e29b-41d4-a716-446655440000
2232
3062
 
2233
3063
  Forbidden:
2234
- 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`).
2235
3067
  content:
2236
3068
  application/json:
2237
3069
  schema:
2238
3070
  $ref: '#/components/schemas/ErrorResponse'
2239
- example:
2240
- error:
2241
- code: insufficient_scope
2242
- message: 'This key does not have the metrics:read scope.'
2243
- meta:
2244
- 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
2245
3086
 
2246
3087
  CreateCampaignForbidden:
2247
3088
  description: |