### Verifying the webhook signature

Source: https://docs.soundstripe.com/reference/webhooks

This guide provides code examples for verifying the X-Soundstripe-Signature header to confirm that webhooks originate from Soundstripe and remain untampered.

```APIDOC
## Verifying the webhook signature

### Description
Every webhook includes an `X-Soundstripe-Signature` header containing an HMAC-SHA256 signature. Verify the signature to confirm the webhook came from Soundstripe and has not been tampered with.

### Verification Logic
The signature is computed over the string `{timestamp}.{payload}`, where `timestamp` is the value of the `X-Soundstripe-Timestamp` header and `payload` is the raw request body. Your API key is used as the HMAC secret.

### Security Note
Always use a constant-time comparison function (like `timingSafeEqual`, `secure_compare`, or `compare_digest`) to prevent timing attacks.
```

--------------------------------

### Retrieve asset response example

Source: https://docs.soundstripe.com/reference/retrieve-an-asset

Example JSON response body returned when successfully retrieving an asset's processing state.

```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "supe_assets",
    "attributes": {
      "status": "processed",
      "media_kind": "image",
      "submitted_at": "2026-05-04T00:00:00Z",
      "processed_at": "2026-05-04T00:00:08Z",
      "original_retained": false
    },
    "links": {
      "self": "https://api.soundstripe.com/v1/supe/assets/550e8400-e29b-41d4-a716-446655440000"
    }
  },
  "links": {
    "self": "https://api.soundstripe.com/v1/supe/assets/550e8400-e29b-41d4-a716-446655440000"
  }
}
```

--------------------------------

### cURL Request

Source: https://docs.soundstripe.com/reference/add-sound-effects-to-private-playlist

Example of a POST request to add sound effects to a playlist using cURL.

```bash
curl --request POST \
     --url https://api.soundstripe.com/v1/my_media/playlists/playlist_id/sound_effects \
     --header 'Accept: application/vnd.api+json' \
     --header 'Content-Type: application/vnd.api+json' \
     --header 'accept: application/vnd.api+json'
```

--------------------------------

### JSON:API Error Response Example

Source: https://docs.soundstripe.com/reference/create-a-search

Example of an error response following the JSON:API format, including a meta object for limit values.

```json
{
  "errors": [
    {
      "detail": "Search may include up to 10 images.",
      "code": "image_count_exceeded",
      "meta": { "limit": 10 },
      "status": 422
    }
  ]
}
```

--------------------------------

### Upload an asset using cURL

Source: https://docs.soundstripe.com/reference/upload-an-asset

Example command to upload an image file using the cURL utility.

```shell
curl -X POST https://api.soundstripe.com/v1/supe/assets \
  -H "Authorization: Token YOUR_API_KEY" \
  -F "file=@hero-shot.jpg;type=image/jpeg"
```

--------------------------------

### cURL Request for Asset Upload

Source: https://docs.soundstripe.com/reference/upload-an-asset

A multi-part cURL request example for uploading assets to the Soundstripe API.

```Shell
curl --request POST \
```

```Shell
     --url https://api.soundstripe.com/v1/supe/assets \
```

```Shell
     --header 'Accept: application/vnd.api+json' \
```

```Shell
     --header 'Content-Type: application/vnd.api+json' \
```

```Shell
     --header 'accept: application/vnd.api+json'
```

--------------------------------

### cURL Request Example

Source: https://docs.soundstripe.com/reference/add-songs-to-private-playlist

A cURL command to add songs to a playlist, requiring the playlist ID in the URL path.

```bash
curl --request POST \
     --url https://api.soundstripe.com/v1/my_media/playlists/playlist_id/songs \
     --header 'Accept: application/vnd.api+json' \
     --header 'Content-Type: application/vnd.api+json' \
     --header 'accept: application/vnd.api+json'
```

--------------------------------

### GET https://api.soundstripe.com/v1/supe/assets/{asset_id}

Source: https://docs.soundstripe.com/reference/retrieve-an-asset

Retrieve the current processing state of a previously uploaded asset.

