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.
- package/CHANGELOG.md +12 -0
- package/README.md +37 -4
- package/dist/cjs/index.cjs +115 -1
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +215 -3
- package/dist/esm/index.js +115 -2
- package/dist/esm/index.js.map +1 -1
- package/openapi/soundlink-public-api-v1.yaml +944 -64
- package/package.json +2 -1
|
@@ -7,10 +7,43 @@ info:
|
|
|
7
7
|
|
|
8
8
|
**Base URL:** `https://api.getsoundlink.com`
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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
|
-
-
|
|
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
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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:
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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-
|
|
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
|
|
1268
|
+
summary: Import video(s) from public HTTPS MP4 URL(s)
|
|
877
1269
|
description: |
|
|
878
|
-
|
|
879
|
-
|
|
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-
|
|
884
|
-
than generic public API routes (default
|
|
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
|
|
887
|
-
|
|
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
|
-
-
|
|
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
|
-
|
|
899
|
-
|
|
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
|
|
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
|
-
-
|
|
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
|
-
|
|
954
|
-
type:
|
|
955
|
-
|
|
956
|
-
|
|
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
|
-
|
|
959
|
-
|
|
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
|
-
-
|
|
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
|
|
2018
|
-
Populated
|
|
2019
|
-
`null` for catalog rows
|
|
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
|
-
|
|
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:
|
|
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
|
-
|
|
2945
|
+
allOf:
|
|
2946
|
+
- $ref: '#/components/schemas/VideoImportStatusError'
|
|
2108
2947
|
nullable: true
|
|
2109
|
-
description:
|
|
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:
|
|
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
|
|
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:
|
|
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
|
-
|
|
2201
|
-
|
|
2202
|
-
|
|
2203
|
-
|
|
2204
|
-
|
|
2205
|
-
|
|
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: |
|