Search

Search the Slipstream catalog. Four endpoints, each suited to a different starting point: a text query, a reference URL, an existing track, or a list of filters.

Endpoints

Method	Path	Use when
`GET`	`/api/v4/search/ai/by-text/`	You have a natural-language description
`GET`	`/api/v4/search/ai/by-url/`	You have a reference song on YouTube, Spotify, etc.
`GET`	`/api/v4/search/ai/by-id/`	You have a Slipstream track and want similar ones
`GET`	`/api/v4/search/ai/filters/`	You need the list of valid genres, moods, BPM ranges, etc.

All four endpoints accept the same set of optional filter parameters and the same pagination scheme.

Authentication

Search is publicly accessible — no token required. Calls are rate-limited; authenticated requests get a higher limit.

Authorization: Bearer <PARTNER_API_KEY>

If you don't send a token, you're throttled at the anonymous tier.

Pagination

All search endpoints support limit/offset pagination via query string:

Parameter	Default	Max	Description
`limit`	20	100	Number of results per page
`offset`	0	—	Result index to start from

Responses include next and previous URLs when more pages are available.

Filter parameters

Every search endpoint accepts the same filters in the query string. Use them to narrow results.

Parameter	Description	Example
`genre`	Single genre	`genre=rock`
`genre__terms`	Multiple genres separated by `__`	`genre__terms=rock__pop`
`subgenre`	Single subgenre	`subgenre=indie`
`subgenre__terms`	Multiple subgenres	`subgenre__terms=indie__alternative`
`mood`	Single mood	`mood=happy`
`mood__terms`	Multiple moods	`mood__terms=happy__sad`
`vocals`	Single vocal type	`vocals=Male Vocals`
`vocals__terms`	Multiple vocal types	`vocals__terms=Male Vocals__Female Vocals`
`tempo`	Tempo descriptor	`tempo=fast`
`tempo__terms`	Multiple tempos	`tempo__terms=fast__slow`
`bpm__range`	BPM range, low and high	`bpm__range=90__120`
`duration__range`	Duration range in seconds	`duration__range=60__300`
`title`	Exact track title	`title=Circle`
`title__contains`	Partial title match	`title__contains=Circ`
`artist`	Exact artist name	`artist=Hint of Mint`
`artist__contains`	Partial artist match	`artist__contains=T-P`
`album`	Exact album name	`album=Bad Habit Tracks`
`album__contains`	Partial album match	`album__contains=Bad Hab`
`restricted`	Filter by restricted flag	`restricted=True`

For the live, complete list of valid values for each filter, call GET /api/v4/search/ai/filters/.

The __terms suffix lets you pass multiple values for any list-style filter. Separate values with __ (double underscore).

The Track object

Every search endpoint returns the same shape for each track in results:

{
  "id": "8a4b2c1d-9e7f-4a6b-b3c2-1f8d4e5a7c6b",
  "name": "Cinematic Rise",
  "artist": { "name": "Jane Doe", "slug": "jane-doe" },
  "length": 142,
  "tempo": 128,
  "is_explicit": false,
  "is_free": true,
  "audio_url": "/api/v4/stream/8a4b2c1d-9e7f-4a6b-b3c2-1f8d4e5a7c6b/?type=track",
  "genre_name": "Cinematic",
  "subgenre_name": "Orchestral",
  "mood_name": "Inspiring",
  "secondary_mood_name": "Hopeful",
  "vocals": "",
  "has_stems": true,
  "cover": "https://...",
  "release_date": "2025-09-12",
  "short_url": "https://slipstreammusic.com/t/...",
  "restricted": false,
  "highlights": []
}

Field	Description
`id`	Slipstream track UUID. Pass to `/by-id/` to find similar, or to the Licensing API.
`name`	Track title.
`artist`	Artist with `name` and `slug`.
`length`	Duration in seconds.
`tempo`	BPM.
`is_explicit`	`true` if marked explicit.
`is_free`	`true` if usable without a paid tier. Inverse of `restricted`.
`audio_url`	Stream proxy path. Records play analytics, redirects to a presigned S3 URL.
`genre_name`, `subgenre_name`, `mood_name`, `secondary_mood_name`	Primary classifications.
`vocals`	Vocal type (e.g., `Male Vocals`, `Female Vocals`, `Mixed Vocals`). Empty for instrumentals.
`has_stems`	`true` if individual stems are available.
`cover`	Cover image URL.
`release_date`	Release date in `YYYY-MM-DD`.
`short_url`	Public Slipstream link to the track.
`restricted`	`true` if the track is restricted (paid tiers, regional rules, etc).
`highlights`	Highlight regions on the audio when the result is from a similarity search.

Errors

HTTP	When
400	Missing required parameter or invalid filter value
429	Rate limit exceeded — back off using the `Retry-After` header
500	The underlying AI service is temporarily unavailable

Overview Search by text