> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/guides/api-reference/folders.md).

# Folders

Organise assets into folders.

## List Folders

> List folders in a workspace. Use parent\_folder\_name to list children of a folder.\
> If parent\_folder\_name is empty, returns root-level folders.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Folders","description":"Organise assets into folders."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListFoldersResponse":{"type":"object","properties":{"folders":{"type":"array","items":{"$ref":"#/components/schemas/v1Folder"},"description":"The list of folders.","readOnly":true},"next_page_token":{"type":"string","description":"Token to retrieve the next page of results.","readOnly":true},"total_size":{"type":"integer","format":"int32","description":"Total folders matching the request filters, across every page.\nIndependent of `page_size` and `page_token`: paging through the\ncollection reports the same value on each response.","readOnly":true}},"description":"=============================================================\nAssetFolderService response messages\n=============================================================\nResponse for ListFolders."},"v1Folder":{"type":"object","properties":{"name":{"type":"string","title":"Server-assigned resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name for this folder (e.g., \"Reports 2026\").\nMust be unique within the same parent folder in the same workspace."},"parent_folder_name":{"type":"string","title":"Resource name of the parent folder, or empty if this is a root folder.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"},"created_by":{"type":"string","description":"ID of the user who created this folder.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was last updated (renamed or moved).","readOnly":true},"asset_count":{"type":"integer","format":"int32","description":"Number of assets directly contained in this folder (non-recursive).","readOnly":true},"folder_count":{"type":"integer","format":"int32","description":"Number of immediate child folders (non-recursive).","readOnly":true}},"description":"=============================================================\nAsset & Folder types\n=============================================================\nA workspace-scoped folder for organising assets.\n\nFolders use an adjacency-list model: each folder optionally points to a\nparent_folder_name. A NULL parent means the folder is at the workspace\nroot. Arbitrary nesting depth is supported.","required":["display_name"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders":{"get":{"summary":"List Folders","description":"List folders in a workspace. Use parent_folder_name to list children of a folder.\nIf parent_folder_name is empty, returns root-level folders.","operationId":"ListFolders","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListFoldersResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"parent_folder_name","description":"If set, list only the immediate children of this folder.\nIf empty, list only root-level folders.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}","in":"query","required":false,"schema":{"type":"string"}},{"name":"page_size","description":"Maximum number of folders to return. Default: 50.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"Page token from a previous ListFolders call.","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"Comma-separated list of fields to sort by, with optional \" asc\" / \" desc\" suffix.\nSortable fields: display_name, create_time, update_time.\nExample: \"display_name asc\" or \"create_time desc\".\nDefault: \"display_name asc\".","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"AIP-160 filter expression.\n\nFilterable fields:\n  display_name  — string equality or substring: display_name = \"Reports\" or display_name : \"rep\"\n  created_by    — exact string equality:        created_by = \"user@example.com\"\n\nLogical operators AND, OR, and parentheses are supported.\n\nExamples:\n  filter = \"display_name : \\\"report\\\"\"\n  filter = \"created_by = \\\"alice@example.com\\\" AND display_name : \\\"2026\\\"\"","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Folders"]}}}}
```

## Create Folder

> Create a folder in a workspace. Set folder.parent\_folder\_name to nest it.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Folders","description":"Organise assets into folders."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Folder":{"type":"object","properties":{"name":{"type":"string","title":"Server-assigned resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name for this folder (e.g., \"Reports 2026\").\nMust be unique within the same parent folder in the same workspace."},"parent_folder_name":{"type":"string","title":"Resource name of the parent folder, or empty if this is a root folder.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"},"created_by":{"type":"string","description":"ID of the user who created this folder.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was last updated (renamed or moved).","readOnly":true},"asset_count":{"type":"integer","format":"int32","description":"Number of assets directly contained in this folder (non-recursive).","readOnly":true},"folder_count":{"type":"integer","format":"int32","description":"Number of immediate child folders (non-recursive).","readOnly":true}},"description":"=============================================================\nAsset & Folder types\n=============================================================\nA workspace-scoped folder for organising assets.\n\nFolders use an adjacency-list model: each folder optionally points to a\nparent_folder_name. A NULL parent means the folder is at the workspace\nroot. Arbitrary nesting depth is supported.","required":["display_name"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders":{"post":{"summary":"Create Folder","description":"Create a folder in a workspace. Set folder.parent_folder_name to nest it.","operationId":"CreateFolder","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Folder"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"folder_id","description":"Optional client-provided folder ID (UUID).","in":"query","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Folder"}}},"description":"The folder to create.\nTo create a nested folder, set folder.parent_folder_name.","required":true},"tags":["Folders"]}}}}
```

