> 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/assets.md).

# Assets

Manage workspace assets: upload, organise, duplicate, move and download.

## List Assets

> List assets in a workspace, optionally filtered by folder.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListAssetsResponse":{"type":"object","properties":{"assets":{"type":"array","items":{"$ref":"#/components/schemas/v1Asset"},"description":"The list of assets.","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 assets 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":"=============================================================\nAssetService response messages\n=============================================================\nResponse for ListAssets."},"v1Asset":{"type":"object","properties":{"name":{"type":"string","title":"Server-assigned resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/assets/{asset}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name for this asset (e.g., \"Q1 Report.pdf\").\nMust be unique within the same folder (or workspace root) in the workspace."},"description":{"type":"string","description":"Optional description."},"folder_name":{"type":"string","description":"Resource name of the folder this asset belongs to.\nEmpty means the asset is at the workspace root (no folder)."},"file_name":{"type":"string","title":"Reference to the underlying Bishop file (org-scoped file_id).\nFormat: organizations/{organization}/files/{file}","readOnly":true},"mime_type":{"type":"string","description":"Server-detected MIME type of the uploaded file.","readOnly":true},"size_bytes":{"type":"string","format":"int64","description":"Size of the file in bytes.","readOnly":true},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form string labels attached to this asset.\nTags are workspace-scoped — the same string may exist on multiple assets\nwithin a workspace. A single asset may carry multiple tags.\nEach tag is stored as provided (trimmed of surrounding whitespace), but\ntags are compared case-insensitively: \"Finance\" and \"finance\" are the same\ntag. Duplicates by case on one asset are dropped (the first one is kept).\nLimits: at most 20 tags per asset; each tag 1-255 characters after trimming.\nTags are updatable via UpdateAsset (include \"tags\" in update_mask).\nUse ListWorkspaceTags to enumerate all tags in use within a workspace."},"created_by":{"type":"string","description":"ID of the user who created this asset.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was last updated (renamed, moved, description changed, or tags changed).","readOnly":true},"reference_uri":{"type":"string","description":"This is an opaque, stable identity handle — NOT a publicly fetchable URL.\nIt deliberately does not embed organization/workspace: callers must\nresolve those from their own request context (e.g. the parent they used\nto look up this asset), never by parsing them out of this string.\nConsumers pass it through bishop-url's parser and resolve it to bytes via\nthe authenticated Asset/File services (e.g. GenerateAssetDownloadUrl).","title":"Canonical bishop:// handle that uniquely identifies this asset's\nunderlying file.\nFormat: bishop://{id}--{filename}   e.g. bishop://ab12cd34--report.pdf","readOnly":true}},"description":"An asset — a workspace-scoped file reference that records human-readable\nname, optional folder placement, and a link to the underlying Bishop file.\n\nAsset bytes are stored in Bishop's existing file storage at the org level.\nThe Asset Manager tracks the workspace + folder context in PostgreSQL.","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}/assets":{"get":{"summary":"List Assets","description":"List assets in a workspace, optionally filtered by folder.","operationId":"ListAssets","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListAssetsResponse"}}}},"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_name","description":"If set, list only assets in this folder.\nIf empty, list assets at the workspace root (no folder).\nUse the special value \"*\" to list all assets across all folders.","in":"query","required":false,"schema":{"type":"string"}},{"name":"page_size","description":"Maximum number of assets to return. Valid: 1–1000. Default: 50.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"Page token from a previous ListAssets call.","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 = \"report\" or display_name : \"rep\"\n  mime_type      — string equality or substring: mime_type = \"application/pdf\" or mime_type : \"pdf\"\n  created_by     — exact string equality:        created_by = \"user@example.com\"\n  tags           — has-tag check (: operator):   tags : \"quarterly\"\n                   tags = \"quarterly\" is also accepted and behaves identically.\n                   Matching is case-insensitive: tags : \"QUARTERLY\" matches \"Quarterly\".\n                   Each term checks one tag; combine several with AND / OR.\n  reference_uri  — exact string equality:        reference_uri = \"bishop://{id}--{filename}\"\n                   Useful when Jarvis or another caller already holds a bishop:// handle\n                   and needs to resolve it back to the full Asset resource. A bare\n                   resource name or presigned HTTPS URL is also accepted; any\n                   org/workspace such a value carries is ignored — org/workspace are\n                   always taken from `parent` above.\n\nLogical operators AND, OR, and parentheses are supported.\n\nExamples:\n  filter = \"mime_type = \\\"application/pdf\\\"\"\n  filter = \"tags : \\\"quarterly\\\" AND created_by = \\\"alice@example.com\\\"\"\n  filter = \"(mime_type : \\\"image\\\" OR mime_type : \\\"video\\\") AND tags : \\\"media\\\"\"\n  filter = \"reference_uri = \\\"bishop://abc123--report.pdf\\\"\"","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, size_bytes, mime_type.\nExample: \"create_time desc\" or \"display_name asc, size_bytes desc\".\nDefault: \"display_name asc\".","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Assets"]}}}}
```

## Create Asset

> Register a new asset by linking an already-uploaded Bishop file to\
> workspace/folder/tag metadata. See upload flow above.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Asset":{"type":"object","properties":{"name":{"type":"string","title":"Server-assigned resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/assets/{asset}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name for this asset (e.g., \"Q1 Report.pdf\").\nMust be unique within the same folder (or workspace root) in the workspace."},"description":{"type":"string","description":"Optional description."},"folder_name":{"type":"string","description":"Resource name of the folder this asset belongs to.\nEmpty means the asset is at the workspace root (no folder)."},"file_name":{"type":"string","title":"Reference to the underlying Bishop file (org-scoped file_id).\nFormat: organizations/{organization}/files/{file}","readOnly":true},"mime_type":{"type":"string","description":"Server-detected MIME type of the uploaded file.","readOnly":true},"size_bytes":{"type":"string","format":"int64","description":"Size of the file in bytes.","readOnly":true},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form string labels attached to this asset.\nTags are workspace-scoped — the same string may exist on multiple assets\nwithin a workspace. A single asset may carry multiple tags.\nEach tag is stored as provided (trimmed of surrounding whitespace), but\ntags are compared case-insensitively: \"Finance\" and \"finance\" are the same\ntag. Duplicates by case on one asset are dropped (the first one is kept).\nLimits: at most 20 tags per asset; each tag 1-255 characters after trimming.\nTags are updatable via UpdateAsset (include \"tags\" in update_mask).\nUse ListWorkspaceTags to enumerate all tags in use within a workspace."},"created_by":{"type":"string","description":"ID of the user who created this asset.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was last updated (renamed, moved, description changed, or tags changed).","readOnly":true},"reference_uri":{"type":"string","description":"This is an opaque, stable identity handle — NOT a publicly fetchable URL.\nIt deliberately does not embed organization/workspace: callers must\nresolve those from their own request context (e.g. the parent they used\nto look up this asset), never by parsing them out of this string.\nConsumers pass it through bishop-url's parser and resolve it to bytes via\nthe authenticated Asset/File services (e.g. GenerateAssetDownloadUrl).","title":"Canonical bishop:// handle that uniquely identifies this asset's\nunderlying file.\nFormat: bishop://{id}--{filename}   e.g. bishop://ab12cd34--report.pdf","readOnly":true}},"description":"An asset — a workspace-scoped file reference that records human-readable\nname, optional folder placement, and a link to the underlying Bishop file.\n\nAsset bytes are stored in Bishop's existing file storage at the org level.\nThe Asset Manager tracks the workspace + folder context in PostgreSQL.","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":{}},"AssetServiceCreateAssetBody":{"type":"object","properties":{"asset":{"$ref":"#/components/schemas/v1Asset"},"file_name":{"type":"string","title":"Resource name of the already-uploaded Bishop file.\nObtained from FilesHttpService.UploadFile response.\nFormat: organizations/{organization}/files/{file}"}},"description":"=============================================================\nAssetService request messages\n=============================================================\nRequest to register a new asset.\n\nUpload flow (2-step):\n  1. Client uploads the file via the existing Bishop file upload service\n     (FilesHttpService.UploadFile) and receives a file resource name.\n  2. Client calls CreateAsset with that file_name and the desired metadata.\n\nThe Asset Service records the workspace + folder context and tag metadata\nin PostgreSQL and links them to the already-uploaded Bishop file.","required":["asset","file_name"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets":{"post":{"summary":"Create Asset","description":"Register a new asset by linking an already-uploaded Bishop file to\nworkspace/folder/tag metadata. See upload flow above.","operationId":"CreateAsset","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Asset"}}}},"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/AssetServiceCreateAssetBody"}}},"required":true},"tags":["Assets"]}}}}
```

