POST /search
Search your audio library using semantic or metadata search. Pass a flat JSON body with your desired filters. All fields are optional, allowing you to send only the parameters you need.
Request
{
"q": "dog barking",
"target": "all",
"tags": ["Thunder", "Sci-Fi"],
"ucs": ["AIRBlow", "ANMLCat"],
"formats": ["WAV", "AIFF"],
"sampleRates": [44100, 48000],
"channels": [1, 2],
"bitDepths": [24],
"minDuration": 1.0,
"maxDuration": 10.0,
"sort": "BestMatch",
"ascending": false,
"limit": 50,
"offset": 0
}
Request Fields
| Field | Type | Description |
|---|
q | string | Search query text |
target | string | Search mode (default: "all"). See table below. |
tags | string[] | Filter by tag names, e.g. ["Thunder", "Sci-Fi"] |
ucs | string[] | Filter by UCS CatIDs, e.g. ["AIRBlow", "ANMLCat"] |
formats | string[] | File format filter, e.g. ["WAV", "MP3"] |
sampleRates | number[] | Sample rate filter, e.g. [44100, 48000] |
channels | number[] | Channel count filter, e.g. [1, 2] |
bitDepths | number[] | Bit depth filter, e.g. [16, 24] |
minDuration | number | Minimum duration in seconds |
maxDuration | number | Maximum duration in seconds |
sort | string | Sort option (default: "BestMatch"). See table below. |
ascending | boolean | Sort direction (default: false) |
limit | number | Max results to return (default: 50) |
offset | number | Pagination offset (default: 0) |
Valid target Values
| Value | Description |
|---|
"all" | Hybrid search (semantic + metadata, default) |
"semantic" | Semantic (AI-powered) search only |
"sfx" | Restrict to SFX files |
"music" | Restrict to Music files |
"tag" | Filter by tag name |
"fileName" | Search by file name |
"artist" | Search by artist |
"grouping" | Search by grouping |
"genre" | Search by genre |
"albumTitle" | Search by album title |
"comment" | Search by comment |
"ucsId" | Search by UCS Category / SubCategory |
"ucsFxName" | Search by UCS FxName |
"ucsCreatorID" | Search by UCS CreatorID |
"ucsSourceID" | Search by UCS SourceID |
"ucsUserCategory" | Search by UCS UserCategory |
"ucsVendorCategory" | Search by UCS VendorCategory |
"ucsUserData" | Search by UCS UserData |
Valid sort Values
| Value | Description |
|---|
"BestMatch" | Sort by relevance score (recommended with semantic / hybrid search) |
"DateAdded" | Sort by date the file was added to the library |
"FileName" | Sort alphabetically by file name |
"Duration" | Sort by audio duration |
"FileSize" | Sort by file size |
"SampleRate" | Sort by sample rate |
"Channels" | Sort by channel count |
"UCSCategory" | Sort by UCS category |
"format" | Sort by file format |
"artist" | Sort by artist |
"albumTitle" | Sort by album title |
"genre" | Sort by genre |
Response
Returns a JSON array of matched file objects.
[
{
"id": 12345,
"absoluteURL": "file:///Users/username/Audio/SFX/explosion_huge.wav",
"score": 95.5,
"matches": [
{
"chunkId": 6789,
"segments": [[0.5, 2.1], [3.0, 4.5]],
"score": 92.0
}
]
}
]
Response Fields
| Field | Type | Description |
|---|
id | number | Unique identifier for the audio asset |
absoluteURL | string | Absolute local file path URL |
score | number | Highest relevance score for the file (0–100) |
matches | array | List of matched audio chunks/segments |
matches[].chunkId | number | ID of the specific matched audio chunk |
matches[].segments | array | Time segments [start, end] in seconds where the match occurs |
matches[].score | number | Relevance score for this specific chunk |