## Get Folder

> Get folder metadata by resource name.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Folders","description":"Organise assets into folders."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Folder":{"type":"object","properties":{"name":{"type":"string","title":"Server-assigned resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name for this folder (e.g., \"Reports 2026\").\nMust be unique within the same parent folder in the same workspace."},"parent_folder_name":{"type":"string","title":"Resource name of the parent folder, or empty if this is a root folder.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"},"created_by":{"type":"string","description":"ID of the user who created this folder.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was last updated (renamed or moved).","readOnly":true},"asset_count":{"type":"integer","format":"int32","description":"Number of assets directly contained in this folder (non-recursive).","readOnly":true},"folder_count":{"type":"integer","format":"int32","description":"Number of immediate child folders (non-recursive).","readOnly":true}},"description":"=============================================================\nAsset & Folder types\n=============================================================\nA workspace-scoped folder for organising assets.\n\nFolders use an adjacency-list model: each folder optionally points to a\nparent_folder_name. A NULL parent means the folder is at the workspace\nroot. Arbitrary nesting depth is supported.","required":["display_name"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders/{folder_id}":{"get":{"summary":"Get Folder","description":"Get folder metadata by resource name.","operationId":"GetFolder","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Folder"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"folder_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Folders"]}}}}
```

## Delete Folder

> Delete a folder. Set force=true to recursively delete all contents.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Folders","description":"Organise assets into folders."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders/{folder_id}":{"delete":{"summary":"Delete Folder","description":"Delete a folder. Set force=true to recursively delete all contents.","operationId":"DeleteFolder","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"folder_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"force","description":"If true, recursively delete all sub-folders and assets within this folder.\nIf false (default), returns FAILED_PRECONDITION if the folder is non-empty.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Folders"]}}}}
```

## Update Folder

> Update a folder (rename or move to a different parent).

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Folders","description":"Organise assets into folders."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Folder":{"type":"object","properties":{"name":{"type":"string","title":"Server-assigned resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name for this folder (e.g., \"Reports 2026\").\nMust be unique within the same parent folder in the same workspace."},"parent_folder_name":{"type":"string","title":"Resource name of the parent folder, or empty if this is a root folder.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"},"created_by":{"type":"string","description":"ID of the user who created this folder.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was last updated (renamed or moved).","readOnly":true},"asset_count":{"type":"integer","format":"int32","description":"Number of assets directly contained in this folder (non-recursive).","readOnly":true},"folder_count":{"type":"integer","format":"int32","description":"Number of immediate child folders (non-recursive).","readOnly":true}},"description":"=============================================================\nAsset & Folder types\n=============================================================\nA workspace-scoped folder for organising assets.\n\nFolders use an adjacency-list model: each folder optionally points to a\nparent_folder_name. A NULL parent means the folder is at the workspace\nroot. Arbitrary nesting depth is supported.","required":["display_name"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders/{folder_id}":{"patch":{"summary":"Update Folder","description":"Update a folder (rename or move to a different parent).","operationId":"UpdateFolder","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Folder"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"folder_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"update_mask","description":"Field mask specifying which fields to update.\nUpdatable fields: display_name, parent_folder_name.","in":"query","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"display_name":{"type":"string","description":"Human-readable display name for this folder (e.g., \"Reports 2026\").\nMust be unique within the same parent folder in the same workspace."},"parent_folder_name":{"type":"string","title":"Resource name of the parent folder, or empty if this is a root folder.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"},"created_by":{"type":"string","description":"ID of the user who created this folder.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was last updated (renamed or moved).","readOnly":true},"asset_count":{"type":"integer","format":"int32","description":"Number of assets directly contained in this folder (non-recursive).","readOnly":true},"folder_count":{"type":"integer","format":"int32","description":"Number of immediate child folders (non-recursive).","readOnly":true}},"title":"The folder with updated fields (display_name and/or parent_folder_name).\nThe name field identifies which folder to update.","required":["display_name"]}}},"description":"The folder with updated fields (display_name and/or parent_folder_name).\nThe name field identifies which folder to update.","required":true},"tags":["Folders"]}}}}
```

## Duplicate Folder

> Deep-duplicate a folder (including all descendant folders and assets).\
> Asset files are copied server-side; no bytes transit the API.\
> The root copy's display\_name is prefixed "Copy of "; descendant names are unchanged.\
> Returns the root Folder of the newly created subtree.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Folders","description":"Organise assets into folders."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Folder":{"type":"object","properties":{"name":{"type":"string","title":"Server-assigned resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name for this folder (e.g., \"Reports 2026\").\nMust be unique within the same parent folder in the same workspace."},"parent_folder_name":{"type":"string","title":"Resource name of the parent folder, or empty if this is a root folder.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"},"created_by":{"type":"string","description":"ID of the user who created this folder.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was last updated (renamed or moved).","readOnly":true},"asset_count":{"type":"integer","format":"int32","description":"Number of assets directly contained in this folder (non-recursive).","readOnly":true},"folder_count":{"type":"integer","format":"int32","description":"Number of immediate child folders (non-recursive).","readOnly":true}},"description":"=============================================================\nAsset & Folder types\n=============================================================\nA workspace-scoped folder for organising assets.\n\nFolders use an adjacency-list model: each folder optionally points to a\nparent_folder_name. A NULL parent means the folder is at the workspace\nroot. Arbitrary nesting depth is supported.","required":["display_name"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AssetFolderServiceDuplicateFolderBody":{"type":"object","properties":{"destination_parent_folder_name":{"type":"string","title":"Destination parent for the duplicated folder.\nEmpty (default) places the copy under the same parent as the original.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"}},"description":"Request to deep-duplicate a folder (including all descendant folders and assets).\nAll asset files are server-side copied (object-store copy; no bytes transit the API).\nThe root copy's display_name is prefixed \"Copy of \"; descendant names are unchanged."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders/{folder_id}:duplicate":{"post":{"summary":"Duplicate Folder","description":"Deep-duplicate a folder (including all descendant folders and assets).\nAsset files are copied server-side; no bytes transit the API.\nThe root copy's display_name is prefixed \"Copy of \"; descendant names are unchanged.\nReturns the root Folder of the newly created subtree.","operationId":"DuplicateFolder","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Folder"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"folder_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetFolderServiceDuplicateFolderBody"}}},"required":true},"tags":["Folders"]}}}}
```