```APIDOC
## GET https://api.soundstripe.com/v1/supe/assets/{asset_id}

### Description
Retrieve the current processing state of a previously uploaded asset. Assets are scoped to your API key; references from other keys return a 404.

### Method
GET

### Endpoint
https://api.soundstripe.com/v1/supe/assets/{asset_id}

### Parameters
#### Path Parameters
- **asset_id** (string) - Required - The asset ID returned when the asset was uploaded.

### Response
#### Success Response (200)
- **data** (object) - The asset data object.
- **data.id** (string) - The asset ID.
- **data.type** (string) - The resource type (supe_assets).
- **data.attributes** (object) - Asset attributes including status, media_kind, submitted_at, processed_at, and original_retained.

#### Response Example
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "supe_assets",
    "attributes": {
      "status": "processed",
      "media_kind": "image",
      "submitted_at": "2026-05-04T00:00:00Z",
      "processed_at": "2026-05-04T00:00:08Z",
      "original_retained": false
    }
  }
}
```

--------------------------------

### Configure webhook receiver body size limits

Source: https://docs.soundstripe.com/reference/webhooks

Configuration examples for common web servers and frameworks to ensure they accept payloads up to 10MB.

```nginx
client_max_body_size 10m;
```

```javascript
express.json({ limit: "10mb" })
```

--------------------------------

### Supe Search API Response Examples

Source: https://docs.soundstripe.com/reference/create-a-search

JSON response structures for successful search creation and various error scenarios.

```json
                  "Result": {
                    "value": {
                      "data": {
                        "id": "fa9b5222768b...",
                        "type": "supe_searches",
                        "attributes": {
                          "status": "processing",
                          "query": "upbeat indie rock for a travel vlog",
                          "context": "Summer road trip montage with golden-hour visuals",
                          "callback_url": "https://your-app.com/webhooks/supe",
                          "asset_ids": []
                        },
                        "links": {
                          "self": "https://api.soundstripe.com/v1/supe/search/fa9b5222768b..."
                        }
                      },
                      "links": {
                        "self": "https://api.soundstripe.com/v1/supe/search"
                      }
                    }
                  }
```

```json
                  "Result": {
                    "value": {
                      "errors": [
                        {
                          "detail": "Incorrect type parameter, type should be supe_searches",
                          "status": 400
                        }
                      ]
                    }
                  }
```

```json
                  "Result": {
                    "value": {
                      "errors": [
                        {
                          "detail": "Authentication token is invalid",
                          "status": 401
                        }
                      ]
                    }
                  }
```

```json
                  "Result": {
                    "value": {
                      "errors": [
                        {
                          "detail": "You do not have access to the Supe Search API",
                          "code": "unauthorized",
                          "status": 403
                        }
                      ]
                    }
                  }
```

```json
                  "Result": {
                    "value": {
                      "errors": [
                        {
                          "detail": "Search must include query, context, or asset_ids.",
                          "code": "insufficient_intent",
                          "status": 422
                        }
                      ]
                    }
                  }
```

```json
                  "Result": {
                    "value": {
                      "errors": [
                        {
                          "detail": "Rate limit exceeded",
                          "status": 429
                        }
                      ]
                    }
                  }
```

--------------------------------

### Retrieve asset cURL request

Source: https://docs.soundstripe.com/reference/retrieve-an-asset

Example cURL command to retrieve an asset by its ID.

```shell
curl --request GET \
     --url https://api.soundstripe.com/v1/supe/assets/asset_id \
     --header 'Accept: application/vnd.api+json' \
     --header 'Content-Type: application/vnd.api+json' \
     --header 'accept: application/vnd.api+json'
```

--------------------------------

### GET /v1/playlists

Source: https://docs.soundstripe.com/reference/list-playlists

Retrieves a list of playlists. Supports pagination through query parameters.

```APIDOC
## GET /v1/playlists

### Description
Retrieve a paginated list of playlists.

### Method
GET

### Endpoint
/v1/playlists

### Parameters
#### Query Parameters
- **page[size]** (integer) - Optional - The number of items per page.
- **page[number]** (integer) - Optional - The page number to retrieve.

### Response
#### Success Response (200)
- **data** (array) - List of playlist objects.
- **links** (object) - Pagination links including self, first, prev, next, and last.
- **meta** (object) - Metadata including total_count.

#### Error Response (400)
- **errors** (array) - List of error objects detailing invalid parameters.
```

--------------------------------

### GET /songs/{id}

Source: https://docs.soundstripe.com/reference/retrieve-a-song

Retrieves the details of a specific song by its ID.

