Create a search

Time	Status	User Agent
Retrieving recent requests…

Submit a search to Soundstripe's AI music supervisor. Provide any combination of a natural language query, scene context, and uploaded asset_ids, plus an HTTPS callback_url to receive the result via webhook.

If an equivalent search was already answered within the last 24 hours, the cached results are returned immediately in the response body (200) and no webhook is sent. Otherwise, the search is enqueued and a search ID is returned (202). When the search completes, the results are delivered to your callback_url via a webhook.

Request body

Attribute	Type	Required	Description
query	`string`	Conditional	Natural language search query (max 2,000 characters).
context	`string`	Conditional	Project or scene context, such as a shot description or creative brief (max 2,000 characters). When supplied without `query` or `asset_ids`, it must contain at least 12 characters of substantive direction.
asset_ids	`array<string>`	Conditional	Asset IDs returned by the asset upload endpoint. Up to 10 image assets and 1 video asset per search. Duplicates are deduplicated. Image and video search must be enabled on your account.
callback_url	`string`	Yes	HTTPS URL to receive the webhook result (max 2,048 characters).

A search must include at least one of query, context, or asset_ids. The request body must also include data.type set to "supe_searches"; bodies that omit or mismatch this value receive a 400 Bad Request.

Example requests

Text-only search

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"
      }
    }
  }'

Search referencing uploaded assets

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"
      }
    }
  }'

Response shapes

202 Accepted (search enqueued)

The search is processing. The full result will be delivered to your callback_url via webhook.

{
  "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"
  }
}

200 OK (cache hit)

An equivalent search was already answered within the last 24 hours for your API key. The full result is returned inline and no webhook is sent. Each returned song uses the same JSON:API shape as GET /v1/songs/:id plus two song-level booleans (has_vocal_version, has_instrumental_version). The response includes audio_files and artists resources for every referenced relationship.

{
  "data": {
    "id": "fa9b5222768b...",
    "type": "supe_searches",
    "attributes": {
      "status": "completed",
      "query": "upbeat indie rock for a travel vlog",
      "context": "Summer road trip montage with golden-hour visuals",
      "asset_ids": []
    },
    "relationships": {
      "songs": {
        "data": [
          { "id": "12556", "type": "songs" }
        ]
      }
    },
    "links": {
      "self": "https://api.soundstripe.com/v1/supe/search/fa9b5222768b..."
    }
  },
  "links": {
    "self": "https://api.soundstripe.com/v1/supe/search"
  },
  "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"
      }
    }
  ]
}

Song attributes

Each song in the included array contains the following attributes:

Attribute	Type	Description
title	`string`	Song title.
description	`string`	Short text description of the song (possibly empty).
energy	`string`	Energy level: `very_low`, `low`, `medium`, or `high`.
explicit	`boolean`	Whether the song contains explicit content.
lyrics	`string`	Song lyrics (possibly empty).
bpm	`integer` or `null`	Beats per minute.
key	`object`	Musical key. name [`string`]: The key's name, e.g., `F`. mode [`string`]: The key's mode, e.g., `minor`.
tags	`object`	Tags grouped by category. genre [`array<string>`]: Genres mood [`array<string>`]: Moods instrument [`array<string>`]: Instruments characteristic [`array<string>`]: Characteristics
playlist_ids	`array<integer>`	Curated playlist IDs the requesting API key is entitled to see.
stems	`string` or `null`	Signed URL to the song's stems bundle, or `null` when stems are unavailable.
has_vocal_version	`boolean`	`true` if at least one audio file in the song's roster has lead vocals.
has_instrumental_version	`boolean`	`true` if at least one audio file in the song's roster is instrumental or background-vocal only.

This is the same attribute set returned by GET /v1/songs/:id, plus the two has_*_version booleans.

Included resources

The top-level included array contains every audio_files and artists resource referenced by the returned songs. Each resource appears at most once even if multiple songs reference it.

`audio_files` resource

Attribute	Type	Description
description	`string`	Audio file description (possibly empty).
song_id	`string`	Parent song ID.
instrumental	`boolean`	`true` when the audio file's vocal degree is not lead vocal.
duration	`number` or `null`	Duration in seconds.
versions.mp3	`string`	Signed URL to the MP3 file. Watermarked on non-live keys.
versions.wav	`string` or `null`	Signed URL to the WAV file. `null` for non-live keys.

The audio_files array includes both the primary audio file and any stem audio files. The primary audio file appears first in the order returned by GET /v1/songs/:id. There is no flag distinguishing primary from stem audio files; rely on the array order if you need only the primary.

`artists` resource

Attribute	Type	Description
name	`string`	Artist name.
image	`string` or `null`	Public profile image URL (unsigned, no expiry).

Signed URLs

Every signed URL in the response (audio files and stems) carries:

Parameter	Value	Notes
`key`	Your API key UUID	The signed URL is bound to your account.
`search_id`	The response's top-level `data.id`	Informational; useful for joining CDN access logs back to the originating search.
`token`, `expires`	Signature and expiry	The URL remains usable for 7 days from response generation.

The search_id parameter is informational and is not part of the signature. Signed URLs expire 7 days after the response is generated; do not cache them long-term. If a URL is approaching expiry, fetch a fresh response via GET /v1/supe/search/{search_id}.

Live vs non-live API keys

API key type	`versions.mp3`	`versions.wav`
Live (production)	Signed URL to full MP3	Signed URL to full WAV
Non-live (test or trial)	Signed URL to watermarked MP3	`null`

Error responses

All error responses follow JSON:API format. Codes that carry limit values include them under meta so you can branch programmatically:

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

Status	Code	Description
401	(none)	Missing or invalid API key.
400	(none)	Request body is missing `data.type` or `data.type` is not `"supe_searches"`.
400	`bad_request`	`asset_ids` is malformed (not an array, contains non-strings, or exceeds the hard size cap).
403	`unauthorized`	API key does not have access to Supe Search for the submitted inputs.
422	`insufficient_intent`	Submission has no `query`, no `asset_ids`, and either no `context` or fewer than 12 characters of substantive context.
422	`context_too_long`	`context` exceeds 2,000 characters.
422	`image_count_exceeded`	More than 10 images referenced. `meta.limit` carries the customer-facing limit.
422	`video_count_exceeded`	More than 1 video referenced. `meta.limit` carries the customer-facing limit.
422	`asset_unavailable`	A referenced asset ID does not exist for this API key.
422	`asset_failed`	A referenced asset reached the `failed` terminal state.
422	`asset_blocked`	A referenced asset was blocked by safety filters.
422	`asset_expired`	A referenced asset's analysis is no longer available.
422	(none)	Other validation error (query too long, invalid or HTTP callback URL, private-IP callback URL).
429	(none)	Rate limit exceeded.

Request body

Example requests

Text-only search

Search referencing uploaded assets

Response shapes

202 Accepted (search enqueued)

200 OK (cache hit)

Song attributes

Included resources

audio_files resource

artists resource

Signed URLs

Live vs non-live API keys

Error responses

200200 — Cache hit. The full result is returned inline; no webhook is sent.

202202 — Search enqueued. The full result will be delivered to the callback URL via webhook.

400400

401401

403403

422422 — Validation error. Codes that carry limit values include them under meta. Common codes: insufficient_intent, context_too_long, image_count_exceeded, video_count_exceeded, asset_unavailable, asset_failed, asset_blocked, asset_expired.

429429

`audio_files` resource

`artists` resource