> ## Documentation Index > Fetch the complete documentation index at: https://www.getsoundlink.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List campaigns > Returns all campaigns for the authenticated organization. Intended for reporting and data warehouse sync. ## OpenAPI ````yaml /openapi/soundlink-public-api-v1.yaml get /v1/campaigns openapi: 3.0.3 info: title: Soundlink Public API version: 0.0.1-draft description: > Campaign listing, metrics, and write operations for Soundlink partner organizations. **Base URL:** `https://api.getsoundlink.com` **Authentication:** send a `sk_*` API key created in the Soundlink app (Settings → Developer → API keys) using one of: 1. **`Authorization: Bearer` (recommended)**: ``` Authorization: Bearer sk_abc123_ ``` 2. **`x-api-key` header (deprecated, retiring 2026-08-17)** — migrate to Bearer above before then: ``` x-api-key: sk_abc123_ ``` Sending both headers returns `401 mixed_credentials`. All responses are wrapped in a standard envelope: ```json { "data": , "meta": { "requestId": "" } } ``` Errors follow the same envelope shape with an `error` field instead of `data`. servers: - url: https://api.getsoundlink.com description: Production security: - apiKeyAuth: [] - apiKeyBearerAuth: [] tags: - name: System description: Connectivity and auth verification - name: Campaigns description: >- Campaign listing, detail, creation, and wallet management (budget, stop, tiers) - name: Metrics description: Campaign performance metrics - name: Videos description: Partner video library import for Full Control campaigns paths: /v1/campaigns: get: tags: - Campaigns summary: List campaigns description: | Returns all campaigns for the authenticated organization. Intended for reporting and data warehouse sync. operationId: listCampaigns parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/pageSize100' - name: sortBy in: query schema: type: string enum: - createdAt default: createdAt - $ref: '#/components/parameters/sortOrder' responses: '200': description: Paginated list of campaigns content: application/json: schema: $ref: '#/components/schemas/CampaignListResponse' example: data: items: - campaignId: f1e28d31-c358-4284-9bef-00a2334625fd organizationId: org_xyz status: active socialPlatform: meta dailyBudget: 20 totalBudget: 140 campaignDuration: 7 createdAt: '2026-04-01T10:00:00Z' updatedAt: '2026-04-08T12:00:00Z' pagination: page: 1 pageSize: 10 totalCount: 42 totalPages: 5 meta: requestId: 550e8400-e29b-41d4-a716-446655440000 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - apiKeyAuth: [] - apiKeyBearerAuth: [] components: parameters: page: name: page in: query schema: type: integer minimum: 1 default: 1 description: Page number (1-indexed) pageSize100: name: pageSize in: query schema: type: integer minimum: 1 maximum: 100 default: 10 description: Items per page (max 100) sortOrder: name: sortOrder in: query schema: type: string enum: - asc - desc default: desc description: Sort direction schemas: CampaignListResponse: type: object required: - data - meta properties: data: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/CampaignSummary' pagination: $ref: '#/components/schemas/Pagination' meta: $ref: '#/components/schemas/Meta' CampaignSummary: type: object required: - campaignId - organizationId - status - socialPlatform - dailyBudget - totalBudget - campaignDuration - generation - createdAt - updatedAt properties: campaignId: type: string organizationId: type: string status: $ref: '#/components/schemas/CampaignStatus' socialPlatform: type: string enum: - meta dailyBudget: type: number description: USD totalBudget: type: number description: USD campaignDuration: type: integer description: Duration in days generation: type: integer enum: - 1 - 2 - 3 description: > Campaign resource generation. `1` = Stripe / one-time / subscription / legacy; `2` = Soundlink managed; `3` = wallet. Public API write operations (budget changes, stop, tier updates) are supported for generation `3` only. createdAt: type: string format: date-time updatedAt: type: string format: date-time Pagination: type: object required: - page - pageSize - totalCount - totalPages properties: page: type: integer pageSize: type: integer totalCount: type: integer totalPages: type: integer Meta: type: object required: - requestId properties: requestId: type: string format: uuid description: Server-generated request ID. Include when contacting support. ErrorResponse: type: object required: - error - meta properties: error: $ref: '#/components/schemas/Error' meta: $ref: '#/components/schemas/Meta' CampaignStatus: type: string enum: - creating - active - paused - stopped - completed - failed - ended Error: type: object required: - code - message properties: code: type: string description: Stable snake_case error code. enum: - invalid_api_key - api_key_revoked - api_key_expired - mixed_credentials - insufficient_scope - not_found - campaign_not_found - invalid_query_parameter - invalid_date_range - page_size_exceeded - invalid_request - invalid_genre - invalid_duration_or_budget - invalid_daily_budget - invalid_duration_days - invalid_spotify_url - invalid_tier_budget_allocation - invalid_tier_status - tier_update_cooldown - wallet_not_enabled - insufficient_credit - idempotency_key_conflict - rate_limit_exceeded - invalid_video_url - video_import_limit_exceeded - video_import_session_not_found - internal_error message: type: string description: Human-readable error description. Do not parse programmatically. details: type: object nullable: true description: | Additive, error-code-specific context (e.g. `available`/`required` on `insufficient_credit`). Absent or `null` for error codes that carry no extra data. additionalProperties: true responses: Unauthorized: description: Missing, malformed, revoked, or expired API key headers: Retry-After: schema: type: integer description: Present only on `rate_limit_exceeded` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_api_key: value: error: code: invalid_api_key message: >- Missing or malformed API key. Expected: sk__ (sent via x-api-key or Authorization: Bearer). meta: requestId: 550e8400-e29b-41d4-a716-446655440000 api_key_revoked: value: error: code: api_key_revoked message: >- This API key has been revoked. Create a new key in Settings → Developer → API keys. meta: requestId: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Valid key but missing required scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: insufficient_scope message: This key does not have the metrics:read scope. meta: requestId: 550e8400-e29b-41d4-a716-446655440000 RateLimited: description: Per-key rate limit exceeded (60/min, 600/hr) headers: Retry-After: required: true schema: type: integer description: Seconds until the rate limit resets content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limit_exceeded message: >- Rate limit exceeded. Retry after the number of seconds indicated in the Retry-After header. meta: requestId: 550e8400-e29b-41d4-a716-446655440000 InternalError: description: Unexpected server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: internal_error message: >- An unexpected error occurred. Contact support with the requestId. meta: requestId: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: > Pass your Soundlink `sk_*` API key in the `x-api-key` header. Keys can carry explicit scopes (for example `campaigns:read`, `metrics:read`, `videos:write`) enforced by the backend. **Deprecated, retiring 2026-08-17** — migrate to `Authorization: Bearer sk_...` (see `apiKeyBearerAuth`) before then. apiKeyBearerAuth: type: http scheme: bearer description: | Pass your Soundlink `sk_*` API key as a Bearer token: `Authorization: Bearer sk__`. Verified with the exact same key as `apiKeyAuth` — just the recommended header for the same `sk_*` credential. Do not combine with `x-api-key`. ````