## Get Asset

> Get asset metadata by resource name.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Asset":{"type":"object","properties":{"name":{"type":"string","title":"Server-assigned resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/assets/{asset}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name for this asset (e.g., \"Q1 Report.pdf\").\nMust be unique within the same folder (or workspace root) in the workspace."},"description":{"type":"string","description":"Optional description."},"folder_name":{"type":"string","description":"Resource name of the folder this asset belongs to.\nEmpty means the asset is at the workspace root (no folder)."},"file_name":{"type":"string","title":"Reference to the underlying Bishop file (org-scoped file_id).\nFormat: organizations/{organization}/files/{file}","readOnly":true},"mime_type":{"type":"string","description":"Server-detected MIME type of the uploaded file.","readOnly":true},"size_bytes":{"type":"string","format":"int64","description":"Size of the file in bytes.","readOnly":true},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form string labels attached to this asset.\nTags are workspace-scoped — the same string may exist on multiple assets\nwithin a workspace. A single asset may carry multiple tags.\nEach tag is stored as provided (trimmed of surrounding whitespace), but\ntags are compared case-insensitively: \"Finance\" and \"finance\" are the same\ntag. Duplicates by case on one asset are dropped (the first one is kept).\nLimits: at most 20 tags per asset; each tag 1-255 characters after trimming.\nTags are updatable via UpdateAsset (include \"tags\" in update_mask).\nUse ListWorkspaceTags to enumerate all tags in use within a workspace."},"created_by":{"type":"string","description":"ID of the user who created this asset.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was last updated (renamed, moved, description changed, or tags changed).","readOnly":true},"reference_uri":{"type":"string","description":"This is an opaque, stable identity handle — NOT a publicly fetchable URL.\nIt deliberately does not embed organization/workspace: callers must\nresolve those from their own request context (e.g. the parent they used\nto look up this asset), never by parsing them out of this string.\nConsumers pass it through bishop-url's parser and resolve it to bytes via\nthe authenticated Asset/File services (e.g. GenerateAssetDownloadUrl).","title":"Canonical bishop:// handle that uniquely identifies this asset's\nunderlying file.\nFormat: bishop://{id}--{filename}   e.g. bishop://ab12cd34--report.pdf","readOnly":true}},"description":"An asset — a workspace-scoped file reference that records human-readable\nname, optional folder placement, and a link to the underlying Bishop file.\n\nAsset bytes are stored in Bishop's existing file storage at the org level.\nThe Asset Manager tracks the workspace + folder context in PostgreSQL.","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}/assets/{asset_id}":{"get":{"summary":"Get Asset","description":"Get asset metadata by resource name.","operationId":"GetAsset","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Asset"}}}},"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":"asset_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Assets"]}}}}
```

## Delete Asset

> Delete an asset (removes metadata and the underlying Bishop file).

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"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}/assets/{asset_id}":{"delete":{"summary":"Delete Asset","description":"Delete an asset (removes metadata and the underlying Bishop file).","operationId":"DeleteAsset","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":"asset_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Assets"]}}}}
```

