# Files

This document contains endpoints for

1. Uploading files to different parts of the app
2. Files feature in the projects

## Uploading and Downloading

Files can be uploaded to tasks, task activities, chat messages, clients, and the files page. For all of these operations, first, you need to send a request to upload the file. After the upload completes, the server will return the id of the file. Then, you can use this id in other API endpoints.

## Upload File

<mark style="color:green;">`POST`</mark> `https://cubicl.io/api/v1/files/upload`

Uploads a file to use later. Returns the details of the saved file.

Unlike other API endpoints, this endpoint accepts a `multipart/form-data` request. The `Content-Length` header must be set to the size of the form data.

Files up to 4GB (4 million KB) in size are supported.

#### Request Body

| Name | Type | Description                 |
| ---- | ---- | --------------------------- |
| file | blob | File content and file name. |

{% tabs %}
{% tab title="200: OK File Details" %}

```javascript
File
```

{% endtab %}

{% tab title="400: Bad Request Invalid parameters" %}

```javascript
// Error details
```

{% endtab %}

{% tab title="403: Forbidden Storage space is full" %}

```javascript
{
    code: 204,
    // Size in bytes
    totalCapacity: number,
    totalSize: number,
}
```

{% endtab %}
{% endtabs %}

## Get Download Link

<mark style="color:blue;">`GET`</mark> `https://cubicl.io/api/v1/files/:id/url`

Files uploaded to Cubicl cannot be accessed without authorization. In order to download a file, you need to request a download link. Then, you can send an HTTP request to the returned link to download the file. Links have a 5-minute lifetime. After that, you need to get another link.

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | string | File id     |

{% tabs %}
{% tab title="200: OK Download URL in JSON format" %}

```javascript
string
```

{% endtab %}
{% endtabs %}

## Files Page Endpoints

These endpoints allow you to view, create, edit and delete files and folders in the Files page of a project and a client.

Cubicl allows you to organize files and directories for both projects and also clients.

The structure of the Files page is similar to the file system in a computer or other file storage services such as Google Drive. It consists of nested file and directory nodes. At the top, a root directory node exists. Directories hold child file and directory nodes. File nodes are not same as the file record returned from [#upload-file](#upload-file "mention") endpoint. File node records point to file records.

## Get Nodes

<mark style="color:blue;">`GET`</mark> `https://cubicl.io/api/v1/file-system-nodes`

Gets file and directory nodes in a directory. The request should be sent with either 'group' or 'customer' parameters.

#### Query Parameters

| Name     | Type   | Description                                                                                                                    |
| -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| group    | string | Project id                                                                                                                     |
| customer | string | Client id                                                                                                                      |
| parent   | string | <p>Id of the directory to search.</p><p>Use 'null' for root directory.</p><p>If not given, will search in all directories.</p> |
| search   | string | Will be searched in file and directory names                                                                                   |

{% tabs %}
{% tab title="200: OK List of file system nodes" %}

```javascript
FileSystemNode[]
```

{% endtab %}
{% endtabs %}

## Create Files

<mark style="color:green;">`POST`</mark> `https://cubicl.io/api/v1/file-system-nodes/files`

Creates file nodes for uploaded files.

Files can be create in either a project's or client's files page. Either `group` or `customer` parameter must be set.

#### Request Body

| Name                                     | Type           | Description                                                           |
| ---------------------------------------- | -------------- | --------------------------------------------------------------------- |
| group                                    | string         | Project id if file is being created in a project's files page         |
| customer                                 | string         | Client id if file is being created in a client's files page           |
| parent<mark style="color:red;">\*</mark> | string \| null | <p>Parent directory id</p><p>null if parent is the root directory</p> |
| files<mark style="color:red;">\*</mark>  | string\[]      | File id list                                                          |

{% tabs %}
{% tab title="200: OK File system node list" %}

```javascript
FileSystemNode[]
```

{% endtab %}
{% endtabs %}

## Create Directory

<mark style="color:green;">`POST`</mark> `https://cubicl.io/api/v1/file-system-nodes/directories`

Creates a directory node.

Files can be created on either a project's or a client's files page. Either `group` or `customer` parameters must be set.

#### Request Body

| Name                                     | Type           | Description                                                           |
| ---------------------------------------- | -------------- | --------------------------------------------------------------------- |
| group                                    | string         | Project id if directory is being created in a project's files page    |
| customer                                 | string         | Client id if directory is being created in a client's files page      |
| parent<mark style="color:red;">\*</mark> | string \| null | <p>Parent directory id</p><p>null if parent is the root directory</p> |
| name<mark style="color:red;">\*</mark>   | string         | Directory name                                                        |

{% tabs %}
{% tab title="200: OK File system node" %}

```javascript
FileSystemNode
```

{% endtab %}
{% endtabs %}

## Delete Nodes

<mark style="color:red;">`DELETE`</mark> `https://cubicl.io/api/v1/file-system-nodes`

Deletes file and directory nodes from a project or a client.

File nodes are deleted together with the file records and the uploaded file. Multiple nodes from different projects or clients cannot be deleted in a single request.

#### Request Body

| Name                                    | Type      | Description  |
| --------------------------------------- | --------- | ------------ |
| nodes<mark style="color:red;">\*</mark> | string\[] | Node id list |

{% tabs %}
{% tab title="204: No Content No content" %}

```javascript
```

{% endtab %}
{% endtabs %}

## Data

#### File

```typescript
type File = {
    _id: string;
    name: string;
    thumbnail?: string; // Link to thumbnail URL if file is a supported image
    // If file is attached from Google Drive
    google?: {
        id: string;
        extension: string;
        webViewLink: string;
        mimeType: string;
    },
    // If file is attached from Dropbox
    dropbox?: {
        id: string;
        webViewLink: string;
    }
}
```

#### File System Node

```typescript
type FileSystemNode = {
    _id : string;
    // Parent directory id. null when parent is the root directory
    parent: string | null;
    group?: string; // Project id
    customer?: string; // Cliend id
    type: 'f' | 'd'; // f for file, d for directory
    file: File | null; // File when type is 'f', null when type is 'd'
    // Set when type is 'd'. If type is 'f', get name from 'file' property.
    name?: string;
    createdAt: number;
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cubicl.io/api-integration/files.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.