```APIDOC
## GET /songs/{id}

### Description
Retrieves the details of a specific song by its ID.

### Method
GET

### Endpoint
/songs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the song.

### Response
#### Success Response (200)
- **data** (object) - The song resource object containing attributes such as bpm, description, energy, explicit, key, lyrics, playlist_ids, stems, tags, and title.

#### Response Example
{
  "data": {
    "id": "12622",
    "type": "songs",
    "attributes": {
      "bpm": 87,
      "description": "A medium energy, classical song that is best described as fun. Electronic drums and drums are the primary instruments in this track.",
      "energy": "medium",
      "explicit": false,
      "key": {
        "name": "A",
        "mode": "major"
      },
      "lyrics": "",
      "playlist_ids": [],
      "stems": "https://...",
      "tags": {
        "characteristic": ["Building"],
        "genre": ["Orchestral"],
        "instrument": ["Electronic Drums"],
        "mood": ["Fun"]
      },
      "title": "Astrid"
    }
  }
}
```

--------------------------------

### GET /v1/my_media/playlists/{playlist_id}

Source: https://docs.soundstripe.com/reference/retrieve-a-private-playlist

Retrieve a single private playlist belonging to the authenticated account.

```APIDOC
## GET /v1/my_media/playlists/{playlist_id}

### Description
Retrieve one private playlist. The playlist must belong to the authenticated account or API key. A missing or inaccessible playlist returns 404; test API keys cannot access private playlists.

### Method
GET

### Endpoint
/v1/my_media/playlists/{playlist_id}

### Parameters
#### Path Parameters
- **playlist_id** (string) - Required - The playlist's ID

#### Query Parameters
- **include** (string) - Optional - Returns related resources of the private playlist. Must be a comma separated string consisting of one or many: `songs`, `songs.audio_files`, `songs.artists`, `sound_effects`.
- **filter[include_alternate_audio_files]** (string) - Optional - If `true`, all audio files for each song will be returned. Defaults to `false`.
- **page[size]** (string) - Optional - The number of songs returned when requesting songs via the `include` param. Defaults to 10.
- **page[number]** (string) - Optional - Specify the page to retrieve when including songs via the `include` parameter. Defaults to the first page.
- **filter[media_type]** (string) - Optional - Returns playlist of that media type. Value can only be `songs` or `sound_effects` and defaults to `songs`.

### Response
#### Success Response (200)
- **data** (object) - The private playlist resource object.
```

--------------------------------

### Generate Release Code with cURL

Source: https://docs.soundstripe.com/docs/clearing-youtube-claims-with-code

Example cURL command to request a release code, replacing placeholders with your specific song ID and API key.

```cURL
curl -X POST \
  "https://api.soundstripe.com/v1/songs/SONG_ID/digital_usages" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "digital_usages"
    }
  }'
```

--------------------------------

### Search API Response Structure

Source: https://docs.soundstripe.com/reference/create-a-search

Example of a successful search response containing song, artist, and audio file data.

```json
{
                          }
                        },
                        "links": {
                          "self": "https://api.soundstripe.com/v1/supe/search/fa9b5222768b..."
                        }
                      },
                      "included": [
                        {
                          "id": "12556",
                          "type": "songs",
                          "attributes": {
                            "title": "After The Storm",
                            "description": "A low energy, classical song that is best described as sad and reflective.",
                            "energy": "low",
                            "explicit": false,
                            "lyrics": "",
                            "bpm": 90,
                            "key": {
                              "name": "F",
                              "mode": "minor"
                            },
                            "tags": {
                              "genre": [
                                "Classical",
                                "Underscore",
                                "Soundtrack / Cinematic"
                              ],
                              "mood": [
                                "Calm",
                                "Reflective",
                                "Sad"
                              ],
                              "instrument": [
                                "Piano",
                                "Strings"
                              ],
                              "characteristic": [
                                "Atmospheric",
                                "Beautiful",
                                "Minimal"
                              ]
                            },
                            "playlist_ids": [
                              4012,
                              4097
                            ],
                            "stems": "https://cdn.soundstripe.com/.../Moments_AfterTheStorm.zip?key=YOUR_API_KEY&search_id=fa9b5222768b...&token=...",
                            "has_vocal_version": false,
                            "has_instrumental_version": true
                          },
                          "relationships": {
                            "artists": {
                              "data": [
                                {
                                  "id": "506",
                                  "type": "artists"
                                }
                              ]
                            },
                            "audio_files": {
                              "data": [
                                {
                                  "id": "47652",
                                  "type": "audio_files"
                                }
                              ]
                            }
                          },
                          "links": {
                            "self": "https://api.soundstripe.com/v1/songs/12556"
                          }
                        },
                        {
                          "id": "47652",
                          "type": "audio_files",
                          "attributes": {
                            "description": "Primary",
                            "song_id": "12556",
                            "instrumental": true,
                            "duration": 226.08,
                            "versions": {
                              "mp3": "https://cdn.soundstripe.com/.../mp3_Moments_AfterTheStorm_FULL.mp3?key=YOUR_API_KEY&search_id=fa9b5222768b...&token=...",
                              "wav": "https://cdn.soundstripe.com/.../wav_Moments_AfterTheStorm_FULL.wav?key=YOUR_API_KEY&search_id=fa9b5222768b...&token=..."
                            }
                          }
                        },
                        {
                          "id": "506",
                          "type": "artists",
                          "attributes": {
                            "name": "Moments",
                            "image": "https://soundstripe-artist-production.imgix.net/.../artist-506.jpg?h=100&w=100"
                          }
                        }
                      ],
                      "links": {
                        "self": "https://api.soundstripe.com/v1/supe/search"
                      }
                    }
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          }
```

