Folders

Folders are the library's structure: the Assets page browses them, uploads land in them, and the API reads and manages them under the asset scopes. A folder has an id, a name, a parent_id (null at the root) and a path (every folder from the root down to it). Names are unique within their parent, case-insensitively.

Reading folders#

GET /assets/folders lists one level of the tree: the root by default, or the children of parent_id. Each folder carries its path, its folder_count (direct sub-folders) and its asset_count (assets directly inside).

curl "https://app.nubu.app/api/v1/assets/folders?parent_id=<folder id>" \
  -H "Authorization: Bearer nubu_api_..."

To find a folder anywhere in the tree by name, pass q instead: GET /assets/folders?q=summer returns every folder whose name contains it (at most limit, default 200), each with its path. Folder lists are not paged: a level lists all its children.

GET /assets/folders/<id> reads one folder and adds subtree: how many folders and assets lie beneath it.

Creating folders#

curl -X POST https://app.nubu.app/api/v1/assets/folders \
  -H "Authorization: Bearer nubu_api_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Summer sale", "parent_id": null }'

The answer (201) carries the folder. Pass parent_id to nest it. Several folders go in one call with { "folders": [ { "name": "Hero" , "parent_id": "<id>" }, ... ] } (up to 50): the answer lists a folder or an error per entry, in order. A name already used in the same parent answers 409 conflict; a parent that is not the organisation's answers 422 validation_failed.

Uploading into a folder#

Pass "folder_id" when you begin an upload (Uploading assets), on a single begin or on every file of a batch. GET /assets?folder_id=<id> lists what a folder holds.

Renaming and moving#

PATCH /assets/folders/<id> with name, parent_id (null for the root) or both. Moving a folder into itself or into one of its own sub-folders answers 422.

Assets move with POST /assets/move:

curl -X POST https://app.nubu.app/api/v1/assets/move \
  -H "Authorization: Bearer nubu_api_..." \
  -H "Content-Type: application/json" \
  -d '{ "asset_ids": ["<asset id>", "<asset id>"], "folder_id": "<folder id>" }'

Up to 1,000 ids in one call; the answer says how many moved (an id that is not the organisation's is skipped). A single asset also moves through PATCH /assets/<id> with folder_id.

Deleting a folder#

DELETE /assets/folders/<id> deletes the folder, its sub-folders and every asset inside them, rows and files, freeing the storage they used, exactly as deleting a folder on the Assets page does. The answer counts what went:

{ "deleted": true, "id": "...", "folders": 3, "assets": 12 }

Creatives that used a deleted asset are cleaned up the way the app does it. While any asset inside the tree is queued for a render or rendering, the delete answers 409 conflict with details.reason render_locked and nothing is deleted; wait for the render to finish.