## Update Asset

> Update mutable asset fields: display\_name, description, tags.\
> Use MoveAsset to change the folder.\
> Include "tags" in update\_mask to replace or clear tags (see UpdateAssetRequest).

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Asset":{"type":"object","properties":{"name":{"type":"string","title":"Server-assigned resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/assets/{asset}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name for this asset (e.g., \"Q1 Report.pdf\").\nMust be unique within the same folder (or workspace root) in the workspace."},"description":{"type":"string","description":"Optional description."},"folder_name":{"type":"string","description":"Resource name of the folder this asset belongs to.\nEmpty means the asset is at the workspace root (no folder)."},"file_name":{"type":"string","title":"Reference to the underlying Bishop file (org-scoped file_id).\nFormat: organizations/{organization}/files/{file}","readOnly":true},"mime_type":{"type":"string","description":"Server-detected MIME type of the uploaded file.","readOnly":true},"size_bytes":{"type":"string","format":"int64","description":"Size of the file in bytes.","readOnly":true},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form string labels attached to this asset.\nTags are workspace-scoped — the same string may exist on multiple assets\nwithin a workspace. A single asset may carry multiple tags.\nEach tag is stored as provided (trimmed of surrounding whitespace), but\ntags are compared case-insensitively: \"Finance\" and \"finance\" are the same\ntag. Duplicates by case on one asset are dropped (the first one is kept).\nLimits: at most 20 tags per asset; each tag 1-255 characters after trimming.\nTags are updatable via UpdateAsset (include \"tags\" in update_mask).\nUse ListWorkspaceTags to enumerate all tags in use within a workspace."},"created_by":{"type":"string","description":"ID of the user who created this asset.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was last updated (renamed, moved, description changed, or tags changed).","readOnly":true},"reference_uri":{"type":"string","description":"This is an opaque, stable identity handle — NOT a publicly fetchable URL.\nIt deliberately does not embed organization/workspace: callers must\nresolve those from their own request context (e.g. the parent they used\nto look up this asset), never by parsing them out of this string.\nConsumers pass it through bishop-url's parser and resolve it to bytes via\nthe authenticated Asset/File services (e.g. GenerateAssetDownloadUrl).","title":"Canonical bishop:// handle that uniquely identifies this asset's\nunderlying file.\nFormat: bishop://{id}--{filename}   e.g. bishop://ab12cd34--report.pdf","readOnly":true}},"description":"An asset — a workspace-scoped file reference that records human-readable\nname, optional folder placement, and a link to the underlying Bishop file.\n\nAsset bytes are stored in Bishop's existing file storage at the org level.\nThe Asset Manager tracks the workspace + folder context in PostgreSQL.","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}/assets/{asset_id}":{"patch":{"summary":"Update Asset","description":"Update mutable asset fields: display_name, description, tags.\nUse MoveAsset to change the folder.\nInclude \"tags\" in update_mask to replace or clear tags (see UpdateAssetRequest).","operationId":"UpdateAsset","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Asset"}}}},"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":"asset_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"update_mask","description":"Field mask specifying which fields to update.\nUpdatable fields: display_name, description, tags.\n\nTag update semantics (via field mask):\n  - Include \"tags\" in update_mask + provide asset.tags = [\"a\",\"b\"] → replace all tags with [\"a\",\"b\"]\n  - Include \"tags\" in update_mask + provide asset.tags = []         → clear all tags\n  - Omit \"tags\" from update_mask                                    → leave tags unchanged\n\nTags are compared case-insensitively; duplicates by case are dropped (the\nfirst one is kept). At most 20 tags; each 1-255 characters after trimming.","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 asset (e.g., \"Q1 Report.pdf\").\nMust be unique within the same folder (or workspace root) in the workspace."},"description":{"type":"string","description":"Optional description."},"folder_name":{"type":"string","description":"Resource name of the folder this asset belongs to.\nEmpty means the asset is at the workspace root (no folder)."},"file_name":{"type":"string","title":"Reference to the underlying Bishop file (org-scoped file_id).\nFormat: organizations/{organization}/files/{file}","readOnly":true},"mime_type":{"type":"string","description":"Server-detected MIME type of the uploaded file.","readOnly":true},"size_bytes":{"type":"string","format":"int64","description":"Size of the file in bytes.","readOnly":true},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form string labels attached to this asset.\nTags are workspace-scoped — the same string may exist on multiple assets\nwithin a workspace. A single asset may carry multiple tags.\nEach tag is stored as provided (trimmed of surrounding whitespace), but\ntags are compared case-insensitively: \"Finance\" and \"finance\" are the same\ntag. Duplicates by case on one asset are dropped (the first one is kept).\nLimits: at most 20 tags per asset; each tag 1-255 characters after trimming.\nTags are updatable via UpdateAsset (include \"tags\" in update_mask).\nUse ListWorkspaceTags to enumerate all tags in use within a workspace."},"created_by":{"type":"string","description":"ID of the user who created this asset.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was last updated (renamed, moved, description changed, or tags changed).","readOnly":true},"reference_uri":{"type":"string","description":"This is an opaque, stable identity handle — NOT a publicly fetchable URL.\nIt deliberately does not embed organization/workspace: callers must\nresolve those from their own request context (e.g. the parent they used\nto look up this asset), never by parsing them out of this string.\nConsumers pass it through bishop-url's parser and resolve it to bytes via\nthe authenticated Asset/File services (e.g. GenerateAssetDownloadUrl).","title":"Canonical bishop:// handle that uniquely identifies this asset's\nunderlying file.\nFormat: bishop://{id}--{filename}   e.g. bishop://ab12cd34--report.pdf","readOnly":true}},"title":"The asset with updated fields. The name field identifies which asset.","required":["display_name"]}}},"description":"The asset with updated fields. The name field identifies which asset.","required":true},"tags":["Assets"]}}}}
```

## Duplicate Asset

> Duplicate an asset — creates a server-side file copy and a new asset record.\
> The new asset's display\_name is prefixed "Copy of "; the original is unchanged.\
> Returns the newly created Asset.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Asset":{"type":"object","properties":{"name":{"type":"string","title":"Server-assigned resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/assets/{asset}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name for this asset (e.g., \"Q1 Report.pdf\").\nMust be unique within the same folder (or workspace root) in the workspace."},"description":{"type":"string","description":"Optional description."},"folder_name":{"type":"string","description":"Resource name of the folder this asset belongs to.\nEmpty means the asset is at the workspace root (no folder)."},"file_name":{"type":"string","title":"Reference to the underlying Bishop file (org-scoped file_id).\nFormat: organizations/{organization}/files/{file}","readOnly":true},"mime_type":{"type":"string","description":"Server-detected MIME type of the uploaded file.","readOnly":true},"size_bytes":{"type":"string","format":"int64","description":"Size of the file in bytes.","readOnly":true},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form string labels attached to this asset.\nTags are workspace-scoped — the same string may exist on multiple assets\nwithin a workspace. A single asset may carry multiple tags.\nEach tag is stored as provided (trimmed of surrounding whitespace), but\ntags are compared case-insensitively: \"Finance\" and \"finance\" are the same\ntag. Duplicates by case on one asset are dropped (the first one is kept).\nLimits: at most 20 tags per asset; each tag 1-255 characters after trimming.\nTags are updatable via UpdateAsset (include \"tags\" in update_mask).\nUse ListWorkspaceTags to enumerate all tags in use within a workspace."},"created_by":{"type":"string","description":"ID of the user who created this asset.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was last updated (renamed, moved, description changed, or tags changed).","readOnly":true},"reference_uri":{"type":"string","description":"This is an opaque, stable identity handle — NOT a publicly fetchable URL.\nIt deliberately does not embed organization/workspace: callers must\nresolve those from their own request context (e.g. the parent they used\nto look up this asset), never by parsing them out of this string.\nConsumers pass it through bishop-url's parser and resolve it to bytes via\nthe authenticated Asset/File services (e.g. GenerateAssetDownloadUrl).","title":"Canonical bishop:// handle that uniquely identifies this asset's\nunderlying file.\nFormat: bishop://{id}--{filename}   e.g. bishop://ab12cd34--report.pdf","readOnly":true}},"description":"An asset — a workspace-scoped file reference that records human-readable\nname, optional folder placement, and a link to the underlying Bishop file.\n\nAsset bytes are stored in Bishop's existing file storage at the org level.\nThe Asset Manager tracks the workspace + folder context in PostgreSQL.","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":{}},"AssetServiceDuplicateAssetBody":{"type":"object","properties":{"destination_folder_name":{"type":"string","title":"Destination folder for the duplicated asset.\nEmpty (default) places the copy in the same folder as the original.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"}},"description":"=============================================================\nAssetService — single-item custom-method request messages (ENG-3815)\n=============================================================\nRequest to duplicate an asset.\nCreates a server-side file copy (object-store copy; no bytes transit the API)\nand registers a new asset record with display_name prefixed \"Copy of \"."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets/{asset_id}:duplicate":{"post":{"summary":"Duplicate Asset","description":"Duplicate an asset — creates a server-side file copy and a new asset record.\nThe new asset's display_name is prefixed \"Copy of \"; the original is unchanged.\nReturns the newly created Asset.","operationId":"DuplicateAsset","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Asset"}}}},"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":"asset_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetServiceDuplicateAssetBody"}}},"required":true},"tags":["Assets"]}}}}
```