## Move Folder

> Move a folder to a new parent (reparent). Returns the updated Folder.\
> Returns FAILED\_PRECONDITION if the move would create a cycle.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Folders","description":"Organise assets into folders."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Folder":{"type":"object","properties":{"name":{"type":"string","title":"Server-assigned resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name for this folder (e.g., \"Reports 2026\").\nMust be unique within the same parent folder in the same workspace."},"parent_folder_name":{"type":"string","title":"Resource name of the parent folder, or empty if this is a root folder.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"},"created_by":{"type":"string","description":"ID of the user who created this folder.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was last updated (renamed or moved).","readOnly":true},"asset_count":{"type":"integer","format":"int32","description":"Number of assets directly contained in this folder (non-recursive).","readOnly":true},"folder_count":{"type":"integer","format":"int32","description":"Number of immediate child folders (non-recursive).","readOnly":true}},"description":"=============================================================\nAsset & Folder types\n=============================================================\nA workspace-scoped folder for organising assets.\n\nFolders use an adjacency-list model: each folder optionally points to a\nparent_folder_name. A NULL parent means the folder is at the workspace\nroot. Arbitrary nesting depth is supported.","required":["display_name"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AssetFolderServiceMoveFolderBody":{"type":"object","properties":{"destination_parent_folder_name":{"type":"string","title":"New parent folder resource name.\nEmpty string means move to the workspace root (no parent).\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"}},"description":"=============================================================\nAssetFolderService — single-item custom-method request messages (ENG-3815)\n=============================================================\nRequest to move a folder to a new parent (reparent).\nReturns FAILED_PRECONDITION if the move would create a cycle."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders/{folder_id}:move":{"post":{"summary":"Move Folder","description":"Move a folder to a new parent (reparent). Returns the updated Folder.\nReturns FAILED_PRECONDITION if the move would create a cycle.","operationId":"MoveFolder","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Folder"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"folder_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetFolderServiceMoveFolderBody"}}},"required":true},"tags":["Folders"]}}}}
```

## Batch Delete Folders

> Delete multiple folders in a single best-effort call.\
> Each folder is deleted independently; per-item results are returned.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Folders","description":"Organise assets into folders."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1BatchDeleteFoldersResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/v1BatchItemResult"},"description":"Per-item results. Length and order match the request `names` list.","readOnly":true}},"description":"=============================================================\nAssetFolderService — batch response messages (ENG-3815)\n=============================================================\nResponse for BatchDeleteFolders. Uses BatchItemResult for best-effort per-item status."},"v1BatchItemResult":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the item that was processed.\nFor assets:  organizations/{org}/workspaces/{ws}/assets/{asset}\nFor folders: organizations/{org}/workspaces/{ws}/folders/{folder}","readOnly":true},"status":{"$ref":"#/components/schemas/rpcStatus"}},"description":"=============================================================\nBatch operation types (shared across batch RPCs)\n=============================================================\nPer-item result for a batch (best-effort) operation.\nReturned in all Batch* response messages."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AssetFolderServiceBatchDeleteFoldersBody":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"},"title":"Resource names of the folders to delete. Max 100 per request.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"},"force":{"type":"boolean","description":"If true, recursively delete all sub-folders and assets within each folder.\nIf false (default), a folder with contents results in FAILED_PRECONDITION for that item."}},"description":"=============================================================\nAssetFolderService — batch request messages (ENG-3815)\n=============================================================\nRequest to delete multiple folders in a single best-effort call.\nEach folder is deleted independently; failures are recorded per-item.","required":["names"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders:batchDelete":{"post":{"summary":"Batch Delete Folders","description":"Delete multiple folders in a single best-effort call.\nEach folder is deleted independently; per-item results are returned.","operationId":"BatchDeleteFolders","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1BatchDeleteFoldersResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetFolderServiceBatchDeleteFoldersBody"}}},"required":true},"tags":["Folders"]}}}}
```

