Access the API with TypeScript

Install the official soundlink package to call the Public API with full TypeScript types. For raw HTTP, see Quickstart. Not sure which approach fits your stack? See SDK overview. To run the campaign lifecycle on your machine, see API emulator.

Prerequisites

API key (sk_*) with the scopes you need — Authentication
Node.js 18+ or an Edge runtime with fetch

Store the key in an environment variable (e.g. SOUNDLINK_API_KEY). Never hardcode keys or ship them to the browser.

1. Install

npm install soundlink

yarn add soundlink

pnpm add soundlink

bun add soundlink

2. Initialize the client

import { Soundlink } from "soundlink";

const soundlink = new Soundlink({
  apiKey: process.env.SOUNDLINK_API_KEY!,
});

You can also pass the key as a string: new Soundlink('sk_your_prefix_your_secret'). The client sends Authorization: Bearer on every request. Your organization is determined from the key.

3. Ping and list campaigns

const { data, error, meta } = await soundlink.ping();
if (error) {
  console.error(error.message, meta?.requestId);
  process.exit(1);
}

const { data: campaigns, error: listError } = await soundlink.campaigns.list({
  page: 1,
  pageSize: 100,
  sortBy: "createdAt",
  sortOrder: "desc",
});

if (listError) {
  console.error(listError.code, listError.message);
}

const { data: campaign } = await soundlink.campaigns.get(
  "f1e28d31-c358-4284-9bef-00a2334625fd",
);
// campaign?.generation === 3 → wallet (writable)

List and get require the campaigns:read scope. Equivalent curl examples are in Quickstart.

Paginate all campaigns

for await (const campaign of soundlink.campaigns.listAll({ pageSize: 100 })) {
  console.log(campaign.campaignId, campaign.generation);
}

Create and manage wallet campaigns

Requires campaigns:write. Write methods take { idempotencyKey } — the SDK sends the Idempotency-Key header. Only generation: 3 (wallet) campaigns support budget, tiers, and stop. See Creating campaigns and Managing campaigns.

const { data: catalog } = await soundlink.strategies.list();

const { data: created, error: createError } = await soundlink.campaigns.create(
  {
    spotifyUrl: "https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl",
    dailyBudget: 25,
    durationDays: 14,
    genre: "Pop",
    strategyType: "maximum_growth",
    campaignName: "Summer single push",
  },
  { idempotencyKey: "create-2026-07-21-mytrack-01" },
);

if (createError || !created) {
  console.error(createError?.code, createError?.message);
  return;
}

await soundlink.campaigns.increaseBudget(
  created.campaignId,
  { amount: 100, mode: "current_and_renewals" },
  { idempotencyKey: "budget-inc-01" },
);

// GET returns `tierId` and `learningStatus`. PATCH expects `tierId` as `targetingTierId`.
// Sending the current allocation does not write. To edit while an active tier is
// LEARNING or FAIL, see Managing campaigns for `acknowledgeLearningWarning`.
const { data: tiers } = await soundlink.campaigns.tiers.get(created.campaignId);
await soundlink.campaigns.tiers.update(created.campaignId, {
  items: (tiers?.tiers ?? []).map((tier) => ({
    targetingTierId: tier.tierId,
    isEnabled: tier.isEnabled,
    newAllocationPercent: tier.allocationPercent,
  })),
});

await soundlink.campaigns.stop(created.campaignId, {
  idempotencyKey: "stop-01",
});

Soundlinks (self-serve)

List, get, and metrics require soundlinks:read. Create and delete require soundlinks:write. Returns only soundlinks not linked to a campaign — campaign-backed links use the Campaigns API. Responses have no spend or fee fields (ads run in your Meta account).

const { data: links, error: linksError } = await soundlink.soundlinks.list({
  page: 1,
  pageSize: 100,
  sortBy: "createdAt",
  sortOrder: "desc",
});

if (linksError) {
  console.error(linksError.code, linksError.message);
}

const { data: created, error: createError } = await soundlink.soundlinks.create(
  {
    name: "Midnight Drive",
    spotifyUrl: "https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl",
    appleMusicUrl: "https://music.apple.com/us/song/anti-hero/1645937493",
    youtubeMusicUrl: "https://music.youtube.com/watch?v=dQw4w9WgXcQ",
  },
  { idempotencyKey: "create-midnight-drive-01" },
);

if (createError || !created) {
  console.error(createError?.code, createError?.message);
}

const { data: detail } = await soundlink.soundlinks.get("V1StGXR8_Z5jdHi6B-myT");
// detail?.appleMusicUrl, detail?.youtubeMusicUrl, detail?.attributionEnabled, detail?.streamValueEventEnabled, detail?.autoFollow, detail?.metaPixelId, detail?.tiktokPixelId