## Generate Asset Download Url

> Generate a presigned download URL for an asset.\
> Delegates to Bishop FilesService.GenerateDownloadUrl.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GenerateAssetDownloadUrlResponse":{"type":"object","properties":{"download_uri":{"type":"string","description":"Presigned download URL for the asset. Valid for expire_duration (default 1 hour).","readOnly":true}},"description":"Response for GenerateAssetDownloadUrl."},"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":{}},"AssetServiceGenerateAssetDownloadUrlBody":{"type":"object","properties":{"expire_duration":{"type":"string","description":"Optional URL expiry duration. Default: 1 hour."}},"description":"Request to generate a presigned download URL for an asset.\nDelegates to Bishop FilesService.GenerateDownloadUrl internally."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets/{asset_id}:generateDownloadUrl":{"post":{"summary":"Generate Asset Download Url","description":"Generate a presigned download URL for an asset.\nDelegates to Bishop FilesService.GenerateDownloadUrl.","operationId":"GenerateAssetDownloadUrl","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GenerateAssetDownloadUrlResponse"}}}},"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":"asset_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetServiceGenerateAssetDownloadUrlBody"}}},"required":true},"tags":["Assets"]}}}}
```

## Move Asset

> Move an asset to a different folder (or to the workspace root).

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Asset":{"type":"object","properties":{"name":{"type":"string","title":"Server-assigned resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/assets/{asset}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name for this asset (e.g., \"Q1 Report.pdf\").\nMust be unique within the same folder (or workspace root) in the workspace."},"description":{"type":"string","description":"Optional description."},"folder_name":{"type":"string","description":"Resource name of the folder this asset belongs to.\nEmpty means the asset is at the workspace root (no folder)."},"file_name":{"type":"string","title":"Reference to the underlying Bishop file (org-scoped file_id).\nFormat: organizations/{organization}/files/{file}","readOnly":true},"mime_type":{"type":"string","description":"Server-detected MIME type of the uploaded file.","readOnly":true},"size_bytes":{"type":"string","format":"int64","description":"Size of the file in bytes.","readOnly":true},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form string labels attached to this asset.\nTags are workspace-scoped — the same string may exist on multiple assets\nwithin a workspace. A single asset may carry multiple tags.\nEach tag is stored as provided (trimmed of surrounding whitespace), but\ntags are compared case-insensitively: \"Finance\" and \"finance\" are the same\ntag. Duplicates by case on one asset are dropped (the first one is kept).\nLimits: at most 20 tags per asset; each tag 1-255 characters after trimming.\nTags are updatable via UpdateAsset (include \"tags\" in update_mask).\nUse ListWorkspaceTags to enumerate all tags in use within a workspace."},"created_by":{"type":"string","description":"ID of the user who created this asset.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was last updated (renamed, moved, description changed, or tags changed).","readOnly":true},"reference_uri":{"type":"string","description":"This is an opaque, stable identity handle — NOT a publicly fetchable URL.\nIt deliberately does not embed organization/workspace: callers must\nresolve those from their own request context (e.g. the parent they used\nto look up this asset), never by parsing them out of this string.\nConsumers pass it through bishop-url's parser and resolve it to bytes via\nthe authenticated Asset/File services (e.g. GenerateAssetDownloadUrl).","title":"Canonical bishop:// handle that uniquely identifies this asset's\nunderlying file.\nFormat: bishop://{id}--{filename}   e.g. bishop://ab12cd34--report.pdf","readOnly":true}},"description":"An asset — a workspace-scoped file reference that records human-readable\nname, optional folder placement, and a link to the underlying Bishop file.\n\nAsset bytes are stored in Bishop's existing file storage at the org level.\nThe Asset Manager tracks the workspace + folder context in PostgreSQL.","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":{}},"AssetServiceMoveAssetBody":{"type":"object","properties":{"destination_folder_name":{"type":"string","title":"Destination folder resource name. Empty string means workspace root.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"}},"description":"Request to move an asset to a different folder (or to the workspace root)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets/{asset_id}:move":{"post":{"summary":"Move Asset","description":"Move an asset to a different folder (or to the workspace root).","operationId":"MoveAsset","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Asset"}}}},"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":"asset_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetServiceMoveAssetBody"}}},"required":true},"tags":["Assets"]}}}}
```

