POST /asset

Add an audio file from disk to a folder in your Curlo library, specifying its metadata at the same time. Ideal for automation: a field recorder or render pipeline drops a file, your script registers it in Curlo with title, artist, tags and UCS classification in one request.

This endpoint is also available as POST /api/asset — both paths are equivalent.

How It Works

folderPath must be the absolute disk path of a local folder that has already been added to Curlo. Collections are virtual and cannot be import targets.
If the file already lives inside the destination folder, it is indexed in place — nothing is copied.
Otherwise the file is copied into the folder by default; pass "move": true to move it instead. Existing files are never overwritten.
Physical properties (duration, sample rate, channels, format, …) are always detected automatically and cannot be overridden.
Metadata you provide takes precedence over values read from the file; a field you omit keeps its auto-detected value, and an empty string clears it.
Curlo fingerprints every import: re-adding an identical file to the same folder returns 409 with the existing asset’s ID.
After creation, the asset is queued for AI vector indexing in the background, so semantic search picks it up once indexing completes.

Request

{
  "filePath": "/Users/me/Downloads/boom_v2.wav",
  "folderPath": "/Volumes/SFX/Explosions",
  "move": false,
  "writeToFile": false,
  "title": "Big Boom v2",
  "artist": "StudioX",
  "genre": "Cinematic",
  "comment": "Great for trailers",
  "assetType": "sfx",
  "isFavorite": true,
  "tags": ["explosion", "cinematic"],
  "ucsCatID": "EXPLReal",
  "ucsFxName": "Boom Big 02",
  "ucsCreatorID": "StudioX",
  "ucsSourceID": "Action Pack Y"
}

Request Fields

Field	Type	Description
`filePath`	`string`	Required. Absolute path to the audio file on disk (`~` is expanded). Must use a supported format (WAV, MP3, FLAC, AIFF, …)
`folderPath`	`string`	Required. Absolute path of the destination folder — a local folder already added to Curlo
`move`	`boolean`	Optional. `false` (default) copies the file into the folder; `true` moves it. Ignored when the file is already inside the destination folder
`writeToFile`	`boolean`	Optional. `false` (default) stores metadata in Curlo’s database only; `true` additionally writes it into the audio file itself (standard tags, plus the UCS BEXT chunk for WAV)
`title`	`string`	Optional. Omitted = keep the value read from the file; `""` clears the field. Same semantics for all metadata fields below
`artist`	`string`	Optional artist override
`genre`	`string`	Optional genre override
`comment`	`string`	Optional comment override
`albumTitle`	`string`	Optional album title override
`grouping`	`string`	Optional grouping override
`bpm`	`number`	Optional BPM override
`assetType`	`string`	Optional. `"sfx"`, `"music"` or `"unknown"`
`isFavorite`	`boolean`	Optional. Mark the new asset as a favorite
`tags`	`string[]`	Optional tag names to assign. Tags that don’t exist yet are created automatically with an auto-assigned color
`ucsCatID`	`string`	Optional UCS Category ID override
`ucsFxName`	`string`	Optional UCS FxName override
`ucsCreatorID`	`string`	Optional UCS CreatorID override
`ucsSourceID`	`string`	Optional UCS SourceID override
`ucsUserCategory`	`string`	Optional UCS UserCategory override
`ucsVendorCategory`	`string`	Optional UCS VendorCategory override
`ucsUserData`	`string`	Optional UCS UserData override

Response

Returns 201 Created with the newly created asset — the same shape as GET /asset, plus one extra field:

{
  "id": 12347,
  "fileName": "boom_v2.wav",
  "format": "WAV",
  "duration": 3.2,
  "tags": ["explosion", "cinematic"],
  "warnings": ["Failed to create tag 'cinematic': network unavailable"]
}

Response Fields

All fields are identical to GET /asset. Additionally:

Field	Type	Description
`warnings`	`string[]`	Only present when non-fatal issues occurred (e.g. a tag could not be created, or writing metadata into the file failed). The asset itself was still created

Errors

Status	Meaning
`400`	Missing/empty `filePath` or `folderPath`, unsupported audio format, invalid `assetType`, or the file could not be parsed
`403`	Free-tier limit of 5,000 files reached
`404`	The audio file does not exist, or `folderPath` doesn’t match any local folder added to Curlo
`409`	A file with the same name already exists in the target folder, or an identical file (same fingerprint) is already indexed in it
`500`	Unexpected server error