{
  "version": "2026.10.27",
  "database": "Main Library",
  "target_app": "REAPER",
  "target_running": true
}

{
  "api_version": 1,
  "version": "2026.10.31",
  "edition": "Ultra",
  "commands": ["GET status", "POST search", "POST collections", "..."]
}

• Lists every local and shared database and marks the one that’s open.

• Category → SubCategory tree, with how many files in the open database fall under each.

• Name, id and root path of each Import.

• Child folders and file counts under path. Leave it empty for the Import root.
• The full folder path is the folder’s id… folders aren’t stored as records.
• Built lazily, one level at a time, so it stays fast on multi-million-file libraries.
• limit / offset page the folders (default 100, max 1000).

{ "path": "...", "total": 12, "folders": [ { "name": "Close", "path": "...", "count": 340 } ] }

• Name and id of each Group.

{ "name": "Car Pass-by" }

{ "id": 7, "name": "Car Pass-by", "created": true }

{ "ids": [88123, 88130] }

{ "added": 2, "skipped": 0, "missing": [] }

• If a Group with that name already exists you get it back with "created": false.
• Sounds already in the Group are skipped. Nothing is ever removed.

• First call lists Collection names. Second returns one Collection’s folder tree with its sounds… path limits it to one subfolder.
• Collections work across databases. Each sound returns its path and cached metadata, plus its id when it’s in the open database.

{
  "name": "Car Pass-by",
  "folders": [ { "name": "Exteriors", "folders": [...], "sounds": [...] } ],
  "sounds": [...]
}

{ "name": "Car Pass-by", "folder": "Exteriors/Close", "ids": [88123, 88130] }

{
  "name": "Car Pass-by", "folder": "Exteriors/Close", "created": true,
  "added": 2, "skipped": 0, "missing": []
}

• The Collection and every folder in folder are created if they don’t exist.
• A Collection keeps its sounds in folders, so folder is required when you send ids.
• Sounds already in that folder are skipped. Nothing is ever removed.

{
  "query": "night",
  "ucs_category": "AMBIENCE",
  "ucs_subcategory": "URBAN",
  "folder": "/Volumes/SFX/AMBIENCE/URBAN",   // path starts-with
  "import_id": 42,
  "min_duration": 30,
  "max_duration": 120,
  "channels": 2,
  "sample_rate": 48000,
  "limit": 50,
  "offset": 0
}

{ "total": 312, "results": [ { sound }, ... ] }

• ucs_category / ucs_subcategory match the UCS name exactly (e.g. DOORS, METAL).
• folder is a full folder path as it is on disk (e.g. from imports/{id}/folders); includes subfolders.
• query uses basehead’s search syntax (e.g. car pass -truck).
• limit (default 50, max 500) / offset page the results so a broad search never returns hundreds of thousands of rows at once.

• Everything in the sound object plus all metadata fields and markers (cue / region / loop / sync). Markers are read from WAV files.

• The files currently selected in basehead’s Results… the user picks in basehead, your tool reads them.

{
  "paths": ["/Volumes/SFX/Deliveries/Ep01"],   // files and/or folders
  "recursive": true,                              // true only for now (false returns 400)
  "database": "Main Library",                  // optional: must be the open database (others are refused)
  "import": { "id": 42 },                         // or { "new": "Ep01 Deliveries" }
  "group":  { "new": "Car Pass-by" }             // optional, or { "id": 7 }
}

{ "job_id": "imp-01", "status": "running" }

{
  "status": "done", "added": 212, "skipped": 3,
  "failed": [ { "error": "..." } ],
  "import_id": 42, "group_id": 7,
  "assets": [ { "path": "...", "id": 88123 } ]
}

• basehead indexes files where they are… it never moves them.
• Leave out "import" and a new Import is created, named after the folder.
• One API import at a time… a second one returns 409 until the first is done.

{ "ids": [88123, 88130], "foreground": true }

• Shows and selects those files in Results so the user can tag them with basehead’s own tools.
• foreground (default false): true also brings basehead to the front… false leaves focus with your tool.
• Up to 4000 ids per call.

{
  "id": 88123,
  "dest": "/Projects/Ep01/SFX",
  "sample_rate": 48000,   // optional
  "bit_depth": 24,       // optional
  "format": "wav"        // optional: wav | flac
}

• Uses the user’s Transfer settings (rename, handles, etc.).
• sample_rate / bit_depth / format override for this call only… saved settings are never changed.
• Returns the path of the written file.
• Cloud files (CloudPacks, Sound Swap) can’t be transferred yet.
• dest is created if it doesn’t exist.
• One transfer at a time (409 if basehead is already transferring).
• sample_rate: 44100, 48000, 88200, 96000, 176400 or 192000. bit_depth: 16, 24 or 32. FLAC is max 24-bit and 8 channels.
• Refused while Force Reference is on in Transfer options, and for split (virtual) records.

{ "ids": [88123, 88130] }

{
  "daw": "REAPER", "sent": 2,
  "files": ["/Volumes/SFX/...wav", "..."],
  "skipped": [ { "id": 9, "reason": "offline (not found on disk)" } ]
}

• Same as pressing X in basehead: sends the sounds to the running target DAW (Options → Target Apps): REAPER, Pro Tools, Nuendo / Cubase, Logic, Premiere or Resolve.
• Always by reference: the DAW gets the original files and basehead makes no copy. (Pro Tools copies them into the session’s Audio Files folder itself.)
• 409 if no target DAW is selected, it isn’t running, or basehead is busy transferring.
• Cloud (CloudPack / Sound Swap), split and offline files are skipped with a reason. Pro Tools also skips FLAC files.
• sent means handed to the DAW. If the DAW refuses something, basehead shows its usual message.
• Up to 500 ids per call.