## Batch Download Folders

> Build a ZIP archive of multiple folders (preserving relative structure)\
> and return a presigned download URL. Folders are processed independently;\
> per-item errors are recorded without failing the overall request.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Folders","description":"Organise assets into folders."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1BatchDownloadFoldersResponse":{"type":"object","properties":{"archive_uri":{"type":"string","description":"Presigned URL for the generated ZIP archive.\nValid for `expire_duration` (default 15 minutes).","readOnly":true},"results":{"type":"array","items":{"$ref":"#/components/schemas/v1BatchItemResult"},"description":"Per-item results for folders that could not be fully included in the archive.","readOnly":true}},"description":"Response for BatchDownloadFolders.\nThe server builds a single ZIP preserving the relative folder structure\nand returns a presigned URL for the archive."},"v1BatchItemResult":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the item that was processed.\nFor assets:  organizations/{org}/workspaces/{ws}/assets/{asset}\nFor folders: organizations/{org}/workspaces/{ws}/folders/{folder}","readOnly":true},"status":{"$ref":"#/components/schemas/rpcStatus"}},"description":"=============================================================\nBatch operation types (shared across batch RPCs)\n=============================================================\nPer-item result for a batch (best-effort) operation.\nReturned in all Batch* response messages."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AssetFolderServiceBatchDownloadFoldersBody":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"},"title":"Resource names of the folders to include. Max 20 per request.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"},"expire_duration":{"type":"string","description":"Optional URL expiry duration for the archive download URL. Default: 15 minutes."}},"description":"Request to download a ZIP archive of multiple folders.\nThe server recursively collects all assets within each folder (including descendants),\nbuilds a ZIP preserving the relative folder structure, and returns a single presigned URL.\nFolders are processed independently; per-item errors are recorded in the response.","required":["names"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders:batchDownload":{"post":{"summary":"Batch Download Folders","description":"Build a ZIP archive of multiple folders (preserving relative structure)\nand return a presigned download URL. Folders are processed independently;\nper-item errors are recorded without failing the overall request.","operationId":"BatchDownloadFolders","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1BatchDownloadFoldersResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetFolderServiceBatchDownloadFoldersBody"}}},"required":true},"tags":["Folders"]}}}}
```

## Batch Duplicate Folders

> Deep-duplicate multiple folders in a single best-effort call.\
> Each folder (and its entire subtree) is duplicated independently.\
> Per-item results are returned; on success the result name is the new root folder.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Folders","description":"Organise assets into folders."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1BatchDuplicateFoldersResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/v1BatchItemResult"},"description":"Per-item results. Length and order match the request `names` list.\nOn success, `BatchItemResult.name` is the resource name of the new root copy.","readOnly":true}},"description":"Response for BatchDuplicateFolders."},"v1BatchItemResult":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the item that was processed.\nFor assets:  organizations/{org}/workspaces/{ws}/assets/{asset}\nFor folders: organizations/{org}/workspaces/{ws}/folders/{folder}","readOnly":true},"status":{"$ref":"#/components/schemas/rpcStatus"}},"description":"=============================================================\nBatch operation types (shared across batch RPCs)\n=============================================================\nPer-item result for a batch (best-effort) operation.\nReturned in all Batch* response messages."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AssetFolderServiceBatchDuplicateFoldersBody":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"},"title":"Resource names of the folders to duplicate. Max 100 per request.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"},"destination_parent_folder_name":{"type":"string","title":"Optional destination parent for all copies.\nEmpty (default) places each copy under the same parent as its original.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"}},"description":"Request to deep-duplicate multiple folders in a single best-effort call.\nEach folder (and its entire subtree + assets) is duplicated independently.","required":["names"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders:batchDuplicate":{"post":{"summary":"Batch Duplicate Folders","description":"Deep-duplicate multiple folders in a single best-effort call.\nEach folder (and its entire subtree) is duplicated independently.\nPer-item results are returned; on success the result name is the new root folder.","operationId":"BatchDuplicateFolders","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1BatchDuplicateFoldersResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetFolderServiceBatchDuplicateFoldersBody"}}},"required":true},"tags":["Folders"]}}}}
```

