GET
/v1/search
Search and browse tracks with the live filter surface.
| Name | Type | Required | Description |
|---|---|---|---|
| q | string | No | Natural-language or keyword query. Korean and English are both accepted by the translate layer. |
| genre / genres | string | string[] | No | Genre filter. Both singular and plural aliases are accepted. |
| mood / moods | string | string[] | No | Mood filter. Both singular and plural aliases are accepted. |
| tags | string | string[] | No | Public taxonomy tag filters. |
| use_cases | string | No | Single-select use case lane. Send one value only; multi-select is not part of v1. |
| instruments | string | string[] | No | Instrument overlap filter from the live browse surface. |
| bpm_min / bpmMin | number | No | Minimum tempo. Snake-case and camelCase aliases are accepted. |
| bpm_max / bpmMax | number | No | Maximum tempo. Snake-case and camelCase aliases are accepted. |
| valence_min / valenceMin | number | No | Minimum valence score. |
| valence_max / valenceMax | number | No | Maximum valence score. |
| arousal_min / arousalMin | number | No | Minimum arousal score. |
| arousal_max / arousalMax | number | No | Maximum arousal score. |
| energy_min / energyMin | number | No | Minimum energy score. |
| energy_max / energyMax | number | No | Maximum energy score. |
| danceability_min / danceabilityMin | number | No | Minimum danceability score. |
| danceability_max / danceabilityMax | number | No | Maximum danceability score. |
| key | string | No | Musical key filter. |
| duration_min / durationMin | number | No | Minimum track duration in seconds. |
| duration_max / durationMax | number | No | Maximum track duration in seconds. |
| content_type | uuid | No | Content type identifier. v1 expects the UUID value, not a slug. |
| instrumental | boolean | No | Restrict results to instrumental or vocal tracks. |
| sort | string | No | Sort mode from the live browse route. Cursor behavior follows the selected sort mode. |
| page | number | No | Page-based pagination input used by page-style sort modes. |
| cursor | string | No | Keyset cursor for cursor-enabled sort modes. Page-style modes use page semantics. |
| limit | number | No | Maximum result count for one response page. |
Response
{ tracks, nextCursor, hasMore }. Cursor semantics follow sort mode: page-style sorts use page; keyset-enabled sorts use cursor/nextCursor.
- use_cases is single-select in v1.
- content_type must be a UUID, not a slug.
- Korean and English are both accepted at q.
- Response header: X-Engine-Version