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

# Files

This document covers the following endpoints:\
\
1\. Uploading files to different parts of the app — **Upload file**\
2\. The files feature in projects\
\
Upload and download\
\
Files can be attached to tasks, task activities, chat messages, customers, and the files page. First **Upload file**; the server returns the file ID. Use that ID in other endpoints.\
\
Files page endpoints\
\
These endpoints let you view, create, update, and delete files and folders on a project or customer Files page.\
\
The Files page is like a computer or Google Drive file system: nested file and directory nodes with a root directory at the top. Directories hold child file and directory nodes. File nodes are not the same as the file record returned by **Upload file**. File node records point to file records.

## Upload file

> Uploads a file and returns its record. \`multipart/form-data\`. Maximum 4 GB.

```json
{"openapi":"3.0.3","info":{"title":"Cubicl API","version":"1.0.0"},"tags":[{"name":"Files","description":"This document covers the following endpoints:<br><br>1. Uploading files to different parts of the app — **Upload file**<br>2. The files feature in projects<br><br>Upload and download<br><br>Files can be attached to tasks, task activities, chat messages, customers, and the files page. First **Upload file**; the server returns the file ID. Use that ID in other endpoints.<br><br>Files page endpoints<br><br>These endpoints let you view, create, update, and delete files and folders on a project or customer Files page.<br><br>The Files page is like a computer or Google Drive file system: nested file and directory nodes with a root directory at the top. Directories hold child file and directory nodes. File nodes are not the same as the file record returned by **Upload file**. File node records point to file records."}],"servers":[{"url":"https://cubicl.io/api/v1","description":"Cubicl production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Access token from the Integrations page. Header: `Authorization: Bearer YOUR_ACCESS_TOKEN`."}},"schemas":{"FileUploadRequest":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"File content and file name"}}},"File":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"thumbnail":{"type":"string"},"google":{"type":"object","properties":{"id":{"type":"string"},"extension":{"type":"string"},"webViewLink":{"type":"string"},"mimeType":{"type":"string"}}},"dropbox":{"type":"object","properties":{"id":{"type":"string"},"webViewLink":{"type":"string"}}}}},"UploadFile403Response":{"type":"object","properties":{"code":{"type":"integer"},"totalCapacity":{"type":"number","description":"Bytes"},"totalSize":{"type":"number","description":"Bytes"}}},"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"ValidationFailed":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"paths":{"/files/upload":{"post":{"tags":["Files"],"summary":"Upload file","description":"Uploads a file and returns its record. `multipart/form-data`. Maximum 4 GB.","operationId":"uploadFile","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/FileUploadRequest"}}}},"responses":{"200":{"description":"File details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"400":{"description":"Bad request"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadFile403Response"}}}},"422":{"$ref":"#/components/responses/ValidationFailed"}}}}}}
```

## Get download URL

> Files uploaded to Cubicl cannot be accessed without permission. Request a download URL, then send an HTTP request to that URL. Links expire after 5 minutes; request a new one after that.

```json
{"openapi":"3.0.3","info":{"title":"Cubicl API","version":"1.0.0"},"tags":[{"name":"Files","description":"This document covers the following endpoints:<br><br>1. Uploading files to different parts of the app — **Upload file**<br>2. The files feature in projects<br><br>Upload and download<br><br>Files can be attached to tasks, task activities, chat messages, customers, and the files page. First **Upload file**; the server returns the file ID. Use that ID in other endpoints.<br><br>Files page endpoints<br><br>These endpoints let you view, create, update, and delete files and folders on a project or customer Files page.<br><br>The Files page is like a computer or Google Drive file system: nested file and directory nodes with a root directory at the top. Directories hold child file and directory nodes. File nodes are not the same as the file record returned by **Upload file**. File node records point to file records."}],"servers":[{"url":"https://cubicl.io/api/v1","description":"Cubicl production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Access token from the Integrations page. Header: `Authorization: Bearer YOUR_ACCESS_TOKEN`."}},"parameters":{"IdPath":{"name":"id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ObjectId"},"description":"Record ID"}},"schemas":{"ObjectId":{"type":"string","description":"MongoDB ObjectId"},"ErrorCodeMessage":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Application error code. Not an HTTP status code."},"message":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"ValidationFailed":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"paths":{"/files/{id}/url":{"get":{"tags":["Files"],"summary":"Get download URL","description":"Files uploaded to Cubicl cannot be accessed without permission. Request a download URL, then send an HTTP request to that URL. Links expire after 5 minutes; request a new one after that.","operationId":"getFileDownloadUrl","parameters":[{"$ref":"#/components/parameters/IdPath"}],"responses":{"200":{"description":"Download URL","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorCodeMessage"}}}},"422":{"$ref":"#/components/responses/ValidationFailed"}}}}}}
```

## List nodes

> Returns file and directory nodes in a directory. The request must include \`group\` or \`customer\`.

```json
{"openapi":"3.0.3","info":{"title":"Cubicl API","version":"1.0.0"},"tags":[{"name":"Files","description":"This document covers the following endpoints:<br><br>1. Uploading files to different parts of the app — **Upload file**<br>2. The files feature in projects<br><br>Upload and download<br><br>Files can be attached to tasks, task activities, chat messages, customers, and the files page. First **Upload file**; the server returns the file ID. Use that ID in other endpoints.<br><br>Files page endpoints<br><br>These endpoints let you view, create, update, and delete files and folders on a project or customer Files page.<br><br>The Files page is like a computer or Google Drive file system: nested file and directory nodes with a root directory at the top. Directories hold child file and directory nodes. File nodes are not the same as the file record returned by **Upload file**. File node records point to file records."}],"servers":[{"url":"https://cubicl.io/api/v1","description":"Cubicl production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Access token from the Integrations page. Header: `Authorization: Bearer YOUR_ACCESS_TOKEN`."}},"schemas":{"ObjectId":{"type":"string","description":"MongoDB ObjectId"},"FileSystemNodeList":{"type":"array","items":{"$ref":"#/components/schemas/FileSystemNode"}},"FileSystemNode":{"type":"object","properties":{"_id":{"type":"string"},"parent":{"type":"string","nullable":true},"group":{"type":"string"},"customer":{"type":"string"},"type":{"type":"string","enum":["f","d"],"description":"`f`: file, `d`: directory"},"file":{"allOf":[{"$ref":"#/components/schemas/File"}],"nullable":true},"name":{"type":"string"},"createdAt":{"$ref":"#/components/schemas/UnixTimestamp"}}},"File":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"thumbnail":{"type":"string"},"google":{"type":"object","properties":{"id":{"type":"string"},"extension":{"type":"string"},"webViewLink":{"type":"string"},"mimeType":{"type":"string"}}},"dropbox":{"type":"object","properties":{"id":{"type":"string"},"webViewLink":{"type":"string"}}}}},"UnixTimestamp":{"type":"number","description":"Unix timestamp (seconds)"},"ErrorCode":{"type":"object","required":["code"],"properties":{"code":{"type":"integer","description":"Application error code. Not an HTTP status code."}}},"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"ForbiddenCode":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorCode"}}}},"ValidationFailed":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"paths":{"/file-system-nodes":{"get":{"tags":["Files"],"summary":"List nodes","description":"Returns file and directory nodes in a directory. The request must include `group` or `customer`.","operationId":"listFileSystemNodes","parameters":[{"name":"group","in":"query","schema":{"$ref":"#/components/schemas/ObjectId"},"description":"Project ID"},{"name":"customer","in":"query","schema":{"$ref":"#/components/schemas/ObjectId"},"description":"Customer ID"},{"name":"parent","in":"query","schema":{"allOf":[{"$ref":"#/components/schemas/ObjectId"},{"nullable":true}]},"description":"Directory ID. Use `null` for the root. If omitted, searches all directories."},{"name":"search","in":"query","schema":{"type":"string"},"description":"Text to search in file and directory names"}],"responses":{"200":{"description":"File system nodes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileSystemNodeList"}}}},"403":{"$ref":"#/components/responses/ForbiddenCode"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}}}}
```

## Delete nodes

> Deletes file and directory nodes from a project or customer. File nodes are deleted together with the file records and uploaded files. Nodes from different projects or customers cannot be deleted in one request.

```json
{"openapi":"3.0.3","info":{"title":"Cubicl API","version":"1.0.0"},"tags":[{"name":"Files","description":"This document covers the following endpoints:<br><br>1. Uploading files to different parts of the app — **Upload file**<br>2. The files feature in projects<br><br>Upload and download<br><br>Files can be attached to tasks, task activities, chat messages, customers, and the files page. First **Upload file**; the server returns the file ID. Use that ID in other endpoints.<br><br>Files page endpoints<br><br>These endpoints let you view, create, update, and delete files and folders on a project or customer Files page.<br><br>The Files page is like a computer or Google Drive file system: nested file and directory nodes with a root directory at the top. Directories hold child file and directory nodes. File nodes are not the same as the file record returned by **Upload file**. File node records point to file records."}],"servers":[{"url":"https://cubicl.io/api/v1","description":"Cubicl production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Access token from the Integrations page. Header: `Authorization: Bearer YOUR_ACCESS_TOKEN`."}},"schemas":{"DeleteFileSystemNodesRequest":{"type":"object","required":["nodes"],"properties":{"nodes":{"type":"array","items":{"type":"string"},"description":"ID list of nodes to delete"}}},"ErrorPlain":{"type":"string"},"ErrorCode":{"type":"object","required":["code"],"properties":{"code":{"type":"integer","description":"Application error code. Not an HTTP status code."}}}},"responses":{"ForbiddenCode":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorCode"}}}},"NotFoundEmpty":{"description":"Not found"}}},"paths":{"/file-system-nodes":{"delete":{"tags":["Files"],"summary":"Delete nodes","description":"Deletes file and directory nodes from a project or customer. File nodes are deleted together with the file records and uploaded files. Nodes from different projects or customers cannot be deleted in one request.","operationId":"deleteFileSystemNodes","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteFileSystemNodesRequest"}}}},"responses":{"204":{"description":"No content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorPlain"}}}},"403":{"$ref":"#/components/responses/ForbiddenCode"},"404":{"$ref":"#/components/responses/NotFoundEmpty"},"422":{"description":"Invalid operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorCode"}}}}}}}}}
```

## Add files

> Creates file nodes for uploaded files. \`group\` or \`customer\` must be set. Upload files first with \*\*Upload file\*\*.

```json
{"openapi":"3.0.3","info":{"title":"Cubicl API","version":"1.0.0"},"tags":[{"name":"Files","description":"This document covers the following endpoints:<br><br>1. Uploading files to different parts of the app — **Upload file**<br>2. The files feature in projects<br><br>Upload and download<br><br>Files can be attached to tasks, task activities, chat messages, customers, and the files page. First **Upload file**; the server returns the file ID. Use that ID in other endpoints.<br><br>Files page endpoints<br><br>These endpoints let you view, create, update, and delete files and folders on a project or customer Files page.<br><br>The Files page is like a computer or Google Drive file system: nested file and directory nodes with a root directory at the top. Directories hold child file and directory nodes. File nodes are not the same as the file record returned by **Upload file**. File node records point to file records."}],"servers":[{"url":"https://cubicl.io/api/v1","description":"Cubicl production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Access token from the Integrations page. Header: `Authorization: Bearer YOUR_ACCESS_TOKEN`."}},"schemas":{"CreateFileSystemFileNodesRequest":{"type":"object","required":["parent","files"],"properties":{"group":{"type":"string","description":"Project ID if on a project Files page"},"customer":{"type":"string","description":"Customer ID if on a customer Files page"},"parent":{"type":"string","nullable":true,"description":"Parent directory ID. `null` if the parent is the root."},"files":{"description":"File ID list","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}},"FileSystemNodeList":{"type":"array","items":{"$ref":"#/components/schemas/FileSystemNode"}},"FileSystemNode":{"type":"object","properties":{"_id":{"type":"string"},"parent":{"type":"string","nullable":true},"group":{"type":"string"},"customer":{"type":"string"},"type":{"type":"string","enum":["f","d"],"description":"`f`: file, `d`: directory"},"file":{"allOf":[{"$ref":"#/components/schemas/File"}],"nullable":true},"name":{"type":"string"},"createdAt":{"$ref":"#/components/schemas/UnixTimestamp"}}},"File":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"thumbnail":{"type":"string"},"google":{"type":"object","properties":{"id":{"type":"string"},"extension":{"type":"string"},"webViewLink":{"type":"string"},"mimeType":{"type":"string"}}},"dropbox":{"type":"object","properties":{"id":{"type":"string"},"webViewLink":{"type":"string"}}}}},"UnixTimestamp":{"type":"number","description":"Unix timestamp (seconds)"},"ErrorCode":{"type":"object","required":["code"],"properties":{"code":{"type":"integer","description":"Application error code. Not an HTTP status code."}}}},"responses":{"ForbiddenCode":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorCode"}}}}}},"paths":{"/file-system-nodes/files":{"post":{"tags":["Files"],"summary":"Add files","description":"Creates file nodes for uploaded files. `group` or `customer` must be set. Upload files first with **Upload file**.","operationId":"createFileSystemFileNodes","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileSystemFileNodesRequest"}}}},"responses":{"200":{"description":"File system node list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileSystemNodeList"}}}},"403":{"$ref":"#/components/responses/ForbiddenCode"},"422":{"description":"Invalid operation"}}}}}}
```

## Add directory

> Creates a directory node. \`group\` or \`customer\` must be set. If the parent is the root, \`parent\` must be \`null\`.

```json
{"openapi":"3.0.3","info":{"title":"Cubicl API","version":"1.0.0"},"tags":[{"name":"Files","description":"This document covers the following endpoints:<br><br>1. Uploading files to different parts of the app — **Upload file**<br>2. The files feature in projects<br><br>Upload and download<br><br>Files can be attached to tasks, task activities, chat messages, customers, and the files page. First **Upload file**; the server returns the file ID. Use that ID in other endpoints.<br><br>Files page endpoints<br><br>These endpoints let you view, create, update, and delete files and folders on a project or customer Files page.<br><br>The Files page is like a computer or Google Drive file system: nested file and directory nodes with a root directory at the top. Directories hold child file and directory nodes. File nodes are not the same as the file record returned by **Upload file**. File node records point to file records."}],"servers":[{"url":"https://cubicl.io/api/v1","description":"Cubicl production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Access token from the Integrations page. Header: `Authorization: Bearer YOUR_ACCESS_TOKEN`."}},"schemas":{"CreateFileSystemDirectoryRequest":{"type":"object","required":["name"],"properties":{"group":{"type":"string","description":"Project ID if on a project Files page"},"customer":{"type":"string","description":"Customer ID if on a customer Files page"},"parent":{"type":"string","nullable":true,"description":"Parent directory ID. `null` if the parent is the root."},"name":{"type":"string","description":"Directory name"}}},"FileSystemNode":{"type":"object","properties":{"_id":{"type":"string"},"parent":{"type":"string","nullable":true},"group":{"type":"string"},"customer":{"type":"string"},"type":{"type":"string","enum":["f","d"],"description":"`f`: file, `d`: directory"},"file":{"allOf":[{"$ref":"#/components/schemas/File"}],"nullable":true},"name":{"type":"string"},"createdAt":{"$ref":"#/components/schemas/UnixTimestamp"}}},"File":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"thumbnail":{"type":"string"},"google":{"type":"object","properties":{"id":{"type":"string"},"extension":{"type":"string"},"webViewLink":{"type":"string"},"mimeType":{"type":"string"}}},"dropbox":{"type":"object","properties":{"id":{"type":"string"},"webViewLink":{"type":"string"}}}}},"UnixTimestamp":{"type":"number","description":"Unix timestamp (seconds)"},"ErrorCode":{"type":"object","required":["code"],"properties":{"code":{"type":"integer","description":"Application error code. Not an HTTP status code."}}}},"responses":{"ForbiddenCode":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorCode"}}}}}},"paths":{"/file-system-nodes/directories":{"post":{"tags":["Files"],"summary":"Add directory","description":"Creates a directory node. `group` or `customer` must be set. If the parent is the root, `parent` must be `null`.","operationId":"createFileSystemDirectory","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileSystemDirectoryRequest"}}}},"responses":{"200":{"description":"File system node","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileSystemNode"}}}},"403":{"$ref":"#/components/responses/ForbiddenCode"},"422":{"description":"Invalid operation"}}}}}}
```
