# 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;
}
```