soundlink 2.0.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -7,19 +7,43 @@ info:
7
7
 
8
8
  **Base URL:** `https://api.getsoundlink.com`
9
9
 
10
- **Authentication:** send a `sk_*` API key created in the Soundlink app (Settings → Developer → API keys) using one of:
10
+ ## Authentication
11
11
 
12
- 1. **`Authorization: Bearer` (recommended)**:
12
+ Send `Authorization: Bearer` with one of:
13
+
14
+ 1. **API key (recommended)** — a `sk_*` key from the Soundlink app
15
+ (Settings → Developer → API keys):
13
16
  ```
14
17
  Authorization: Bearer sk_abc123_<token>
15
18
  ```
16
19
 
17
- 2. **`x-api-key` header (deprecated, retiring 2026-08-17)** — migrate to Bearer above before then:
20
+ 2. **OAuth Bearer** — an access token from Sign in with Soundlink
21
+ (authorization code or client credentials). Token scopes use the
22
+ same strings as Public API key scopes (for example `campaigns:read`,
23
+ `metrics:read`):
18
24
  ```
19
- x-api-key: sk_abc123_<token>
25
+ Authorization: Bearer <oauth_access_token>
20
26
  ```
21
27
 
22
- Sending both headers returns `401 mixed_credentials`.
28
+ `x-api-key` is no longer accepted and is ignored if sent. Requests
29
+ without `Authorization: Bearer` return `401 invalid_api_key` (or
30
+ `401 invalid_token` when a Bearer value is present but neither a
31
+ recognized `sk_*` key nor a valid OAuth access token).
32
+
33
+ ### Which operations accept OAuth?
34
+
35
+ | Operations | Required scope | Auth |
36
+ | --- | --- | --- |
37
+ | `GET /v1/ping` | any granted Public API scope | API key (Bearer) or OAuth Bearer |
38
+ | Campaign reads (`GET /v1/strategies`, `GET /v1/campaigns`, campaign detail, tiers) | `campaigns:read` | API key (Bearer) or OAuth Bearer |
39
+ | Metrics reads (overview, breakdown, exports) | `metrics:read` | API key (Bearer) or OAuth Bearer |
40
+ | Campaign writes (create, stop, budget, tier updates) | `campaigns:write` | API key (Bearer) or OAuth Bearer |
41
+ | Video import / import status | `videos:write` | API key (Bearer) or OAuth Bearer |
42
+ | Soundlink reads (list, detail, metrics overview/timeseries/breakdown/engagement, JSONL exports) | `soundlinks:read` | API key (Bearer) or OAuth Bearer |
43
+
44
+ Per-operation scope requirements are also marked with `x-required-scope`
45
+ (except `GET /v1/ping`, which accepts any valid credential with at least
46
+ one Public API scope granted to the key/token).
23
47
 
24
48
  All responses are wrapped in a standard envelope:
25
49
  ```json
@@ -33,8 +57,8 @@ servers:
33
57
  description: Production
34
58
 
35
59
  security:
36
- - apiKeyAuth: []
37
60
  - apiKeyBearerAuth: []
61
+ - oauthBearer: []
38
62
 
39
63
  tags:
40
64
  - name: System
@@ -45,6 +69,8 @@ tags:
45
69
  description: Campaign performance metrics
46
70
  - name: Videos
47
71
  description: Partner video library import for Full Control campaigns
72
+ - name: Soundlinks
73
+ description: Soundlink listing, detail, and performance metrics
48
74
 
49
75
  paths:
50
76
  /v1/ping:
@@ -53,12 +79,13 @@ paths:
53
79
  summary: Verify connectivity and authentication
54
80
  description: |
55
81
  Returns `{ "status": "ok" }` if the request is authenticated and the
56
- API is reachable. Useful for verifying a newly issued key before making
57
- data requests.
82
+ API is reachable. Useful for verifying a newly issued API key or OAuth
83
+ access token before making data requests. Accepts either credential;
84
+ no specific scope is required beyond a valid key/token.
58
85
  tags: [System]
59
86
  security:
60
- - apiKeyAuth: []
61
87
  - apiKeyBearerAuth: []
88
+ - oauthBearer: []
62
89
  responses:
63
90
  '200':
64
91
  description: Authenticated and reachable
@@ -95,11 +122,11 @@ paths:
95
122
  `POST /v1/campaigns`. Built-in strategies apply platform default
96
123
  tiering internally; only `custom` allows `tierTargeting` on create.
97
124
 
98
- Requires the `campaigns:read` scope.
125
+ Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
99
126
  tags: [Campaigns]
100
127
  security:
101
- - apiKeyAuth: []
102
128
  - apiKeyBearerAuth: []
129
+ - oauthBearer: []
103
130
  x-required-scope: campaigns:read
104
131
  responses:
105
132
  '200':
@@ -133,10 +160,13 @@ paths:
133
160
  description: |
134
161
  Returns all campaigns for the authenticated organization.
135
162
  Intended for reporting and data warehouse sync.
163
+
164
+ Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
136
165
  tags: [Campaigns]
137
166
  security:
138
- - apiKeyAuth: []
139
167
  - apiKeyBearerAuth: []
168
+ - oauthBearer: []
169
+ x-required-scope: campaigns:read
140
170
  parameters:
141
171
  - $ref: '#/components/parameters/page'
142
172
  - $ref: '#/components/parameters/pageSize100'
@@ -190,10 +220,12 @@ paths:
190
220
  deducted from the wallet balance), so the `Idempotency-Key` header
191
221
  is **required** on every request. See the header description below
192
222
  for retry semantics.
223
+
224
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
193
225
  tags: [Campaigns]
194
226
  security:
195
- - apiKeyAuth: []
196
227
  - apiKeyBearerAuth: []
228
+ - oauthBearer: []
197
229
  x-required-scope: campaigns:write
198
230
  parameters:
199
231
  - $ref: '#/components/parameters/idempotencyKey'
@@ -283,11 +315,15 @@ paths:
283
315
  get:
284
316
  operationId: getCampaign
285
317
  summary: Get campaign
286
- description: Fetch full details for a single campaign.
318
+ description: |
319
+ Fetch full details for a single campaign.
320
+
321
+ Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
287
322
  tags: [Campaigns]
288
323
  security:
289
- - apiKeyAuth: []
290
324
  - apiKeyBearerAuth: []
325
+ - oauthBearer: []
326
+ x-required-scope: campaigns:read
291
327
  parameters:
292
328
  - $ref: '#/components/parameters/campaignId'
293
329
  responses:
@@ -331,11 +367,13 @@ paths:
331
367
  already-stopped campaign succeeds without double-refunding. The
332
368
  `Idempotency-Key` header is also **required** so retries of the same
333
369
  request replay the original response without repeating side effects.
370
+
371
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
334
372
  tags: [Campaigns]
335
373
  x-required-scope: campaigns:write
336
374
  security:
337
- - apiKeyAuth: []
338
375
  - apiKeyBearerAuth: []
376
+ - oauthBearer: []
339
377
  parameters:
340
378
  - $ref: '#/components/parameters/campaignId'
341
379
  - $ref: '#/components/parameters/idempotencyKey'
@@ -377,11 +415,13 @@ paths:
377
415
  - `current_and_renewals` — applies to the current cycle and future renewals
378
416
 
379
417
  Debits the organization wallet when the current cycle is increased.
418
+
419
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
380
420
  tags: [Campaigns]
381
421
  x-required-scope: campaigns:write
382
422
  security:
383
- - apiKeyAuth: []
384
423
  - apiKeyBearerAuth: []
424
+ - oauthBearer: []
385
425
  parameters:
386
426
  - $ref: '#/components/parameters/campaignId'
387
427
  - $ref: '#/components/parameters/idempotencyKey'
@@ -450,11 +490,13 @@ paths:
450
490
  - `targetDailyBudget` must be at least `$10`/day and lower than the
451
491
  current daily budget
452
492
  - more than 3 days must remain in the current cycle
493
+
494
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
453
495
  tags: [Campaigns]
454
496
  x-required-scope: campaigns:write
455
497
  security:
456
- - apiKeyAuth: []
457
498
  - apiKeyBearerAuth: []
499
+ - oauthBearer: []
458
500
  parameters:
459
501
  - $ref: '#/components/parameters/campaignId'
460
502
  - $ref: '#/components/parameters/idempotencyKey'
@@ -501,11 +543,13 @@ paths:
501
543
  updated (`lastUpdate`). Use this before `PATCH` to build a valid request.
502
544
 
503
545
  **Wallet campaigns only** (`generation: 3`).
546
+
547
+ Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
504
548
  tags: [Campaigns]
505
549
  x-required-scope: campaigns:read
506
550
  security:
507
- - apiKeyAuth: []
508
551
  - apiKeyBearerAuth: []
552
+ - oauthBearer: []
509
553
  parameters:
510
554
  - $ref: '#/components/parameters/campaignId'
511
555
  responses:
@@ -552,11 +596,13 @@ paths:
552
596
 
553
597
  **Cooldown:** after a successful update, further tier changes are
554
598
  blocked for **72 hours** (`409 tier_update_cooldown`).
599
+
600
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
555
601
  tags: [Campaigns]
556
602
  x-required-scope: campaigns:write
557
603
  security:
558
- - apiKeyAuth: []
559
604
  - apiKeyBearerAuth: []
605
+ - oauthBearer: []
560
606
  parameters:
561
607
  - $ref: '#/components/parameters/campaignId'
562
608
  requestBody:
@@ -618,10 +664,13 @@ paths:
618
664
  `/metrics/breakdown` for those.
619
665
 
620
666
  Suitable for dashboards and quick syncs.
667
+
668
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
621
669
  tags: [Metrics]
622
670
  security:
623
- - apiKeyAuth: []
624
671
  - apiKeyBearerAuth: []
672
+ - oauthBearer: []
673
+ x-required-scope: metrics:read
625
674
  parameters:
626
675
  - $ref: '#/components/parameters/campaignId'
627
676
  - $ref: '#/components/parameters/startDate'
@@ -677,10 +726,13 @@ paths:
677
726
 
678
727
  Maps to the **Countries** tab in the Soundlink Insights UI.
679
728
  Use for daily warehouse loads.
729
+
730
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
680
731
  tags: [Metrics]
681
732
  security:
682
- - apiKeyAuth: []
683
733
  - apiKeyBearerAuth: []
734
+ - oauthBearer: []
735
+ x-required-scope: metrics:read
684
736
  parameters:
685
737
  - $ref: '#/components/parameters/campaignId'
686
738
  - $ref: '#/components/parameters/startDate'
@@ -780,10 +832,13 @@ paths:
780
832
  to 7 days after the date closes due to delayed events from Meta and
781
833
  Spotify. Re-fetching and re-ingesting on the primary key is safe
782
834
  (idempotent).
835
+
836
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
783
837
  tags: [Metrics]
784
838
  security:
785
- - apiKeyAuth: []
786
839
  - apiKeyBearerAuth: []
840
+ - oauthBearer: []
841
+ x-required-scope: metrics:read
787
842
  parameters:
788
843
  - $ref: '#/components/parameters/campaignId'
789
844
  - $ref: '#/components/parameters/startDate'
@@ -818,6 +873,116 @@ paths:
818
873
  '429': { $ref: '#/components/responses/RateLimited' }
819
874
  '500': { $ref: '#/components/responses/InternalError' }
820
875
 
876
+ /v1/campaigns/{campaignId}/metrics/engagement:
877
+ get:
878
+ operationId: getCampaignEngagement
879
+ summary: Campaign engagement breakdown
880
+ description: |
881
+ Per-day, per-track engagement metrics for a campaign. One row per
882
+ `(report_date, campaign_id, engagement_context, country_code, engaged_spotify_track_id)`.
883
+ Results are paginated.
884
+
885
+ **Row schema:** `campaign_engagement_daily` v1.0 — the same schema used
886
+ in JSONL bulk exports. Rows are idempotent on the primary key; re-ingesting
887
+ is safe.
888
+
889
+ **Key difference from `/metrics/breakdown`:** this endpoint covers the
890
+ full engagement window — including post-campaign streaming activity —
891
+ not just dates when the campaign was actively running.
892
+
893
+ **`engagement_context` values:**
894
+ - `catalog` — same-artist spillover (and direct promoted-track plays)
895
+ on track campaigns.
896
+ - `playlist` — per-track performance inside the promoted playlist on
897
+ playlist campaigns.
898
+
899
+ **`listeners` is deduplicated within each row only.** Do not sum
900
+ `listeners` across days to get a campaign total.
901
+
902
+ **Date range:** if you omit both dates, defaults to the last **90 days**
903
+ ending today. Override with `startDate` / `endDate`. **Responses are
904
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
905
+
906
+ **Mutability window:** rows for a given `report_date` can be revised
907
+ for up to 7 days after the date closes due to delayed Spotify
908
+ playback events.
909
+
910
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
911
+ tags: [Metrics]
912
+ security:
913
+ - apiKeyBearerAuth: []
914
+ - oauthBearer: []
915
+ x-required-scope: metrics:read
916
+ parameters:
917
+ - $ref: '#/components/parameters/campaignId'
918
+ - $ref: '#/components/parameters/startDate'
919
+ - $ref: '#/components/parameters/endDate'
920
+ - name: engagementContext
921
+ in: query
922
+ schema:
923
+ type: string
924
+ enum: [catalog, playlist]
925
+ description: Filter to a single engagement context. Omit to return both.
926
+ - $ref: '#/components/parameters/page'
927
+ - $ref: '#/components/parameters/pageSize500'
928
+ - name: sortBy
929
+ in: query
930
+ schema:
931
+ type: string
932
+ enum: [report_date]
933
+ default: report_date
934
+ - $ref: '#/components/parameters/sortOrder'
935
+ responses:
936
+ '200':
937
+ description: Paginated engagement rows (`campaign_engagement_daily` schema)
938
+ content:
939
+ application/json:
940
+ schema:
941
+ $ref: '#/components/schemas/MetricsEngagementResponse'
942
+ example:
943
+ data:
944
+ schemaVersion: '1.0'
945
+ items:
946
+ - provider: soundlink
947
+ account_id: a7ac3173-2f71-4e79-921f-d15d7112cc9a
948
+ schema_version: '1.0'
949
+ report_date: '2026-04-08'
950
+ report_date_timezone: UTC
951
+ exported_at: '2026-05-22T10:12:11Z'
952
+ campaign_id: 8ccd7b88-2591-4b94-848f-f142f5c6bba1
953
+ campaign_name: 9 To 5
954
+ campaign_target_type: track
955
+ campaign_target_isrc: DEXW62500272
956
+ campaign_target_spotify_track_id: 2RkZ5WPkKyBf0u8vN3dNgb
957
+ campaign_target_playlist_id: null
958
+ status: ended
959
+ engagement_context: catalog
960
+ country_code: US
961
+ engaged_track_isrc: DEXW62500001
962
+ engaged_spotify_track_id: 4cOdK2wGLETKBW3PvgPWqT
963
+ engaged_track_name: Till The Sunrise
964
+ playlist_position: null
965
+ new_listeners: 42
966
+ returning_listeners: 18
967
+ listeners: 60
968
+ new_listener_streams: 58
969
+ returning_listener_streams: 31
970
+ streams: 89
971
+ spl: 1.48
972
+ pagination:
973
+ page: 1
974
+ pageSize: 50
975
+ totalCount: 120
976
+ totalPages: 3
977
+ meta:
978
+ requestId: 550e8400-e29b-41d4-a716-446655440000
979
+ '400': { $ref: '#/components/responses/BadRequest' }
980
+ '401': { $ref: '#/components/responses/Unauthorized' }
981
+ '403': { $ref: '#/components/responses/Forbidden' }
982
+ '404': { $ref: '#/components/responses/NotFound' }
983
+ '429': { $ref: '#/components/responses/RateLimited' }
984
+ '500': { $ref: '#/components/responses/InternalError' }
985
+
821
986
  /v1/campaigns/{campaignId}/metrics/engagement/export:
822
987
  get:
823
988
  operationId: exportCampaignEngagement
@@ -825,7 +990,9 @@ paths:
825
990
  description: |
826
991
  Streams the full engagement dataset for a campaign as
827
992
  **newline-delimited JSON (JSONL)**. Every line is a complete, valid
828
- JSON object conforming to the `campaign_engagement_daily` v1.0 schema.
993
+ JSON object conforming to the `campaign_engagement_daily` v1.0 schema
994
+ — identical to the rows returned by `GET /metrics/engagement` but
995
+ without pagination or an envelope wrapper.
829
996
 
830
997
  Designed for data pipeline consumers: load directly into BigQuery,
831
998
  Snowflake, or any JSONL-aware ingest tool without cursor logic.
@@ -850,10 +1017,13 @@ paths:
850
1017
  **Mutability:** rows for a given `report_date` can be revised for up to
851
1018
  7 days after the date closes. Re-fetching and re-ingesting on the
852
1019
  primary key is safe (idempotent).
1020
+
1021
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
853
1022
  tags: [Metrics]
854
1023
  security:
855
- - apiKeyAuth: []
856
1024
  - apiKeyBearerAuth: []
1025
+ - oauthBearer: []
1026
+ x-required-scope: metrics:read
857
1027
  parameters:
858
1028
  - $ref: '#/components/parameters/campaignId'
859
1029
  - $ref: '#/components/parameters/startDate'
@@ -894,885 +1064,2148 @@ paths:
894
1064
  '429': { $ref: '#/components/responses/RateLimited' }
895
1065
  '500': { $ref: '#/components/responses/InternalError' }
896
1066
 
897
- /v1/videos/import:
898
- post:
899
- operationId: importVideo
900
- summary: Import a video from a public HTTPS MP4 URL
1067
+ /v1/soundlinks:
1068
+ get:
1069
+ operationId: listSoundlinks
1070
+ summary: List soundlinks
901
1071
  description: |
902
- Downloads a single public HTTPS MP4, stages it for ingestion, and starts
903
- the background video pipeline. Returns `202` while processing, or `200`
904
- with `videoId` immediately when the organization already has the same video
905
- (content duplicate).
1072
+ Returns the organization's self-serve soundlinks. Soundlinks linked
1073
+ to a campaign are the campaign's underlying resource and are served
1074
+ by the Campaigns endpoints instead.
906
1075
 
907
- Requires the `videos:write` scope. Subject to a stricter per-key rate limit
908
- than generic public API routes (default 5 imports per hour per API key).
1076
+ Soundlink schemas contain no financial fields: ads for self-serve
1077
+ soundlinks run in your own Meta account, so spend is not visible to
1078
+ Soundlink.
909
1079
 
910
- Poll `GET /v1/videos/import/{sessionId}` until `status` is `ready` or `failed`.
911
- Use the returned `videoId` in Full Control campaign `creativeDirection.selectedCreatives`.
912
- tags: [Videos]
1080
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1081
+ tags: [Soundlinks]
913
1082
  security:
914
- - apiKeyAuth: []
915
1083
  - apiKeyBearerAuth: []
916
- x-required-scope: videos:write
917
- requestBody:
918
- required: true
919
- content:
920
- application/json:
921
- schema:
922
- $ref: '#/components/schemas/VideoImportRequest'
923
- example:
924
- url: 'https://cdn.example.com/promo.mp4'
1084
+ - oauthBearer: []
1085
+ x-required-scope: soundlinks:read
1086
+ parameters:
1087
+ - $ref: '#/components/parameters/page'
1088
+ - $ref: '#/components/parameters/pageSize100'
1089
+ - name: sortBy
1090
+ in: query
1091
+ schema:
1092
+ type: string
1093
+ enum: [createdAt]
1094
+ default: createdAt
1095
+ - $ref: '#/components/parameters/sortOrder'
925
1096
  responses:
926
1097
  '200':
927
- description: Duplicate video already in the organization's library
1098
+ description: Paginated list of soundlinks
928
1099
  content:
929
1100
  application/json:
930
1101
  schema:
931
- $ref: '#/components/schemas/VideoImportStartResponse'
932
- '202':
933
- description: Import accepted; ingestion in progress
1102
+ $ref: '#/components/schemas/SoundlinkListResponse'
1103
+ example:
1104
+ data:
1105
+ items:
1106
+ - soundlinkId: V1StGXR8_Z5jdHi6B-myT
1107
+ organizationId: a7ac3173-2f71-4e79-921f-d15d7112dd11
1108
+ name: Midnight Drive
1109
+ url: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
1110
+ targetType: track
1111
+ spotifyUrl: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
1112
+ status: active
1113
+ createdAt: '2026-04-01T10:00:00Z'
1114
+ pagination:
1115
+ page: 1
1116
+ pageSize: 10
1117
+ totalCount: 42
1118
+ totalPages: 5
1119
+ meta:
1120
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1121
+ '401': { $ref: '#/components/responses/Unauthorized' }
1122
+ '403': { $ref: '#/components/responses/Forbidden' }
1123
+ '429': { $ref: '#/components/responses/RateLimited' }
1124
+ '500': { $ref: '#/components/responses/InternalError' }
1125
+
1126
+ /v1/soundlinks/{soundlinkId}:
1127
+ get:
1128
+ operationId: getSoundlink
1129
+ summary: Get soundlink
1130
+ description: |
1131
+ Fetch details for a single self-serve soundlink. Soundlinks linked
1132
+ to a campaign are not addressable here and return `404`.
1133
+
1134
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1135
+ tags: [Soundlinks]
1136
+ security:
1137
+ - apiKeyBearerAuth: []
1138
+ - oauthBearer: []
1139
+ x-required-scope: soundlinks:read
1140
+ parameters:
1141
+ - $ref: '#/components/parameters/soundlinkId'
1142
+ responses:
1143
+ '200':
1144
+ description: Soundlink detail
934
1145
  content:
935
1146
  application/json:
936
1147
  schema:
937
- $ref: '#/components/schemas/VideoImportStartResponse'
1148
+ $ref: '#/components/schemas/SoundlinkDetailResponse'
1149
+ example:
1150
+ data:
1151
+ soundlinkId: V1StGXR8_Z5jdHi6B-myT
1152
+ organizationId: a7ac3173-2f71-4e79-921f-d15d7112dd11
1153
+ name: Midnight Drive
1154
+ url: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
1155
+ targetType: track
1156
+ spotifyUrl: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
1157
+ status: active
1158
+ createdAt: '2026-04-01T10:00:00Z'
1159
+ autoFollow: true
1160
+ metaPixelId: '1234567890123456'
1161
+ tiktokPixelId: null
1162
+ meta:
1163
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1164
+ '401': { $ref: '#/components/responses/Unauthorized' }
1165
+ '403': { $ref: '#/components/responses/Forbidden' }
1166
+ '404': { $ref: '#/components/responses/NotFound' }
1167
+ '429': { $ref: '#/components/responses/RateLimited' }
1168
+ '500': { $ref: '#/components/responses/InternalError' }
1169
+
1170
+ /v1/soundlinks/{soundlinkId}/metrics/overview:
1171
+ get:
1172
+ operationId: getSoundlinkMetricsOverview
1173
+ summary: Soundlink metrics overview
1174
+ description: |
1175
+ Soundlink-level totals for a date range: landing page views, outbound
1176
+ clicks, listeners, streams, followers, and derived ratios. Totals are
1177
+ sums of country-day mart rows (`api_smart_link_country_daily`);
1178
+ `listeners` is the sum of daily country `new_listeners` (not
1179
+ period-unique). No per-day rows — use `/metrics/timeseries` for those,
1180
+ or `/metrics/breakdown` for country-day rows (including new/returning
1181
+ splits).
1182
+
1183
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1184
+ tags: [Soundlinks]
1185
+ security:
1186
+ - apiKeyBearerAuth: []
1187
+ - oauthBearer: []
1188
+ x-required-scope: soundlinks:read
1189
+ parameters:
1190
+ - $ref: '#/components/parameters/soundlinkId'
1191
+ - $ref: '#/components/parameters/soundlinkStartDate'
1192
+ - $ref: '#/components/parameters/soundlinkEndDate'
1193
+ responses:
1194
+ '200':
1195
+ description: Soundlink totals
1196
+ content:
1197
+ application/json:
1198
+ schema:
1199
+ $ref: '#/components/schemas/SoundlinkMetricsOverviewResponse'
1200
+ example:
1201
+ data:
1202
+ views: 4821
1203
+ link_clicks: 890
1204
+ streams: 9340
1205
+ listeners: 3980
1206
+ followers: 312
1207
+ streams_per_listener: 2.35
1208
+ ctr_lp: 0.185
1209
+ meta:
1210
+ requestId: 550e8400-e29b-41d4-a716-446655440000
938
1211
  '400': { $ref: '#/components/responses/BadRequest' }
939
1212
  '401': { $ref: '#/components/responses/Unauthorized' }
940
1213
  '403': { $ref: '#/components/responses/Forbidden' }
1214
+ '404': { $ref: '#/components/responses/NotFound' }
941
1215
  '429': { $ref: '#/components/responses/RateLimited' }
942
1216
  '500': { $ref: '#/components/responses/InternalError' }
943
1217
 
944
- /v1/videos/import/{sessionId}:
1218
+ /v1/soundlinks/{soundlinkId}/metrics/timeseries:
945
1219
  get:
946
- operationId: getVideoImportStatus
947
- summary: Get video import session status
1220
+ operationId: getSoundlinkMetricsTimeseries
1221
+ summary: Soundlink metrics timeseries
948
1222
  description: |
949
- Returns processing status and the resulting `videoId` when ingestion completes.
950
- Requires the `videos:write` scope.
951
- tags: [Videos]
1223
+ Per-day metrics for a soundlink. One row per `report_date`. Results
1224
+ are paginated.
1225
+
1226
+ **Row schema:** `soundlink_daily` v1.0. Rows are idempotent on the
1227
+ primary key `(provider, account_id, report_date, soundlink_id)`;
1228
+ re-ingesting is safe.
1229
+
1230
+ **Mutability window:** rows for a given `report_date` can be revised
1231
+ for up to 7 days after the date closes due to delayed Spotify playback
1232
+ events. Re-fetch or re-ingest accordingly.
1233
+
1234
+ Rows are aggregated across countries (no `country_code`) and
1235
+ contain no financial fields. For country-day rows use
1236
+ `/metrics/breakdown` (and `/metrics/breakdown/export`).
1237
+
1238
+ Maps to the **Trends** tab in the Soundlink Insights UI.
1239
+
1240
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1241
+ tags: [Soundlinks]
952
1242
  security:
953
- - apiKeyAuth: []
954
1243
  - apiKeyBearerAuth: []
955
- x-required-scope: videos:write
1244
+ - oauthBearer: []
1245
+ x-required-scope: soundlinks:read
956
1246
  parameters:
957
- - name: sessionId
958
- in: path
959
- required: true
1247
+ - $ref: '#/components/parameters/soundlinkId'
1248
+ - $ref: '#/components/parameters/soundlinkStartDate'
1249
+ - $ref: '#/components/parameters/soundlinkEndDate'
1250
+ - $ref: '#/components/parameters/page'
1251
+ - $ref: '#/components/parameters/pageSize500'
1252
+ - name: sortBy
1253
+ in: query
960
1254
  schema:
961
1255
  type: string
962
- format: uuid
963
- description: Upload session ID returned by `POST /v1/videos/import`
1256
+ enum: [report_date]
1257
+ default: report_date
1258
+ - $ref: '#/components/parameters/sortOrder'
964
1259
  responses:
965
1260
  '200':
966
- description: Import session status
1261
+ description: Paginated per-day rows (`soundlink_daily` schema)
967
1262
  content:
968
1263
  application/json:
969
1264
  schema:
970
- $ref: '#/components/schemas/VideoImportStatusResponse'
1265
+ $ref: '#/components/schemas/SoundlinkTimeseriesResponse'
1266
+ example:
1267
+ data:
1268
+ schemaVersion: '1.0'
1269
+ items:
1270
+ - provider: soundlink
1271
+ account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
1272
+ schema_version: '1.0'
1273
+ report_date: '2026-08-01'
1274
+ report_date_timezone: UTC
1275
+ exported_at: '2026-08-28T03:00:00Z'
1276
+ soundlink_id: V1StGXR8_Z5jdHi6B-myT
1277
+ soundlink_name: Midnight Drive
1278
+ soundlink_target_type: track
1279
+ soundlink_target_isrc: DEXW62500259
1280
+ soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
1281
+ soundlink_target_playlist_id: null
1282
+ views: 4821
1283
+ link_clicks: 890
1284
+ streams: 203
1285
+ listeners: 145
1286
+ new_listeners: 120
1287
+ returning_listeners: 25
1288
+ new_listener_streams: 160
1289
+ returning_listener_streams: 43
1290
+ followers: 12
1291
+ streams_per_listener: 1.4
1292
+ ctr_lp: 0.185
1293
+ pagination:
1294
+ page: 1
1295
+ pageSize: 50
1296
+ totalCount: 90
1297
+ totalPages: 2
1298
+ meta:
1299
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1300
+ '400': { $ref: '#/components/responses/BadRequest' }
971
1301
  '401': { $ref: '#/components/responses/Unauthorized' }
972
1302
  '403': { $ref: '#/components/responses/Forbidden' }
973
1303
  '404': { $ref: '#/components/responses/NotFound' }
974
1304
  '429': { $ref: '#/components/responses/RateLimited' }
975
1305
  '500': { $ref: '#/components/responses/InternalError' }
976
1306
 
977
- components:
978
- securitySchemes:
979
- apiKeyAuth:
980
- type: apiKey
981
- in: header
982
- name: x-api-key
1307
+ /v1/soundlinks/{soundlinkId}/metrics/breakdown:
1308
+ get:
1309
+ operationId: getSoundlinkMetricsBreakdown
1310
+ summary: Soundlink metrics breakdown
983
1311
  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.
1312
+ Per-day metrics broken down by country. One row per
1313
+ `(report_date, soundlink_id, country_code)`. Can be large, so results
1314
+ are paginated.
988
1315
 
989
- apiKeyBearerAuth:
990
- type: http
991
- scheme: bearer
992
- description: |
993
- Pass your Soundlink `sk_*` API key as a Bearer token:
994
- `Authorization: Bearer sk_<prefix>_<token>`. Verified with the exact
995
- same key as `apiKeyAuth` — just the recommended header for the same
996
- `sk_*` credential. Do not combine with `x-api-key`.
1316
+ **Row schema:** `soundlink_country_daily` v1.0 — the same schema used
1317
+ in JSONL bulk exports. Rows are idempotent on the primary key
1318
+ `(provider, account_id, report_date, soundlink_id, country_code)`;
1319
+ re-ingesting is safe.
997
1320
 
998
- parameters:
999
- campaignId:
1000
- name: campaignId
1001
- in: path
1002
- required: true
1003
- schema:
1004
- type: string
1005
- description: Campaign identifier (UUID)
1321
+ **Mutability window:** rows for a given `report_date` can be revised
1322
+ for up to 7 days after the date closes due to delayed Spotify playback
1323
+ events. Re-fetch or re-ingest accordingly.
1006
1324
 
1007
- idempotencyKey:
1008
- name: Idempotency-Key
1009
- in: header
1010
- required: true
1011
- schema:
1012
- type: string
1013
- minLength: 1
1014
- maxLength: 255
1015
- description: |
1016
- A unique string identifying this request, used to safely retry write
1017
- operations (create, stop, budget increase/decrease) without repeating
1018
- side effects. Required on every request that references this parameter.
1019
- Reusing this key with an unchanged request body replays the original
1020
- response; reusing it with a different body returns
1021
- `409 idempotency_key_conflict`. Keys are honored for 24 hours.
1325
+ Rows contain no financial fields: ads for self-serve soundlinks run
1326
+ in your own Meta account, so spend is not visible to Soundlink.
1022
1327
 
1023
- page:
1024
- name: page
1025
- in: query
1026
- schema:
1027
- type: integer
1028
- minimum: 1
1029
- default: 1
1030
- description: Page number (1-indexed)
1328
+ Maps to the **Countries** tab in the Soundlink Insights UI.
1329
+ Use `/metrics/timeseries` for country-aggregated daily Trends rows.
1031
1330
 
1032
- pageSize100:
1033
- name: pageSize
1034
- in: query
1035
- schema:
1036
- type: integer
1037
- minimum: 1
1038
- maximum: 100
1039
- default: 10
1040
- description: Items per page (max 100)
1041
-
1042
- pageSize500:
1043
- name: pageSize
1044
- in: query
1045
- schema:
1046
- type: integer
1047
- minimum: 1
1048
- maximum: 500
1049
- default: 50
1050
- description: Rows per page (max 500; higher default than list endpoints)
1051
-
1052
- sortOrder:
1053
- name: sortOrder
1054
- in: query
1055
- schema:
1056
- type: string
1057
- enum: [asc, desc]
1058
- default: desc
1059
- description: Sort direction
1331
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1332
+ tags: [Soundlinks]
1333
+ security:
1334
+ - apiKeyBearerAuth: []
1335
+ - oauthBearer: []
1336
+ x-required-scope: soundlinks:read
1337
+ parameters:
1338
+ - $ref: '#/components/parameters/soundlinkId'
1339
+ - $ref: '#/components/parameters/soundlinkStartDate'
1340
+ - $ref: '#/components/parameters/soundlinkEndDate'
1341
+ - $ref: '#/components/parameters/page'
1342
+ - $ref: '#/components/parameters/pageSize500'
1343
+ - name: sortBy
1344
+ in: query
1345
+ schema:
1346
+ type: string
1347
+ enum: [report_date, country_code]
1348
+ default: report_date
1349
+ - $ref: '#/components/parameters/sortOrder'
1350
+ responses:
1351
+ '200':
1352
+ description: Paginated per-day country rows (`soundlink_country_daily` schema)
1353
+ content:
1354
+ application/json:
1355
+ schema:
1356
+ $ref: '#/components/schemas/SoundlinkBreakdownResponse'
1357
+ example:
1358
+ data:
1359
+ schemaVersion: '1.0'
1360
+ items:
1361
+ - provider: soundlink
1362
+ account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
1363
+ schema_version: '1.0'
1364
+ report_date: '2026-08-01'
1365
+ report_date_timezone: UTC
1366
+ exported_at: '2026-08-28T03:00:00Z'
1367
+ soundlink_id: V1StGXR8_Z5jdHi6B-myT
1368
+ soundlink_name: Midnight Drive
1369
+ soundlink_target_type: track
1370
+ soundlink_target_isrc: DEXW62500259
1371
+ soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
1372
+ soundlink_target_playlist_id: null
1373
+ country_code: US
1374
+ views: 4821
1375
+ link_clicks: 890
1376
+ streams: 203
1377
+ listeners: 145
1378
+ new_listeners: 120
1379
+ returning_listeners: 25
1380
+ new_listener_streams: 160
1381
+ returning_listener_streams: 43
1382
+ followers: 12
1383
+ streams_per_listener: 1.4
1384
+ ctr_lp: 0.185
1385
+ pagination:
1386
+ page: 1
1387
+ pageSize: 50
1388
+ totalCount: 340
1389
+ totalPages: 7
1390
+ meta:
1391
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1392
+ '400': { $ref: '#/components/responses/BadRequest' }
1393
+ '401': { $ref: '#/components/responses/Unauthorized' }
1394
+ '403': { $ref: '#/components/responses/Forbidden' }
1395
+ '404': { $ref: '#/components/responses/NotFound' }
1396
+ '429': { $ref: '#/components/responses/RateLimited' }
1397
+ '500': { $ref: '#/components/responses/InternalError' }
1060
1398
 
1061
- startDate:
1062
- name: startDate
1063
- in: query
1064
- schema:
1065
- type: string
1066
- format: date
1067
- description: Inclusive start date (`YYYY-MM-DD`). Defaults to campaign start date.
1399
+ /v1/soundlinks/{soundlinkId}/metrics/breakdown/export:
1400
+ get:
1401
+ operationId: exportSoundlinkMetricsBreakdown
1402
+ summary: Soundlink metrics breakdown export (JSONL)
1403
+ description: |
1404
+ Streams the full country-level metrics dataset for a soundlink as
1405
+ **newline-delimited JSON (JSONL)**. Every line is a complete, valid
1406
+ JSON object conforming to the `soundlink_country_daily` v1.0 schema
1407
+ — identical to the rows returned by `GET /metrics/breakdown` but
1408
+ without pagination or an envelope wrapper.
1068
1409
 
1069
- endDate:
1070
- name: endDate
1071
- in: query
1072
- schema:
1073
- type: string
1074
- format: date
1075
- description: Inclusive end date (`YYYY-MM-DD`). Defaults to today.
1410
+ Designed for data pipeline consumers: load directly into BigQuery,
1411
+ Snowflake, or any JSONL-aware ingest tool without cursor logic.
1076
1412
 
1077
- schemas:
1078
- # --- Shared ---
1413
+ **Usage:**
1414
+ ```
1415
+ GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export
1416
+ Accept: application/x-ndjson
1417
+ ```
1079
1418
 
1080
- Meta:
1081
- type: object
1082
- required: [requestId]
1083
- properties:
1084
- requestId:
1085
- type: string
1086
- format: uuid
1087
- description: Server-generated request ID. Include when contacting support.
1419
+ **Date range:** if you omit both dates, defaults to the last **90 days**
1420
+ ending today. Override with `startDate` / `endDate`. **Responses are
1421
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
1422
+ Page longer histories in 90-day slices.
1088
1423
 
1089
- Pagination:
1090
- type: object
1091
- required: [page, pageSize, totalCount, totalPages]
1092
- properties:
1093
- page:
1094
- type: integer
1095
- pageSize:
1096
- type: integer
1097
- totalCount:
1098
- type: integer
1099
- totalPages:
1100
- type: integer
1424
+ **Mutability:** rows for a given `report_date` can be revised for up
1425
+ to 7 days after the date closes due to delayed Spotify playback
1426
+ events. Re-fetching and re-ingesting on the primary key is safe
1427
+ (idempotent).
1101
1428
 
1102
- Error:
1103
- type: object
1104
- required: [code, message]
1105
- properties:
1106
- code:
1107
- type: string
1108
- description: Stable snake_case error code.
1109
- enum:
1110
- - invalid_api_key
1111
- - api_key_revoked
1112
- - api_key_expired
1113
- - mixed_credentials
1114
- - insufficient_scope
1115
- - not_found
1116
- - campaign_not_found
1117
- - invalid_query_parameter
1118
- - invalid_date_range
1119
- - page_size_exceeded
1120
- - invalid_request
1121
- - invalid_genre
1122
- - invalid_duration_or_budget
1123
- - invalid_daily_budget
1124
- - invalid_duration_days
1125
- - invalid_spotify_url
1126
- - invalid_tier_budget_allocation
1127
- - invalid_tier_status
1128
- - tier_update_cooldown
1129
- - wallet_not_enabled
1130
- - insufficient_credit
1131
- - idempotency_key_conflict
1132
- - rate_limit_exceeded
1133
- - invalid_video_url
1134
- - video_import_limit_exceeded
1135
- - video_import_session_not_found
1136
- - internal_error
1137
- message:
1138
- type: string
1139
- description: Human-readable error description. Do not parse programmatically.
1140
- details:
1141
- type: object
1142
- nullable: true
1429
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1430
+ tags: [Soundlinks]
1431
+ security:
1432
+ - apiKeyBearerAuth: []
1433
+ - oauthBearer: []
1434
+ x-required-scope: soundlinks:read
1435
+ parameters:
1436
+ - $ref: '#/components/parameters/soundlinkId'
1437
+ - $ref: '#/components/parameters/startDate'
1438
+ - $ref: '#/components/parameters/endDate'
1439
+ responses:
1440
+ '200':
1143
1441
  description: |
1144
- Additive, error-code-specific context (e.g. `available`/`required`
1145
- on `insufficient_credit`). Absent or `null` for error codes that
1146
- carry no extra data.
1147
- additionalProperties: true
1442
+ JSONL stream. Each line is a `soundlink_country_daily` v1.0 row.
1443
+ Lines are sorted by `(report_date asc, country_code)`.
1444
+ headers:
1445
+ Content-Disposition:
1446
+ schema:
1447
+ type: string
1448
+ description: |
1449
+ `attachment; filename="breakdown_{soundlinkId}_{startDate}_{endDate}.jsonl"`
1450
+ example: 'attachment; filename="breakdown_V1StGXR8_Z5jdHi6B-myT_2026-08-01_2026-08-31.jsonl"'
1451
+ X-Row-Count:
1452
+ schema:
1453
+ type: integer
1454
+ description: Total number of rows in the response.
1455
+ content:
1456
+ application/x-ndjson:
1457
+ schema:
1458
+ $ref: '#/components/schemas/SoundlinkCountryDailyRow'
1459
+ example: |
1460
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"country_code":"US","views":4821,"link_clicks":890,"streams":203,"listeners":145,"new_listeners":120,"returning_listeners":25,"new_listener_streams":160,"returning_listener_streams":43,"followers":12,"streams_per_listener":1.4,"ctr_lp":0.185}
1461
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"country_code":"DE","views":2103,"link_clicks":31,"streams":87,"listeners":61,"new_listeners":48,"returning_listeners":13,"new_listener_streams":64,"returning_listener_streams":23,"followers":4,"streams_per_listener":1.43,"ctr_lp":0.0147}
1462
+ '400': { $ref: '#/components/responses/BadRequest' }
1463
+ '401': { $ref: '#/components/responses/Unauthorized' }
1464
+ '403': { $ref: '#/components/responses/Forbidden' }
1465
+ '404': { $ref: '#/components/responses/NotFound' }
1466
+ '429': { $ref: '#/components/responses/RateLimited' }
1467
+ '500': { $ref: '#/components/responses/InternalError' }
1148
1468
 
1149
- ErrorResponse:
1150
- type: object
1151
- required: [error, meta]
1152
- properties:
1153
- error:
1154
- $ref: '#/components/schemas/Error'
1155
- meta:
1156
- $ref: '#/components/schemas/Meta'
1469
+ /v1/soundlinks/{soundlinkId}/metrics/engagement:
1470
+ get:
1471
+ operationId: getSoundlinkEngagement
1472
+ summary: Soundlink engagement breakdown
1473
+ description: |
1474
+ Per-day, per-track engagement metrics for a soundlink. One row per
1475
+ `(report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id)`.
1476
+ Results are paginated.
1157
1477
 
1158
- # --- Campaign ---
1478
+ **Row schema:** `soundlink_engagement_daily` v1.0 — the same schema used
1479
+ in JSONL bulk exports. Rows are idempotent on the primary key; re-ingesting
1480
+ is safe.
1159
1481
 
1160
- CampaignStatus:
1161
- type: string
1162
- enum: [creating, active, paused, stopped, completed, failed, ended]
1482
+ **Key difference from `/metrics/breakdown`:** breakdown aggregates
1483
+ views, streams, and listeners by **country** (`soundlink_country_daily`);
1484
+ engagement breaks down **which tracks** listeners played, including
1485
+ catalog spillover and playlist slot performance (`engagement_context`,
1486
+ `engaged_spotify_track_id`).
1163
1487
 
1164
- CampaignSummary:
1165
- type: object
1166
- required:
1167
- [
1168
- campaignId,
1169
- organizationId,
1170
- status,
1171
- socialPlatform,
1172
- dailyBudget,
1173
- totalBudget,
1174
- campaignDuration,
1175
- generation,
1176
- createdAt,
1177
- updatedAt,
1178
- ]
1179
- properties:
1180
- campaignId:
1181
- type: string
1182
- organizationId:
1183
- type: string
1184
- status:
1185
- $ref: '#/components/schemas/CampaignStatus'
1186
- socialPlatform:
1187
- type: string
1188
- enum: [meta]
1189
- dailyBudget:
1190
- type: number
1191
- description: USD
1192
- totalBudget:
1193
- type: number
1194
- description: USD
1195
- campaignDuration:
1196
- type: integer
1197
- description: Duration in days
1198
- generation:
1199
- type: integer
1200
- enum: [1, 2, 3]
1201
- description: |
1202
- Campaign resource generation. `1` = Stripe / one-time / subscription /
1203
- legacy; `2` = Soundlink managed; `3` = wallet. Public API write
1204
- operations (budget changes, stop, tier updates) are supported for
1205
- generation `3` only.
1206
- createdAt:
1207
- type: string
1208
- format: date-time
1209
- updatedAt:
1210
- type: string
1211
- format: date-time
1488
+ **`engagement_context` values:**
1489
+ - `catalog` — same-artist spillover (and direct promoted-track plays)
1490
+ on track soundlinks.
1491
+ - `playlist` — per-track performance inside the promoted playlist on
1492
+ playlist soundlinks.
1212
1493
 
1213
- CampaignDetail:
1214
- allOf:
1215
- - $ref: '#/components/schemas/CampaignSummary'
1216
- - type: object
1217
- properties:
1218
- strategyType:
1219
- type: string
1220
- description: |
1221
- Growth strategy (e.g. `custom`, `maximum_growth`, `market_discovery`).
1222
- Set at campaign creation.
1494
+ **`listeners` is deduplicated within each row only.** Do not sum
1495
+ `listeners` across days to get a soundlink total.
1223
1496
 
1224
- CampaignListResponse:
1225
- type: object
1226
- required: [data, meta]
1227
- properties:
1228
- data:
1229
- type: object
1230
- required: [items, pagination]
1231
- properties:
1232
- items:
1233
- type: array
1234
- items:
1235
- $ref: '#/components/schemas/CampaignSummary'
1236
- pagination:
1237
- $ref: '#/components/schemas/Pagination'
1238
- meta:
1239
- $ref: '#/components/schemas/Meta'
1497
+ **Date range:** if you omit both dates, defaults to the last **90 days**
1498
+ ending today. Override with `startDate` / `endDate`. **Responses are
1499
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
1240
1500
 
1241
- CampaignDetailResponse:
1242
- type: object
1243
- required: [data, meta]
1244
- properties:
1245
- data:
1246
- $ref: '#/components/schemas/CampaignDetail'
1247
- meta:
1248
- $ref: '#/components/schemas/Meta'
1501
+ **Mutability window:** rows for a given `report_date` can be revised
1502
+ for up to 7 days after the date closes due to delayed Spotify
1503
+ playback events.
1249
1504
 
1250
- CampaignTier:
1251
- type: object
1252
- required: [tierId, tierName, isEnabled, allocationPercent]
1253
- properties:
1254
- tierId:
1255
- type: integer
1256
- description: Targeting tier identifier.
1257
- tierName:
1258
- type: string
1259
- description: Human-readable tier name.
1260
- isEnabled:
1261
- type: boolean
1262
- description: Whether this tier is currently active.
1263
- allocationPercent:
1264
- type: number
1265
- minimum: 0
1266
- maximum: 100
1267
- description: Share of campaign budget allocated to this tier.
1505
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1506
+ tags: [Soundlinks]
1507
+ security:
1508
+ - apiKeyBearerAuth: []
1509
+ - oauthBearer: []
1510
+ x-required-scope: soundlinks:read
1511
+ parameters:
1512
+ - $ref: '#/components/parameters/soundlinkId'
1513
+ - $ref: '#/components/parameters/startDate'
1514
+ - $ref: '#/components/parameters/endDate'
1515
+ - name: engagementContext
1516
+ in: query
1517
+ schema:
1518
+ type: string
1519
+ enum: [catalog, playlist]
1520
+ description: Filter to a single engagement context. Omit to return both.
1521
+ - $ref: '#/components/parameters/page'
1522
+ - $ref: '#/components/parameters/pageSize500'
1523
+ - name: sortBy
1524
+ in: query
1525
+ schema:
1526
+ type: string
1527
+ enum: [report_date]
1528
+ default: report_date
1529
+ - $ref: '#/components/parameters/sortOrder'
1530
+ responses:
1531
+ '200':
1532
+ description: Paginated engagement rows (`soundlink_engagement_daily` schema)
1533
+ content:
1534
+ application/json:
1535
+ schema:
1536
+ $ref: '#/components/schemas/SoundlinkEngagementResponse'
1537
+ example:
1538
+ data:
1539
+ schemaVersion: '1.0'
1540
+ items:
1541
+ - provider: soundlink
1542
+ account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
1543
+ schema_version: '1.0'
1544
+ report_date: '2026-08-01'
1545
+ report_date_timezone: UTC
1546
+ exported_at: '2026-08-28T03:00:00Z'
1547
+ soundlink_id: V1StGXR8_Z5jdHi6B-myT
1548
+ soundlink_name: Midnight Drive
1549
+ soundlink_target_type: track
1550
+ soundlink_target_isrc: DEXW62500259
1551
+ soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
1552
+ soundlink_target_playlist_id: null
1553
+ engagement_context: catalog
1554
+ country_code: US
1555
+ engaged_track_isrc: DEXW62500001
1556
+ engaged_spotify_track_id: 4cOdK2wGLETKBW3PvgPWqT
1557
+ engaged_track_name: Till The Sunrise
1558
+ playlist_position: null
1559
+ new_listeners: 42
1560
+ returning_listeners: 18
1561
+ listeners: 60
1562
+ new_listener_streams: 58
1563
+ returning_listener_streams: 31
1564
+ streams: 89
1565
+ spl: 1.48
1566
+ pagination:
1567
+ page: 1
1568
+ pageSize: 50
1569
+ totalCount: 120
1570
+ totalPages: 3
1571
+ meta:
1572
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1573
+ '400': { $ref: '#/components/responses/BadRequest' }
1574
+ '401': { $ref: '#/components/responses/Unauthorized' }
1575
+ '403': { $ref: '#/components/responses/Forbidden' }
1576
+ '404': { $ref: '#/components/responses/NotFound' }
1577
+ '429': { $ref: '#/components/responses/RateLimited' }
1578
+ '500': { $ref: '#/components/responses/InternalError' }
1268
1579
 
1269
- CampaignTiersData:
1270
- type: object
1271
- required: [lastUpdate, tiers]
1272
- properties:
1273
- lastUpdate:
1274
- type: string
1275
- format: date-time
1276
- nullable: true
1277
- description: |
1278
- ISO-8601 timestamp of the last manual tier status update, or null
1279
- if tiers have never been updated.
1280
- tiers:
1281
- type: array
1282
- items:
1283
- $ref: '#/components/schemas/CampaignTier'
1580
+ /v1/soundlinks/{soundlinkId}/metrics/engagement/export:
1581
+ get:
1582
+ operationId: exportSoundlinkEngagement
1583
+ summary: Soundlink engagement export (JSONL)
1584
+ description: |
1585
+ Streams the full engagement dataset for a soundlink as
1586
+ **newline-delimited JSON (JSONL)**. Every line is a complete, valid
1587
+ JSON object conforming to the `soundlink_engagement_daily` v1.0 schema
1588
+ — identical to the rows returned by `GET /metrics/engagement` but
1589
+ without pagination or an envelope wrapper.
1284
1590
 
1285
- CampaignTiersResponse:
1286
- type: object
1287
- required: [data, meta]
1288
- properties:
1289
- data:
1290
- $ref: '#/components/schemas/CampaignTiersData'
1291
- meta:
1292
- $ref: '#/components/schemas/Meta'
1591
+ Designed for data pipeline consumers: load directly into BigQuery,
1592
+ Snowflake, or any JSONL-aware ingest tool without cursor logic.
1293
1593
 
1294
- TierStatusUpdateItem:
1295
- type: object
1296
- required: [targetingTierId, isEnabled, newAllocationPercent]
1297
- properties:
1298
- targetingTierId:
1299
- type: integer
1300
- minimum: 1
1301
- description: Targeting tier identifier.
1302
- isEnabled:
1303
- type: boolean
1304
- description: Whether to enable or disable this tier.
1305
- newAllocationPercent:
1306
- type: number
1307
- minimum: 0
1308
- maximum: 100
1309
- description: New budget share for this tier (all items must sum to 100).
1594
+ **Usage:**
1595
+ ```
1596
+ GET /v1/soundlinks/{soundlinkId}/metrics/engagement/export
1597
+ Accept: application/x-ndjson
1598
+ ```
1310
1599
 
1311
- UpdateCampaignTiersRequest:
1312
- type: object
1313
- required: [items]
1314
- properties:
1315
- items:
1316
- type: array
1317
- minItems: 1
1318
- items:
1319
- $ref: '#/components/schemas/TierStatusUpdateItem'
1600
+ **Response body (one JSON object per line, no trailing comma):**
1601
+ ```
1602
+ {"provider":"soundlink","report_date":"2026-08-01","streams":89,...}
1603
+ {"provider":"soundlink","report_date":"2026-08-02","streams":104,...}
1604
+ ```
1320
1605
 
1321
- Genre:
1322
- type: string
1323
- description: Strictly validated against the platform's genre list.
1324
- enum:
1325
- - Alternative/Indie
1326
- - Ambient/Sleep
1327
- - Chill/Background
1328
- - Classical
1329
- - Country
1330
- - Electronic/Dance
1331
- - Hip-Hop/R&B
1332
- - Latin/Reggaeton
1333
- - Pop
1334
- - Rock
1335
- - Christmas
1606
+ **Date range:** if you omit both dates, defaults to the last **90 days**
1607
+ ending today. Override with `startDate` / `endDate`. **Responses are
1608
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
1609
+ Page longer histories in 90-day slices.
1336
1610
 
1337
- StrategyType:
1338
- type: string
1339
- enum:
1340
- - maximum_growth
1341
- - market_discovery
1342
- - revenue_maximization
1343
- - custom
1611
+ **Mutability:** rows for a given `report_date` can be revised for up to
1612
+ 7 days after the date closes. Re-fetching and re-ingesting on the
1613
+ primary key is safe (idempotent).
1344
1614
 
1345
- CreativeDirection:
1615
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1616
+ tags: [Soundlinks]
1617
+ security:
1618
+ - apiKeyBearerAuth: []
1619
+ - oauthBearer: []
1620
+ x-required-scope: soundlinks:read
1621
+ parameters:
1622
+ - $ref: '#/components/parameters/soundlinkId'
1623
+ - $ref: '#/components/parameters/startDate'
1624
+ - $ref: '#/components/parameters/endDate'
1625
+ - name: engagementContext
1626
+ in: query
1627
+ schema:
1628
+ type: string
1629
+ enum: [catalog, playlist]
1630
+ description: Filter to a single engagement context. Omit to return both.
1631
+ responses:
1632
+ '200':
1633
+ description: |
1634
+ JSONL stream. Each line is a `soundlink_engagement_daily` v1.0 row.
1635
+ Lines are sorted by `(report_date asc, engagement_context, country_code, engaged_spotify_track_id)`.
1636
+ headers:
1637
+ Content-Disposition:
1638
+ schema:
1639
+ type: string
1640
+ description: |
1641
+ `attachment; filename="engagement_{soundlinkId}_{startDate}_{endDate}.jsonl"`
1642
+ example: 'attachment; filename="engagement_V1StGXR8_Z5jdHi6B-myT_2026-08-01_2026-08-31.jsonl"'
1643
+ X-Row-Count:
1644
+ schema:
1645
+ type: integer
1646
+ description: Total number of rows in the response. Useful for progress tracking when streaming.
1647
+ content:
1648
+ application/x-ndjson:
1649
+ schema:
1650
+ $ref: '#/components/schemas/SoundlinkEngagementDailyRow'
1651
+ example: |
1652
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"engagement_context":"catalog","country_code":"US","engaged_track_isrc":"DEXW62500001","engaged_spotify_track_id":"4cOdK2wGLETKBW3PvgPWqT","engaged_track_name":"Till The Sunrise","playlist_position":null,"new_listeners":42,"returning_listeners":18,"listeners":60,"new_listener_streams":58,"returning_listener_streams":31,"streams":89,"spl":1.48}
1653
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"playlist","soundlink_target_isrc":null,"soundlink_target_spotify_track_id":null,"soundlink_target_playlist_id":"37i9dQZF1Epwit2GR54N9P","engagement_context":"playlist","country_code":"DE","engaged_track_isrc":"DEXW62500001","engaged_spotify_track_id":"4cOdK2wGLETKBW3PvgPWqT","engaged_track_name":"Till The Sunrise","playlist_position":14,"new_listeners":19,"returning_listeners":7,"listeners":26,"new_listener_streams":24,"returning_listener_streams":11,"streams":35,"spl":1.35}
1654
+ '400': { $ref: '#/components/responses/BadRequest' }
1655
+ '401': { $ref: '#/components/responses/Unauthorized' }
1656
+ '403': { $ref: '#/components/responses/Forbidden' }
1657
+ '404': { $ref: '#/components/responses/NotFound' }
1658
+ '429': { $ref: '#/components/responses/RateLimited' }
1659
+ '500': { $ref: '#/components/responses/InternalError' }
1660
+
1661
+ /v1/videos/import:
1662
+ post:
1663
+ operationId: importVideo
1664
+ summary: Import video(s) from public HTTPS MP4 URL(s)
1346
1665
  description: |
1347
- How the campaign's ad creative is produced. Omit entirely to use the
1348
- platform's default (`do_it_for_me`).
1349
- oneOf:
1350
- - $ref: '#/components/schemas/DoItForMeCreativeDirection'
1351
- - $ref: '#/components/schemas/FullControlCreativeDirection'
1352
- discriminator:
1353
- propertyName: type
1354
- mapping:
1355
- do_it_for_me: '#/components/schemas/DoItForMeCreativeDirection'
1356
- full_control: '#/components/schemas/FullControlCreativeDirection'
1666
+ Accepts a single `url` or a `videos` array (1–5 items). Creates one upload
1667
+ session, enqueues async download/staging, and returns `202` with `sessionId`.
1357
1668
 
1358
- DoItForMeCreativeDirection:
1359
- type: object
1360
- required: [type]
1361
- properties:
1362
- type:
1363
- type: string
1364
- enum: [do_it_for_me]
1365
- description: Soundlink selects and produces the ad creative.
1669
+ Requires the `videos:write` scope. Subject to a stricter per-credential rate
1670
+ limit than generic public API routes (default 20 imports per hour per API key
1671
+ or OAuth grant). This caps how many import requests are accepted per hour,
1672
+ not how long ingestion takes.
1366
1673
 
1367
- FullControlCreativeDirection:
1368
- type: object
1369
- required: [type, selectedCreatives]
1370
- properties:
1371
- type:
1372
- type: string
1373
- enum: [full_control]
1374
- selectedCreatives:
1375
- type: array
1376
- minItems: 1
1377
- items:
1378
- $ref: '#/components/schemas/SelectedCreative'
1379
- description: One or more previously imported video creatives to use for the ad. Required for full control.
1674
+ Poll `GET /v1/videos/import/{sessionId}` until `status` is `ready`, `partial`,
1675
+ or `failed`. For single-URL imports, use `videoId` when ready. For batches
1676
+ (`count > 1`), use `videoIds`.
1677
+ tags: [Videos]
1678
+ security:
1679
+ - apiKeyBearerAuth: []
1680
+ - oauthBearer: []
1681
+ x-required-scope: videos:write
1682
+ requestBody:
1683
+ required: true
1684
+ content:
1685
+ application/json:
1686
+ schema:
1687
+ $ref: '#/components/schemas/VideoImportRequest'
1688
+ examples:
1689
+ single:
1690
+ summary: Single URL (legacy)
1691
+ value:
1692
+ url: 'https://cdn.example.com/promo.mp4'
1693
+ batch:
1694
+ summary: Batch of URLs
1695
+ value:
1696
+ videos:
1697
+ - url: 'https://cdn.example.com/a.mp4'
1698
+ - url: 'https://cdn.example.com/b.mp4'
1699
+ responses:
1700
+ '200':
1701
+ description: Duplicate video already in the organization's library (sync legacy path only)
1702
+ content:
1703
+ application/json:
1704
+ schema:
1705
+ $ref: '#/components/schemas/VideoImportStartResponse'
1706
+ '202':
1707
+ description: Import accepted; ingestion in progress
1708
+ content:
1709
+ application/json:
1710
+ schema:
1711
+ $ref: '#/components/schemas/VideoImportStartResponse'
1712
+ '400': { $ref: '#/components/responses/BadRequest' }
1713
+ '401': { $ref: '#/components/responses/Unauthorized' }
1714
+ '403': { $ref: '#/components/responses/Forbidden' }
1715
+ '429': { $ref: '#/components/responses/RateLimited' }
1716
+ '500': { $ref: '#/components/responses/InternalError' }
1380
1717
 
1381
- SelectedCreative:
1382
- type: object
1383
- required: [videoId]
1384
- properties:
1385
- videoId:
1386
- type: string
1387
- format: uuid
1388
- description: |
1389
- ID of a video previously imported into your video library. Import
1390
- videos via the video import endpoint before referencing them here.
1718
+ /v1/videos/import/{sessionId}:
1719
+ get:
1720
+ operationId: getVideoImportStatus
1721
+ summary: Get video import session status
1722
+ description: |
1723
+ Returns processing status. For single-URL sessions, includes `videoId` when ready.
1724
+ For batch sessions (`count > 1`), includes `videoIds` and `counts`.
1725
+ Requires the `videos:write` scope.
1726
+ tags: [Videos]
1727
+ security:
1728
+ - apiKeyBearerAuth: []
1729
+ - oauthBearer: []
1730
+ x-required-scope: videos:write
1731
+ parameters:
1732
+ - name: sessionId
1733
+ in: path
1734
+ required: true
1735
+ schema:
1736
+ type: string
1737
+ format: uuid
1738
+ description: Upload session ID returned by `POST /v1/videos/import`
1739
+ responses:
1740
+ '200':
1741
+ description: Import session status
1742
+ content:
1743
+ application/json:
1744
+ schema:
1745
+ $ref: '#/components/schemas/VideoImportStatusResponse'
1746
+ '401': { $ref: '#/components/responses/Unauthorized' }
1747
+ '403': { $ref: '#/components/responses/Forbidden' }
1748
+ '404': { $ref: '#/components/responses/NotFound' }
1749
+ '429': { $ref: '#/components/responses/RateLimited' }
1750
+ '500': { $ref: '#/components/responses/InternalError' }
1391
1751
 
1392
- CustomTier:
1752
+ components:
1753
+ securitySchemes:
1754
+ apiKeyBearerAuth:
1755
+ type: http
1756
+ scheme: bearer
1757
+ description: |
1758
+ Pass your Soundlink `sk_*` API key as a Bearer token:
1759
+ `Authorization: Bearer sk_<prefix>_<token>` (not an OAuth token; see
1760
+ `oauthBearer` for that). Accepted on all Public API operations. Send
1761
+ only one `Authorization` header per request.
1762
+
1763
+ oauthBearer:
1764
+ type: http
1765
+ scheme: bearer
1766
+ bearerFormat: JWT
1767
+ description: |
1768
+ OAuth 2.0 access token from Sign in with Soundlink
1769
+ (`Authorization: Bearer <oauth_access_token>`).
1770
+ Token scopes must include the operation's required scope
1771
+ (see `x-required-scope` and the Authentication section).
1772
+ Accepted on all Public API operations (reads and writes).
1773
+
1774
+ parameters:
1775
+ campaignId:
1776
+ name: campaignId
1777
+ in: path
1778
+ required: true
1779
+ schema:
1780
+ type: string
1781
+ description: Campaign identifier (UUID)
1782
+
1783
+ idempotencyKey:
1784
+ name: Idempotency-Key
1785
+ in: header
1786
+ required: true
1787
+ schema:
1788
+ type: string
1789
+ minLength: 1
1790
+ maxLength: 255
1791
+ description: |
1792
+ A unique string identifying this request, used to safely retry write
1793
+ operations (create, stop, budget increase/decrease) without repeating
1794
+ side effects. Required on every request that references this parameter.
1795
+ Reusing this key with an unchanged request body replays the original
1796
+ response; reusing it with a different body returns
1797
+ `409 idempotency_key_conflict`. Keys are honored for 24 hours.
1798
+
1799
+ page:
1800
+ name: page
1801
+ in: query
1802
+ schema:
1803
+ type: integer
1804
+ minimum: 1
1805
+ default: 1
1806
+ description: Page number (1-indexed)
1807
+
1808
+ pageSize100:
1809
+ name: pageSize
1810
+ in: query
1811
+ schema:
1812
+ type: integer
1813
+ minimum: 1
1814
+ maximum: 100
1815
+ default: 10
1816
+ description: Items per page (max 100)
1817
+
1818
+ pageSize500:
1819
+ name: pageSize
1820
+ in: query
1821
+ schema:
1822
+ type: integer
1823
+ minimum: 1
1824
+ maximum: 500
1825
+ default: 50
1826
+ description: Rows per page (max 500; higher default than list endpoints)
1827
+
1828
+ sortOrder:
1829
+ name: sortOrder
1830
+ in: query
1831
+ schema:
1832
+ type: string
1833
+ enum: [asc, desc]
1834
+ default: desc
1835
+ description: Sort direction
1836
+
1837
+ startDate:
1838
+ name: startDate
1839
+ in: query
1840
+ schema:
1841
+ type: string
1842
+ format: date
1843
+ description: Inclusive start date (`YYYY-MM-DD`). Defaults to campaign start date.
1844
+
1845
+ endDate:
1846
+ name: endDate
1847
+ in: query
1848
+ schema:
1849
+ type: string
1850
+ format: date
1851
+ description: Inclusive end date (`YYYY-MM-DD`). Defaults to today.
1852
+
1853
+ soundlinkId:
1854
+ name: soundlinkId
1855
+ in: path
1856
+ required: true
1857
+ schema:
1858
+ type: string
1859
+ description: Soundlink identifier (URL-safe string, same ID used in the public sndl.ink URL)
1860
+
1861
+ soundlinkStartDate:
1862
+ name: startDate
1863
+ in: query
1864
+ schema:
1865
+ type: string
1866
+ format: date
1867
+ description: |
1868
+ Inclusive start date (`YYYY-MM-DD`) for soundlink overview and
1869
+ timeseries. Defaults to the soundlink creation date when omitted.
1870
+
1871
+ soundlinkEndDate:
1872
+ name: endDate
1873
+ in: query
1874
+ schema:
1875
+ type: string
1876
+ format: date
1877
+ description: Inclusive end date (`YYYY-MM-DD`). Defaults to today.
1878
+
1879
+ schemas:
1880
+ # --- Shared ---
1881
+
1882
+ Meta:
1393
1883
  type: object
1394
- required: [name, percentBudget]
1884
+ required: [requestId]
1395
1885
  properties:
1396
- name:
1397
- type: string
1398
- countries:
1399
- type: array
1400
- items:
1401
- type: string
1402
- description: ISO 3166-1 alpha-2 country codes.
1403
- language:
1886
+ requestId:
1404
1887
  type: string
1405
- description: ISO 639-1 language code.
1406
- percentBudget:
1407
- type: number
1408
- description: Share of the campaign budget allocated to this tier. All tiers in a request must sum to 100.
1888
+ format: uuid
1889
+ description: Server-generated request ID. Include when contacting support.
1409
1890
 
1410
- TierTargeting:
1891
+ Pagination:
1411
1892
  type: object
1412
- description: |
1413
- Custom tier targeting. Required when `strategyType` is `custom`: provide a
1414
- non-empty `customTierIds` and/or `customTiers` array. Omit entirely for
1415
- non-custom strategies (platform default tiering applies).
1893
+ required: [page, pageSize, totalCount, totalPages]
1416
1894
  properties:
1417
- customTierIds:
1418
- type: array
1419
- items:
1420
- type: integer
1421
- customTiers:
1422
- type: array
1423
- description: |
1424
- Inline custom tiers to create with the campaign. At most 5 active
1425
- tiers (percentBudget > 0) are allowed; inactive (0%) entries do not
1426
- count toward that limit. Each active tier must receive at least
1427
- $1.50 of dailyBudget (gross). percentBudget values must sum to 100.
1428
- items:
1429
- $ref: '#/components/schemas/CustomTier'
1895
+ page:
1896
+ type: integer
1897
+ pageSize:
1898
+ type: integer
1899
+ totalCount:
1900
+ type: integer
1901
+ totalPages:
1902
+ type: integer
1430
1903
 
1431
- CreateCampaignRequestShared:
1904
+ Error:
1432
1905
  type: object
1433
- required: [spotifyUrl, dailyBudget, durationDays, genre]
1906
+ required: [code, message]
1434
1907
  properties:
1435
- spotifyUrl:
1908
+ code:
1436
1909
  type: string
1437
- format: uri
1438
- description: |
1439
- Spotify track or playlist URL to promote. Must be a valid track or
1440
- playlist link to a resource that currently exists on Spotify.
1441
- dailyBudget:
1442
- type: number
1443
- minimum: 10
1444
- description: |
1445
- USD, per day. Must be at least 10 (same floor as the Soundlink UI).
1446
- durationDays:
1447
- description: |
1448
- Campaign duration in days. Must be an integer from 7 to 30 (UI custom
1449
- range), or 60, or 90 (UI dropdown extras).
1450
- oneOf:
1451
- - type: integer
1452
- minimum: 7
1453
- maximum: 30
1454
- - type: integer
1455
- enum: [60, 90]
1456
- genre:
1457
- $ref: '#/components/schemas/Genre'
1458
- campaignName:
1910
+ description: Stable snake_case error code.
1911
+ enum:
1912
+ - invalid_api_key
1913
+ - api_key_revoked
1914
+ - api_key_expired
1915
+ - insufficient_scope
1916
+ - not_found
1917
+ - campaign_not_found
1918
+ - invalid_query_parameter
1919
+ - invalid_date_range
1920
+ - page_size_exceeded
1921
+ - invalid_request
1922
+ - invalid_genre
1923
+ - invalid_duration_or_budget
1924
+ - invalid_daily_budget
1925
+ - invalid_duration_days
1926
+ - invalid_spotify_url
1927
+ - invalid_tier_budget_allocation
1928
+ - invalid_tier_status
1929
+ - tier_update_cooldown
1930
+ - wallet_not_enabled
1931
+ - insufficient_credit
1932
+ - idempotency_key_conflict
1933
+ - rate_limit_exceeded
1934
+ - invalid_video_url
1935
+ - video_import_limit_exceeded
1936
+ - video_import_session_not_found
1937
+ - internal_error
1938
+ message:
1459
1939
  type: string
1460
- description: Optional. Server generates a default (track title + short random suffix) when omitted.
1461
- creativeDirection:
1462
- $ref: '#/components/schemas/CreativeDirection'
1463
- trackOptions:
1940
+ description: Human-readable error description. Do not parse programmatically.
1941
+ details:
1464
1942
  type: object
1465
- description: Options that only apply when `spotifyUrl` is a track link. Ignored when `spotifyUrl` is a playlist link.
1466
- properties:
1467
- artistIdFollow:
1468
- type: string
1469
- description: Pass-through artist identifier.
1470
- clonedFromCampaignId:
1943
+ nullable: true
1944
+ description: |
1945
+ Additive, error-code-specific context (e.g. `available`/`required`
1946
+ on `insufficient_credit`). Absent or `null` for error codes that
1947
+ carry no extra data.
1948
+ additionalProperties: true
1949
+
1950
+ ErrorResponse:
1951
+ type: object
1952
+ required: [error, meta]
1953
+ properties:
1954
+ error:
1955
+ $ref: '#/components/schemas/Error'
1956
+ meta:
1957
+ $ref: '#/components/schemas/Meta'
1958
+
1959
+ # --- Campaign ---
1960
+
1961
+ CampaignStatus:
1962
+ type: string
1963
+ enum: [creating, active, paused, stopped, completed, failed, ended]
1964
+
1965
+ CampaignSummary:
1966
+ type: object
1967
+ required:
1968
+ [
1969
+ campaignId,
1970
+ organizationId,
1971
+ status,
1972
+ socialPlatform,
1973
+ dailyBudget,
1974
+ totalBudget,
1975
+ campaignDuration,
1976
+ generation,
1977
+ createdAt,
1978
+ updatedAt,
1979
+ ]
1980
+ properties:
1981
+ campaignId:
1471
1982
  type: string
1472
- format: uuid
1473
- description: >-
1474
- Optional UUID of a campaign in your organization this create is
1475
- cloned from. Records lineage only — it does not copy settings from
1476
- the source; all other create fields must still be provided. Unknown
1477
- or other-organization IDs return `400 invalid_request`.
1983
+ organizationId:
1984
+ type: string
1985
+ status:
1986
+ $ref: '#/components/schemas/CampaignStatus'
1987
+ socialPlatform:
1988
+ type: string
1989
+ enum: [meta]
1990
+ dailyBudget:
1991
+ type: number
1992
+ description: USD
1993
+ totalBudget:
1994
+ type: number
1995
+ description: USD
1996
+ campaignDuration:
1997
+ type: integer
1998
+ description: Duration in days
1999
+ generation:
2000
+ type: integer
2001
+ enum: [1, 2, 3]
2002
+ description: |
2003
+ Campaign resource generation. `1` = Stripe / one-time / subscription /
2004
+ legacy; `2` = Soundlink managed; `3` = wallet. Public API write
2005
+ operations (budget changes, stop, tier updates) are supported for
2006
+ generation `3` only.
2007
+ createdAt:
2008
+ type: string
2009
+ format: date-time
2010
+ updatedAt:
2011
+ type: string
2012
+ format: date-time
1478
2013
 
1479
- CreateCampaignRequestWithoutTiers:
2014
+ CampaignDetail:
1480
2015
  allOf:
1481
- - $ref: '#/components/schemas/CreateCampaignRequestShared'
2016
+ - $ref: '#/components/schemas/CampaignSummary'
1482
2017
  - type: object
1483
- required: [strategyType]
1484
2018
  properties:
1485
2019
  strategyType:
1486
2020
  type: string
1487
- enum:
1488
- - maximum_growth
1489
- - market_discovery
1490
- - revenue_maximization
1491
2021
  description: |
1492
- Non-custom growth strategy. Do not send `tierTargeting` with these
1493
- values; the platform applies default tiering.
1494
- not:
1495
- required: [tierTargeting]
2022
+ Growth strategy (e.g. `custom`, `maximum_growth`, `market_discovery`).
2023
+ Set at campaign creation.
1496
2024
 
1497
- CreateCampaignRequestCustom:
1498
- allOf:
1499
- - $ref: '#/components/schemas/CreateCampaignRequestShared'
1500
- - type: object
1501
- required: [strategyType, tierTargeting]
2025
+ CampaignListResponse:
2026
+ type: object
2027
+ required: [data, meta]
2028
+ properties:
2029
+ data:
2030
+ type: object
2031
+ required: [items, pagination]
1502
2032
  properties:
1503
- strategyType:
1504
- type: string
1505
- enum: [custom]
1506
- description: |
1507
- Custom growth strategy. Requires `tierTargeting` with a non-empty
1508
- `customTierIds` and/or `customTiers` array.
1509
- tierTargeting:
1510
- $ref: '#/components/schemas/TierTargeting'
2033
+ items:
2034
+ type: array
2035
+ items:
2036
+ $ref: '#/components/schemas/CampaignSummary'
2037
+ pagination:
2038
+ $ref: '#/components/schemas/Pagination'
2039
+ meta:
2040
+ $ref: '#/components/schemas/Meta'
1511
2041
 
1512
- CreateCampaignRequest:
1513
- description: |
1514
- Create a wallet-funded campaign. When `strategyType` is `custom`,
1515
- `tierTargeting` is required. For `maximum_growth`, `market_discovery`,
1516
- or `revenue_maximization`, do not send `tierTargeting` (platform default
1517
- tiering applies).
1518
- oneOf:
1519
- - $ref: '#/components/schemas/CreateCampaignRequestWithoutTiers'
1520
- - $ref: '#/components/schemas/CreateCampaignRequestCustom'
2042
+ CampaignDetailResponse:
2043
+ type: object
2044
+ required: [data, meta]
2045
+ properties:
2046
+ data:
2047
+ $ref: '#/components/schemas/CampaignDetail'
2048
+ meta:
2049
+ $ref: '#/components/schemas/Meta'
2050
+
2051
+ CampaignTier:
2052
+ type: object
2053
+ required: [tierId, tierName, isEnabled, allocationPercent]
2054
+ properties:
2055
+ tierId:
2056
+ type: integer
2057
+ description: Targeting tier identifier.
2058
+ tierName:
2059
+ type: string
2060
+ description: Human-readable tier name.
2061
+ isEnabled:
2062
+ type: boolean
2063
+ description: Whether this tier is currently active.
2064
+ allocationPercent:
2065
+ type: number
2066
+ minimum: 0
2067
+ maximum: 100
2068
+ description: Share of campaign budget allocated to this tier.
2069
+
2070
+ CampaignTiersData:
2071
+ type: object
2072
+ required: [lastUpdate, tiers]
2073
+ properties:
2074
+ lastUpdate:
2075
+ type: string
2076
+ format: date-time
2077
+ nullable: true
2078
+ description: |
2079
+ ISO-8601 timestamp of the last manual tier status update, or null
2080
+ if tiers have never been updated.
2081
+ tiers:
2082
+ type: array
2083
+ items:
2084
+ $ref: '#/components/schemas/CampaignTier'
2085
+
2086
+ CampaignTiersResponse:
2087
+ type: object
2088
+ required: [data, meta]
2089
+ properties:
2090
+ data:
2091
+ $ref: '#/components/schemas/CampaignTiersData'
2092
+ meta:
2093
+ $ref: '#/components/schemas/Meta'
2094
+
2095
+ TierStatusUpdateItem:
2096
+ type: object
2097
+ required: [targetingTierId, isEnabled, newAllocationPercent]
2098
+ properties:
2099
+ targetingTierId:
2100
+ type: integer
2101
+ minimum: 1
2102
+ description: Targeting tier identifier.
2103
+ isEnabled:
2104
+ type: boolean
2105
+ description: Whether to enable or disable this tier.
2106
+ newAllocationPercent:
2107
+ type: number
2108
+ minimum: 0
2109
+ maximum: 100
2110
+ description: New budget share for this tier (all items must sum to 100).
2111
+
2112
+ UpdateCampaignTiersRequest:
2113
+ type: object
2114
+ required: [items]
2115
+ properties:
2116
+ items:
2117
+ type: array
2118
+ minItems: 1
2119
+ items:
2120
+ $ref: '#/components/schemas/TierStatusUpdateItem'
2121
+
2122
+ Genre:
2123
+ type: string
2124
+ description: Strictly validated against the platform's genre list.
2125
+ enum:
2126
+ - Alternative/Indie
2127
+ - Ambient/Sleep
2128
+ - Chill/Background
2129
+ - Classical
2130
+ - Country
2131
+ - Electronic/Dance
2132
+ - Hip-Hop/R&B
2133
+ - Latin/Reggaeton
2134
+ - Pop
2135
+ - Rock
2136
+ - Christmas
2137
+
2138
+ StrategyType:
2139
+ type: string
2140
+ enum:
2141
+ - maximum_growth
2142
+ - market_discovery
2143
+ - revenue_maximization
2144
+ - custom
2145
+
2146
+ CreativeDirection:
2147
+ description: |
2148
+ How the campaign's ad creative is produced. Omit entirely to use the
2149
+ platform's default (`do_it_for_me`).
2150
+ oneOf:
2151
+ - $ref: '#/components/schemas/DoItForMeCreativeDirection'
2152
+ - $ref: '#/components/schemas/FullControlCreativeDirection'
2153
+ discriminator:
2154
+ propertyName: type
2155
+ mapping:
2156
+ do_it_for_me: '#/components/schemas/DoItForMeCreativeDirection'
2157
+ full_control: '#/components/schemas/FullControlCreativeDirection'
2158
+
2159
+ DoItForMeCreativeDirection:
2160
+ type: object
2161
+ required: [type]
2162
+ properties:
2163
+ type:
2164
+ type: string
2165
+ enum: [do_it_for_me]
2166
+ description: Soundlink selects and produces the ad creative.
2167
+
2168
+ FullControlCreativeDirection:
2169
+ type: object
2170
+ required: [type, selectedCreatives]
2171
+ properties:
2172
+ type:
2173
+ type: string
2174
+ enum: [full_control]
2175
+ selectedCreatives:
2176
+ type: array
2177
+ minItems: 1
2178
+ items:
2179
+ $ref: '#/components/schemas/SelectedCreative'
2180
+ description: One or more previously imported video creatives to use for the ad. Required for full control.
2181
+
2182
+ SelectedCreative:
2183
+ type: object
2184
+ required: [videoId]
2185
+ properties:
2186
+ videoId:
2187
+ type: string
2188
+ format: uuid
2189
+ description: |
2190
+ ID of a video previously imported into your video library. Import
2191
+ videos via the video import endpoint before referencing them here.
2192
+
2193
+ CustomTier:
2194
+ type: object
2195
+ required: [name, percentBudget]
2196
+ properties:
2197
+ name:
2198
+ type: string
2199
+ countries:
2200
+ type: array
2201
+ items:
2202
+ type: string
2203
+ description: ISO 3166-1 alpha-2 country codes.
2204
+ language:
2205
+ type: string
2206
+ description: ISO 639-1 language code.
2207
+ percentBudget:
2208
+ type: number
2209
+ description: Share of the campaign budget allocated to this tier. All tiers in a request must sum to 100.
2210
+
2211
+ TierTargeting:
2212
+ type: object
2213
+ description: |
2214
+ Custom tier targeting. Required when `strategyType` is `custom`: provide a
2215
+ non-empty `customTierIds` and/or `customTiers` array. Omit entirely for
2216
+ non-custom strategies (platform default tiering applies).
2217
+ properties:
2218
+ customTierIds:
2219
+ type: array
2220
+ items:
2221
+ type: integer
2222
+ customTiers:
2223
+ type: array
2224
+ description: |
2225
+ Inline custom tiers to create with the campaign. At most 5 active
2226
+ tiers (percentBudget > 0) are allowed; inactive (0%) entries do not
2227
+ count toward that limit. Each active tier must receive at least
2228
+ $1.50 of dailyBudget (gross). percentBudget values must sum to 100.
2229
+ items:
2230
+ $ref: '#/components/schemas/CustomTier'
2231
+
2232
+ CreateCampaignRequestShared:
2233
+ type: object
2234
+ required: [spotifyUrl, dailyBudget, durationDays, genre]
2235
+ properties:
2236
+ spotifyUrl:
2237
+ type: string
2238
+ format: uri
2239
+ description: |
2240
+ Spotify track or playlist URL to promote. Must be a valid track or
2241
+ playlist link to a resource that currently exists on Spotify.
2242
+ dailyBudget:
2243
+ type: number
2244
+ minimum: 10
2245
+ description: |
2246
+ USD, per day. Must be at least 10 (same floor as the Soundlink UI).
2247
+ durationDays:
2248
+ description: |
2249
+ Campaign duration in days. Must be an integer from 7 to 30 (UI custom
2250
+ range), or 60, or 90 (UI dropdown extras).
2251
+ oneOf:
2252
+ - type: integer
2253
+ minimum: 7
2254
+ maximum: 30
2255
+ - type: integer
2256
+ enum: [60, 90]
2257
+ genre:
2258
+ $ref: '#/components/schemas/Genre'
2259
+ campaignName:
2260
+ type: string
2261
+ description: Optional. Server generates a default (track title + short random suffix) when omitted.
2262
+ creativeDirection:
2263
+ $ref: '#/components/schemas/CreativeDirection'
2264
+ trackOptions:
2265
+ type: object
2266
+ description: Options that only apply when `spotifyUrl` is a track link. Ignored when `spotifyUrl` is a playlist link.
2267
+ properties:
2268
+ artistIdFollow:
2269
+ type: string
2270
+ description: Pass-through artist identifier.
2271
+ clonedFromCampaignId:
2272
+ type: string
2273
+ format: uuid
2274
+ description: >-
2275
+ Optional UUID of a campaign in your organization this create is
2276
+ cloned from. Records lineage only — it does not copy settings from
2277
+ the source; all other create fields must still be provided. Unknown
2278
+ or other-organization IDs return `400 invalid_request`.
2279
+
2280
+ CreateCampaignRequestWithoutTiers:
2281
+ allOf:
2282
+ - $ref: '#/components/schemas/CreateCampaignRequestShared'
2283
+ - type: object
2284
+ required: [strategyType]
2285
+ properties:
2286
+ strategyType:
2287
+ type: string
2288
+ enum:
2289
+ - maximum_growth
2290
+ - market_discovery
2291
+ - revenue_maximization
2292
+ description: |
2293
+ Non-custom growth strategy. Do not send `tierTargeting` with these
2294
+ values; the platform applies default tiering.
2295
+ not:
2296
+ required: [tierTargeting]
2297
+
2298
+ CreateCampaignRequestCustom:
2299
+ allOf:
2300
+ - $ref: '#/components/schemas/CreateCampaignRequestShared'
2301
+ - type: object
2302
+ required: [strategyType, tierTargeting]
2303
+ properties:
2304
+ strategyType:
2305
+ type: string
2306
+ enum: [custom]
2307
+ description: |
2308
+ Custom growth strategy. Requires `tierTargeting` with a non-empty
2309
+ `customTierIds` and/or `customTiers` array.
2310
+ tierTargeting:
2311
+ $ref: '#/components/schemas/TierTargeting'
2312
+
2313
+ CreateCampaignRequest:
2314
+ description: |
2315
+ Create a wallet-funded campaign. When `strategyType` is `custom`,
2316
+ `tierTargeting` is required. For `maximum_growth`, `market_discovery`,
2317
+ or `revenue_maximization`, do not send `tierTargeting` (platform default
2318
+ tiering applies).
2319
+ oneOf:
2320
+ - $ref: '#/components/schemas/CreateCampaignRequestWithoutTiers'
2321
+ - $ref: '#/components/schemas/CreateCampaignRequestCustom'
2322
+
2323
+ CampaignCreateData:
2324
+ type: object
2325
+ required: [campaignId, status]
2326
+ properties:
2327
+ campaignId:
2328
+ type: string
2329
+ status:
2330
+ $ref: '#/components/schemas/CampaignStatus'
2331
+
2332
+ CreateCampaignResponse:
2333
+ type: object
2334
+ required: [data, meta]
2335
+ properties:
2336
+ data:
2337
+ $ref: '#/components/schemas/CampaignCreateData'
2338
+ meta:
2339
+ $ref: '#/components/schemas/Meta'
2340
+
2341
+ CampaignStopData:
2342
+ type: object
2343
+ required: [campaignId, status]
2344
+ properties:
2345
+ campaignId:
2346
+ type: string
2347
+ status:
2348
+ $ref: '#/components/schemas/CampaignStatus'
2349
+ description: Campaign status after stop (typically `stopped`).
2350
+
2351
+ StopCampaignResponse:
2352
+ type: object
2353
+ required: [data, meta]
2354
+ properties:
2355
+ data:
2356
+ $ref: '#/components/schemas/CampaignStopData'
2357
+ meta:
2358
+ $ref: '#/components/schemas/Meta'
2359
+
2360
+ StrategyCatalogItem:
2361
+ type: object
2362
+ required: [strategyType, tierTargetingAllowed]
2363
+ properties:
2364
+ strategyType:
2365
+ $ref: '#/components/schemas/StrategyType'
2366
+ tierTargetingAllowed:
2367
+ type: boolean
2368
+ description: |
2369
+ When `false`, omit `tierTargeting` on create (platform default
2370
+ tiering applies). Only `custom` allows `tierTargeting`.
2371
+
2372
+ StrategiesCatalogData:
2373
+ type: object
2374
+ required: [strategies]
2375
+ properties:
2376
+ strategies:
2377
+ type: array
2378
+ items:
2379
+ $ref: '#/components/schemas/StrategyCatalogItem'
2380
+
2381
+ StrategiesCatalogResponse:
2382
+ type: object
2383
+ required: [data, meta]
2384
+ properties:
2385
+ data:
2386
+ $ref: '#/components/schemas/StrategiesCatalogData'
2387
+ meta:
2388
+ $ref: '#/components/schemas/Meta'
2389
+
2390
+ BudgetIncreaseMode:
2391
+ type: string
2392
+ enum: [current_cycle, next_renewal, current_and_renewals]
2393
+ description: |
2394
+ Defaults to `current_and_renewals` when omitted on increase requests.
2395
+
2396
+ BudgetDecreaseMode:
2397
+ type: string
2398
+ enum: [current_cycle, current_and_renewals]
2399
+ description: |
2400
+ Defaults to `current_and_renewals` when omitted on decrease requests.
2401
+ `next_renewal` is not supported for decreases.
2402
+
2403
+ IncreaseCampaignBudgetRequest:
2404
+ type: object
2405
+ required: [amount]
2406
+ properties:
2407
+ amount:
2408
+ type: number
2409
+ description: |
2410
+ Wallet debit / top-up amount in USD. Must be positive, except
2411
+ `mode: next_renewal` with `targetDailyBudget` where `amount` may
2412
+ be `0`.
2413
+ mode:
2414
+ $ref: '#/components/schemas/BudgetIncreaseMode'
2415
+ targetDailyBudget:
2416
+ type: number
2417
+ minimum: 0
2418
+ exclusiveMinimum: true
2419
+ description: |
2420
+ Optional absolute next-cycle daily budget (USD). Most useful with
2421
+ `mode: next_renewal`.
2422
+
2423
+ IncreaseCampaignBudgetData:
2424
+ type: object
2425
+ required: [campaignId, mode, amount, walletBalance]
2426
+ properties:
2427
+ campaignId:
2428
+ type: string
2429
+ mode:
2430
+ $ref: '#/components/schemas/BudgetIncreaseMode'
2431
+ amount:
2432
+ type: number
2433
+ walletBalance:
2434
+ type: number
2435
+ description: Organization wallet balance after the increase.
2436
+ walletNextCycleDailyBudget:
2437
+ type: number
2438
+ nullable: true
2439
+ description: Next-cycle daily budget when set by this request.
2440
+
2441
+ IncreaseCampaignBudgetResponse:
2442
+ type: object
2443
+ required: [data, meta]
2444
+ properties:
2445
+ data:
2446
+ $ref: '#/components/schemas/IncreaseCampaignBudgetData'
2447
+ meta:
2448
+ $ref: '#/components/schemas/Meta'
2449
+
2450
+ DecreaseCampaignBudgetRequest:
2451
+ type: object
2452
+ required: [targetDailyBudget]
2453
+ properties:
2454
+ targetDailyBudget:
2455
+ type: number
2456
+ minimum: 10
2457
+ description: |
2458
+ New daily budget in USD (gross). Must be at least `$10`/day and
2459
+ lower than the campaign's current daily budget.
2460
+ mode:
2461
+ $ref: '#/components/schemas/BudgetDecreaseMode'
2462
+
2463
+ DecreaseCampaignBudgetData:
2464
+ type: object
2465
+ required: [campaignId, mode, targetDailyBudget, accepted]
2466
+ properties:
2467
+ campaignId:
2468
+ type: string
2469
+ mode:
2470
+ $ref: '#/components/schemas/BudgetDecreaseMode'
2471
+ targetDailyBudget:
2472
+ type: number
2473
+ accepted:
2474
+ type: boolean
2475
+ enum: [true]
2476
+ description: |
2477
+ Always `true` on success. Unused budget refund is applied
2478
+ asynchronously after acceptance.
2479
+ walletNextCycleDailyBudget:
2480
+ type: number
2481
+ nullable: true
2482
+ description: |
2483
+ Present for `current_and_renewals` when the next-cycle daily
2484
+ budget was updated. Omitted for `current_cycle`.
2485
+
2486
+ DecreaseCampaignBudgetResponse:
2487
+ type: object
2488
+ required: [data, meta]
2489
+ properties:
2490
+ data:
2491
+ $ref: '#/components/schemas/DecreaseCampaignBudgetData'
2492
+ meta:
2493
+ $ref: '#/components/schemas/Meta'
2494
+
2495
+ # --- Metrics ---
2496
+
2497
+ MetricsOverview:
2498
+ type: object
2499
+ description: |
2500
+ Campaign-level totals aggregated across all countries for the requested
2501
+ date range. Field names align with the `campaign_country_daily` row
2502
+ schema — values here are the sum of country rows.
2503
+ required:
2504
+ [
2505
+ listeners,
2506
+ streams,
2507
+ followers,
2508
+ spend_media,
2509
+ spend_total,
2510
+ fees,
2511
+ currency,
2512
+ cpl,
2513
+ cpf,
2514
+ streams_per_listener,
2515
+ ]
2516
+ properties:
2517
+ listeners:
2518
+ type: integer
2519
+ description: Unique attributed Spotify listeners (sum of country rows).
2520
+ streams:
2521
+ type: integer
2522
+ description: Attributed Spotify streams (sum of country rows).
2523
+ followers:
2524
+ type: integer
2525
+ description: Attributed artist follower gains (sum of country rows).
2526
+ impressions:
2527
+ type: integer
2528
+ nullable: true
2529
+ description: Total Meta ad impressions. Null if not available.
2530
+ ad_clicks:
2531
+ type: integer
2532
+ nullable: true
2533
+ description: Total Meta ad clicks (all click types).
2534
+ link_clicks:
2535
+ type: integer
2536
+ nullable: true
2537
+ description: Outbound clicks to Spotify via the Soundlink landing page.
2538
+ spend_media:
2539
+ type: number
2540
+ description: Amount billed to Meta for ad delivery. Excludes Soundlink fees. USD.
2541
+ spend_total:
2542
+ type: number
2543
+ description: Total billed by Soundlink (spend_media + fees). USD.
2544
+ fees:
2545
+ type: number
2546
+ description: Soundlink service fee (spend_total - spend_media). USD.
2547
+ currency:
2548
+ type: string
2549
+ description: Currency for spend fields. Currently always `USD`.
2550
+ cpl:
2551
+ type: number
2552
+ description: Cost per listener (spend_media / listeners).
2553
+ cpf:
2554
+ type: number
2555
+ description: Cost per follower (spend_media / followers).
2556
+ streams_per_listener:
2557
+ type: number
2558
+ description: streams / listeners. Zero if listeners is zero.
2559
+
2560
+ MetricsOverviewResponse:
2561
+ type: object
2562
+ required: [data, meta]
2563
+ properties:
2564
+ data:
2565
+ $ref: '#/components/schemas/MetricsOverview'
2566
+ meta:
2567
+ $ref: '#/components/schemas/Meta'
2568
+
2569
+ BreakdownRow:
2570
+ type: object
2571
+ description: |
2572
+ One row of the `campaign_country_daily` v1.0 schema.
2573
+ Primary key: `(provider, account_id, report_date, campaign_id, country_code)`.
2574
+ Rows are idempotent — re-ingesting on the primary key is safe.
2575
+ Values for a given `report_date` may be revised for up to 7 days after
2576
+ the date closes due to delayed events from Meta and Spotify.
2577
+ required:
2578
+ - provider
2579
+ - account_id
2580
+ - schema_version
2581
+ - report_date
2582
+ - report_date_timezone
2583
+ - exported_at
2584
+ - campaign_id
2585
+ - campaign_name
2586
+ - campaign_target_type
2587
+ - country_code
2588
+ - streams
2589
+ - listeners
2590
+ - followers
2591
+ - streams_per_listener
2592
+ - spend_media
2593
+ - spend_total
2594
+ - fees
2595
+ - currency
2596
+ - currency_account
2597
+ - cpl
2598
+ - cpf
2599
+ - cost_per_result
2600
+ properties:
2601
+ provider:
2602
+ type: string
2603
+ enum: [soundlink]
2604
+ description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
2605
+ account_id:
2606
+ type: string
2607
+ description: Soundlink organization ID (UUID).
2608
+ schema_version:
2609
+ type: string
2610
+ description: Schema version. Pin your ingest pipeline to this value.
2611
+ example: '1.0'
2612
+ report_date:
2613
+ type: string
2614
+ format: date
2615
+ description: UTC calendar date the metrics belong to (`YYYY-MM-DD`).
2616
+ report_date_timezone:
2617
+ type: string
2618
+ enum: [UTC]
2619
+ description: Always `UTC`.
2620
+ exported_at:
2621
+ type: string
2622
+ format: date-time
2623
+ description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
2624
+ campaign_id:
2625
+ type: string
2626
+ description: Soundlink campaign UUID. Stable for the lifetime of the campaign.
2627
+ campaign_name:
2628
+ type: string
2629
+ description: Human-readable campaign name.
2630
+ campaign_target_type:
2631
+ type: string
2632
+ nullable: true
2633
+ enum: [track, playlist]
2634
+ description: Whether this campaign promotes a track or playlist. `null` if undetermined.
2635
+ campaign_target_isrc:
2636
+ type: string
2637
+ nullable: true
2638
+ description: ISRC of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
2639
+ campaign_target_spotify_track_id:
2640
+ type: string
2641
+ nullable: true
2642
+ description: Spotify track ID of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
2643
+ campaign_target_playlist_id:
2644
+ type: string
2645
+ nullable: true
2646
+ description: Spotify playlist ID. Populated when `campaign_target_type = playlist`; otherwise `null`.
2647
+ country_code:
2648
+ type: string
2649
+ description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
2650
+ impressions:
2651
+ type: integer
2652
+ nullable: true
2653
+ description: Total Meta ad impressions served in this country on this day.
2654
+ ad_clicks:
2655
+ type: integer
2656
+ nullable: true
2657
+ description: Total clicks on the Meta ad (all click types). Use `ctr_adclick` for ad-level CTR.
2658
+ link_clicks:
2659
+ type: integer
2660
+ nullable: true
2661
+ description: Clicks on "Continue with Spotify" on the Soundlink landing page. Use `cpc_linkclick` / `ctr_linkclick` for outbound CPC/CTR.
2662
+ streams:
2663
+ type: integer
2664
+ description: Spotify streams attributed to this campaign in this country on this day (7-day click-through window). Observed events, not modelled estimates.
2665
+ listeners:
2666
+ type: integer
2667
+ description: Unique Spotify listeners attributed to this campaign in this country on this day (7-day click-through window). Summing country rows gives the correct campaign-level total.
2668
+ followers:
2669
+ type: integer
2670
+ description: Spotify artist follower gains attributed to this campaign in this country on this day (7-day click-through window).
2671
+ streams_per_listener:
2672
+ type: number
2673
+ description: streams / listeners for this row. Zero if listeners is zero.
2674
+ spend_media:
2675
+ type: number
2676
+ description: Amount billed to Meta for ad delivery in this country on this day. Excludes Soundlink service fees. In `currency`.
2677
+ spend_total:
2678
+ type: number
2679
+ description: Total billed by Soundlink (spend_media + fees). Computed as `spend_media / (1 - fee_pct)`.
2680
+ fees:
2681
+ type: number
2682
+ description: Soundlink service fee (spend_total - spend_media).
2683
+ currency:
2684
+ type: string
2685
+ description: Currency for spend fields. Currently always `USD`.
2686
+ currency_account:
2687
+ type: string
2688
+ description: Account billing currency. Currently always `USD`. Will differ from `currency` once EUR delivery is available.
2689
+ cpl:
2690
+ type: number
2691
+ description: Cost per listener (spend_media / listeners). Zero if listeners is zero.
2692
+ cpf:
2693
+ type: number
2694
+ description: Cost per follower (spend_media / followers). Zero if followers is zero.
2695
+ cpc_linkclick:
2696
+ type: number
2697
+ nullable: true
2698
+ description: Cost per outbound click (spend_media / link_clicks). Null if link_clicks is null or zero.
2699
+ ctr_linkclick:
2700
+ type: number
2701
+ nullable: true
2702
+ description: Outbound CTR (link_clicks / impressions). Null if impressions is null or zero.
2703
+ ctr_adclick:
2704
+ type: number
2705
+ nullable: true
2706
+ description: Meta ad CTR (ad_clicks / impressions). Null if impressions is null or zero.
2707
+ cost_per_result:
2708
+ type: number
2709
+ description: Cost per primary campaign result. Currently equivalent to `cpf` (cost per follower). See `result_type`.
2710
+ result_type:
2711
+ type: string
2712
+ nullable: true
2713
+ enum: [lp_click, stream, follow]
2714
+ description: The conversion event used for `cost_per_result`. Currently always `follow`.
2715
+
2716
+ MetricsBreakdownResponse:
2717
+ type: object
2718
+ required: [data, meta]
2719
+ properties:
2720
+ data:
2721
+ type: object
2722
+ required: [schemaVersion, items, pagination]
2723
+ properties:
2724
+ schemaVersion:
2725
+ type: string
2726
+ description: Version of the `campaign_country_daily` row schema. Pin your ingest pipeline to this.
2727
+ example: '1.0'
2728
+ items:
2729
+ type: array
2730
+ items:
2731
+ $ref: '#/components/schemas/BreakdownRow'
2732
+ pagination:
2733
+ $ref: '#/components/schemas/Pagination'
2734
+ meta:
2735
+ $ref: '#/components/schemas/Meta'
2736
+
2737
+ MetricsEngagementResponse:
2738
+ type: object
2739
+ required: [data, meta]
2740
+ properties:
2741
+ data:
2742
+ type: object
2743
+ required: [schemaVersion, items, pagination]
2744
+ properties:
2745
+ schemaVersion:
2746
+ type: string
2747
+ description: Version of the `campaign_engagement_daily` row schema. Pin your ingest pipeline to this.
2748
+ example: '1.0'
2749
+ items:
2750
+ type: array
2751
+ items:
2752
+ $ref: '#/components/schemas/EngagementRow'
2753
+ pagination:
2754
+ $ref: '#/components/schemas/Pagination'
2755
+ meta:
2756
+ $ref: '#/components/schemas/Meta'
2757
+
2758
+ # --- Engagement ---
2759
+
2760
+ EngagementRow:
2761
+ type: object
2762
+ description: |
2763
+ One row of the `campaign_engagement_daily` v1.0 schema.
2764
+ Primary key: `(provider, account_id, report_date, campaign_id, engagement_context, country_code, engaged_spotify_track_id)`.
2765
+ Rows are idempotent — re-ingesting on the primary key is safe.
2766
+ Values for a given `report_date` may be revised for up to 7 days after
2767
+ the date closes due to delayed Spotify playback events.
2768
+ required:
2769
+ - provider
2770
+ - account_id
2771
+ - schema_version
2772
+ - report_date
2773
+ - report_date_timezone
2774
+ - exported_at
2775
+ - campaign_id
2776
+ - campaign_name
2777
+ - campaign_target_type
2778
+ - status
2779
+ - engagement_context
2780
+ - country_code
2781
+ - engaged_spotify_track_id
2782
+ - engaged_track_name
2783
+ - new_listeners
2784
+ - returning_listeners
2785
+ - listeners
2786
+ - new_listener_streams
2787
+ - returning_listener_streams
2788
+ - streams
2789
+ - spl
2790
+ properties:
2791
+ provider:
2792
+ type: string
2793
+ enum: [soundlink]
2794
+ description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
2795
+ account_id:
2796
+ type: string
2797
+ description: Soundlink organization ID (UUID).
2798
+ schema_version:
2799
+ type: string
2800
+ description: Schema version string. Pin your ingest pipeline to this value.
2801
+ example: '1.0'
2802
+ report_date:
2803
+ type: string
2804
+ format: date
2805
+ description: UTC calendar date the metrics belong to (`YYYY-MM-DD`). Rows can change for up to 7 days after close.
2806
+ report_date_timezone:
2807
+ type: string
2808
+ enum: [UTC]
2809
+ description: Always `UTC`.
2810
+ exported_at:
2811
+ type: string
2812
+ format: date-time
2813
+ description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
2814
+ campaign_id:
2815
+ type: string
2816
+ description: Soundlink campaign UUID. Stable for the lifetime of the campaign.
2817
+ campaign_name:
2818
+ type: string
2819
+ description: Human-readable campaign name.
2820
+ campaign_target_type:
2821
+ type: string
2822
+ nullable: true
2823
+ enum: [track, playlist]
2824
+ description: Whether this campaign promotes a track or a playlist. `null` if undetermined.
2825
+ campaign_target_isrc:
2826
+ type: string
2827
+ nullable: true
2828
+ description: ISRC of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
2829
+ campaign_target_spotify_track_id:
2830
+ type: string
2831
+ nullable: true
2832
+ description: Spotify track ID of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
2833
+ campaign_target_playlist_id:
2834
+ type: string
2835
+ nullable: true
2836
+ description: Spotify playlist ID. Populated when `campaign_target_type = playlist`; otherwise `null`.
2837
+ status:
2838
+ type: string
2839
+ enum: [active, ended, scheduled]
2840
+ description: |
2841
+ Campaign lifecycle status on `report_date`.
2842
+ `active` = campaign was running; `ended` = campaign had ended or was refunded;
2843
+ `scheduled` = `report_date` is before campaign start.
2844
+ Post-campaign rows will have `status = ended`.
2845
+ engagement_context:
2846
+ type: string
2847
+ enum: [catalog, playlist]
2848
+ description: |
2849
+ Which dashboard section the row maps to.
2850
+ `catalog` = same-artist spillover (and direct promoted-track plays) on track campaigns.
2851
+ `playlist` = per-track performance inside the promoted playlist on playlist campaigns.
2852
+ country_code:
2853
+ type: string
2854
+ description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
2855
+ example: US
2856
+ engaged_track_isrc:
2857
+ type: string
2858
+ nullable: true
2859
+ description: |
2860
+ ISRC of the track that received listens. May differ from `campaign_target_isrc`
2861
+ for catalog spillover rows. `null` if ISRC could not be resolved.
2862
+ engaged_spotify_track_id:
2863
+ type: string
2864
+ description: |
2865
+ Stable track identifier used in the primary key. Currently this is the
2866
+ Spotify track ID for the engaged track.
2867
+ example: 4cOdK2wGLETKBW3PvgPWqT
2868
+ engaged_track_name:
2869
+ type: string
2870
+ description: Display name of the engaged track.
2871
+ playlist_position:
2872
+ type: integer
2873
+ nullable: true
2874
+ minimum: 1
2875
+ description: |
2876
+ 1-based slot of the engaged track on the promoted playlist for `report_date` (1 = top).
2877
+ Populated only when `engagement_context = playlist` and that day's playlist crawl listed the track.
2878
+ `null` for catalog rows; before the day's crawl completes (current UTC day is often null until later morning UTC);
2879
+ when the track was not listed or could not be matched to that day's crawl; or while historical backfill is still catching up.
2880
+ Field is beta until historical backfill finishes. Treat `null` as unavailable — not an error.
2881
+ new_listeners:
2882
+ type: integer
2883
+ minimum: 0
2884
+ description: Unique listeners whose first play of this track on this smart link occurred on `report_date`.
2885
+ returning_listeners:
2886
+ type: integer
2887
+ minimum: 0
2888
+ description: Unique listeners who played this track on `report_date` but whose first play was on an earlier date.
2889
+ listeners:
2890
+ type: integer
2891
+ minimum: 0
2892
+ description: |
2893
+ Total unique listeners on `report_date`: `new_listeners + returning_listeners`.
2894
+ **Do not sum across days** — the same listener can appear on multiple `report_date` rows.
2895
+ new_listener_streams:
2896
+ type: integer
2897
+ minimum: 0
2898
+ description: Stream count from new listeners on `report_date`.
2899
+ returning_listener_streams:
2900
+ type: integer
2901
+ minimum: 0
2902
+ description: Stream count from returning listeners on `report_date`.
2903
+ streams:
2904
+ type: integer
2905
+ minimum: 0
2906
+ description: |
2907
+ Total streams on `report_date`: `new_listener_streams + returning_listener_streams`.
2908
+ Safe to sum within a day; summing across days counts repeat listens.
2909
+ spl:
2910
+ type: number
2911
+ description: Streams per listener (`streams / listeners`). Zero if `listeners` is zero.
1521
2912
 
1522
- CampaignCreateData:
1523
- type: object
1524
- required: [campaignId, status]
1525
- properties:
1526
- campaignId:
1527
- type: string
1528
- status:
1529
- $ref: '#/components/schemas/CampaignStatus'
2913
+ # --- Soundlinks ---
1530
2914
 
1531
- CreateCampaignResponse:
1532
- type: object
1533
- required: [data, meta]
1534
- properties:
1535
- data:
1536
- $ref: '#/components/schemas/CampaignCreateData'
1537
- meta:
1538
- $ref: '#/components/schemas/Meta'
2915
+ SoundlinkStatus:
2916
+ type: string
2917
+ enum: [draft, active, archived]
1539
2918
 
1540
- CampaignStopData:
2919
+ SoundlinkSummary:
1541
2920
  type: object
1542
- required: [campaignId, status]
2921
+ required: [soundlinkId, organizationId, name, url, targetType, status, createdAt]
1543
2922
  properties:
1544
- campaignId:
2923
+ soundlinkId:
2924
+ type: string
2925
+ description: |
2926
+ Unique ID of this soundlink (URL-safe string, same ID used in the
2927
+ public sndl.ink URL).
2928
+ example: V1StGXR8_Z5jdHi6B-myT
2929
+ organizationId:
2930
+ type: string
2931
+ description: Soundlink organization ID (UUID).
2932
+ name:
2933
+ type: string
2934
+ description: Human-readable soundlink name.
2935
+ url:
2936
+ type: string
2937
+ format: uri
2938
+ description: Public soundlink landing page URL.
2939
+ example: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
2940
+ targetType:
2941
+ type: string
2942
+ nullable: true
2943
+ enum: [track, album, playlist]
2944
+ description: |
2945
+ Type of Spotify resource this soundlink promotes. `null` if the
2946
+ target could not be determined.
2947
+ spotifyUrl:
1545
2948
  type: string
2949
+ format: uri
2950
+ nullable: true
2951
+ description: Spotify URL of the promoted resource.
1546
2952
  status:
1547
- $ref: '#/components/schemas/CampaignStatus'
1548
- description: Campaign status after stop (typically `stopped`).
2953
+ $ref: '#/components/schemas/SoundlinkStatus'
2954
+ createdAt:
2955
+ type: string
2956
+ format: date-time
1549
2957
 
1550
- StopCampaignResponse:
2958
+ SoundlinkListResponse:
1551
2959
  type: object
1552
2960
  required: [data, meta]
1553
2961
  properties:
1554
2962
  data:
1555
- $ref: '#/components/schemas/CampaignStopData'
2963
+ type: object
2964
+ required: [items, pagination]
2965
+ properties:
2966
+ items:
2967
+ type: array
2968
+ items:
2969
+ $ref: '#/components/schemas/SoundlinkSummary'
2970
+ pagination:
2971
+ $ref: '#/components/schemas/Pagination'
1556
2972
  meta:
1557
2973
  $ref: '#/components/schemas/Meta'
1558
2974
 
1559
- StrategyCatalogItem:
1560
- type: object
1561
- required: [strategyType, tierTargetingAllowed]
1562
- properties:
1563
- strategyType:
1564
- $ref: '#/components/schemas/StrategyType'
1565
- tierTargetingAllowed:
1566
- type: boolean
1567
- description: |
1568
- When `false`, omit `tierTargeting` on create (platform default
1569
- tiering applies). Only `custom` allows `tierTargeting`.
1570
-
1571
- StrategiesCatalogData:
1572
- type: object
1573
- required: [strategies]
1574
- properties:
1575
- strategies:
1576
- type: array
1577
- items:
1578
- $ref: '#/components/schemas/StrategyCatalogItem'
2975
+ SoundlinkDetail:
2976
+ allOf:
2977
+ - $ref: '#/components/schemas/SoundlinkSummary'
2978
+ - type: object
2979
+ required: [autoFollow, metaPixelId, tiktokPixelId]
2980
+ properties:
2981
+ autoFollow:
2982
+ type: boolean
2983
+ description: |
2984
+ Whether auto-follow is configured for this soundlink. Whether
2985
+ it takes effect also depends on the organization's plan.
2986
+ metaPixelId:
2987
+ type: string
2988
+ nullable: true
2989
+ description: Meta pixel ID configured on this soundlink. `null` if not set.
2990
+ tiktokPixelId:
2991
+ type: string
2992
+ nullable: true
2993
+ description: TikTok pixel ID configured on this soundlink. `null` if not set.
1579
2994
 
1580
- StrategiesCatalogResponse:
2995
+ SoundlinkDetailResponse:
1581
2996
  type: object
1582
2997
  required: [data, meta]
1583
2998
  properties:
1584
2999
  data:
1585
- $ref: '#/components/schemas/StrategiesCatalogData'
3000
+ $ref: '#/components/schemas/SoundlinkDetail'
1586
3001
  meta:
1587
3002
  $ref: '#/components/schemas/Meta'
1588
3003
 
1589
- BudgetIncreaseMode:
1590
- type: string
1591
- enum: [current_cycle, next_renewal, current_and_renewals]
1592
- description: |
1593
- Defaults to `current_and_renewals` when omitted on increase requests.
1594
-
1595
- BudgetDecreaseMode:
1596
- type: string
1597
- enum: [current_cycle, current_and_renewals]
1598
- description: |
1599
- Defaults to `current_and_renewals` when omitted on decrease requests.
1600
- `next_renewal` is not supported for decreases.
1601
-
1602
- IncreaseCampaignBudgetRequest:
1603
- type: object
1604
- required: [amount]
1605
- properties:
1606
- amount:
1607
- type: number
1608
- description: |
1609
- Wallet debit / top-up amount in USD. Must be positive, except
1610
- `mode: next_renewal` with `targetDailyBudget` where `amount` may
1611
- be `0`.
1612
- mode:
1613
- $ref: '#/components/schemas/BudgetIncreaseMode'
1614
- targetDailyBudget:
1615
- type: number
1616
- minimum: 0
1617
- exclusiveMinimum: true
1618
- description: |
1619
- Optional absolute next-cycle daily budget (USD). Most useful with
1620
- `mode: next_renewal`.
1621
-
1622
- IncreaseCampaignBudgetData:
3004
+ SoundlinkMetricsOverview:
1623
3005
  type: object
1624
- required: [campaignId, mode, amount, walletBalance]
3006
+ description: |
3007
+ Soundlink-level totals for the requested date range. Additive fields
3008
+ are sums of `api_smart_link_country_daily` country-day rows.
3009
+ required: [views, streams, listeners, followers, streams_per_listener]
1625
3010
  properties:
1626
- campaignId:
1627
- type: string
1628
- mode:
1629
- $ref: '#/components/schemas/BudgetIncreaseMode'
1630
- amount:
1631
- type: number
1632
- walletBalance:
1633
- type: number
1634
- description: Organization wallet balance after the increase.
1635
- walletNextCycleDailyBudget:
1636
- type: number
3011
+ views:
3012
+ type: integer
3013
+ description: Soundlink landing page views in the period (sum of country-day rows).
3014
+ link_clicks:
3015
+ type: integer
1637
3016
  nullable: true
1638
- description: Next-cycle daily budget when set by this request.
1639
-
1640
- IncreaseCampaignBudgetResponse:
1641
- type: object
1642
- required: [data, meta]
1643
- properties:
1644
- data:
1645
- $ref: '#/components/schemas/IncreaseCampaignBudgetData'
1646
- meta:
1647
- $ref: '#/components/schemas/Meta'
1648
-
1649
- DecreaseCampaignBudgetRequest:
1650
- type: object
1651
- required: [targetDailyBudget]
1652
- properties:
1653
- targetDailyBudget:
1654
- type: number
1655
- minimum: 10
1656
3017
  description: |
1657
- New daily budget in USD (gross). Must be at least `$10`/day and
1658
- lower than the campaign's current daily budget.
1659
- mode:
1660
- $ref: '#/components/schemas/BudgetDecreaseMode'
1661
-
1662
- DecreaseCampaignBudgetData:
1663
- type: object
1664
- required: [campaignId, mode, targetDailyBudget, accepted]
1665
- properties:
1666
- campaignId:
1667
- type: string
1668
- mode:
1669
- $ref: '#/components/schemas/BudgetDecreaseMode'
1670
- targetDailyBudget:
1671
- type: number
1672
- accepted:
1673
- type: boolean
1674
- enum: [true]
3018
+ Clicks on "Continue with Spotify" on the landing page — outbound
3019
+ clicks to Spotify. Null if not tracked for this soundlink type.
3020
+ streams:
3021
+ type: integer
3022
+ description: Attributed Spotify streams (sum of country-day rows).
3023
+ listeners:
3024
+ type: integer
1675
3025
  description: |
1676
- Always `true` on success. Unused budget refund is applied
1677
- asynchronously after acceptance.
1678
- walletNextCycleDailyBudget:
3026
+ Sum of country-day `new_listeners` from the mart (first-play
3027
+ attributed listeners). Not period-unique across days/countries,
3028
+ and not equal to summing breakdown `listeners` (new + returning).
3029
+ followers:
3030
+ type: integer
3031
+ description: Attributed Spotify artist follower gains in the period.
3032
+ streams_per_listener:
3033
+ type: number
3034
+ description: streams / listeners. Zero if listeners is zero.
3035
+ ctr_lp:
1679
3036
  type: number
1680
3037
  nullable: true
1681
3038
  description: |
1682
- Present for `current_and_renewals` when the next-cycle daily
1683
- budget was updated. Omitted for `current_cycle`.
3039
+ Landing page click-through rate (link_clicks / views). Computed
3040
+ against landing page views, not ad impressions — do not combine
3041
+ with `ctr_linkclick` from campaign metrics. Null if views is zero
3042
+ or link_clicks is null.
1684
3043
 
1685
- DecreaseCampaignBudgetResponse:
3044
+ SoundlinkMetricsOverviewResponse:
1686
3045
  type: object
1687
3046
  required: [data, meta]
1688
3047
  properties:
1689
3048
  data:
1690
- $ref: '#/components/schemas/DecreaseCampaignBudgetData'
3049
+ $ref: '#/components/schemas/SoundlinkMetricsOverview'
1691
3050
  meta:
1692
3051
  $ref: '#/components/schemas/Meta'
1693
3052
 
1694
- # --- Metrics ---
1695
-
1696
- MetricsOverview:
3053
+ SoundlinkDailyRow:
1697
3054
  type: object
1698
3055
  description: |
1699
- Campaign-level totals aggregated across all countries for the requested
1700
- date range. Field names align with the `campaign_country_daily` row
1701
- schema — values here are the sum of country rows.
3056
+ One row of the `soundlink_daily` v1.0 schema.
3057
+ Primary key: `(provider, account_id, report_date, soundlink_id)`.
3058
+ Rows are idempotent — re-ingesting on the primary key is safe.
3059
+ Values for a given `report_date` may be revised for up to 7 days after
3060
+ the date closes due to delayed Spotify playback events.
3061
+ Rows are aggregated across countries (no `country_code` in v1.0) and
3062
+ contain no financial fields.
1702
3063
  required:
1703
- [
1704
- listeners,
1705
- streams,
1706
- followers,
1707
- spend_media,
1708
- spend_total,
1709
- fees,
1710
- currency,
1711
- cpl,
1712
- cpf,
1713
- streams_per_listener,
1714
- ]
3064
+ - provider
3065
+ - account_id
3066
+ - schema_version
3067
+ - report_date
3068
+ - report_date_timezone
3069
+ - exported_at
3070
+ - soundlink_id
3071
+ - soundlink_name
3072
+ - soundlink_target_type
3073
+ - views
3074
+ - streams
3075
+ - listeners
3076
+ - followers
3077
+ - streams_per_listener
1715
3078
  properties:
1716
- listeners:
3079
+ provider:
3080
+ type: string
3081
+ enum: [soundlink]
3082
+ description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
3083
+ account_id:
3084
+ type: string
3085
+ description: Soundlink organization ID (UUID).
3086
+ schema_version:
3087
+ type: string
3088
+ description: Schema version. Pin your ingest pipeline to this value.
3089
+ example: '1.0'
3090
+ report_date:
3091
+ type: string
3092
+ format: date
3093
+ description: UTC calendar date the metrics belong to (`YYYY-MM-DD`).
3094
+ report_date_timezone:
3095
+ type: string
3096
+ enum: [UTC]
3097
+ description: Always `UTC`.
3098
+ exported_at:
3099
+ type: string
3100
+ format: date-time
3101
+ description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
3102
+ soundlink_id:
3103
+ type: string
3104
+ description: Unique ID of this soundlink.
3105
+ example: V1StGXR8_Z5jdHi6B-myT
3106
+ soundlink_name:
3107
+ type: string
3108
+ description: Human-readable soundlink name.
3109
+ soundlink_target_type:
3110
+ type: string
3111
+ nullable: true
3112
+ enum: [track, playlist]
3113
+ description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
3114
+ soundlink_target_isrc:
3115
+ type: string
3116
+ nullable: true
3117
+ description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
3118
+ soundlink_target_spotify_track_id:
3119
+ type: string
3120
+ nullable: true
3121
+ description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
3122
+ soundlink_target_playlist_id:
3123
+ type: string
3124
+ nullable: true
3125
+ description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
3126
+ views:
1717
3127
  type: integer
1718
- description: Unique attributed Spotify listeners (sum of country rows).
3128
+ description: Soundlink landing page views on this day.
3129
+ link_clicks:
3130
+ type: integer
3131
+ nullable: true
3132
+ description: |
3133
+ Clicks on "Continue with Spotify" on the landing page — outbound
3134
+ clicks to Spotify. Null if not tracked for this soundlink type.
1719
3135
  streams:
1720
3136
  type: integer
1721
- description: Attributed Spotify streams (sum of country rows).
1722
- followers:
3137
+ description: |
3138
+ Spotify streams attributed to this soundlink on this day:
3139
+ `new_listener_streams + returning_listener_streams`. Observed
3140
+ Spotify-side events, not modelled estimates. Safe to sum within a
3141
+ day; summing across days counts repeat listens.
3142
+ listeners:
3143
+ type: integer
3144
+ description: |
3145
+ Unique Spotify listeners attributed to this soundlink on this day:
3146
+ `new_listeners + returning_listeners`. **Do not sum across days** —
3147
+ the same listener can appear on multiple `report_date` rows.
3148
+ new_listeners:
1723
3149
  type: integer
1724
- description: Attributed artist follower gains (sum of country rows).
1725
- impressions:
3150
+ nullable: true
3151
+ description: Unique listeners whose first play via this soundlink occurred on `report_date`.
3152
+ returning_listeners:
1726
3153
  type: integer
1727
3154
  nullable: true
1728
- description: Total Meta ad impressions. Null if not available.
1729
- ad_clicks:
3155
+ description: Unique listeners who played on `report_date` but whose first play was on an earlier date.
3156
+ new_listener_streams:
1730
3157
  type: integer
1731
3158
  nullable: true
1732
- description: Total Meta ad clicks (all click types).
1733
- link_clicks:
3159
+ description: Stream count from new listeners on `report_date`.
3160
+ returning_listener_streams:
1734
3161
  type: integer
1735
3162
  nullable: true
1736
- description: Outbound clicks to Spotify via the Soundlink landing page.
1737
- spend_media:
1738
- type: number
1739
- description: Amount billed to Meta for ad delivery. Excludes Soundlink fees. USD.
1740
- spend_total:
1741
- type: number
1742
- description: Total billed by Soundlink (spend_media + fees). USD.
1743
- fees:
1744
- type: number
1745
- description: Soundlink service fee (spend_total - spend_media). USD.
1746
- currency:
1747
- type: string
1748
- description: Currency for spend fields. Currently always `USD`.
1749
- cpl:
1750
- type: number
1751
- description: Cost per listener (spend_media / listeners).
1752
- cpf:
1753
- type: number
1754
- description: Cost per follower (spend_media / followers).
3163
+ description: Stream count from returning listeners on `report_date`.
3164
+ followers:
3165
+ type: integer
3166
+ description: Spotify artist follower gains attributed to this soundlink on this day.
1755
3167
  streams_per_listener:
1756
3168
  type: number
1757
- description: streams / listeners. Zero if listeners is zero.
3169
+ description: streams / listeners for this row. Zero if listeners is zero.
3170
+ ctr_lp:
3171
+ type: number
3172
+ nullable: true
3173
+ description: |
3174
+ Landing page click-through rate (link_clicks / views). Computed
3175
+ against landing page views, not ad impressions — do not combine
3176
+ with `ctr_linkclick` from `campaign_country_daily`. Null if views
3177
+ is zero or link_clicks is null.
1758
3178
 
1759
- MetricsOverviewResponse:
3179
+ SoundlinkTimeseriesResponse:
1760
3180
  type: object
1761
3181
  required: [data, meta]
1762
3182
  properties:
1763
3183
  data:
1764
- $ref: '#/components/schemas/MetricsOverview'
3184
+ type: object
3185
+ required: [schemaVersion, items, pagination]
3186
+ properties:
3187
+ schemaVersion:
3188
+ type: string
3189
+ description: Version of the `soundlink_daily` row schema. Pin your ingest pipeline to this.
3190
+ example: '1.0'
3191
+ items:
3192
+ type: array
3193
+ items:
3194
+ $ref: '#/components/schemas/SoundlinkDailyRow'
3195
+ pagination:
3196
+ $ref: '#/components/schemas/Pagination'
1765
3197
  meta:
1766
3198
  $ref: '#/components/schemas/Meta'
1767
3199
 
1768
- BreakdownRow:
3200
+ SoundlinkCountryDailyRow:
1769
3201
  type: object
1770
3202
  description: |
1771
- One row of the `campaign_country_daily` v1.0 schema.
1772
- Primary key: `(provider, account_id, report_date, campaign_id, country_code)`.
3203
+ One row of the `soundlink_country_daily` v1.0 schema.
3204
+ Primary key: `(provider, account_id, report_date, soundlink_id, country_code)`.
1773
3205
  Rows are idempotent — re-ingesting on the primary key is safe.
1774
3206
  Values for a given `report_date` may be revised for up to 7 days after
1775
- the date closes due to delayed events from Meta and Spotify.
3207
+ the date closes due to delayed Spotify playback events.
3208
+ Rows contain no financial fields.
1776
3209
  required:
1777
3210
  - provider
1778
3211
  - account_id
@@ -1780,22 +3213,15 @@ components:
1780
3213
  - report_date
1781
3214
  - report_date_timezone
1782
3215
  - exported_at
1783
- - campaign_id
1784
- - campaign_name
1785
- - campaign_target_type
3216
+ - soundlink_id
3217
+ - soundlink_name
3218
+ - soundlink_target_type
1786
3219
  - country_code
3220
+ - views
1787
3221
  - streams
1788
3222
  - listeners
1789
3223
  - followers
1790
3224
  - streams_per_listener
1791
- - spend_media
1792
- - spend_total
1793
- - fees
1794
- - currency
1795
- - currency_account
1796
- - cpl
1797
- - cpf
1798
- - cost_per_result
1799
3225
  properties:
1800
3226
  provider:
1801
3227
  type: string
@@ -1820,99 +3246,88 @@ components:
1820
3246
  type: string
1821
3247
  format: date-time
1822
3248
  description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
1823
- campaign_id:
3249
+ soundlink_id:
1824
3250
  type: string
1825
- description: Soundlink campaign UUID. Stable for the lifetime of the campaign.
1826
- campaign_name:
3251
+ description: Unique ID of this soundlink.
3252
+ example: V1StGXR8_Z5jdHi6B-myT
3253
+ soundlink_name:
1827
3254
  type: string
1828
- description: Human-readable campaign name.
1829
- campaign_target_type:
3255
+ description: Human-readable soundlink name.
3256
+ soundlink_target_type:
1830
3257
  type: string
1831
3258
  nullable: true
1832
3259
  enum: [track, playlist]
1833
- description: Whether this campaign promotes a track or playlist. `null` if undetermined.
1834
- campaign_target_isrc:
3260
+ description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
3261
+ soundlink_target_isrc:
1835
3262
  type: string
1836
3263
  nullable: true
1837
- description: ISRC of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
1838
- campaign_target_spotify_track_id:
3264
+ description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
3265
+ soundlink_target_spotify_track_id:
1839
3266
  type: string
1840
3267
  nullable: true
1841
- description: Spotify track ID of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
1842
- campaign_target_playlist_id:
3268
+ description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
3269
+ soundlink_target_playlist_id:
1843
3270
  type: string
1844
3271
  nullable: true
1845
- description: Spotify playlist ID. Populated when `campaign_target_type = playlist`; otherwise `null`.
3272
+ description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
1846
3273
  country_code:
1847
3274
  type: string
1848
3275
  description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
1849
- impressions:
1850
- type: integer
1851
- nullable: true
1852
- description: Total Meta ad impressions served in this country on this day.
1853
- ad_clicks:
3276
+ views:
1854
3277
  type: integer
1855
- nullable: true
1856
- description: Total clicks on the Meta ad (all click types). Use `ctr_adclick` for ad-level CTR.
3278
+ description: Soundlink landing page views in this country on this day.
1857
3279
  link_clicks:
1858
3280
  type: integer
1859
3281
  nullable: true
1860
- description: Clicks on "Continue with Spotify" on the Soundlink landing page. Use `cpc_linkclick` / `ctr_linkclick` for outbound CPC/CTR.
3282
+ description: |
3283
+ Clicks on "Continue with Spotify" on the landing page — outbound
3284
+ clicks to Spotify. Null if not tracked for this soundlink type.
1861
3285
  streams:
1862
3286
  type: integer
1863
- description: Spotify streams attributed to this campaign in this country on this day (7-day click-through window). Observed events, not modelled estimates.
3287
+ description: |
3288
+ Spotify streams attributed to this soundlink in this country on this
3289
+ day: `new_listener_streams + returning_listener_streams`. Observed
3290
+ Spotify-side events, not modelled estimates. Safe to sum within a
3291
+ day; summing across days counts repeat listens.
1864
3292
  listeners:
1865
3293
  type: integer
1866
- description: Unique Spotify listeners attributed to this campaign in this country on this day (7-day click-through window). Summing country rows gives the correct campaign-level total.
3294
+ description: |
3295
+ Unique Spotify listeners attributed to this soundlink in this
3296
+ country on this day: `new_listeners + returning_listeners`.
3297
+ **Do not sum across days** — the same listener can appear on
3298
+ multiple `report_date` rows.
3299
+ new_listeners:
3300
+ type: integer
3301
+ nullable: true
3302
+ description: Unique listeners whose first play via this soundlink occurred on `report_date` in this country.
3303
+ returning_listeners:
3304
+ type: integer
3305
+ nullable: true
3306
+ description: Unique listeners who played on `report_date` in this country but whose first play was on an earlier date.
3307
+ new_listener_streams:
3308
+ type: integer
3309
+ nullable: true
3310
+ description: Stream count from new listeners on `report_date` in this country.
3311
+ returning_listener_streams:
3312
+ type: integer
3313
+ nullable: true
3314
+ description: Stream count from returning listeners on `report_date` in this country.
1867
3315
  followers:
1868
3316
  type: integer
1869
- description: Spotify artist follower gains attributed to this campaign in this country on this day (7-day click-through window).
3317
+ description: Spotify artist follower gains attributed to this soundlink in this country on this day.
1870
3318
  streams_per_listener:
1871
3319
  type: number
1872
3320
  description: streams / listeners for this row. Zero if listeners is zero.
1873
- spend_media:
1874
- type: number
1875
- description: Amount billed to Meta for ad delivery in this country on this day. Excludes Soundlink service fees. In `currency`.
1876
- spend_total:
1877
- type: number
1878
- description: Total billed by Soundlink (spend_media + fees). Computed as `spend_media / (1 - fee_pct)`.
1879
- fees:
1880
- type: number
1881
- description: Soundlink service fee (spend_total - spend_media).
1882
- currency:
1883
- type: string
1884
- description: Currency for spend fields. Currently always `USD`.
1885
- currency_account:
1886
- type: string
1887
- description: Account billing currency. Currently always `USD`. Will differ from `currency` once EUR delivery is available.
1888
- cpl:
1889
- type: number
1890
- description: Cost per listener (spend_media / listeners). Zero if listeners is zero.
1891
- cpf:
3321
+ ctr_lp:
1892
3322
  type: number
1893
- description: Cost per follower (spend_media / followers). Zero if followers is zero.
1894
- cpc_linkclick:
1895
- type: number
1896
- nullable: true
1897
- description: Cost per outbound click (spend_media / link_clicks). Null if link_clicks is null or zero.
1898
- ctr_linkclick:
1899
- type: number
1900
- nullable: true
1901
- description: Outbound CTR (link_clicks / impressions). Null if impressions is null or zero.
1902
- ctr_adclick:
1903
- type: number
1904
- nullable: true
1905
- description: Meta ad CTR (ad_clicks / impressions). Null if impressions is null or zero.
1906
- cost_per_result:
1907
- type: number
1908
- description: Cost per primary campaign result. Currently equivalent to `cpf` (cost per follower). See `result_type`.
1909
- result_type:
1910
- type: string
1911
3323
  nullable: true
1912
- enum: [lp_click, stream, follow]
1913
- description: The conversion event used for `cost_per_result`. Currently always `follow`.
3324
+ description: |
3325
+ Landing page click-through rate (link_clicks / views). Computed
3326
+ against landing page views, not ad impressions — do not combine
3327
+ with `ctr_linkclick` from `campaign_country_daily`. Null if views
3328
+ is zero or link_clicks is null.
1914
3329
 
1915
- MetricsBreakdownResponse:
3330
+ SoundlinkBreakdownResponse:
1916
3331
  type: object
1917
3332
  required: [data, meta]
1918
3333
  properties:
@@ -1922,27 +3337,48 @@ components:
1922
3337
  properties:
1923
3338
  schemaVersion:
1924
3339
  type: string
1925
- description: Version of the `campaign_country_daily` row schema. Pin your ingest pipeline to this.
3340
+ description: Version of the `soundlink_country_daily` row schema. Pin your ingest pipeline to this.
1926
3341
  example: '1.0'
1927
3342
  items:
1928
3343
  type: array
1929
3344
  items:
1930
- $ref: '#/components/schemas/BreakdownRow'
3345
+ $ref: '#/components/schemas/SoundlinkCountryDailyRow'
1931
3346
  pagination:
1932
3347
  $ref: '#/components/schemas/Pagination'
1933
3348
  meta:
1934
3349
  $ref: '#/components/schemas/Meta'
1935
3350
 
1936
- # --- Engagement ---
3351
+ SoundlinkEngagementResponse:
3352
+ type: object
3353
+ required: [data, meta]
3354
+ properties:
3355
+ data:
3356
+ type: object
3357
+ required: [schemaVersion, items, pagination]
3358
+ properties:
3359
+ schemaVersion:
3360
+ type: string
3361
+ description: Version of the `soundlink_engagement_daily` row schema. Pin your ingest pipeline to this.
3362
+ example: '1.0'
3363
+ items:
3364
+ type: array
3365
+ items:
3366
+ $ref: '#/components/schemas/SoundlinkEngagementDailyRow'
3367
+ pagination:
3368
+ $ref: '#/components/schemas/Pagination'
3369
+ meta:
3370
+ $ref: '#/components/schemas/Meta'
1937
3371
 
1938
- EngagementRow:
3372
+ SoundlinkEngagementDailyRow:
1939
3373
  type: object
1940
3374
  description: |
1941
- One row of the `campaign_engagement_daily` v1.0 schema.
1942
- Primary key: `(provider, account_id, report_date, campaign_id, engagement_context, country_code, engaged_spotify_track_id)`.
3375
+ One row of the `soundlink_engagement_daily` v1.0 schema.
3376
+ Primary key: `(provider, account_id, report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id)`.
1943
3377
  Rows are idempotent — re-ingesting on the primary key is safe.
1944
3378
  Values for a given `report_date` may be revised for up to 7 days after
1945
3379
  the date closes due to delayed Spotify playback events.
3380
+ No `status` field: soundlinks do not store per-day lifecycle history.
3381
+ No financial fields.
1946
3382
  required:
1947
3383
  - provider
1948
3384
  - account_id
@@ -1950,10 +3386,9 @@ components:
1950
3386
  - report_date
1951
3387
  - report_date_timezone
1952
3388
  - exported_at
1953
- - campaign_id
1954
- - campaign_name
1955
- - campaign_target_type
1956
- - status
3389
+ - soundlink_id
3390
+ - soundlink_name
3391
+ - soundlink_target_type
1957
3392
  - engagement_context
1958
3393
  - country_code
1959
3394
  - engaged_spotify_track_id
@@ -1989,44 +3424,37 @@ components:
1989
3424
  type: string
1990
3425
  format: date-time
1991
3426
  description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
1992
- campaign_id:
3427
+ soundlink_id:
1993
3428
  type: string
1994
- description: Soundlink campaign UUID. Stable for the lifetime of the campaign.
1995
- campaign_name:
3429
+ description: Unique ID of this soundlink.
3430
+ example: V1StGXR8_Z5jdHi6B-myT
3431
+ soundlink_name:
1996
3432
  type: string
1997
- description: Human-readable campaign name.
1998
- campaign_target_type:
3433
+ description: Human-readable soundlink name.
3434
+ soundlink_target_type:
1999
3435
  type: string
2000
3436
  nullable: true
2001
3437
  enum: [track, playlist]
2002
- description: Whether this campaign promotes a track or a playlist. `null` if undetermined.
2003
- campaign_target_isrc:
3438
+ description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
3439
+ soundlink_target_isrc:
2004
3440
  type: string
2005
3441
  nullable: true
2006
- description: ISRC of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
2007
- campaign_target_spotify_track_id:
3442
+ description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
3443
+ soundlink_target_spotify_track_id:
2008
3444
  type: string
2009
3445
  nullable: true
2010
- description: Spotify track ID of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
2011
- campaign_target_playlist_id:
3446
+ description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
3447
+ soundlink_target_playlist_id:
2012
3448
  type: string
2013
3449
  nullable: true
2014
- description: Spotify playlist ID. Populated when `campaign_target_type = playlist`; otherwise `null`.
2015
- status:
2016
- type: string
2017
- enum: [active, ended, scheduled]
2018
- description: |
2019
- Campaign lifecycle status on `report_date`.
2020
- `active` = campaign was running; `ended` = campaign had ended or was refunded;
2021
- `scheduled` = `report_date` is before campaign start.
2022
- Post-campaign rows will have `status = ended`.
3450
+ description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
2023
3451
  engagement_context:
2024
3452
  type: string
2025
3453
  enum: [catalog, playlist]
2026
3454
  description: |
2027
- Which dashboard section the row maps to.
2028
- `catalog` = same-artist spillover (and direct promoted-track plays) on track campaigns.
2029
- `playlist` = per-track performance inside the promoted playlist on playlist campaigns.
3455
+ Which section this row belongs to.
3456
+ `catalog`: plays of the promoted track and same-artist catalog tracks (track soundlinks).
3457
+ `playlist`: per-track performance inside the promoted playlist (playlist soundlinks).
2030
3458
  country_code:
2031
3459
  type: string
2032
3460
  description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
@@ -2035,13 +3463,11 @@ components:
2035
3463
  type: string
2036
3464
  nullable: true
2037
3465
  description: |
2038
- ISRC of the track that received listens. May differ from `campaign_target_isrc`
3466
+ ISRC of the track that received listens. May differ from `soundlink_target_isrc`
2039
3467
  for catalog spillover rows. `null` if ISRC could not be resolved.
2040
3468
  engaged_spotify_track_id:
2041
3469
  type: string
2042
- description: |
2043
- Stable track identifier used in the primary key. Currently this is the
2044
- Spotify track ID for the engaged track.
3470
+ description: Spotify track ID of the engaged track. Part of the primary key.
2045
3471
  example: 4cOdK2wGLETKBW3PvgPWqT
2046
3472
  engaged_track_name:
2047
3473
  type: string
@@ -2052,14 +3478,11 @@ components:
2052
3478
  minimum: 1
2053
3479
  description: |
2054
3480
  1-based slot of the engaged track on the promoted playlist for `report_date` (1 = top).
2055
- Populated only when `engagement_context = playlist` and that day's playlist crawl listed the track.
2056
- `null` for catalog rows; before the day's crawl completes (current UTC day is often null until later morning UTC);
2057
- when the track was not listed or could not be matched to that day's crawl; or while historical backfill is still catching up.
2058
- Field is beta until historical backfill finishes. Treat `null` as unavailable — not an error.
3481
+ Populated only when `engagement_context = playlist`. Treat `null` as unavailable, not an error.
2059
3482
  new_listeners:
2060
3483
  type: integer
2061
3484
  minimum: 0
2062
- description: Unique listeners whose first play of this track on this smart link occurred on `report_date`.
3485
+ description: Unique listeners whose first play of this track via this soundlink occurred on `report_date`.
2063
3486
  returning_listeners:
2064
3487
  type: integer
2065
3488
  minimum: 0
@@ -2092,16 +3515,44 @@ components:
2092
3515
 
2093
3516
  VideoImportRequest:
2094
3517
  type: object
2095
- required: [url]
3518
+ description: |
3519
+ Provide either `url` (single) or `videos` (batch of 1–5). Do not send both.
2096
3520
  properties:
2097
3521
  url:
2098
3522
  type: string
2099
3523
  format: uri
2100
- description: Public HTTPS URL to an MP4 file (max 50 MB).
3524
+ description: Public HTTPS URL to an MP4 file (max 50 MB). Mutually exclusive with `videos`.
3525
+ videos:
3526
+ type: array
3527
+ minItems: 1
3528
+ maxItems: 5
3529
+ description: Batch of video URLs. Mutually exclusive with `url`.
3530
+ items:
3531
+ type: object
3532
+ required: [url]
3533
+ properties:
3534
+ url:
3535
+ type: string
3536
+ format: uri
3537
+ description: Public HTTPS URL to an MP4 file (max 50 MB).
2101
3538
 
2102
3539
  VideoImportStatus:
2103
3540
  type: string
2104
- enum: [processing, ready, failed]
3541
+ enum: [processing, ready, failed, partial]
3542
+
3543
+ VideoImportCounts:
3544
+ type: object
3545
+ required: [total, ready, failed]
3546
+ properties:
3547
+ total:
3548
+ type: integer
3549
+ description: Videos admitted in the session
3550
+ ready:
3551
+ type: integer
3552
+ description: Ingested successfully
3553
+ failed:
3554
+ type: integer
3555
+ description: Ingestion failures (download failures fail the whole session in this phase)
2105
3556
 
2106
3557
  VideoImportStartData:
2107
3558
  type: object
@@ -2113,6 +3564,9 @@ components:
2113
3564
  description: Upload session ID for status polling
2114
3565
  status:
2115
3566
  $ref: '#/components/schemas/VideoImportStatus'
3567
+ count:
3568
+ type: integer
3569
+ description: Number of videos accepted for import
2116
3570
  videoId:
2117
3571
  type: string
2118
3572
  format: uuid
@@ -2141,11 +3595,40 @@ components:
2141
3595
  type: string
2142
3596
  format: uuid
2143
3597
  nullable: true
2144
- description: Background video ID when `status` is `ready`
3598
+ description: Present for single-URL sessions when ready or failed after ingest
3599
+ videoIds:
3600
+ type: array
3601
+ items:
3602
+ type: string
3603
+ format: uuid
3604
+ description: Ready video IDs for batch sessions (`count > 1`)
3605
+ counts:
3606
+ $ref: '#/components/schemas/VideoImportCounts'
2145
3607
  error:
2146
- type: string
3608
+ allOf:
3609
+ - $ref: '#/components/schemas/VideoImportStatusError'
2147
3610
  nullable: true
2148
- description: Failure reason when `status` is `failed`
3611
+ description: Present when status is failed
3612
+
3613
+ VideoImportStatusError:
3614
+ type: object
3615
+ required: [code, message]
3616
+ properties:
3617
+ code:
3618
+ type: string
3619
+ enum:
3620
+ - video_too_large
3621
+ - invalid_video_content_type
3622
+ - storage_limit_exceeded
3623
+ - no_videos_imported
3624
+ - duplicate_videos
3625
+ - import_failed
3626
+ description: >
3627
+ Machine-readable failure code. Legacy sessions without a stored
3628
+ code fall back to import_failed.
3629
+ message:
3630
+ type: string
3631
+ description: Human-readable failure message
2149
3632
 
2150
3633
  VideoImportStatusResponse:
2151
3634
  type: object
@@ -2204,7 +3687,10 @@ components:
2204
3687
  requestId: 550e8400-e29b-41d4-a716-446655440000
2205
3688
 
2206
3689
  Unauthorized:
2207
- description: Missing, malformed, revoked, or expired API key
3690
+ description: |
3691
+ Missing or invalid credentials. Covers missing/malformed API keys,
3692
+ invalid or expired OAuth access tokens, and revoked API keys.
3693
+ `x-api-key` is not accepted and is ignored if sent.
2208
3694
  headers:
2209
3695
  Retry-After:
2210
3696
  schema:
@@ -2219,7 +3705,14 @@ components:
2219
3705
  value:
2220
3706
  error:
2221
3707
  code: invalid_api_key
2222
- message: 'Missing or malformed API key. Expected: sk_<prefix>_<token> (sent via x-api-key or Authorization: Bearer).'
3708
+ message: 'Missing credentials. Send Authorization: Bearer.'
3709
+ meta:
3710
+ requestId: 550e8400-e29b-41d4-a716-446655440000
3711
+ invalid_token:
3712
+ value:
3713
+ error:
3714
+ code: invalid_token
3715
+ message: 'OAuth access token is invalid or expired.'
2223
3716
  meta:
2224
3717
  requestId: 550e8400-e29b-41d4-a716-446655440000
2225
3718
  api_key_revoked:
@@ -2231,17 +3724,28 @@ components:
2231
3724
  requestId: 550e8400-e29b-41d4-a716-446655440000
2232
3725
 
2233
3726
  Forbidden:
2234
- description: Valid key but missing required scope
3727
+ description: |
3728
+ Authenticated but not allowed: missing required scope, or OAuth access
3729
+ disabled for the organization (`access_denied`).
2235
3730
  content:
2236
3731
  application/json:
2237
3732
  schema:
2238
3733
  $ref: '#/components/schemas/ErrorResponse'
2239
- example:
2240
- error:
2241
- code: insufficient_scope
2242
- message: 'This key does not have the metrics:read scope.'
2243
- meta:
2244
- requestId: 550e8400-e29b-41d4-a716-446655440000
3734
+ examples:
3735
+ insufficient_scope:
3736
+ value:
3737
+ error:
3738
+ code: insufficient_scope
3739
+ message: 'This token does not have the metrics:read scope.'
3740
+ meta:
3741
+ requestId: 550e8400-e29b-41d4-a716-446655440000
3742
+ access_denied:
3743
+ value:
3744
+ error:
3745
+ code: access_denied
3746
+ message: 'OAuth access is not enabled for this organization.'
3747
+ meta:
3748
+ requestId: 550e8400-e29b-41d4-a716-446655440000
2245
3749
 
2246
3750
  CreateCampaignForbidden:
2247
3751
  description: |