--------------------------------

### GET /v1/my_media/playlists

Source: https://docs.soundstripe.com/reference/list-private-playlists

Retrieve a list of private playlists associated with the authenticated account or API key.

```APIDOC
## GET /v1/my_media/playlists

### Description
Retrieve the private playlists available to the authenticated account or API key. Private-playlist endpoints require a live API key.

### Method
GET

### Endpoint
/v1/my_media/playlists

### Parameters
#### Query Parameters
- **include** (string) - Optional - Returns related resources of the playlist. Must be a comma separated string consisting of one or many: `songs`, `songs.audio_files`, `songs.artists`, `playlist_categories`.
- **filter[include_alternate_audio_files]** (string) - Optional - If `true`, all audio files for each song will be returned. By default, this is `false`.
- **filter[media_type]** (string) - Optional - Filter private playlists by media type: `songs` or `sound_effects`.

### Response
#### Success Response (200)
- **data** (object) - Private playlists available to the authenticated account or API key.

#### Response Example
{
  "data": [
    {
      "id": "272249",
      "type": "private_playlists",
      "attributes": {
        "name": "My First Playlist",
        "description": "A collection of my favorite Soundstripe songs",
        "duration": 6948.34267,
        "image": "https://soundstripe.imgix.net/.../private-playlist.jpg?auto=format",
        "song_ids": [7055, 7571],
        "sound_effect_ids": [],
        "media_type": "songs",
        "shareable": false
      },
      "relationships": {
        "songs": {
          "data": [
            { "id": "7055", "type": "songs" },
            { "id": "7571", "type": "songs" }
          ]
        }
      }
    }
  ],
  "links": {
    "self": "https://api.soundstripe.com/v1/my_media/playlists?filter%5Bmedia_type%5D=songs"
  }
}
```

--------------------------------

### GET /songs

Source: https://docs.soundstripe.com/reference/list-songs

Retrieves a paginated collection of songs based on the provided filter and pagination parameters.

```APIDOC
## GET /songs

### Description
Retrieves a paginated list of songs. Supports filtering by various attributes and pagination controls.

### Method
GET

### Endpoint
/songs

### Parameters
#### Query Parameters
- **filter[bpm][max]** (int32) - Optional - Maximum BPM
- **filter[bpm][min]** (int32) - Optional - Minimum BPM
- **filter[duration][consider_alternate_audio_files]** (boolean) - Optional - If true, songs will be returned if any of their audio files match the duration criteria.
- **filter[duration][max]** (int32) - Optional - Maximum duration of the song's primary audio file
- **filter[duration][min]** (int32) - Optional - Minimum duration of the song's primary audio file
- **filter[energy]** (string) - Optional - Energy to filter by (very_low, low, medium, high)
- **filter[include_alternate_audio_files]** (boolean) - Optional - If true, all audio files for each song will be returned.
- **filter[instrumental]** (boolean) - Optional - If true, only show songs that have at least one instrumental audio file.
- **filter[isrc]** (string) - Optional - Filter by ISRC (12-character code).
- **filter[q]** (string) - Optional - Search query
- **filter[tags][characteristic]** (string) - Optional - Comma-separated characteristic tags to filter by.
- **filter[tags][genre]** (string) - Optional - Comma-separated genre tags to filter by.
- **filter[tags][instrument]** (string) - Optional - Comma-separated instrument tags to filter by.
- **filter[tags][mood]** (string) - Optional - Comma-separated mood tags to filter by.
- **filter[vocals]** (boolean) - Optional - If true, only show songs that have at least one vocal audio file.
- **page[size]** (int32) - Optional - Number of songs to return per page (1-100, default 10).
- **page[number]** (int32) - Optional - One-indexed page number to return (default 1).

### Response
#### Success Response (200)
- Returns a paginated collection of songs. Includes pagination links in the top-level `links` object.
```