## Batch Move Folders

> Move multiple folders to a destination parent in a single best-effort call.\
> Each folder is moved independently; per-item results are returned.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Folders","description":"Organise assets into folders."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1BatchMoveFoldersResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/v1BatchItemResult"},"description":"Per-item results. Length and order match the request `names` list.","readOnly":true}},"description":"Response for BatchMoveFolders."},"v1BatchItemResult":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the item that was processed.\nFor assets:  organizations/{org}/workspaces/{ws}/assets/{asset}\nFor folders: organizations/{org}/workspaces/{ws}/folders/{folder}","readOnly":true},"status":{"$ref":"#/components/schemas/rpcStatus"}},"description":"=============================================================\nBatch operation types (shared across batch RPCs)\n=============================================================\nPer-item result for a batch (best-effort) operation.\nReturned in all Batch* response messages."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AssetFolderServiceBatchMoveFoldersBody":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"},"title":"Resource names of the folders to move. Max 100 per request.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"},"destination_parent_folder_name":{"type":"string","title":"New parent folder resource name for all folders in `names`.\nEmpty string means move to the workspace root.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"}},"description":"Request to move multiple folders to a destination parent in a single best-effort call.\nEach folder is moved independently; failures (including cycle detection) are recorded per-item.","required":["names"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders:batchMove":{"post":{"summary":"Batch Move Folders","description":"Move multiple folders to a destination parent in a single best-effort call.\nEach folder is moved independently; per-item results are returned.","operationId":"BatchMoveFolders","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1BatchMoveFoldersResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetFolderServiceBatchMoveFoldersBody"}}},"required":true},"tags":["Folders"]}}}}
```

## Get Folder Tree

> Get the full folder tree for a workspace (all folders, nested).

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Folders","description":"Organise assets into folders."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GetFolderTreeResponse":{"type":"object","properties":{"roots":{"type":"array","items":{"$ref":"#/components/schemas/v1FolderTreeNode"},"description":"Root-level folder nodes (folders with no parent).","readOnly":true}},"description":"Response for GetFolderTree — the full folder hierarchy for a workspace."},"v1FolderTreeNode":{"type":"object","properties":{"folder":{"$ref":"#/components/schemas/v1Folder"},"children":{"type":"array","items":{"$ref":"#/components/schemas/v1FolderTreeNode"},"description":"Immediate child folders."}},"description":"A node in the folder tree returned by GetFolderTree."},"v1Folder":{"type":"object","properties":{"name":{"type":"string","title":"Server-assigned resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name for this folder (e.g., \"Reports 2026\").\nMust be unique within the same parent folder in the same workspace."},"parent_folder_name":{"type":"string","title":"Resource name of the parent folder, or empty if this is a root folder.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"},"created_by":{"type":"string","description":"ID of the user who created this folder.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the folder was last updated (renamed or moved).","readOnly":true},"asset_count":{"type":"integer","format":"int32","description":"Number of assets directly contained in this folder (non-recursive).","readOnly":true},"folder_count":{"type":"integer","format":"int32","description":"Number of immediate child folders (non-recursive).","readOnly":true}},"description":"=============================================================\nAsset & Folder types\n=============================================================\nA workspace-scoped folder for organising assets.\n\nFolders use an adjacency-list model: each folder optionally points to a\nparent_folder_name. A NULL parent means the folder is at the workspace\nroot. Arbitrary nesting depth is supported.","required":["display_name"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/folders:tree":{"get":{"summary":"Get Folder Tree","description":"Get the full folder tree for a workspace (all folders, nested).","operationId":"GetFolderTree","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetFolderTreeResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Folders"]}}}}
```
