> ## 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.

# Syncing soundlinks

> List and detail endpoints for soundlinks without a campaign.

Use the Soundlinks API to discover soundlinks that belong to your organization and are **not** tied to a Soundlink-funded campaign. Those soundlinks do not appear in `GET /v1/campaigns`. For paid campaigns, use [Syncing campaigns](/docs/syncing-campaigns).

Requires `soundlinks:read`. See [Authentication](/docs/authentication#scopes-v1). To create or archive a soundlink, see [Creating soundlinks](/docs/creating-soundlinks).

<Note>
  Existing API keys keep the scopes they were minted with. Create a **new** key
  and add `soundlinks:read` to call these routes.
</Note>

Campaign-linked soundlinks are the campaign's underlying resource. List and detail them with the Campaigns API. A campaign-backed `soundlinkId` on these routes returns `404`. Missing `soundlinks:read` returns `403 insufficient_scope`. See [Errors](/docs/errors) for the full list.

## List soundlinks

`GET /v1/soundlinks`

Includes archived rows (`status: archived`). Supports pagination:

| Param      | Default | Max |
| ---------- | ------- | --- |
| `page`     | 1       | —   |
| `pageSize` | 10      | 100 |

`sortBy` is `createdAt`. `soundlinkId` is a URL-safe string — the same ID in the public `sndl.ink` URL — not a campaign UUID.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS 'https://api.getsoundlink.com/v1/soundlinks?page=1&pageSize=100' \
  -H 'Authorization: Bearer sk_YOUR_PREFIX_YOUR_SECRET'
```

Walk pages until `pagination.page >= pagination.totalPages`.

## Soundlink detail

`GET /v1/soundlinks/{soundlinkId}`

Returns catalog fields plus `autoFollow`, `artistIdFollow`, `metaPixelId`, and `tiktokPixelId`. Archived soundlinks still appear (`status: archived`). Unknown, cross-org, or campaign-linked IDs return `404`. The Meta CAPI token is never returned.

Use the `soundlinkId` from the list response in all `/metrics/*` paths.

## Typical sync flow

1. **Daily:** `GET /v1/soundlinks` — upsert catalog
2. **Daily:** [soundlink metrics](/docs/soundlink-metrics) per active soundlink

## Organization scope

Your organization is determined only from the API key (or OAuth token). You never pass an organization id in query params.

* Soundlink **list and detail** JSON uses `organizationId`.
* Metrics JSONL / warehouse rows use `account_id` for the **same** organization UUID. Join catalog to metrics on `soundlink_id`.

<Note>
  Node.js: `soundlink.soundlinks.list` — [TypeScript SDK](/docs/typescript-sdk).
  DuckDB or BigQuery: [warehouse connector](/docs/warehouse-connector).
</Note>

## Next

[Creating soundlinks](/docs/creating-soundlinks) · [Warehouse connector](/docs/warehouse-connector) · [Soundlink metrics](/docs/soundlink-metrics) → [API Reference](/docs/api-reference)