--------------------------------

### GET /v1/categories

Source: https://docs.soundstripe.com/reference/list-categories

Retrieve a paginated list of sound-effect categories. Use the include parameter to fetch related subcategories.

```APIDOC
## GET /v1/categories

### Description
Retrieve a paginated list of sound-effect categories. Each category includes a subcategories relationship; add include=subcategories to receive the related category objects in the top-level included array.

### Method
GET

### Endpoint
/v1/categories

### Parameters
#### Query Parameters
- **include** (array) - Optional - Returns related resources of the category. Must be a comma separated string consisting of one or many: subcategories.
- **page[size]** (integer) - Optional - Number of results to return per page, from 1 to 100. Default: 10.
- **page[number]** (integer) - Optional - One-indexed page number to return. Default: 1.

### Response
#### Success Response (200)
- **data** (array) - A list of category objects.
- **included** (array) - Related resources if requested.
- **links** (object) - Pagination links.
- **meta** (object) - Metadata including total_count.

#### Response Example
{
  "data": [
    {
      "id": "12",
      "type": "categories",
      "attributes": {
        "name": "Ambiance",
        "parent_id": null
      },
      "links": {
        "self": "https://api.soundstripe.com/v1/categories/12"
      },
      "relationships": {
        "subcategories": {
          "data": [
            {
              "id": "13",
              "type": "categories"
            }
          ],
          "links": {
            "self": "https://api.soundstripe.com/v1/categories/12/relationships/subcategories",
            "related": "https://api.soundstripe.com/v1/categories"
          }
        }
      }
    }
  ],
  "meta": {
    "total_count": 36
  }
}
```

--------------------------------

### Tag Object JSON Representation

Source: https://docs.soundstripe.com/reference/the-tag-object

Example of a tag object structure including its ID, type, and attributes.

```json
{
  "id": "8_bit",
  "type": "tags",
  "attributes": {
    "category": "genre",
    "name": "8-bit"
  }
}
```

--------------------------------

### OpenAPI Specification for List Tags

Source: https://docs.soundstripe.com/reference/list-tags

