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.

This endpoint is also available as POST /api/search — both paths are equivalent. Note that a GET request to /search returns 405; you must use POST with a JSON body.

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. Each value resolves in this order: an exact CatID (e.g. `"AIRBlow"`) matches that subcategory; a top-level Category name or its CatShort (e.g. `"ANIMALS"`, `"ANML"`) matches the entire category; unknown values fall back to prefix matching. See UCS resolution below.
`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`)

UCS Value Resolution

Each ucs string is resolved with case-insensitive matching, in this order:

Exact CatID — a known subcategory code (e.g. "AIRBlow", "ANMLCat") matches files assigned to exactly that subcategory.
Category name or CatShort — a top-level category name (e.g. "ANIMALS", "WEATHER") or its short code (e.g. "ANML", "WTHR") matches every subcategory in that category.
Fallback — unrecognized values are prefix-matched against assigned CatIDs.

Note: In UCS v8.2.1 a few strings are both a category’s CatShort and a specific subcategory’s CatID (e.g. "BEEP" is the BEEPS short code and the CatID of BEEPS-GENERAL; same for "RAIN", "WIND" and all ARCHIVED/WEATHER/SWOOSHES shorts). The exact CatID wins: "BEEP" matches only BEEPS-GENERAL. To filter a whole category, pass its Category name or a non-colliding short code — e.g. "BEEPS" for the entire BEEPS family.

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