const { data: overview } = await soundlink.soundlinks.metricsOverview(
  "V1StGXR8_Z5jdHi6B-myT",
  { startDate: "2026-08-01", endDate: "2026-08-31" },
);

const { data: breakdown } = await soundlink.soundlinks.breakdown.list(
  "V1StGXR8_Z5jdHi6B-myT",
  { startDate: "2026-08-01", endDate: "2026-08-31", pageSize: 50 },
);

Full REST guides: Syncing soundlinks · Soundlink metrics · Creating soundlinks. Scopes: Authentication.

Response pattern

Every method returns { data, error, meta? } — the same envelope as the REST API. HTTP errors are not thrown; check error and use requestId when contacting support.

Do not use try/catch for normal API failures. The SDK only throws for configuration, parse, or transport errors. See Errors below and Errors for API codes.

Campaign metrics and exports

const { data: overview } = await soundlink.metrics.overview(
  "f1e28d31-c358-4284-9bef-00a2334625fd",
  {
    startDate: "2026-01-01",
    endDate: "2026-03-31",
  },
);

const { data: stream } = await soundlink.metrics.breakdown.export(
  "f1e28d31-c358-4284-9bef-00a2334625fd",
  {
    startDate: "2026-01-01",
    endDate: "2026-03-31",
  },
);

if (stream) {
  for await (const row of stream) {
    await warehouse.insert(row);
  }
}

For smaller datasets: await soundlink.metrics.breakdown.export.collect('f1e28d31-c358-4284-9bef-00a2334625fd'). Engagement exports work the same way: soundlink.metrics.engagement.export and .export.collect. See Campaign metrics and JSONL exports.

Configuration

const soundlink = new Soundlink({
  apiKey: process.env.SOUNDLINK_API_KEY!,
  baseUrl: "https://api.getsoundlink.com", // default
  timeout: 30_000,
  maxRetries: 2, // retries on 429/5xx; writes reuse the same Idempotency-Key
  fetch: customFetch, // optional — tests or Edge
});

Methods

Every method maps 1:1 to a Public API route. All return Promise<ApiResponse<T>> unless noted.

System

Method	REST endpoint	Returns
`soundlink.ping()`	`GET /v1/ping`	`ApiResponse<PingData>`

Strategies

Requires campaigns:read.

Method	REST endpoint	Returns
`soundlink.strategies.list()`	`GET /v1/strategies`	`ApiResponse<StrategiesCatalogData>`

Campaigns (read)

Requires campaigns:read.

Method	REST endpoint	Returns
`soundlink.campaigns.list(params?)`	`GET /v1/campaigns`	`ApiResponse<CampaignListData>`
`soundlink.campaigns.get(campaignId)`	`GET /v1/campaigns/{id}`	`ApiResponse<CampaignDetail>`
`soundlink.campaigns.activity(id, params?)`	`GET .../activity`	`ApiResponse<CampaignActivityData>`
`soundlink.campaigns.listAll(params?)`	Paginated `list`	`AsyncGenerator<CampaignSummary>`

list params: page, pageSize (max 100), sortBy (createdAt | status), sortOrder (asc | desc). activity is a page of creative adds, budget changes, and other campaign events. startDate is YYYY-MM-DD (from 00:00:00Z) or an ISO-8601 timestamp. Omit it for the full history. page defaults to 1. pageSize defaults to 20 and maxes at 100. See Activity. For multi-campaign reads, use the REST batch routes in Campaign metrics and Activity.

Campaigns (write)

Requires campaigns:write. Pass { idempotencyKey } on create, stop, and budget methods. Wallet campaigns only (generation: 3) for budget / tiers / stop.

Method	REST endpoint	Returns
`soundlink.campaigns.create(body, { idempotencyKey })`	`POST /v1/campaigns`	`ApiResponse<CampaignCreateData>`
`soundlink.campaigns.stop(id, { idempotencyKey })`	`POST .../stop`	`ApiResponse<CampaignStopData>`
`soundlink.campaigns.increaseBudget(id, body, { idempotencyKey })`	`POST .../budget/increase`	`ApiResponse<IncreaseCampaignBudgetData>`
`soundlink.campaigns.decreaseBudget(id, body, { idempotencyKey })`	`POST .../budget/decrease`	`ApiResponse<DecreaseCampaignBudgetData>`
`soundlink.campaigns.tiers.get(id)`	`GET .../tiers`	`ApiResponse<CampaignTiersData>`
`soundlink.campaigns.tiers.update(id, body)`	`PATCH .../tiers`	`ApiResponse<CampaignTiersData>`

Soundlinks

