soundlink 1.0.0 → 1.1.1

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.
@@ -0,0 +1,1289 @@
1
+ openapi: 3.0.3
2
+ info:
3
+ title: Soundlink Public API
4
+ version: 0.0.1-draft
5
+ description: |
6
+ Read-only campaign and metrics API for Soundlink partner organizations.
7
+
8
+ **Base URL:** `https://api.getsoundlink.com`
9
+
10
+ **Authentication:** `x-api-key` header using a `sk_*` API key issued by Soundlink Engineering.
11
+ ```
12
+ x-api-key: sk_abc123_<token>
13
+ ```
14
+
15
+ All responses are wrapped in a standard envelope:
16
+ ```json
17
+ { "data": <payload>, "meta": { "requestId": "<uuid>" } }
18
+ ```
19
+
20
+ Errors follow the same envelope shape with an `error` field instead of `data`.
21
+
22
+ servers:
23
+ - url: https://api.getsoundlink.com
24
+ description: Production
25
+
26
+ security:
27
+ - apiKeyAuth: []
28
+
29
+ tags:
30
+ - name: System
31
+ description: Connectivity and auth verification
32
+ - name: Campaigns
33
+ description: Campaign listing and detail
34
+ - name: Metrics
35
+ description: Campaign performance metrics
36
+
37
+ paths:
38
+ /v1/ping:
39
+ get:
40
+ operationId: ping
41
+ summary: Verify connectivity and authentication
42
+ description: |
43
+ Returns `{ "status": "ok" }` if the request is authenticated and the
44
+ API is reachable. Useful for verifying a newly issued key before making
45
+ data requests.
46
+ tags: [System]
47
+ security:
48
+ - apiKeyAuth: []
49
+ responses:
50
+ '200':
51
+ description: Authenticated and reachable
52
+ content:
53
+ application/json:
54
+ schema:
55
+ type: object
56
+ required: [data, meta]
57
+ properties:
58
+ data:
59
+ type: object
60
+ required: [status]
61
+ properties:
62
+ status:
63
+ type: string
64
+ example: ok
65
+ meta:
66
+ $ref: '#/components/schemas/Meta'
67
+ example:
68
+ data:
69
+ status: ok
70
+ meta:
71
+ requestId: 550e8400-e29b-41d4-a716-446655440000
72
+ '401': { $ref: '#/components/responses/Unauthorized' }
73
+ '429': { $ref: '#/components/responses/RateLimited' }
74
+ '500': { $ref: '#/components/responses/InternalError' }
75
+
76
+ /v1/campaigns:
77
+ get:
78
+ operationId: listCampaigns
79
+ summary: List campaigns
80
+ description: |
81
+ Returns all campaigns for the authenticated organization.
82
+ Intended for reporting and data warehouse sync.
83
+ tags: [Campaigns]
84
+ security:
85
+ - apiKeyAuth: []
86
+ parameters:
87
+ - $ref: '#/components/parameters/page'
88
+ - $ref: '#/components/parameters/pageSize100'
89
+ - name: sortBy
90
+ in: query
91
+ schema:
92
+ type: string
93
+ enum: [createdAt, status]
94
+ default: createdAt
95
+ - $ref: '#/components/parameters/sortOrder'
96
+ responses:
97
+ '200':
98
+ description: Paginated list of campaigns
99
+ content:
100
+ application/json:
101
+ schema:
102
+ $ref: '#/components/schemas/CampaignListResponse'
103
+ example:
104
+ data:
105
+ items:
106
+ - campaignId: camp_abc123
107
+ organizationId: org_xyz
108
+ status: active
109
+ socialPlatform: meta
110
+ dailyBudget: 20.0
111
+ totalBudget: 140.0
112
+ campaignDuration: 7
113
+ createdAt: '2026-04-01T10:00:00Z'
114
+ updatedAt: '2026-04-08T12:00:00Z'
115
+ pagination:
116
+ page: 1
117
+ pageSize: 10
118
+ totalCount: 42
119
+ totalPages: 5
120
+ meta:
121
+ requestId: 550e8400-e29b-41d4-a716-446655440000
122
+ '401': { $ref: '#/components/responses/Unauthorized' }
123
+ '403': { $ref: '#/components/responses/Forbidden' }
124
+ '429': { $ref: '#/components/responses/RateLimited' }
125
+ '500': { $ref: '#/components/responses/InternalError' }
126
+
127
+ /v1/campaigns/{campaignId}:
128
+ get:
129
+ operationId: getCampaign
130
+ summary: Get campaign
131
+ description: Fetch full details for a single campaign.
132
+ tags: [Campaigns]
133
+ security:
134
+ - apiKeyAuth: []
135
+ parameters:
136
+ - $ref: '#/components/parameters/campaignId'
137
+ responses:
138
+ '200':
139
+ description: Campaign detail
140
+ content:
141
+ application/json:
142
+ schema:
143
+ $ref: '#/components/schemas/CampaignDetailResponse'
144
+ example:
145
+ data:
146
+ campaignId: camp_abc123
147
+ organizationId: org_xyz
148
+ status: active
149
+ socialPlatform: meta
150
+ dailyBudget: 20.0
151
+ totalBudget: 140.0
152
+ campaignDuration: 7
153
+ strategyType: custom
154
+ createdAt: '2026-04-01T10:00:00Z'
155
+ updatedAt: '2026-04-08T12:00:00Z'
156
+ meta:
157
+ requestId: 550e8400-e29b-41d4-a716-446655440000
158
+ '401': { $ref: '#/components/responses/Unauthorized' }
159
+ '403': { $ref: '#/components/responses/Forbidden' }
160
+ '404': { $ref: '#/components/responses/NotFound' }
161
+ '429': { $ref: '#/components/responses/RateLimited' }
162
+ '500': { $ref: '#/components/responses/InternalError' }
163
+
164
+ /v1/campaigns/{campaignId}/metrics/overview:
165
+ get:
166
+ operationId: getCampaignMetricsOverview
167
+ summary: Campaign metrics overview
168
+ description: |
169
+ Campaign-level totals for a date range: spend, conversions, listeners,
170
+ streams, followers, and derived ratios. No per-day rows — use
171
+ `/metrics/breakdown` for those.
172
+
173
+ Suitable for dashboards and quick syncs.
174
+ tags: [Metrics]
175
+ security:
176
+ - apiKeyAuth: []
177
+ parameters:
178
+ - $ref: '#/components/parameters/campaignId'
179
+ - $ref: '#/components/parameters/startDate'
180
+ - $ref: '#/components/parameters/endDate'
181
+ responses:
182
+ '200':
183
+ description: Campaign totals
184
+ content:
185
+ application/json:
186
+ schema:
187
+ $ref: '#/components/schemas/MetricsOverviewResponse'
188
+ example:
189
+ data:
190
+ listeners: 4821
191
+ streams: 9340
192
+ followers: 312
193
+ impressions: 48210
194
+ ad_clicks: 1120
195
+ link_clicks: 890
196
+ spend_media: 134.50
197
+ spend_total: 168.13
198
+ fees: 33.63
199
+ currency: USD
200
+ cpl: 0.028
201
+ cpf: 0.43
202
+ streams_per_listener: 1.94
203
+ meta:
204
+ requestId: 550e8400-e29b-41d4-a716-446655440000
205
+ '400': { $ref: '#/components/responses/BadRequest' }
206
+ '401': { $ref: '#/components/responses/Unauthorized' }
207
+ '403': { $ref: '#/components/responses/Forbidden' }
208
+ '404': { $ref: '#/components/responses/NotFound' }
209
+ '429': { $ref: '#/components/responses/RateLimited' }
210
+ '500': { $ref: '#/components/responses/InternalError' }
211
+
212
+ /v1/campaigns/{campaignId}/metrics/breakdown:
213
+ get:
214
+ operationId: getCampaignMetricsBreakdown
215
+ summary: Campaign metrics breakdown
216
+ description: |
217
+ Per-day metrics broken down by country. One row per
218
+ `(report_date, campaign_id, country_code)`. Can be large, so results
219
+ are paginated.
220
+
221
+ **Row schema:** `campaign_country_daily` v1.0 — the same schema used
222
+ in JSONL bulk exports. Rows are idempotent on the primary key
223
+ `(provider, account_id, report_date, campaign_id, country_code)`;
224
+ re-ingesting is safe.
225
+
226
+ **Mutability window:** rows for a given `report_date` can be revised
227
+ for up to 7 days after the date closes due to delayed events from
228
+ Meta and Spotify. Re-fetch or re-ingest accordingly.
229
+
230
+ Maps to the **Countries** tab in the Soundlink Insights UI.
231
+ Use for daily warehouse loads.
232
+ tags: [Metrics]
233
+ security:
234
+ - apiKeyAuth: []
235
+ parameters:
236
+ - $ref: '#/components/parameters/campaignId'
237
+ - $ref: '#/components/parameters/startDate'
238
+ - $ref: '#/components/parameters/endDate'
239
+ - $ref: '#/components/parameters/page'
240
+ - $ref: '#/components/parameters/pageSize500'
241
+ - name: sortBy
242
+ in: query
243
+ schema:
244
+ type: string
245
+ enum: [report_date, spend_total]
246
+ default: report_date
247
+ - $ref: '#/components/parameters/sortOrder'
248
+ responses:
249
+ '200':
250
+ description: Paginated per-day country rows (`campaign_country_daily` schema)
251
+ content:
252
+ application/json:
253
+ schema:
254
+ $ref: '#/components/schemas/MetricsBreakdownResponse'
255
+ example:
256
+ data:
257
+ schemaVersion: '1.0'
258
+ items:
259
+ - provider: soundlink
260
+ account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
261
+ schema_version: '1.0'
262
+ report_date: '2026-04-01'
263
+ report_date_timezone: UTC
264
+ exported_at: '2026-05-20T03:00:00Z'
265
+ campaign_id: f1e28d31-c358-4284-9bef-00a2334625fd
266
+ campaign_name: Sleep Playlist
267
+ campaign_target_type: track
268
+ campaign_target_isrc: DEXW62500259
269
+ campaign_target_spotify_track_id: 6habFhsOp2NvndAvgiJ01P
270
+ campaign_target_playlist_id: null
271
+ country_code: US
272
+ impressions: 4821
273
+ ad_clicks: 112
274
+ link_clicks: 89
275
+ streams: 203
276
+ listeners: 145
277
+ followers: 12
278
+ streams_per_listener: 1.4
279
+ spend_media: 42.50
280
+ spend_total: 53.13
281
+ fees: 10.63
282
+ currency: USD
283
+ currency_account: USD
284
+ cpl: 0.293
285
+ cpf: 3.542
286
+ cpc_linkclick: 0.478
287
+ ctr_linkclick: 0.0185
288
+ ctr_adclick: 0.0232
289
+ cost_per_result: 3.542
290
+ result_type: follow
291
+ pagination:
292
+ page: 1
293
+ pageSize: 50
294
+ totalCount: 340
295
+ totalPages: 7
296
+ meta:
297
+ requestId: 550e8400-e29b-41d4-a716-446655440000
298
+ '400': { $ref: '#/components/responses/BadRequest' }
299
+ '401': { $ref: '#/components/responses/Unauthorized' }
300
+ '403': { $ref: '#/components/responses/Forbidden' }
301
+ '404': { $ref: '#/components/responses/NotFound' }
302
+ '429': { $ref: '#/components/responses/RateLimited' }
303
+ '500': { $ref: '#/components/responses/InternalError' }
304
+
305
+ /v1/campaigns/{campaignId}/metrics/breakdown/export:
306
+ get:
307
+ operationId: exportCampaignMetricsBreakdown
308
+ summary: Campaign metrics breakdown export (JSONL)
309
+ description: |
310
+ Streams the full country-level metrics dataset for a campaign as
311
+ **newline-delimited JSON (JSONL)**. Every line is a complete, valid
312
+ JSON object conforming to the `campaign_country_daily` v1.0 schema
313
+ — identical to the rows returned by `GET /metrics/breakdown` but
314
+ without pagination or an envelope wrapper.
315
+
316
+ Designed for data pipeline consumers: load directly into BigQuery,
317
+ Snowflake, or any JSONL-aware ingest tool without cursor logic.
318
+
319
+ **Usage:**
320
+ ```
321
+ GET /v1/campaigns/{campaignId}/metrics/breakdown/export
322
+ Accept: application/x-ndjson
323
+ ```
324
+
325
+ **Date range:** defaults to the full campaign active period. Override
326
+ with `startDate` / `endDate`. **Responses are capped at 90 days** —
327
+ use `startDate` / `endDate` to slice through longer windows manually.
328
+
329
+ **Mutability:** rows for a given `report_date` can be revised for up
330
+ to 7 days after the date closes due to delayed events from Meta and
331
+ Spotify. Re-fetching and re-ingesting on the primary key is safe
332
+ (idempotent).
333
+ tags: [Metrics]
334
+ security:
335
+ - apiKeyAuth: []
336
+ parameters:
337
+ - $ref: '#/components/parameters/campaignId'
338
+ - $ref: '#/components/parameters/startDate'
339
+ - $ref: '#/components/parameters/endDate'
340
+ responses:
341
+ '200':
342
+ description: |
343
+ JSONL stream. Each line is a `campaign_country_daily` v1.0 row.
344
+ Lines are sorted by `(report_date asc, country_code)`.
345
+ headers:
346
+ Content-Disposition:
347
+ schema:
348
+ type: string
349
+ description: |
350
+ `attachment; filename="breakdown_{campaignId}_{startDate}_{endDate}.jsonl"`
351
+ example: 'attachment; filename="breakdown_f1e28d31_2026-04-01_2026-05-01.jsonl"'
352
+ X-Row-Count:
353
+ schema:
354
+ type: integer
355
+ description: Total number of rows in the response.
356
+ content:
357
+ application/x-ndjson:
358
+ schema:
359
+ $ref: '#/components/schemas/BreakdownRow'
360
+ example: |
361
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-04-01","report_date_timezone":"UTC","exported_at":"2026-05-20T03:00:00Z","campaign_id":"f1e28d31-c358-4284-9bef-00a2334625fd","campaign_name":"Sleep Playlist","campaign_target_type":"track","campaign_target_isrc":"DEXW62500259","campaign_target_spotify_track_id":"6habFhsOp2NvndAvgiJ01P","campaign_target_playlist_id":null,"country_code":"US","impressions":4821,"ad_clicks":112,"link_clicks":89,"streams":203,"listeners":145,"followers":12,"streams_per_listener":1.4,"spend_media":42.50,"spend_total":53.13,"fees":10.63,"currency":"USD","currency_account":"USD","cpl":0.293,"cpf":3.542,"cpc_linkclick":0.478,"ctr_linkclick":0.0185,"ctr_adclick":0.0232,"cost_per_result":3.542,"result_type":"follow"}
362
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-04-01","report_date_timezone":"UTC","exported_at":"2026-05-20T03:00:00Z","campaign_id":"f1e28d31-c358-4284-9bef-00a2334625fd","campaign_name":"Sleep Playlist","campaign_target_type":"track","campaign_target_isrc":"DEXW62500259","campaign_target_spotify_track_id":"6habFhsOp2NvndAvgiJ01P","campaign_target_playlist_id":null,"country_code":"DE","impressions":2103,"ad_clicks":48,"link_clicks":31,"streams":87,"listeners":61,"followers":4,"streams_per_listener":1.43,"spend_media":18.20,"spend_total":22.75,"fees":4.55,"currency":"USD","currency_account":"USD","cpl":0.298,"cpf":4.55,"cpc_linkclick":0.587,"ctr_linkclick":0.0148,"ctr_adclick":0.0228,"cost_per_result":4.55,"result_type":"follow"}
363
+ '400': { $ref: '#/components/responses/BadRequest' }
364
+ '401': { $ref: '#/components/responses/Unauthorized' }
365
+ '403': { $ref: '#/components/responses/Forbidden' }
366
+ '404': { $ref: '#/components/responses/NotFound' }
367
+ '429': { $ref: '#/components/responses/RateLimited' }
368
+ '500': { $ref: '#/components/responses/InternalError' }
369
+
370
+ /v1/campaigns/{campaignId}/metrics/engagement:
371
+ get:
372
+ operationId: getCampaignEngagement
373
+ summary: Campaign engagement breakdown
374
+ description: |
375
+ Per-day, per-track engagement metrics for a campaign. One row per
376
+ `(report_date, campaign_id, engagement_context, engaged_spotify_track_id)`.
377
+
378
+ **Key difference from `/metrics/breakdown`:** this endpoint covers the
379
+ full engagement window — including post-campaign streaming activity —
380
+ not just dates when the campaign was actively running. Use this for
381
+ catalog spillover analysis and long-tail retention.
382
+
383
+ **`engagement_context` values:**
384
+ - `catalog` — same-artist spillover (and direct promoted-track plays)
385
+ on track campaigns. `engaged_track_isrc` may equal
386
+ `campaign_target_isrc` (the promoted track itself) or differ
387
+ (spillover tracks).
388
+ - `playlist` — per-track performance inside the promoted playlist on
389
+ playlist campaigns. One row per track in the playlist per day.
390
+
391
+ **`listeners` is deduplicated within each row only.** Do not sum
392
+ `listeners` across days to get a campaign total — the same listener
393
+ can appear on multiple `report_date` rows.
394
+
395
+ Row schema: `campaign_engagement_daily` v1.0. Rows are idempotent on
396
+ the primary key; re-ingesting is safe.
397
+
398
+ **Mutability window:** rows for a given `report_date` can be revised
399
+ for up to 7 days after the date closes due to delayed Spotify
400
+ playback events.
401
+ tags: [Metrics]
402
+ security:
403
+ - apiKeyAuth: []
404
+ parameters:
405
+ - $ref: '#/components/parameters/campaignId'
406
+ - $ref: '#/components/parameters/startDate'
407
+ - $ref: '#/components/parameters/endDate'
408
+ - name: engagementContext
409
+ in: query
410
+ schema:
411
+ type: string
412
+ enum: [catalog, playlist]
413
+ description: |
414
+ Filter to a single engagement context. Omit to return both.
415
+ - $ref: '#/components/parameters/page'
416
+ - $ref: '#/components/parameters/pageSize500'
417
+ - name: sortBy
418
+ in: query
419
+ schema:
420
+ type: string
421
+ enum: [report_date, streams, listeners]
422
+ default: report_date
423
+ - $ref: '#/components/parameters/sortOrder'
424
+ responses:
425
+ '200':
426
+ description: Paginated per-day per-track engagement rows (`campaign_engagement_daily` schema)
427
+ content:
428
+ application/json:
429
+ schema:
430
+ $ref: '#/components/schemas/EngagementBreakdownResponse'
431
+ example:
432
+ data:
433
+ schemaVersion: '1.0'
434
+ items:
435
+ - provider: soundlink
436
+ account_id: a7ac3173-2f71-4e79-921f-d15d7112cc9a
437
+ schema_version: '1.0'
438
+ report_date: '2026-04-08'
439
+ report_date_timezone: UTC
440
+ exported_at: '2026-05-22T10:12:11Z'
441
+ campaign_id: 8ccd7b88-2591-4b94-848f-f142f5c6bba1
442
+ campaign_name: 9 To 5
443
+ campaign_target_type: track
444
+ campaign_target_isrc: DEXW62500272
445
+ campaign_target_spotify_track_id: 2RkZ5WPkKyBf0u8vN3dNgb
446
+ campaign_target_playlist_id: null
447
+ status: ended
448
+ engagement_context: catalog
449
+ country_code: US
450
+ engaged_track_isrc: DEXW62500001
451
+ engaged_spotify_track_id: 4cOdK2wGLETKBW3PvgPWqT
452
+ engaged_track_name: Till The Sunrise
453
+ playlist_position: null
454
+ new_listeners: 42
455
+ returning_listeners: 18
456
+ listeners: 60
457
+ new_listener_streams: 58
458
+ returning_listener_streams: 31
459
+ streams: 89
460
+ spl: 1.48
461
+ pagination:
462
+ page: 1
463
+ pageSize: 50
464
+ totalCount: 210
465
+ totalPages: 5
466
+ meta:
467
+ requestId: 550e8400-e29b-41d4-a716-446655440000
468
+ '400': { $ref: '#/components/responses/BadRequest' }
469
+ '401': { $ref: '#/components/responses/Unauthorized' }
470
+ '403': { $ref: '#/components/responses/Forbidden' }
471
+ '404': { $ref: '#/components/responses/NotFound' }
472
+ '429': { $ref: '#/components/responses/RateLimited' }
473
+ '500': { $ref: '#/components/responses/InternalError' }
474
+
475
+ /v1/campaigns/{campaignId}/metrics/engagement/export:
476
+ get:
477
+ operationId: exportCampaignEngagement
478
+ summary: Campaign engagement export (JSONL)
479
+ description: |
480
+ Streams the full engagement dataset for a campaign as
481
+ **newline-delimited JSON (JSONL)**. Every line is a complete, valid
482
+ JSON object conforming to the `campaign_engagement_daily` v1.0 schema
483
+ — identical to the rows returned by `GET /metrics/engagement` but
484
+ without pagination or an envelope wrapper.
485
+
486
+ Designed for data pipeline consumers: load directly into BigQuery,
487
+ Snowflake, or any JSONL-aware ingest tool without cursor logic.
488
+
489
+ **Usage:**
490
+ ```
491
+ GET /v1/campaigns/{campaignId}/metrics/engagement/export
492
+ Accept: application/x-ndjson
493
+ ```
494
+
495
+ **Response body (one JSON object per line, no trailing comma):**
496
+ ```
497
+ {"provider":"soundlink","report_date":"2026-04-01","streams":89,...}
498
+ {"provider":"soundlink","report_date":"2026-04-02","streams":104,...}
499
+ ```
500
+
501
+ **Date range:** defaults to the full campaign lifetime plus 30 days
502
+ post-end to capture tail engagement. Override with `startDate` /
503
+ `endDate`. **Responses are capped at 90 days** — if the requested
504
+ range exceeds 90 days, the most recent 90 days are returned. Use
505
+ `startDate` / `endDate` to page through longer windows in 90-day
506
+ slices.
507
+
508
+ **Mutability:** same 7-day revision window as the paginated endpoint.
509
+ Re-fetching and re-ingesting on the primary key is safe (idempotent).
510
+ tags: [Metrics]
511
+ security:
512
+ - apiKeyAuth: []
513
+ parameters:
514
+ - $ref: '#/components/parameters/campaignId'
515
+ - $ref: '#/components/parameters/startDate'
516
+ - $ref: '#/components/parameters/endDate'
517
+ - name: engagementContext
518
+ in: query
519
+ schema:
520
+ type: string
521
+ enum: [catalog, playlist]
522
+ description: Filter to a single engagement context. Omit to return both.
523
+ responses:
524
+ '200':
525
+ description: |
526
+ JSONL stream. Each line is a `campaign_engagement_daily` v1.0 row.
527
+ Lines are sorted by `(report_date asc, engagement_context, country_code, engaged_spotify_track_id)`.
528
+ headers:
529
+ Content-Disposition:
530
+ schema:
531
+ type: string
532
+ description: |
533
+ `attachment; filename="engagement_{campaignId}_{startDate}_{endDate}.jsonl"`
534
+ example: 'attachment; filename="engagement_8ccd7b88_2026-04-01_2026-05-01.jsonl"'
535
+ X-Row-Count:
536
+ schema:
537
+ type: integer
538
+ description: Total number of rows in the response. Useful for progress tracking when streaming.
539
+ content:
540
+ application/x-ndjson:
541
+ schema:
542
+ $ref: '#/components/schemas/EngagementRow'
543
+ example: |
544
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112cc9a","schema_version":"1.0","report_date":"2026-04-08","report_date_timezone":"UTC","exported_at":"2026-05-22T10:12:11Z","campaign_id":"8ccd7b88-2591-4b94-848f-f142f5c6bba1","campaign_name":"9 To 5","campaign_target_type":"track","campaign_target_isrc":"DEXW62500272","campaign_target_spotify_track_id":"2RkZ5WPkKyBf0u8vN3dNgb","campaign_target_playlist_id":null,"status":"ended","engagement_context":"catalog","country_code":"US","engaged_track_isrc":"DEXW62500001","engaged_spotify_track_id":"4cOdK2wGLETKBW3PvgPWqT","engaged_track_name":"Till The Sunrise","playlist_position":null,"new_listeners":42,"returning_listeners":18,"listeners":60,"new_listener_streams":58,"returning_listener_streams":31,"streams":89,"spl":1.48}
545
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112cc9a","schema_version":"1.0","report_date":"2026-04-08","report_date_timezone":"UTC","exported_at":"2026-05-22T10:12:11Z","campaign_id":"8ccd7b88-2591-4b94-848f-f142f5c6bba1","campaign_name":"9 To 5","campaign_target_type":"track","campaign_target_isrc":"DEXW62500272","campaign_target_spotify_track_id":"2RkZ5WPkKyBf0u8vN3dNgb","campaign_target_playlist_id":null,"status":"ended","engagement_context":"catalog","country_code":"DE","engaged_track_isrc":"DEXW62500001","engaged_spotify_track_id":"4cOdK2wGLETKBW3PvgPWqT","engaged_track_name":"Till The Sunrise","playlist_position":14,"new_listeners":19,"returning_listeners":7,"listeners":26,"new_listener_streams":24,"returning_listener_streams":11,"streams":35,"spl":1.35}
546
+ '400': { $ref: '#/components/responses/BadRequest' }
547
+ '401': { $ref: '#/components/responses/Unauthorized' }
548
+ '403': { $ref: '#/components/responses/Forbidden' }
549
+ '404': { $ref: '#/components/responses/NotFound' }
550
+ '429': { $ref: '#/components/responses/RateLimited' }
551
+ '500': { $ref: '#/components/responses/InternalError' }
552
+
553
+ components:
554
+ securitySchemes:
555
+ apiKeyAuth:
556
+ type: apiKey
557
+ in: header
558
+ name: x-api-key
559
+ description: |
560
+ Pass your Soundlink `sk_*` API key in the `x-api-key` header.
561
+ Keys can carry explicit scopes (for example `campaigns:read`, `metrics:read`) enforced by the backend.
562
+
563
+ parameters:
564
+ campaignId:
565
+ name: campaignId
566
+ in: path
567
+ required: true
568
+ schema:
569
+ type: string
570
+ description: Campaign identifier (e.g. `camp_abc123`)
571
+
572
+ page:
573
+ name: page
574
+ in: query
575
+ schema:
576
+ type: integer
577
+ minimum: 1
578
+ default: 1
579
+ description: Page number (1-indexed)
580
+
581
+ pageSize100:
582
+ name: pageSize
583
+ in: query
584
+ schema:
585
+ type: integer
586
+ minimum: 1
587
+ maximum: 100
588
+ default: 10
589
+ description: Items per page (max 100)
590
+
591
+ pageSize500:
592
+ name: pageSize
593
+ in: query
594
+ schema:
595
+ type: integer
596
+ minimum: 1
597
+ maximum: 500
598
+ default: 50
599
+ description: Rows per page (max 500; higher default than list endpoints)
600
+
601
+ sortOrder:
602
+ name: sortOrder
603
+ in: query
604
+ schema:
605
+ type: string
606
+ enum: [asc, desc]
607
+ default: desc
608
+ description: Sort direction
609
+
610
+ startDate:
611
+ name: startDate
612
+ in: query
613
+ schema:
614
+ type: string
615
+ format: date
616
+ description: Inclusive start date (`YYYY-MM-DD`). Defaults to campaign start date.
617
+
618
+ endDate:
619
+ name: endDate
620
+ in: query
621
+ schema:
622
+ type: string
623
+ format: date
624
+ description: Inclusive end date (`YYYY-MM-DD`). Defaults to today.
625
+
626
+ schemas:
627
+ # --- Shared ---
628
+
629
+ Meta:
630
+ type: object
631
+ required: [requestId]
632
+ properties:
633
+ requestId:
634
+ type: string
635
+ format: uuid
636
+ description: Server-generated request ID. Include when contacting support.
637
+
638
+ Pagination:
639
+ type: object
640
+ required: [page, pageSize, totalCount, totalPages]
641
+ properties:
642
+ page:
643
+ type: integer
644
+ pageSize:
645
+ type: integer
646
+ totalCount:
647
+ type: integer
648
+ totalPages:
649
+ type: integer
650
+
651
+ Error:
652
+ type: object
653
+ required: [code, message]
654
+ properties:
655
+ code:
656
+ type: string
657
+ description: Stable snake_case error code.
658
+ enum:
659
+ - invalid_api_key
660
+ - api_key_revoked
661
+ - api_key_expired
662
+ - mixed_credentials
663
+ - insufficient_scope
664
+ - not_found
665
+ - campaign_not_found
666
+ - invalid_query_parameter
667
+ - invalid_date_range
668
+ - page_size_exceeded
669
+ - rate_limit_exceeded
670
+ - internal_error
671
+ message:
672
+ type: string
673
+ description: Human-readable error description. Do not parse programmatically.
674
+
675
+ ErrorResponse:
676
+ type: object
677
+ required: [error, meta]
678
+ properties:
679
+ error:
680
+ $ref: '#/components/schemas/Error'
681
+ meta:
682
+ $ref: '#/components/schemas/Meta'
683
+
684
+ # --- Campaign ---
685
+
686
+ CampaignStatus:
687
+ type: string
688
+ enum: [creating, active, paused, completed, failed]
689
+
690
+ CampaignSummary:
691
+ type: object
692
+ required:
693
+ [
694
+ campaignId,
695
+ organizationId,
696
+ status,
697
+ socialPlatform,
698
+ dailyBudget,
699
+ totalBudget,
700
+ campaignDuration,
701
+ createdAt,
702
+ updatedAt,
703
+ ]
704
+ properties:
705
+ campaignId:
706
+ type: string
707
+ organizationId:
708
+ type: string
709
+ status:
710
+ $ref: '#/components/schemas/CampaignStatus'
711
+ socialPlatform:
712
+ type: string
713
+ enum: [meta]
714
+ dailyBudget:
715
+ type: number
716
+ description: USD
717
+ totalBudget:
718
+ type: number
719
+ description: USD
720
+ campaignDuration:
721
+ type: integer
722
+ description: Duration in days
723
+ createdAt:
724
+ type: string
725
+ format: date-time
726
+ updatedAt:
727
+ type: string
728
+ format: date-time
729
+
730
+ CampaignDetail:
731
+ allOf:
732
+ - $ref: '#/components/schemas/CampaignSummary'
733
+ - type: object
734
+ properties:
735
+ strategyType:
736
+ type: string
737
+ description: |
738
+ Growth strategy (e.g. `custom`, `maximum_growth`, `market_discovery`).
739
+ Set at campaign creation.
740
+
741
+ CampaignListResponse:
742
+ type: object
743
+ required: [data, meta]
744
+ properties:
745
+ data:
746
+ type: object
747
+ required: [items, pagination]
748
+ properties:
749
+ items:
750
+ type: array
751
+ items:
752
+ $ref: '#/components/schemas/CampaignSummary'
753
+ pagination:
754
+ $ref: '#/components/schemas/Pagination'
755
+ meta:
756
+ $ref: '#/components/schemas/Meta'
757
+
758
+ CampaignDetailResponse:
759
+ type: object
760
+ required: [data, meta]
761
+ properties:
762
+ data:
763
+ $ref: '#/components/schemas/CampaignDetail'
764
+ meta:
765
+ $ref: '#/components/schemas/Meta'
766
+
767
+ # --- Metrics ---
768
+
769
+ MetricsOverview:
770
+ type: object
771
+ description: |
772
+ Campaign-level totals aggregated across all countries for the requested
773
+ date range. Field names align with the `campaign_country_daily` row
774
+ schema — values here are the sum of country rows.
775
+ required:
776
+ [
777
+ listeners,
778
+ streams,
779
+ followers,
780
+ spend_media,
781
+ spend_total,
782
+ fees,
783
+ currency,
784
+ cpl,
785
+ cpf,
786
+ streams_per_listener,
787
+ ]
788
+ properties:
789
+ listeners:
790
+ type: integer
791
+ description: Unique attributed Spotify listeners (sum of country rows).
792
+ streams:
793
+ type: integer
794
+ description: Attributed Spotify streams (sum of country rows).
795
+ followers:
796
+ type: integer
797
+ description: Attributed artist follower gains (sum of country rows).
798
+ impressions:
799
+ type: integer
800
+ nullable: true
801
+ description: Total Meta ad impressions. Null if not available.
802
+ ad_clicks:
803
+ type: integer
804
+ nullable: true
805
+ description: Total Meta ad clicks (all click types).
806
+ link_clicks:
807
+ type: integer
808
+ nullable: true
809
+ description: Outbound clicks to Spotify via the Soundlink landing page.
810
+ spend_media:
811
+ type: number
812
+ description: Amount billed to Meta for ad delivery. Excludes Soundlink fees. USD.
813
+ spend_total:
814
+ type: number
815
+ description: Total billed by Soundlink (spend_media + fees). USD.
816
+ fees:
817
+ type: number
818
+ description: Soundlink service fee (spend_total - spend_media). USD.
819
+ currency:
820
+ type: string
821
+ description: Currency for spend fields. Currently always `USD`.
822
+ cpl:
823
+ type: number
824
+ description: Cost per listener (spend_media / listeners).
825
+ cpf:
826
+ type: number
827
+ description: Cost per follower (spend_media / followers).
828
+ streams_per_listener:
829
+ type: number
830
+ description: streams / listeners. Zero if listeners is zero.
831
+
832
+ MetricsOverviewResponse:
833
+ type: object
834
+ required: [data, meta]
835
+ properties:
836
+ data:
837
+ $ref: '#/components/schemas/MetricsOverview'
838
+ meta:
839
+ $ref: '#/components/schemas/Meta'
840
+
841
+ BreakdownRow:
842
+ type: object
843
+ description: |
844
+ One row of the `campaign_country_daily` v1.0 schema.
845
+ Primary key: `(provider, account_id, report_date, campaign_id, country_code)`.
846
+ Rows are idempotent — re-ingesting on the primary key is safe.
847
+ Values for a given `report_date` may be revised for up to 7 days after
848
+ the date closes due to delayed events from Meta and Spotify.
849
+ required:
850
+ - provider
851
+ - account_id
852
+ - schema_version
853
+ - report_date
854
+ - report_date_timezone
855
+ - exported_at
856
+ - campaign_id
857
+ - campaign_name
858
+ - campaign_target_type
859
+ - country_code
860
+ - streams
861
+ - listeners
862
+ - followers
863
+ - streams_per_listener
864
+ - spend_media
865
+ - spend_total
866
+ - fees
867
+ - currency
868
+ - currency_account
869
+ - cpl
870
+ - cpf
871
+ - cost_per_result
872
+ properties:
873
+ provider:
874
+ type: string
875
+ enum: [soundlink]
876
+ description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
877
+ account_id:
878
+ type: string
879
+ description: Soundlink organization ID (UUID).
880
+ schema_version:
881
+ type: string
882
+ description: Schema version. Pin your ingest pipeline to this value.
883
+ example: '1.0'
884
+ report_date:
885
+ type: string
886
+ format: date
887
+ description: UTC calendar date the metrics belong to (`YYYY-MM-DD`).
888
+ report_date_timezone:
889
+ type: string
890
+ enum: [UTC]
891
+ description: Always `UTC`.
892
+ exported_at:
893
+ type: string
894
+ format: date-time
895
+ description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
896
+ campaign_id:
897
+ type: string
898
+ description: Soundlink campaign UUID. Stable for the lifetime of the campaign.
899
+ campaign_name:
900
+ type: string
901
+ description: Human-readable campaign name.
902
+ campaign_target_type:
903
+ type: string
904
+ nullable: true
905
+ enum: [track, playlist]
906
+ description: Whether this campaign promotes a track or playlist. `null` if undetermined.
907
+ campaign_target_isrc:
908
+ type: string
909
+ nullable: true
910
+ description: ISRC of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
911
+ campaign_target_spotify_track_id:
912
+ type: string
913
+ nullable: true
914
+ description: Spotify track ID of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
915
+ campaign_target_playlist_id:
916
+ type: string
917
+ nullable: true
918
+ description: Spotify playlist ID. Populated when `campaign_target_type = playlist`; otherwise `null`.
919
+ country_code:
920
+ type: string
921
+ description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
922
+ impressions:
923
+ type: integer
924
+ nullable: true
925
+ description: Total Meta ad impressions served in this country on this day.
926
+ ad_clicks:
927
+ type: integer
928
+ nullable: true
929
+ description: Total clicks on the Meta ad (all click types). Use `ctr_adclick` for ad-level CTR.
930
+ link_clicks:
931
+ type: integer
932
+ nullable: true
933
+ description: Clicks on "Continue with Spotify" on the Soundlink landing page. Use `cpc_linkclick` / `ctr_linkclick` for outbound CPC/CTR.
934
+ streams:
935
+ type: integer
936
+ description: Spotify streams attributed to this campaign in this country on this day (7-day click-through window). Observed events, not modelled estimates.
937
+ listeners:
938
+ type: integer
939
+ 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.
940
+ followers:
941
+ type: integer
942
+ description: Spotify artist follower gains attributed to this campaign in this country on this day (7-day click-through window).
943
+ streams_per_listener:
944
+ type: number
945
+ description: streams / listeners for this row. Zero if listeners is zero.
946
+ spend_media:
947
+ type: number
948
+ description: Amount billed to Meta for ad delivery in this country on this day. Excludes Soundlink service fees. In `currency`.
949
+ spend_total:
950
+ type: number
951
+ description: Total billed by Soundlink (spend_media + fees). Computed as `spend_media / (1 - fee_pct)`.
952
+ fees:
953
+ type: number
954
+ description: Soundlink service fee (spend_total - spend_media).
955
+ currency:
956
+ type: string
957
+ description: Currency for spend fields. Currently always `USD`.
958
+ currency_account:
959
+ type: string
960
+ description: Account billing currency. Currently always `USD`. Will differ from `currency` once EUR delivery is available.
961
+ cpl:
962
+ type: number
963
+ description: Cost per listener (spend_media / listeners). Zero if listeners is zero.
964
+ cpf:
965
+ type: number
966
+ description: Cost per follower (spend_media / followers). Zero if followers is zero.
967
+ cpc_linkclick:
968
+ type: number
969
+ nullable: true
970
+ description: Cost per outbound click (spend_media / link_clicks). Null if link_clicks is null or zero.
971
+ ctr_linkclick:
972
+ type: number
973
+ nullable: true
974
+ description: Outbound CTR (link_clicks / impressions). Null if impressions is null or zero.
975
+ ctr_adclick:
976
+ type: number
977
+ nullable: true
978
+ description: Meta ad CTR (ad_clicks / impressions). Null if impressions is null or zero.
979
+ cost_per_result:
980
+ type: number
981
+ description: Cost per primary campaign result. Currently equivalent to `cpf` (cost per follower). See `result_type`.
982
+ result_type:
983
+ type: string
984
+ nullable: true
985
+ enum: [lp_click, stream, follow]
986
+ description: The conversion event used for `cost_per_result`. Currently always `follow`.
987
+
988
+ MetricsBreakdownResponse:
989
+ type: object
990
+ required: [data, meta]
991
+ properties:
992
+ data:
993
+ type: object
994
+ required: [schemaVersion, items, pagination]
995
+ properties:
996
+ schemaVersion:
997
+ type: string
998
+ description: Version of the `campaign_country_daily` row schema. Pin your ingest pipeline to this.
999
+ example: '1.0'
1000
+ items:
1001
+ type: array
1002
+ items:
1003
+ $ref: '#/components/schemas/BreakdownRow'
1004
+ pagination:
1005
+ $ref: '#/components/schemas/Pagination'
1006
+ meta:
1007
+ $ref: '#/components/schemas/Meta'
1008
+
1009
+ # --- Engagement ---
1010
+
1011
+ EngagementRow:
1012
+ type: object
1013
+ description: |
1014
+ One row of the `campaign_engagement_daily` v1.0 schema.
1015
+ Primary key: `(provider, account_id, report_date, campaign_id, engagement_context, country_code, engaged_spotify_track_id)`.
1016
+ Rows are idempotent — re-ingesting on the primary key is safe.
1017
+ Values for a given `report_date` may be revised for up to 7 days after
1018
+ the date closes due to delayed Spotify playback events.
1019
+ required:
1020
+ - provider
1021
+ - account_id
1022
+ - schema_version
1023
+ - report_date
1024
+ - report_date_timezone
1025
+ - exported_at
1026
+ - campaign_id
1027
+ - campaign_name
1028
+ - campaign_target_type
1029
+ - status
1030
+ - engagement_context
1031
+ - country_code
1032
+ - engaged_spotify_track_id
1033
+ - engaged_track_name
1034
+ - new_listeners
1035
+ - returning_listeners
1036
+ - listeners
1037
+ - new_listener_streams
1038
+ - returning_listener_streams
1039
+ - streams
1040
+ - spl
1041
+ properties:
1042
+ provider:
1043
+ type: string
1044
+ enum: [soundlink]
1045
+ description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
1046
+ account_id:
1047
+ type: string
1048
+ description: Soundlink organization ID (UUID).
1049
+ schema_version:
1050
+ type: string
1051
+ description: Schema version string. Pin your ingest pipeline to this value.
1052
+ example: '1.0'
1053
+ report_date:
1054
+ type: string
1055
+ format: date
1056
+ description: UTC calendar date the metrics belong to (`YYYY-MM-DD`). Rows can change for up to 7 days after close.
1057
+ report_date_timezone:
1058
+ type: string
1059
+ enum: [UTC]
1060
+ description: Always `UTC`.
1061
+ exported_at:
1062
+ type: string
1063
+ format: date-time
1064
+ description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
1065
+ campaign_id:
1066
+ type: string
1067
+ description: Soundlink campaign UUID. Stable for the lifetime of the campaign.
1068
+ campaign_name:
1069
+ type: string
1070
+ description: Human-readable campaign name.
1071
+ campaign_target_type:
1072
+ type: string
1073
+ nullable: true
1074
+ enum: [track, playlist]
1075
+ description: Whether this campaign promotes a track or a playlist. `null` if undetermined.
1076
+ campaign_target_isrc:
1077
+ type: string
1078
+ nullable: true
1079
+ description: ISRC of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
1080
+ campaign_target_spotify_track_id:
1081
+ type: string
1082
+ nullable: true
1083
+ description: Spotify track ID of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
1084
+ campaign_target_playlist_id:
1085
+ type: string
1086
+ nullable: true
1087
+ description: Spotify playlist ID. Populated when `campaign_target_type = playlist`; otherwise `null`.
1088
+ status:
1089
+ type: string
1090
+ enum: [active, ended, scheduled]
1091
+ description: |
1092
+ Campaign lifecycle status on `report_date`.
1093
+ `active` = campaign was running; `ended` = campaign had ended or was refunded;
1094
+ `scheduled` = `report_date` is before campaign start.
1095
+ Post-campaign rows will have `status = ended`.
1096
+ engagement_context:
1097
+ type: string
1098
+ enum: [catalog, playlist]
1099
+ description: |
1100
+ Which dashboard section the row maps to.
1101
+ `catalog` = same-artist spillover (and direct promoted-track plays) on track campaigns.
1102
+ `playlist` = per-track performance inside the promoted playlist on playlist campaigns.
1103
+ country_code:
1104
+ type: string
1105
+ description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
1106
+ example: US
1107
+ engaged_track_isrc:
1108
+ type: string
1109
+ nullable: true
1110
+ description: |
1111
+ ISRC of the track that received listens. May differ from `campaign_target_isrc`
1112
+ for catalog spillover rows. `null` if ISRC could not be resolved.
1113
+ engaged_spotify_track_id:
1114
+ type: string
1115
+ description: |
1116
+ Stable track identifier used in the primary key. Currently this is the
1117
+ Spotify track ID for the engaged track.
1118
+ example: 4cOdK2wGLETKBW3PvgPWqT
1119
+ engaged_track_name:
1120
+ type: string
1121
+ description: Display name of the engaged track.
1122
+ playlist_position:
1123
+ type: integer
1124
+ nullable: true
1125
+ minimum: 1
1126
+ description: |
1127
+ 1-based slot index of the engaged track in the promoted playlist on `report_date`.
1128
+ Populated for `engagement_context = playlist` when playlist snapshot data is available.
1129
+ `null` for catalog rows and until position data is delivered (reserved for future delivery in v1.0).
1130
+ new_listeners:
1131
+ type: integer
1132
+ minimum: 0
1133
+ description: Unique listeners whose first play of this track on this smart link occurred on `report_date`.
1134
+ returning_listeners:
1135
+ type: integer
1136
+ minimum: 0
1137
+ description: Unique listeners who played this track on `report_date` but whose first play was on an earlier date.
1138
+ listeners:
1139
+ type: integer
1140
+ minimum: 0
1141
+ description: |
1142
+ Total unique listeners on `report_date`: `new_listeners + returning_listeners`.
1143
+ **Do not sum across days** — the same listener can appear on multiple `report_date` rows.
1144
+ new_listener_streams:
1145
+ type: integer
1146
+ minimum: 0
1147
+ description: Stream count from new listeners on `report_date`.
1148
+ returning_listener_streams:
1149
+ type: integer
1150
+ minimum: 0
1151
+ description: Stream count from returning listeners on `report_date`.
1152
+ streams:
1153
+ type: integer
1154
+ minimum: 0
1155
+ description: |
1156
+ Total streams on `report_date`: `new_listener_streams + returning_listener_streams`.
1157
+ Safe to sum within a day; summing across days counts repeat listens.
1158
+ spl:
1159
+ type: number
1160
+ description: Streams per listener (`streams / listeners`). Zero if `listeners` is zero.
1161
+
1162
+ EngagementBreakdownResponse:
1163
+ type: object
1164
+ required: [data, meta]
1165
+ properties:
1166
+ data:
1167
+ type: object
1168
+ required: [schemaVersion, items, pagination]
1169
+ properties:
1170
+ schemaVersion:
1171
+ type: string
1172
+ description: Version of the `campaign_engagement_daily` row schema. Pin your ingest pipeline to this.
1173
+ example: '1.0'
1174
+ items:
1175
+ type: array
1176
+ items:
1177
+ $ref: '#/components/schemas/EngagementRow'
1178
+ pagination:
1179
+ $ref: '#/components/schemas/Pagination'
1180
+ meta:
1181
+ $ref: '#/components/schemas/Meta'
1182
+
1183
+ responses:
1184
+ BadRequest:
1185
+ description: Invalid query parameter or date range
1186
+ content:
1187
+ application/json:
1188
+ schema:
1189
+ $ref: '#/components/schemas/ErrorResponse'
1190
+ examples:
1191
+ invalid_query_parameter:
1192
+ value:
1193
+ error:
1194
+ code: invalid_query_parameter
1195
+ message: 'pageSize must be an integer between 1 and 500.'
1196
+ meta:
1197
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1198
+ invalid_date_range:
1199
+ value:
1200
+ error:
1201
+ code: invalid_date_range
1202
+ message: 'endDate must not be before startDate.'
1203
+ meta:
1204
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1205
+
1206
+ Unauthorized:
1207
+ description: Missing, malformed, revoked, or expired API key
1208
+ headers:
1209
+ Retry-After:
1210
+ schema:
1211
+ type: integer
1212
+ description: Present only on `rate_limit_exceeded`
1213
+ content:
1214
+ application/json:
1215
+ schema:
1216
+ $ref: '#/components/schemas/ErrorResponse'
1217
+ examples:
1218
+ invalid_api_key:
1219
+ value:
1220
+ error:
1221
+ code: invalid_api_key
1222
+ message: 'Authorization header is missing or malformed.'
1223
+ meta:
1224
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1225
+ api_key_revoked:
1226
+ value:
1227
+ error:
1228
+ code: api_key_revoked
1229
+ message: 'This API key has been revoked. Contact Soundlink Engineering to mint a new key.'
1230
+ meta:
1231
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1232
+
1233
+ Forbidden:
1234
+ description: Valid key but missing required scope
1235
+ content:
1236
+ application/json:
1237
+ schema:
1238
+ $ref: '#/components/schemas/ErrorResponse'
1239
+ example:
1240
+ error:
1241
+ code: insufficient_scope
1242
+ message: 'This key does not have the metrics:read scope.'
1243
+ meta:
1244
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1245
+
1246
+ NotFound:
1247
+ description: Campaign not found, belongs to another org, or feature flag is off
1248
+ content:
1249
+ application/json:
1250
+ schema:
1251
+ $ref: '#/components/schemas/ErrorResponse'
1252
+ example:
1253
+ error:
1254
+ code: campaign_not_found
1255
+ message: 'Campaign not found.'
1256
+ meta:
1257
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1258
+
1259
+ RateLimited:
1260
+ description: Per-key rate limit exceeded (60/min, 600/hr)
1261
+ headers:
1262
+ Retry-After:
1263
+ required: true
1264
+ schema:
1265
+ type: integer
1266
+ description: Seconds until the rate limit resets
1267
+ content:
1268
+ application/json:
1269
+ schema:
1270
+ $ref: '#/components/schemas/ErrorResponse'
1271
+ example:
1272
+ error:
1273
+ code: rate_limit_exceeded
1274
+ message: 'Rate limit exceeded. Retry after the number of seconds indicated in the Retry-After header.'
1275
+ meta:
1276
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1277
+
1278
+ InternalError:
1279
+ description: Unexpected server error
1280
+ content:
1281
+ application/json:
1282
+ schema:
1283
+ $ref: '#/components/schemas/ErrorResponse'
1284
+ example:
1285
+ error:
1286
+ code: internal_error
1287
+ message: 'An unexpected error occurred. Contact support with the requestId.'
1288
+ meta:
1289
+ requestId: 550e8400-e29b-41d4-a716-446655440000