# Soundlink API

## Docs

- [Introduction](https://www.getsoundlink.com/docs/index.md): Soundlink documentation — learn the product and integrate the Public API.
- [For Developers](https://www.getsoundlink.com/docs/developers.md): Sync Soundlink campaigns and metrics into your tools, warehouses, and apps.
- [Quickstart](https://www.getsoundlink.com/docs/quickstart.md): Create an API key in Soundlink, verify it with ping, and fetch your first campaign list.
- [Authentication](https://www.getsoundlink.com/docs/authentication.md): Create API keys in Soundlink, then use them with scopes, expiration, and Authorization Bearer.
- [Errors](https://www.getsoundlink.com/docs/errors.md): Standard error codes and HTTP status mapping for the Public API v1.
- [Overview](https://www.getsoundlink.com/docs/sdks.md): When to use the TypeScript SDK vs raw HTTP for the Soundlink Public API.
- [Access the API with TypeScript](https://www.getsoundlink.com/docs/typescript-sdk.md): Install the soundlink SDK and call campaigns, write methods, and metrics from Node.js or Edge.
- [Syncing campaigns](https://www.getsoundlink.com/docs/syncing-campaigns.md): List and detail endpoints for keeping your campaign catalog in sync.
- [Creating campaigns](https://www.getsoundlink.com/docs/creating-campaigns.md): Create wallet-funded campaigns via the API — strategies, budget rules, creatives, tier targeting, and idempotent retries.
- [Managing campaigns](https://www.getsoundlink.com/docs/managing-campaigns.md): Increase or decrease budget, update geographic tiers, and stop wallet campaigns via the API.
- [Importing videos](https://www.getsoundlink.com/docs/importing-videos.md): Build your organization's video library via the API — import MP4s by URL, poll processing status, and use videoIds in campaigns.
- [Understanding metrics](https://www.getsoundlink.com/docs/understanding-metrics.md): When to use overview, breakdown, and engagement endpoints.
- [Playlist position](https://www.getsoundlink.com/docs/playlist-position.md): Read daily track positions on playlist campaigns from the engagement export.
- [JSONL exports](https://www.getsoundlink.com/docs/jsonl-exports.md): Bulk metrics downloads for data pipelines without pagination.
- [Soundlink OAuth Integration](https://www.getsoundlink.com/docs/set-up-soundlink-oauth.md): Connect your application to a Soundlink organization using Authorization Code + PKCE, then keep access with Client Credentials.
- [OAuth: Authorization Code + PKCE](https://www.getsoundlink.com/docs/oauth-authorization-code.md): Connect a user's Soundlink organization to your app with the Authorization Code + PKCE grant, then read their identity via userinfo.
- [OAuth: Client Credentials](https://www.getsoundlink.com/docs/oauth-client-credentials.md): Mint unattended access tokens for an organization that already granted consent, and revoke a grant when the integration ends.
- [OAuth: Scopes, Endpoints & Errors](https://www.getsoundlink.com/docs/oauth-scopes-and-errors.md): Which OAuth scope unlocks which resource endpoint, the OAuth and resource error shapes, and a security checklist for your integration.
- [Introduction](https://www.getsoundlink.com/docs/learn/index.md): Learn how Soundlink works — billing, campaigns, and workspace features for artists and labels.
- [Credit wallet](https://www.getsoundlink.com/docs/learn/wallet/index.md): Prepaid workspace balance you use to fund Soundlink campaigns without paying by card for every cycle.
- [Balance & ledger](https://www.getsoundlink.com/docs/learn/wallet/balance-and-ledger.md): How your credit wallet balance works and how to read transaction history.
- [Payment methods](https://www.getsoundlink.com/docs/learn/wallet/payment-methods.md): Save and manage payment methods for wallet top-ups and auto-recharge.
- [Auto-recharge](https://www.getsoundlink.com/docs/learn/wallet/auto-recharge.md): Automatically top up your credit wallet when balance is insufficient for renewals.
- [Top up](https://www.getsoundlink.com/docs/learn/wallet/top-up.md): Add credits to your workspace credit wallet with a one-time payment from a saved payment method.
- [Paying for campaigns](https://www.getsoundlink.com/docs/learn/wallet/paying-for-campaigns.md): New paid growth campaigns are funded from your credit wallet. Top up if balance is short; keep a backup card for renewals.
- [Renewals](https://www.getsoundlink.com/docs/learn/wallet/renewals.md): How wallet campaigns renew, auto-renew, auto-recharge fallback, failed renewals, and upcoming renewals.
- [Campaign budget changes](https://www.getsoundlink.com/docs/learn/wallet/campaign-budget-top-up.md): Raise or lower daily budget on an active wallet campaign using credits from your wallet.
- [Limitations & edge cases](https://www.getsoundlink.com/docs/learn/wallet/limitations-and-edge-cases.md): Rules, campaign statuses, refunds, and situations you should know about when using the credit wallet.
- [Verify connectivity and authentication](https://www.getsoundlink.com/docs/api-reference/system/verify-connectivity-and-authentication.md): Returns `{ "status": "ok" }` if the request is authenticated and the API is reachable. Useful for verifying a newly issued key before making data requests.
- [List campaign strategy types](https://www.getsoundlink.com/docs/api-reference/campaigns/list-campaign-strategy-types.md): Returns the static catalog of `strategyType` values accepted by `POST /v1/campaigns`. Built-in strategies apply platform default tiering internally; only `custom` allows `tierTargeting` on create.
- [List campaigns](https://www.getsoundlink.com/docs/api-reference/campaigns/list-campaigns.md): Returns all campaigns for the authenticated organization. Intended for reporting and data warehouse sync.
- [Create a wallet-funded campaign](https://www.getsoundlink.com/docs/api-reference/campaigns/create-a-wallet-funded-campaign.md): Creates a campaign funded from the organization's wallet balance. Requires the `campaigns:write` scope, and the organization must be enabled for wallet billing.
- [Get campaign](https://www.getsoundlink.com/docs/api-reference/campaigns/get-campaign.md): Fetch full details for a single campaign.
- [Stop a wallet campaign and refund unspent budget](https://www.getsoundlink.com/docs/api-reference/campaigns/stop-a-wallet-campaign-and-refund-unspent-budget.md): Stops delivery for a wallet-funded campaign and refunds unspent budget to the organization wallet. Requires the `campaigns:write` scope.
- [Increase wallet campaign budget](https://www.getsoundlink.com/docs/api-reference/campaigns/increase-wallet-campaign-budget.md): Raises budget for a wallet-funded campaign. Requires the `campaigns:write` scope and an `Idempotency-Key` header.
- [Decrease wallet campaign daily budget](https://www.getsoundlink.com/docs/api-reference/campaigns/decrease-wallet-campaign-daily-budget.md): Lowers the daily budget for a wallet-funded campaign to `targetDailyBudget`. Requires the `campaigns:write` scope and an `Idempotency-Key` header.
- [Get campaign tier allocation](https://www.getsoundlink.com/docs/api-reference/campaigns/get-campaign-tier-allocation.md): Returns the current geographic tier allocation for a wallet campaign: which tiers are enabled, their budget share, and when tiers were last updated (`lastUpdate`). Use this before `PATCH` to build a valid request.
- [Update campaign tier allocation](https://www.getsoundlink.com/docs/api-reference/campaigns/update-campaign-tier-allocation.md): Enable or disable geographic tiers and optionally reallocate budget shares for a wallet campaign.
- [Campaign metrics overview](https://www.getsoundlink.com/docs/api-reference/metrics/campaign-metrics-overview.md): Campaign-level totals for a date range: spend, conversions, listeners, streams, followers, and derived ratios. No per-day rows — use `/metrics/breakdown` for those.
- [Campaign metrics breakdown](https://www.getsoundlink.com/docs/api-reference/metrics/campaign-metrics-breakdown.md): Per-day metrics broken down by country. One row per `(report_date, campaign_id, country_code)`. Can be large, so results are paginated.
- [Campaign metrics breakdown export (JSONL)](https://www.getsoundlink.com/docs/api-reference/metrics/campaign-metrics-breakdown-export-jsonl.md): Streams the full country-level metrics dataset for a campaign as **newline-delimited JSON (JSONL)**. Every line is a complete, valid JSON object conforming to the `campaign_country_daily` v1.0 schema — identical to the rows returned by `GET /metrics/breakdown` but without pagination or an envelope w…
- [Campaign engagement export (JSONL)](https://www.getsoundlink.com/docs/api-reference/metrics/campaign-engagement-export-jsonl.md): Streams the full engagement dataset for a campaign as **newline-delimited JSON (JSONL)**. Every line is a complete, valid JSON object conforming to the `campaign_engagement_daily` v1.0 schema.
- [Import a video from a public HTTPS MP4 URL](https://www.getsoundlink.com/docs/api-reference/videos/import-a-video-from-a-public-https-mp4-url.md): Downloads a single public HTTPS MP4, stages it for ingestion, and starts the background video pipeline. Returns `202` while processing, or `200` with `videoId` immediately when the organization already has the same video (content duplicate).
- [Get video import session status](https://www.getsoundlink.com/docs/api-reference/videos/get-video-import-session-status.md): Returns processing status and the resulting `videoId` when ingestion completes. Requires the `videos:write` scope.

## OpenAPI Specs

- [soundlink-public-api-v1](https://www.getsoundlink.com/docs/openapi/soundlink-public-api-v1.yaml)