The complete OpenAPI definition for the Soundstripe API, including security schemes, path parameters for filtering and pagination, and example response payloads.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "soundstripe",
    "version": "1"
  },
  "servers": [
    {
      "url": "https://api.soundstripe.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "x-bearer-format": "token"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/v1/tags": {
      "get": {
        "summary": "List tags",
        "description": "",
        "operationId": "list-tags",
        "parameters": [
          {
            "name": "filter[category]",
            "in": "query",
            "description": "Category of tags to filter by. One of: `characteristic`, `genre`, `instrument`, or `mood`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page[size]",
            "in": "query",
            "description": "Number of results to return per page, from 1 to 100.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 10,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "page[number]",
            "in": "query",
            "description": "One-indexed page number to return.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1,
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200 — Published tags returned as a paginated collection.",
            "content": {
              "application/vnd.api+json": {
                "examples": {
                  "Result": {
                    "value": {
                      "data": [
                        {
                          "id": "electronic",
                          "type": "tags",
                          "attributes": {
                            "name": "Electronic",
                            "category": "genre"
                          },
                          "links": {
                            "self": "https://api.soundstripe.com/v1/tags/electronic"
                          },
                          "relationships": {}
                        }
                      ],
                      "included": [],
                      "links": {
                        "self": "https://api.soundstripe.com/v1/tags?page%5Bsize%5D=10&page%5Bnumber%5D=1",
                        "first": "https://api.soundstripe.com/v1/tags?page%5Bsize%5D=10&page%5Bnumber%5D=1",
                        "prev": null,
                        "next": "https://api.soundstripe.com/v1/tags?page%5Bsize%5D=10&page%5Bnumber%5D=2",
                        "last": "https://api.soundstripe.com/v1/tags?page%5Bsize%5D=10&page%5Bnumber%5D=5",
                        "meta": {
                          "total_count": 48
                        }
                      },
                      "meta": {
                        "total_count": 48
                      }
                    }
                  }
                },
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "400 — Invalid request parameter.",
            "content": {
              "application/vnd.api+json": {
                "examples": {
                  "Result": {
                    "value": {
                      "errors": [
                        {
                          "detail": "The request contains an invalid parameter.",
                          "status": 400
                        }
                      ]
                    }
                  }
                },
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [
      {
        "key": "Content-Type",
        "value": "application/vnd.api+json"
      },
      {
        "key": "Accept",
        "value": "application/vnd.api+json"
      }
    ],
    "explorer-enabled": true,
    "proxy-enabled": false
  },
  "x-readme-fauxas": true
}
```

--------------------------------

### Retrieve paginated list response structure

Source: https://docs.soundstripe.com/reference/pagination

Example of a JSON response from a list endpoint, including the 'links' object for navigation and 'meta' data for total counts.

```JSON
{
  "data": [],
  "links": {
    "self": "https://api.soundstripe.com/v1/songs?page%5Bsize%5D=10&page%5Bnumber%5D=1",
    "first": "https://api.soundstripe.com/v1/songs?page%5Bsize%5D=10&page%5Bnumber%5D=1",
    "prev": null,
    "next": "https://api.soundstripe.com/v1/songs?page%5Bsize%5D=10&page%5Bnumber%5D=2",
    "last": "https://api.soundstripe.com/v1/songs?page%5Bsize%5D=10&page%5Bnumber%5D=800",
    "meta": {
      "total_count": 8000
    }
  }
}
```

--------------------------------

### GET /v1/playlists/{playlist_id}

Source: https://docs.soundstripe.com/reference/retrieve-a-playlist

Retrieve a curated playlist by its unique ID, with options to include related media and paginate results.

```APIDOC
## GET /v1/playlists/{playlist_id}

### Description
Retrieve one curated playlist by ID. The response identifies the playlist's related media and playlist categories; use `include` to return the full related resources in `included`.

### Method
GET

### Endpoint
/v1/playlists/{playlist_id}

### Parameters
#### Path Parameters
- **playlist_id** (string) - Required - The playlist's ID

#### Query Parameters
- **include** (string) - Optional - Returns related resources of the playlist. Must be a comma separated string consisting of one or many: `songs`, `songs.audio_files`, `songs.artists`, `playlist_categories`.
- **filter[include_alternate_audio_files]** (boolean) - Optional - If `true`, all audio files for each song will be returned. Defaults to `false`.
- **page[size]** (integer) - Optional - The number of songs or sound effects to be returned. Default: 10.
- **page[number]** (integer) - Optional - Specify the page to retrieve when including songs. Default: 1.
- **filter[media_type]** (string) - Optional - Returns playlist of that media type. Value can be `songs` or `sound_effects`. Defaults to `songs`.

### Response
#### Success Response (200)
- **data** (object) - The playlist resource object.
```

--------------------------------

### GET https://api.soundstripe.com/v1/songs

Source: https://docs.soundstripe.com/reference/list-songs

Retrieve a paginated collection of songs. The response includes a data array of songs and an included array containing referenced artists and audio files.

```APIDOC
## GET https://api.soundstripe.com/v1/songs

### Description
Retrieve a paginated collection of songs. The `data` array contains songs, and `included` contains the artists and audio files referenced by those songs.

### Method
GET

### Endpoint
https://api.soundstripe.com/v1/songs

### Parameters
#### Query Parameters
- **filter[isrc]** (string) - Optional - Find songs by International Standard Recording Code (12-character).
- **filter[include_alternate_audio_files]** (boolean) - Optional - Set to true to include every audio file for each returned song.
- **page[size]** (integer) - Optional - Number of results to return.

### Request Example
curl --get "https://api.soundstripe.com/v1/songs" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Accept: application/vnd.api+json" \
  --data-urlencode "filter[isrc]=US-ABC-12-34567" \
  --data-urlencode "page[size]=10"
```

--------------------------------

### GET /v1/sound_effects/{sound_effect_id}

Source: https://docs.soundstripe.com/reference/retrieve-a-sound-effect

Retrieve a single sound effect by its ID.

```APIDOC
## GET /v1/sound_effects/{sound_effect_id}

### Description
Retrieve one sound effect by ID. This endpoint requires Sound Effects API access.

### Method
GET

### Endpoint
/v1/sound_effects/{sound_effect_id}

### Parameters
#### Path Parameters
- **sound_effect_id** (integer) - Required - The Sound Effect's ID

### Response
#### Success Response (200)
- **data** (object) - The sound effect object containing attributes such as title, description, categories, and file versions.

#### Response Example
{
  "data": {
    "id": "9999",
    "type": "sound_effects",
    "attributes": {
      "title": "Motocross Decelerate 01",
      "description": "Honda 450cc off-road bike long decelerating process.",
      "primary_category": "transportation",
      "primary_subcategory": "motorcycles",
      "categories": ["transportation"],
      "subcategories": ["motorcycles", "bicycles"],
      "duration": 14.241,
      "versions": {
        "mp3": "https://cdn.soundstripe.com/.../Motocross_Decelerate_01.mp3?key=YOUR_API_KEY&token=...",
        "wav": "https://cdn.soundstripe.com/.../Motocross_Decelerate_01.wav?key=YOUR_API_KEY&token=..."
      }
    },
    "relationships": {
      "category_levels": {
        "data": []
      }
    }
  }
}
```

--------------------------------

### GET /v1/supe/search/{search_id}

Source: https://docs.soundstripe.com/reference/supe-search

Retrieves the results of a previously submitted search by its ID.

```APIDOC
## GET /v1/supe/search/{search_id}

### Description
Fetches the results for a specific search ID. This is useful for retrieving results after a webhook has been delivered or if URLs are approaching expiry.

### Method
GET

### Endpoint
/v1/supe/search/{search_id}

### Parameters
#### Path Parameters
- **search_id** (string) - Required - The unique identifier for the search request.
```

--------------------------------

### POST /v1/supe/assets

Source: https://docs.soundstripe.com/reference/upload-an-asset

Uploads a new asset to the system. The request is queued for processing upon acceptance.

```APIDOC
## POST /v1/supe/assets

### Description
Uploads an asset to the Soundstripe platform. The request returns a 202 status code indicating the asset is queued for processing.

### Method
POST

### Endpoint
https://api.soundstripe.com/v1/supe/assets

### Request Body
- **file** (file) - Required - The asset file to be uploaded.

### Response
#### Success Response (202)
- **status** (integer) - 202 — Upload accepted; the asset is queued for processing.

#### Error Responses
- **400** - Missing `file` parameter.
- **401** - Unauthorized.
- **403** - API key does not have access to upload assets of this type.
- **422** - Validation error (e.g., `empty_file`, `unsupported_format`, `image_size_exceeded`).
- **429** - Daily upload quota exceeded.
```

--------------------------------

### GET /v1/playlist_categories/{playlist_category_id}

Source: https://docs.soundstripe.com/reference/retrieve-a-playlist-category

Retrieve a single published song-playlist category by providing its ID.

```APIDOC
## GET /v1/playlist_categories/{playlist_category_id}

### Description
Retrieve one published song-playlist category by ID.

### Method
GET

### Endpoint
/v1/playlist_categories/{playlist_category_id}

### Parameters
#### Path Parameters
- **playlist_category_id** (string) - Required - The playlist category ID

### Response
#### Success Response (200)
- **data** (object) - Playlist category retrieved.

#### Response Example
{
  "data": {
    "id": "7",
    "type": "playlist_categories",
    "attributes": {
      "name": "Staff Curated",
      "media_type": "songs"
    },
    "links": {
      "self": "https://api.soundstripe.com/v1/playlist_categories/7"
    },
    "relationships": {}
  },
  "included": [],
  "links": {
    "self": "https://api.soundstripe.com/v1/playlist_categories/7"
  }
}
```

--------------------------------

### Retrieve a playlist via cURL

Source: https://docs.soundstripe.com/reference/retrieve-a-playlist

Use this command to fetch a specific playlist by ID. Include related resources like songs and audio files by specifying them in the include query parameter.

```sh
curl --get "https://api.soundstripe.com/v1/playlists/7457" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Accept: application/vnd.api+json" \
  --data-urlencode "include=songs,songs.audio_files"
```

--------------------------------

### Perform a Search Request

Source: https://docs.soundstripe.com/reference/create-a-search

Use these cURL commands to initiate a search. The text-only search uses a query string, while the asset-referenced search uses specific asset IDs.

```sh
curl -X POST https://api.soundstripe.com/v1/supe/search \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "supe_searches",
      "attributes": {
        "query": "upbeat indie rock for a travel vlog",
        "context": "Summer road trip montage with golden-hour visuals",
        "callback_url": "https://your-app.com/webhooks/supe"
      }
    }
  }'
```

```sh
curl -X POST https://api.soundstripe.com/v1/supe/search \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "supe_searches",
      "attributes": {
        "context": "Opening title sequence, cinematic and tense",
        "asset_ids": [
          "550e8400-e29b-41d4-a716-446655440000",
          "550e8400-e29b-41d4-a716-446655440001"
        ],
        "callback_url": "https://your-app.com/webhooks/supe"
      }
    }
  }'
```

--------------------------------

### List playlists via cURL

Source: https://docs.soundstripe.com/reference/list-playlists

Retrieve a paginated list of playlists using the Soundstripe API with specific resource inclusions.

```sh
curl --get "https://api.soundstripe.com/v1/playlists" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Accept: application/vnd.api+json" \
  --data-urlencode "include=songs,songs.artists,playlist_categories" \
  --data-urlencode "page[size]=10"
```

--------------------------------

### POST https://api.soundstripe.com/v1/my_media/playlists

Source: https://docs.soundstripe.com/reference/create-a-private-playlist

Creates a private playlist for the authenticated account or API key.

```APIDOC
## POST https://api.soundstripe.com/v1/my_media/playlists

### Description
Creates a private playlist for the authenticated account or API key. You must provide a name and media_type (songs or sound_effects) in the data object.

### Method
POST

### Endpoint
https://api.soundstripe.com/v1/my_media/playlists

### Request Body
- **data** (object) - Required - The data object containing playlist details including name, media_type, description, shareable status, and initial media IDs.

### Response
#### Success Response (200)
- **200** - Private playlist created.

#### Error Response (400)
- **400** - Invalid request parameter.
```

--------------------------------

### Create a private playlist via cURL

Source: https://docs.soundstripe.com/reference/create-a-private-playlist

Use this cURL command to send a POST request to the playlists endpoint with the required JSON:API headers.

```Shell
curl --request POST \
     --url https://api.soundstripe.com/v1/my_media/playlists \
     --header 'Accept: application/vnd.api+json' \
     --header 'Content-Type: application/vnd.api+json' \
     --header 'accept: application/vnd.api+json'
```

--------------------------------

### cURL Request for Removing Songs

Source: https://docs.soundstripe.com/reference/remove-songs-from-private-playlist

Example of a DELETE request to the playlist songs endpoint using cURL.

```bash
curl --request DELETE \
     --url https://api.soundstripe.com/v1/my_media/playlists/playlist_id/songs \
     --header 'Accept: application/vnd.api+json' \
     --header 'Content-Type: application/vnd.api+json' \
     --header 'accept: application/vnd.api+json'
```

--------------------------------

### Pagination Parameters

Source: https://docs.soundstripe.com/reference/pagination

List API methods support pagination using the 'page' key with 'size' and 'number' parameters.

```APIDOC
## Pagination

### Description
All top-level API resources that support 'list' calls are paginated. You can control the results using query parameters nested under a 'page' key.

### Query Parameters
- **page[size]** (integer) - Optional - The number of results to return (1-100). Default is 10.
- **page[number]** (integer) - Optional - The page to return, one-indexed. Default is 1.

### Response
List endpoints return a top-level 'links' object to facilitate navigation.

#### Response Example
{
  "data": [],
  "links": {
    "self": "https://api.soundstripe.com/v1/songs?page%5Bsize%5D=10&page%5Bnumber%5D=1",
    "first": "https://api.soundstripe.com/v1/songs?page%5Bsize%5D=10&page%5Bnumber%5D=1",
    "prev": null,
    "next": "https://api.soundstripe.com/v1/songs?page%5Bsize%5D=10&page%5Bnumber%5D=2",
    "last": "https://api.soundstripe.com/v1/songs?page%5Bsize%5D=10&page%5Bnumber%5D=800",
    "meta": {
      "total_count": 8000
    }
  }
}
```

--------------------------------

### GET /v1/songs

Source: https://docs.soundstripe.com/reference/list-songs

Retrieves a paginated collection of songs. Supports filtering and pagination via query parameters.

```APIDOC
## GET /v1/songs

### Description
Retrieves a paginated collection of songs. A valid filter with no matches returns an empty data array.

### Method
GET

### Endpoint
https://api.soundstripe.com/v1/songs

### Query Parameters
- **page[size]** (integer) - Optional - The number of items per page.
- **page[number]** (integer) - Optional - The page number to retrieve.
- **filter[isrc]** (string) - Optional - Filter by a 12-character ISRC.
- **filter[q]** (string) - Optional - Search query string (max 512 characters).

### Response
#### Success Response (200)
- **data** (array) - A paginated collection of song objects.

#### Error Responses
- **400** - Invalid query parameter.
- **401** - Authentication token is missing or invalid.
- **403** - API key is expired, inactive, or lacks permission.
- **413** - Query parameter exceeds length limit.
- **429** - Rate limit exceeded.
- **500** - Unexpected server error.
```