## Refresh Asset Content

> Refresh the asset's cached content fields — size\_bytes, mime\_type,\
> update\_time — from its backing file.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Asset":{"type":"object","properties":{"name":{"type":"string","title":"Server-assigned resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/assets/{asset}","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name for this asset (e.g., \"Q1 Report.pdf\").\nMust be unique within the same folder (or workspace root) in the workspace."},"description":{"type":"string","description":"Optional description."},"folder_name":{"type":"string","description":"Resource name of the folder this asset belongs to.\nEmpty means the asset is at the workspace root (no folder)."},"file_name":{"type":"string","title":"Reference to the underlying Bishop file (org-scoped file_id).\nFormat: organizations/{organization}/files/{file}","readOnly":true},"mime_type":{"type":"string","description":"Server-detected MIME type of the uploaded file.","readOnly":true},"size_bytes":{"type":"string","format":"int64","description":"Size of the file in bytes.","readOnly":true},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form string labels attached to this asset.\nTags are workspace-scoped — the same string may exist on multiple assets\nwithin a workspace. A single asset may carry multiple tags.\nEach tag is stored as provided (trimmed of surrounding whitespace), but\ntags are compared case-insensitively: \"Finance\" and \"finance\" are the same\ntag. Duplicates by case on one asset are dropped (the first one is kept).\nLimits: at most 20 tags per asset; each tag 1-255 characters after trimming.\nTags are updatable via UpdateAsset (include \"tags\" in update_mask).\nUse ListWorkspaceTags to enumerate all tags in use within a workspace."},"created_by":{"type":"string","description":"ID of the user who created this asset.","readOnly":true},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the asset was last updated (renamed, moved, description changed, or tags changed).","readOnly":true},"reference_uri":{"type":"string","description":"This is an opaque, stable identity handle — NOT a publicly fetchable URL.\nIt deliberately does not embed organization/workspace: callers must\nresolve those from their own request context (e.g. the parent they used\nto look up this asset), never by parsing them out of this string.\nConsumers pass it through bishop-url's parser and resolve it to bytes via\nthe authenticated Asset/File services (e.g. GenerateAssetDownloadUrl).","title":"Canonical bishop:// handle that uniquely identifies this asset's\nunderlying file.\nFormat: bishop://{id}--{filename}   e.g. bishop://ab12cd34--report.pdf","readOnly":true}},"description":"An asset — a workspace-scoped file reference that records human-readable\nname, optional folder placement, and a link to the underlying Bishop file.\n\nAsset bytes are stored in Bishop's existing file storage at the org level.\nThe Asset Manager tracks the workspace + folder context in PostgreSQL.","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":{}},"AssetServiceRefreshAssetContentBody":{"type":"object","description":"Request to refresh an asset's cached content fields from its backing file."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets/{asset_id}:refreshContent":{"post":{"summary":"Refresh Asset Content","description":"Refresh the asset's cached content fields — size_bytes, mime_type,\nupdate_time — from its backing file.","operationId":"RefreshAssetContent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Asset"}}}},"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":"asset_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetServiceRefreshAssetContentBody"}}},"required":true},"tags":["Assets"]}}}}
```

## Trace Asset Usage

> TraceAssetUsage returns all automations that reference a specific asset (file).\
> Assets are read-only references, so no usage type is reported. An asset id is the\
> underlying Bishop file id.\
> Per AIP-136, this is a custom method using the :traceAssetUsage suffix.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1TraceAssetUsageResponse":{"type":"object","properties":{"automations":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationAssetUsage"},"description":"Automations that reference the specified asset."}},"description":"TraceAssetUsageResponse returns automations that reference the specified asset."},"v1AutomationAssetUsage":{"type":"object","properties":{"automation_id":{"type":"string","description":"The automation ID that references the asset.\nThis is the automation ID portion only (e.g., the {automation} part of the resource name)."},"display_name":{"type":"string","description":"Display name of the automation (denormalized for UI convenience)."}},"description":"AutomationAssetUsage represents an automation that references a specific asset.\nAssets are read-only references, so no usage type is reported."},"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}/assets/{asset_id}:traceAssetUsage":{"get":{"summary":"Trace Asset Usage","description":"TraceAssetUsage returns all automations that reference a specific asset (file).\nAssets are read-only references, so no usage type is reported. An asset id is the\nunderlying Bishop file id.\nPer AIP-136, this is a custom method using the :traceAssetUsage suffix.","operationId":"TraceAssetUsage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1TraceAssetUsageResponse"}}}},"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":"asset_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Assets"]}}}}
```

