# REST APIs

**Prefix**: /internal/services/files/v1/

## General

## Get file metadata (check user belongs to comapny)

<mark style="color:blue;">`GET`</mark> `/internal/services/files/v1/:company_id/files/:file_id`

This route is called to get the metadata related to the `file_id` mentioned in the URL

{% tabs %}
{% tab title="200 " %}

```
Response:
  {
    "resource": {
        "company_id": "uuid-v4",
        "id": "uuid-v4",
        "application_id": "string",
        "created_at": "number",
        "encryption_key": "",
        "metadata": {
            "name": "string",
            "mime": "string"
        },
        "thumbnails": [
            {
                "index": number,
                "id": "string,
                "size": number,
                "type": "string",
                "width": number,
                "height": number
            }
        ],
        "updated_at": number,
        "upload_data": {
            "size": number,
            "chunks": number
        },
        "user_id": "uuid-v4"
    }
  }
```

{% endtab %}
{% endtabs %}

## Download a file&#x20;

<mark style="color:blue;">`GET`</mark> `/internal/services/files/v1/companies/:company_id/files/:file_id/download`

This route is called to download the file related to the `file_id` mentionned in the URL

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Download thumbnails

<mark style="color:blue;">`GET`</mark> `/internal/services/files/v1/companies/:company_id/files/:file_id/thumbnails/:id`

This route is called to download the thumbnail related to the `file_id` mentionned in the URL

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Delete a file

<mark style="color:red;">`DELETE`</mark> `/internal/services/files/v1/companies/:company_id/files/:file_id`

This route is called to delete the file related to the `file_id` mentionned in the URL

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Classic upload

To upload a single file, you must call this route and put the file binary data into a "file" multipart section.

## Upload a file&#x20;

<mark style="color:green;">`POST`</mark> `/internal/services/files/v1/companies/:company_id/files?thumbnail_sync=1`

This route is called to upload a file when chunk upload is not necessary.\
Thumbnail\_sync: when set then backend will wait up to 10 seconds for preview to be generated before reply.

#### Query Parameters

| Name            | Type    | Description |
| --------------- | ------- | ----------- |
| thumbnail\_sync | boolean |             |

#### Request Body

| Name | Type   | Description                     |
| ---- | ------ | ------------------------------- |
| File | object | The file which will be uploaded |

{% tabs %}
{% tab title="200 " %}

```
response : 
  {
    "resource": {
        "company_id": "uuid-v4",
        "metadata": {
            "name": "string",
            "mime": "string"
        },
        "thumbnails": [],
        "application_id": string,
        "upload_data": {
            "size": number,
            "chunks": number
        },
        "id": "uuid-v4",
        "updated_at": number,
        "created_at": number
  }
}
  
```

{% endtab %}
{% endtabs %}

## Upload with chunk

To upload a file in multiple chunk you must first initial the file itself, and then upload into the file.

The file initialization and following upload calls takes this parameters as **a query string**:

* **filename**: string, file name
* **type**: string, mime type for the file
* **total\_chunks**: number, total number of chunk to be uploaded
* **total\_Size**: number, sum of every chunk size (total file size)
* **chunk\_number**: number, current chunk uploaded, set it to undefined during file creation process.
* **thumbnail\_sync:** when set then backend will wait up to 10 seconds for the preview to be generated before to reply.

## Upload a file with chunk

<mark style="color:green;">`POST`</mark> `/internal/services/files/v1/companies/:company_id/files/?filename...`

This route should first be called without data to initialise the entity for multi-chunk, then chunks must be sent on other route below

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Overwrite a file&#x20;

<mark style="color:green;">`POST`</mark> `/internal/services/files/v1/companies/:company_id/files/:file_id/?totalChunks...`

Overwrite a file \
(check user belongs to company)\
User can call this if the file was not already uploaded. If file already exist only apps can do this (users cannot directly overwrite a file).

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}


---

# 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://doc.twake.app/internal-documentation/backend-services/files-service/rest-apis.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.