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.
- package/CHANGELOG.md +6 -0
- package/README.md +34 -1
- package/dist/cjs/index.cjs +114 -0
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +214 -2
- package/dist/esm/index.js +114 -1
- package/dist/esm/index.js.map +1 -1
- package/openapi/soundlink-public-api-v1.yaml +909 -68
- package/package.json +2 -1
|
@@ -7,19 +7,43 @@ info:
|
|
|
7
7
|
|
|
8
8
|
**Base URL:** `https://api.getsoundlink.com`
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
## Authentication
|
|
11
11
|
|
|
12
|
-
|
|
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.
|
|
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
|
-
|
|
25
|
+
Authorization: Bearer <oauth_access_token>
|
|
20
26
|
```
|
|
21
27
|
|
|
22
|
-
|
|
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
|
|
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:
|
|
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
|
|
1268
|
+
summary: Import video(s) from public HTTPS MP4 URL(s)
|
|
901
1269
|
description: |
|
|
902
|
-
|
|
903
|
-
|
|
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-
|
|
908
|
-
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.
|
|
909
1277
|
|
|
910
|
-
Poll `GET /v1/videos/import/{sessionId}` until `status` is `ready
|
|
911
|
-
|
|
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
|
-
|
|
924
|
-
|
|
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
|
|
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
|
|
995
|
-
|
|
996
|
-
|
|
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
|
-
-
|
|
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
|
-
|
|
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:
|
|
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
|
-
|
|
2945
|
+
allOf:
|
|
2946
|
+
- $ref: '#/components/schemas/VideoImportStatusError'
|
|
2147
2947
|
nullable: true
|
|
2148
|
-
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
|
|
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:
|
|
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
|
|
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:
|
|
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
|
-
|
|
2240
|
-
|
|
2241
|
-
|
|
2242
|
-
|
|
2243
|
-
|
|
2244
|
-
|
|
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: |
|