Folders
Hierarchical containers for Assets. Folders can be nested, listed, downloaded as a single archive, and shared externally.
Scopes
| Scope | Reach |
|---|---|
store:read | Listing, reading, downloading, viewing shares. |
store:write | Creating, updating, patching, deleting. |
Endpoints
List Folders
GET /api/store/folder/
Returns a page of folder records.
Required scope: store:read · also accepts API key
Query parameters — standard pagination set; see Conventions › Pagination. Defaults: sort_by=created, sort_order=desc, hydrate=true.
Response 200 — FolderInDbCursorPage
Get Folder Filter Metadata
GET /api/store/folder/filters
Returns the filter/operator/sort options accepted by List Folders. See Conventions › Filter Metadata.
Required scope: store:read
Response 200 — open metadata object.
Get Folder by ID
GET /api/store/folder/{id}
Returns a single folder.
Required scope: store:read · also accepts API key
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Folder ID. |
Response 200 — FolderRead
Get Folder Shares
GET /api/store/folder/{id}/shares
Lists every share record that targets a given folder.
Required scope: store:read
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Folder ID. |
Response 200 — array of share records.
Download Folder
GET /api/store/folder/{id}/download
Downloads the contents of a folder as a single archive (zip).
Required scope: store:read
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Folder ID. |
Response 200 — binary archive stream.
Create Folder
POST /api/store/folder/
Creates a new folder. Supply a parent ID in the body to nest it under another folder; omit for a root-level folder.
Required scope: store:write
Request body — FolderWriteCreate
Response 201 — FolderRead
Update Folder by ID
PUT /api/store/folder/{id}
Replaces the folder's metadata (name, parent, etc.).
Required scope: store:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Folder ID. |
Request body — FolderWriteReplace
Response 200 — FolderRead
Patch Folder
PATCH /api/store/folder/{id}
Partial folder update — supply only the fields you want to change.
Required scope: store:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Folder ID. |
Request body — FolderWriteUpdate
Response 200 — FolderRead
Delete Folder by ID
DELETE /api/store/folder/{id}
Removes the folder. Behavior on non-empty folders (cascade vs. reject) is defined by tenant configuration — check the response body of any 409 Conflict for guidance.
Required scope: store:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Folder ID. |
Response 204 — empty.