## Batch Delete Assets

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

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1BatchDeleteAssetsResponse":{"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":"=============================================================\nAssetService — batch response messages (ENG-3815)\n=============================================================\nResponse for BatchDeleteAssets. 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":{}},"AssetServiceBatchDeleteAssetsBody":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"},"title":"Resource names of the assets to delete. Max 100 per request.\nFormat: organizations/{organization}/workspaces/{workspace}/assets/{asset}"}},"description":"=============================================================\nAssetService — batch request messages (ENG-3815)\n=============================================================\nRequest to delete multiple assets in a single best-effort call.\nEach asset is deleted independently; failures are recorded per-item.","required":["names"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets:batchDelete":{"post":{"summary":"Batch Delete Assets","description":"Delete multiple assets in a single best-effort call.\nEach asset is deleted independently; per-item results are returned.","operationId":"BatchDeleteAssets","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1BatchDeleteAssetsResponse"}}}},"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/AssetServiceBatchDeleteAssetsBody"}}},"required":true},"tags":["Assets"]}}}}
```

## Batch Download Assets

> Build a ZIP archive of multiple assets and return a presigned download URL.\
> Assets are collected 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":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1BatchDownloadAssetsResponse":{"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 assets that could not be included in the archive.\nItems with OK status were successfully added. Items with non-OK status\nwere skipped; their names are still returned here for client awareness.","readOnly":true}},"description":"Response for BatchDownloadAssets.\nThe server builds a ZIP of all successfully resolved assets and returns\na single 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":{}},"AssetServiceBatchDownloadAssetsBody":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"},"title":"Resource names of the assets to include. Max 100 per request.\nFormat: organizations/{organization}/workspaces/{workspace}/assets/{asset}"},"expire_duration":{"type":"string","description":"Optional URL expiry duration for the archive download URL. Default: 15 minutes."}},"description":"Request to generate a presigned download URL for each of a batch of assets.\nEach asset produces its own presigned URL + ZIP archive entry.\nThe server builds a ZIP archive containing all successfully resolved assets\nand returns a single presigned URL for the archive.","required":["names"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets:batchDownload":{"post":{"summary":"Batch Download Assets","description":"Build a ZIP archive of multiple assets and return a presigned download URL.\nAssets are collected independently; per-item errors are recorded without\nfailing the overall request.","operationId":"BatchDownloadAssets","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1BatchDownloadAssetsResponse"}}}},"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/AssetServiceBatchDownloadAssetsBody"}}},"required":true},"tags":["Assets"]}}}}
```

## Batch Duplicate Assets

> Duplicate multiple assets in a single best-effort call.\
> Each asset is duplicated independently; per-item results are returned.\
> On success, the result name is the resource name of the new copy.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1BatchDuplicateAssetsResponse":{"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 copy.","readOnly":true}},"description":"Response for BatchDuplicateAssets."},"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":{}},"AssetServiceBatchDuplicateAssetsBody":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"},"title":"Resource names of the assets to duplicate. Max 100 per request.\nFormat: organizations/{organization}/workspaces/{workspace}/assets/{asset}"},"destination_folder_name":{"type":"string","title":"Optional destination folder for all copies.\nEmpty (default) places each copy in the same folder as its original.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"}},"description":"Request to duplicate multiple assets in a single best-effort call.\nEach asset is duplicated independently; failures are recorded per-item.\nCopies are placed in destination_folder_name if set; otherwise each copy\nlands in the same folder as its original.","required":["names"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets:batchDuplicate":{"post":{"summary":"Batch Duplicate Assets","description":"Duplicate multiple assets in a single best-effort call.\nEach asset is duplicated independently; per-item results are returned.\nOn success, the result name is the resource name of the new copy.","operationId":"BatchDuplicateAssets","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1BatchDuplicateAssetsResponse"}}}},"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/AssetServiceBatchDuplicateAssetsBody"}}},"required":true},"tags":["Assets"]}}}}
```

## Batch Move Assets

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

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1BatchMoveAssetsResponse":{"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 BatchMoveAssets."},"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":{}},"AssetServiceBatchMoveAssetsBody":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"},"title":"Resource names of the assets to move. Max 100 per request.\nFormat: organizations/{organization}/workspaces/{workspace}/assets/{asset}"},"destination_folder_name":{"type":"string","title":"Destination folder resource name. Empty string means workspace root.\nFormat: organizations/{organization}/workspaces/{workspace}/folders/{folder}"}},"description":"Request to move multiple assets to a destination folder in a single best-effort call.\nEach asset is moved independently; failures are recorded per-item.","required":["names"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/assets:batchMove":{"post":{"summary":"Batch Move Assets","description":"Move multiple assets to a destination folder in a single best-effort call.\nEach asset is moved independently; per-item results are returned.","operationId":"BatchMoveAssets","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1BatchMoveAssetsResponse"}}}},"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/AssetServiceBatchMoveAssetsBody"}}},"required":true},"tags":["Assets"]}}}}
```

## List Workspace Tags

> List all unique tags in use across all assets in a workspace.\
> Returns a deduplicated, sorted list of tag strings. Tags are compared\
> case-insensitively, so each tag appears once regardless of case.\
> Used to populate the Tags filter dropdown in the Library UI.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Manage workspace assets: upload, organise, duplicate, move and download."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListWorkspaceTagsResponse":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"},"description":"Deduplicated, sorted list of all tag strings in use across all assets\nin the workspace. Tags are deduplicated case-insensitively, so each tag\nappears once. Used to populate the Tags filter dropdown in the Library UI.","readOnly":true}},"description":"Response for ListWorkspaceTags."},"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}/assets:tags":{"get":{"summary":"List Workspace Tags","description":"List all unique tags in use across all assets in a workspace.\nReturns a deduplicated, sorted list of tag strings. Tags are compared\ncase-insensitively, so each tag appears once regardless of case.\nUsed to populate the Tags filter dropdown in the Library UI.","operationId":"ListWorkspaceTags","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListWorkspaceTagsResponse"}}}},"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":["Assets"]}}}}
```
