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

{
  "api_version": 1,
  "edition": "Ultra",
  "commands": ["search", "import", "transfer", "..."]
}

• 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.

• Name and id of each Group.

• 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": [...]
}

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

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

• limit / 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).

• 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,
  "database": "Main Library",                  // optional, default = open DB
  "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": [ { "path": "...", "error": "unreadable" } ],
  "import_id": 42, "group_id": 7,
  "assets": [ { "path": "...", "id": 88123 } ]
}

• basehead indexes files where they are… it never moves them.

{ "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.

{
  "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.