> ## 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. # Save an organization pixel > Saves the Conversions API access token and/or default flag for `pixelId`. The same call creates the pixel or rotates its token, and both return `200`: - No Meta pixel yet: the pixel is saved (`accessToken` required). - `pixelId` matches a Meta pixel the organization already has: its access token is replaced when `accessToken` is sent. - A different Meta pixel for the same organization: the new pixel is saved alongside existing ones. - The pixel is configured by another organization: `409 meta_pixel_conflict`. - The access token is already used with another pixel: `400 invalid_request`. - `platform` other than `meta`: `400 invalid_request`. - Optional `isDefault` sets or clears the org default for Meta. At least one of `accessToken` or `isDefault` is required. The response never includes the access token. Use `POST /v1/pixels/{pixelId}/test-events` to check the pixel and token. Requires `pixels:write`. Organizations without custom pixels enabled get `403 custom_pixel_not_enabled`. Does not require `Idempotency-Key`; repeating the same request is safe. **Auth:** Accepts API key or OAuth Bearer (`pixels:write`). ## OpenAPI ````yaml /openapi/soundlink-public-api-v1.yaml put /v1/pixels/{pixelId} 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 `Authorization: Bearer` with one of: 1. **API key (recommended)** — a `sk_*` key from the Soundlink app (Settings → Developer → API keys): ``` Authorization: Bearer sk_abc123_ ``` 2. **OAuth Bearer** — an access token from Sign in with Soundlink (authorization code or client credentials). Token scopes use the same strings as Public API key scopes (for example `campaigns:read`, `metrics:read`): ``` Authorization: Bearer ``` `x-api-key` is no longer accepted and is ignored if sent. Requests without `Authorization: Bearer` return `401 invalid_api_key` (or `401 invalid_token` when a Bearer value is present but neither a recognized `sk_*` key nor a valid OAuth access token). ### Which operations accept OAuth? | Operations | Required scope | Auth | | --- | --- | --- | | `GET /v1/ping` | any granted Public API scope | API key (Bearer) or OAuth Bearer | | Campaign reads (`GET /v1/strategies`, `GET /v1/campaigns`, campaign detail, tiers) | `campaigns:read` | API key (Bearer) or OAuth Bearer | | Metrics reads (overview, breakdown, exports) | `metrics:read` | API key (Bearer) or OAuth Bearer | | Campaign listening insights + campaign cohort retention (**Label / Enterprise / committed / self-serve**) | `metrics:read` | API key (Bearer) or OAuth Bearer | | Campaign writes (create, stop, budget, tier updates) | `campaigns:write` | API key (Bearer) or OAuth Bearer | | Pixel reads (`GET /v1/pixels`) | `pixels:read` | API key (Bearer) or OAuth Bearer | | Pixel writes (save pixel, test events) | `pixels:write` | API key (Bearer) or OAuth Bearer | | Video import / import status | `videos:write` | API key (Bearer) or OAuth Bearer | | Soundlink reads (list, detail, metrics overview/breakdown/engagement, JSONL exports) | `soundlinks:read` | API key (Bearer) or OAuth Bearer | | Soundlink listening insights + soundlink cohort retention (**Label / Enterprise / committed / self-serve**) | `soundlinks:read` | API key (Bearer) or OAuth Bearer | | Soundlink writes (create, archive, test events) | `soundlinks:write` | API key (Bearer) or OAuth Bearer | | Wallet read (`GET /v1/wallet`) | `wallet:read` | API key (Bearer) or OAuth Bearer | Per-operation scope requirements are also marked with `x-required-scope` (except `GET /v1/ping`, which accepts any valid credential with at least one Public API scope granted to the key/token). 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: - apiKeyBearerAuth: [] - oauthBearer: [] tags: - name: System description: Connectivity and auth verification - name: Wallet description: Organization wallet balance - name: Pixels description: Organization ad pixels that receive a copy of Soundlink conversion events - 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 - name: Soundlinks description: Soundlink listing, detail, creation, archive, and performance metrics paths: /v1/pixels/{pixelId}: put: tags: - Pixels summary: Save an organization pixel description: | Saves the Conversions API access token and/or default flag for `pixelId`. The same call creates the pixel or rotates its token, and both return `200`: - No Meta pixel yet: the pixel is saved (`accessToken` required). - `pixelId` matches a Meta pixel the organization already has: its access token is replaced when `accessToken` is sent. - A different Meta pixel for the same organization: the new pixel is saved alongside existing ones. - The pixel is configured by another organization: `409 meta_pixel_conflict`. - The access token is already used with another pixel: `400 invalid_request`. - `platform` other than `meta`: `400 invalid_request`. - Optional `isDefault` sets or clears the org default for Meta. At least one of `accessToken` or `isDefault` is required. The response never includes the access token. Use `POST /v1/pixels/{pixelId}/test-events` to check the pixel and token. Requires `pixels:write`. Organizations without custom pixels enabled get `403 custom_pixel_not_enabled`. Does not require `Idempotency-Key`; repeating the same request is safe. **Auth:** Accepts API key or OAuth Bearer (`pixels:write`). operationId: updatePixel parameters: - name: pixelId in: path required: true schema: type: string minLength: 1 description: Pixel id on the ad platform. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdatePixelRequest' example: platform: meta accessToken: EAAB... isDefault: true responses: '200': description: Pixel saved or token rotated content: application/json: schema: $ref: '#/components/schemas/UpdatePixelResponse' example: data: id: '1234567890123456' platform: meta isDefault: true status: ok lastErrorCode: null errorSince: null meta: requestId: 550e8400-e29b-41d4-a716-446655440000 '400': $ref: '#/components/responses/UpdatePixelBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/PixelForbidden' '409': $ref: '#/components/responses/PixelConflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - apiKeyBearerAuth: [] - oauthBearer: [] components: schemas: UpdatePixelRequest: type: object required: - platform properties: platform: $ref: '#/components/schemas/PixelPlatform' accessToken: type: string minLength: 1 description: | Conversions API access token. Stored and never returned. Required when creating a new pixel; optional when only updating `isDefault`. isDefault: type: boolean description: | Sets or clears the organization's default Meta pixel. At least one of `accessToken` or `isDefault` must be present. UpdatePixelResponse: type: object required: - data - meta properties: data: $ref: '#/components/schemas/Pixel' meta: $ref: '#/components/schemas/Meta' PixelPlatform: type: string enum: - meta description: Ad platform for the pixel. Only `meta` is supported today. Pixel: type: object required: - id - platform - isDefault - status - lastErrorCode - errorSince properties: id: type: string platform: $ref: '#/components/schemas/PixelPlatform' isDefault: type: boolean description: | Whether this pixel is the organization's default for its platform. Only drives the app soundlink create picker; create APIs never fall back to it. status: type: string enum: - ok - error description: | `error` while an open send-error episode exists for this pixel; `ok` otherwise. lastErrorCode: type: string nullable: true description: Platform error code for the open episode, or `null`. errorSince: type: string format: date-time nullable: true description: When the open error episode started, or `null`. 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' Error: type: object required: - code - message properties: code: type: string description: Stable snake_case error code. enum: - invalid_api_key - invalid_token - api_key_revoked - api_key_expired - access_denied - insufficient_scope - not_found - not_in_listening_graph - 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 - learning_edit_ack_required - wallet_not_enabled - premium_plan_required - soundlink_plan_required - custom_pixel_not_enabled - meta_pixel_conflict - pixel_in_use - 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: UpdatePixelBadRequest: description: | Missing or malformed request body, unsupported platform, or the access token is already used with another pixel. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_body: value: error: code: invalid_request message: 'Invalid request body at accessToken: Required.' meta: requestId: 550e8400-e29b-41d4-a716-446655440000 access_token_in_use: value: error: code: invalid_request message: Access token is already in use with another pixel ID meta: requestId: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: | Missing or invalid credentials. Covers missing/malformed API keys, invalid or expired OAuth access tokens, and revoked API keys. `x-api-key` is not accepted and is ignored if sent. 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 credentials. Send Authorization: Bearer.' meta: requestId: 550e8400-e29b-41d4-a716-446655440000 invalid_token: value: error: code: invalid_token message: OAuth access token is invalid or expired. 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 PixelForbidden: description: | Valid credentials but missing the required scope, or custom pixels are not enabled for the organization. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficient_scope: value: error: code: insufficient_scope message: This key does not have the campaigns:write scope. meta: requestId: 550e8400-e29b-41d4-a716-446655440000 custom_pixel_not_enabled: value: error: code: custom_pixel_not_enabled message: This organization does not have a custom Meta pixel enabled. meta: requestId: 550e8400-e29b-41d4-a716-446655440000 PixelConflict: description: | The pixel is configured by another organization. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: pixel_owned_by_another_organization: value: error: code: meta_pixel_conflict message: >- This pixel can't be used with this account. Check the pixel ID and access token, or contact support. 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: apiKeyBearerAuth: type: http scheme: bearer description: | Pass your Soundlink `sk_*` API key as a Bearer token: `Authorization: Bearer sk__` (not an OAuth token; see `oauthBearer` for that). Accepted on all Public API operations. Send only one `Authorization` header per request. oauthBearer: type: http scheme: bearer bearerFormat: JWT description: | OAuth 2.0 access token from Sign in with Soundlink (`Authorization: Bearer `). Token scopes must include the operation's required scope (see `x-required-scope` and the Authentication section). Accepted on all Public API operations (reads and writes). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.