Requires soundlinks:read. Self-serve soundlinks only (not campaign-linked). Breakdown and engagement helpers require soundlink 2.2.0+.

Method	REST endpoint	Returns
`soundlink.soundlinks.list(params?)`	`GET /v1/soundlinks`	`ApiResponse<SoundlinkListData>`
`soundlink.soundlinks.get(soundlinkId)`	`GET /v1/soundlinks/{id}`	`ApiResponse<SoundlinkDetail>`
`soundlink.soundlinks.create(body, { idempotencyKey })`	`POST /v1/soundlinks`	`ApiResponse<SoundlinkDetail>`
`soundlink.soundlinks.delete(soundlinkId)`	`DELETE /v1/soundlinks/{id}`	`ApiResponse<SoundlinkDetail>`
`soundlink.soundlinks.metricsOverview(id, params?)`	`GET .../metrics/overview`	`ApiResponse<SoundlinkMetricsOverview>`
`soundlink.soundlinks.breakdown.list(id, params?)`	`GET .../metrics/breakdown`	`ApiResponse<SoundlinkBreakdownListData>`
`soundlink.soundlinks.breakdown.export(id, params?)`	`GET .../metrics/breakdown/export`	`ApiResponse<JsonlStream<SoundlinkBreakdownRow>>`
`soundlink.soundlinks.breakdown.export.collect(id, params?)`	Same export route	`ApiResponse<ExportCollection<SoundlinkBreakdownRow>>`
`soundlink.soundlinks.engagement.list(id, params?)`	`GET .../metrics/engagement`	`ApiResponse<SoundlinkEngagementListData>`
`soundlink.soundlinks.engagement.export(id, params?)`	`GET .../metrics/engagement/export`	`ApiResponse<JsonlStream<SoundlinkEngagementRow>>`
`soundlink.soundlinks.engagement.export.collect(id, params?)`	Same export route	`ApiResponse<ExportCollection<SoundlinkEngagementRow>>`

list params: page, pageSize (max 100), sortBy (createdAt), sortOrder (asc | desc). Breakdown and engagement list pageSize max is 500. Export windows are capped at 90 days per request. create requires soundlinks:write and { idempotencyKey }. Optional appleMusicUrl and youtubeMusicUrl are HTTPS song or playlist URLs. Songs and catalog playlists are checked with the provider; missing content returns 400 invalid_request. An Apple library playlist is format-checked only, and an Apple album share-sheet link (?i=) is stored as the canonical song URL. Optional attributionEnabled defaults to true; false skips Spotify login and cannot be combined with autoFollow: true. Optional streamValueEventEnabled defaults to false. true turns on Soundlink Stream Value when your organization is already enabled for it, and cannot be combined with attributionEnabled: false. Otherwise create returns 403 stream_value_not_enabled. Detail returns the music URLs, attributionEnabled, and streamValueEventEnabled. List items do not include them. delete archives the soundlink and does not send Idempotency-Key. URL rules: Creating soundlinks.

Campaign metrics

Requires metrics:read.

Method	REST endpoint	Returns
`soundlink.metrics.overview(id, params?)`	`GET .../metrics/overview`	`ApiResponse<MetricsOverview>`
`soundlink.metrics.creatives(id)`	`GET .../metrics/creatives`	`ApiResponse<CreativeMetrics>`
`soundlink.metrics.creativeDaily(id, params?)`	`GET .../metrics/creative-daily`	`ApiResponse<CreativeDailyData>`
`soundlink.metrics.breakdown.list(id, params?)`	`GET .../metrics/breakdown`	`ApiResponse<BreakdownListData>`
`soundlink.metrics.breakdown.export(id, params?)`	`GET .../metrics/breakdown/export`	`ApiResponse<JsonlStream<BreakdownRow>>`
`soundlink.metrics.breakdown.export.collect(id, params?)`	Same export route	`ApiResponse<ExportCollection<BreakdownRow>>`
`soundlink.metrics.engagement.export(id, params?)`	`GET .../metrics/engagement/export`	`ApiResponse<JsonlStream<EngagementRow>>`
`soundlink.metrics.engagement.export.collect(id, params?)`	Same export route	`ApiResponse<ExportCollection<EngagementRow>>`

Date params use inclusive YYYY-MM-DD. Export windows are capped at 90 days per request. Breakdown list pageSize max is 500. Paginated campaign engagement (GET .../metrics/engagement) is not in the SDK — use the HTTP path in Campaign metrics. creatives is a lifetime snapshot grouped by background video. Each child has the audio cut as timestamp_start_ms and timestamp_end_ms (both null when the cut is not a ready sound). It rejects dates. creativeDaily is one row per day and Meta ad creative: spend_media, impressions, followers, and cpf. cpf is null when followers is zero. pageSize defaults to 50 and maxes at 500. Omit both dates for every day that has rows. See Creative daily.

Types

All public types are exported from soundlink for use in your app:

import type {
  ApiResponse,
  ApiError,
  ApiMeta,
  PingData,
  CampaignSummary,
  CampaignDetail,
  CampaignGeneration,
  CampaignListData,
  CampaignListParams,
  CreateCampaignRequest,
  CampaignCreateData,
  StrategiesCatalogData,
  SoundlinkSummary,
  SoundlinkDetail,
  SoundlinkListData,
  SoundlinkListParams,
  SoundlinkMetricsOverview,
  SoundlinkBreakdownRow,
  SoundlinkBreakdownListData,
  SoundlinkEngagementRow,
  SoundlinkEngagementListData,
  MetricsOverview,
  BreakdownRow,
  BreakdownListData,
  BreakdownListParams,
  BreakdownExportParams,
  EngagementRow,
  EngagementExportParams,
  ExportCollection,
  JsonlStream,
  SoundlinkClientOptions,
  PublicApiErrorCode,
} from "soundlink";

Group	Types
Envelope	`ApiResponse<T>`, `ApiError`, `ApiMeta`, `PublicApiErrorCode`
Campaigns	`CampaignSummary`, `CampaignDetail`, `CampaignActivityItem`, `CampaignGeneration`, `CreateCampaignRequest`, `CampaignStatus`
Soundlinks	`SoundlinkSummary`, `SoundlinkDetail`, `SoundlinkListData`, `SoundlinkMetricsOverview`, `SoundlinkBreakdownRow`, `SoundlinkEngagementRow`
Strategies	`StrategiesCatalogData`, `StrategyCatalogItem`, `StrategyType`
Campaign metrics	`MetricsOverview`, `CreativeMetrics`, `CreativeDailyRow`, `BreakdownRow`, `BreakdownListData`, `EngagementRow`
Params	`DateRangeParams`, `SoundlinkListParams`, `SoundlinkBreakdownListParams`, `SoundlinkEngagementListParams`, `BreakdownListParams`, `BreakdownExportParams`, `EngagementExportParams`, `IdempotencyOptions`
Exports	`JsonlStream<T>`, `ExportCollection<T>`
Client	`Soundlink`, `SoundlinkClientOptions`

Row shapes match the warehouse schemas documented in Campaign metrics. For full field lists, use the API Reference or your IDE hover hints on the imported types.

Errors

The SDK has two error paths. Most of the time you only need the first.

API errors (returned, not thrown)

When the Public API returns 4xx or 5xx, the SDK resolves with { data: null, error, meta? }:

const { data, error, meta } = await soundlink.campaigns.get("camp_unknown");

if (error) {
  // error.code    — e.g. 'campaign_not_found'
  // error.message — human-readable
  // error.status  — HTTP status (404, 429, …)
  // error.requestId — same as meta?.requestId
  // error.retryAfter — seconds, on 429 only
  // error.details — code-specific context when present
  //                 (e.g. available/required on insufficient_credit)

  if (error.code === "rate_limit_exceeded" && error.retryAfter) {
    await sleep(error.retryAfter * 1000);
  }

  if (error.code === "insufficient_credit") {
    console.error("wallet", error.details);
  }
}

Always check error before using data. Error codes and HTTP mapping: Errors.

SDK errors (thrown)

These extend SoundlinkSdkError and mean something went wrong outside a normal API response:

Class	When
`SoundlinkConfigError`	Missing or invalid API key at construction
`SoundlinkParseError`	Response body could not be parsed
`SoundlinkSdkError`	Unexpected transport failure

import { Soundlink, SoundlinkConfigError } from "soundlink";

try {
  const soundlink = new Soundlink({ apiKey: "" }); // throws SoundlinkConfigError
} catch (err) {
  if (err instanceof SoundlinkConfigError) {
    console.error("Fix your API key configuration");
  }
}

Use try/catch for client setup and rare transport failures. Use { data, error } for everything the API returns.

Syncing soundlinks → Creating soundlinks → Creating campaigns → Managing campaigns → Campaign metrics

Get started

AI tools

For Developers

Learn

Access the API with TypeScript

Prerequisites

1. Install

2. Initialize the client

3. Ping and list campaigns

Paginate all campaigns

Create and manage wallet campaigns

Soundlinks (self-serve)

Response pattern

Campaign metrics and exports

Configuration

Methods

System

Strategies

Campaigns (read)

Campaigns (write)

Soundlinks

Campaign metrics

Types

Errors

API errors (returned, not thrown)

SDK errors (thrown)

Next