# Files

Files are the heart of the Onehub service and are organized via [folders](/methods/folders.md). You can **create**, **read**, **download**, **update**, and **delete** files. You can also **list** all items in a folder.

{% hint style="warning" %}
All files are versioned. Creating a file in the same location of an identically named file will automatically create a new version of the previously existing file.
{% endhint %}

{% hint style="info" %}
All Files have Thumbnails. Thumbnails are generated image representations of a file in [PNG](https://en.wikipedia.org/wiki/Portable_Network_Graphics) format. They are 128 pixels on their largest side with the shorter side varying, based on the aspect ratio of the file. If the file is smaller than 128x128, the thumbnail will be exactly the same size as the file.
{% endhint %}

## Create a File

<mark style="color:green;">`POST`</mark> `https://ws-api.onehub.com/folders/:id/files`

Uploads a file to the folder specified via `:id`.

#### Path Parameters

| Name | Type    | Description                                                               |
| ---- | ------- | ------------------------------------------------------------------------- |
| :id  | integer | The unique identifier of the folder you would like to upload the file to. |

#### Headers

| Name         | Type   | Description                                                                                                                                                           |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| content-type | string | Onehub requires file uploads to be sent with the `content-type` header of `multipart/form-data` rather than `application/json`.                                       |
| boundary     | string | Required by the content-type header, this parameter indicates the file contents in the post body. See your particular library's documentation on how to achieve this. |

#### Request Body

| Name | Type   | Description                                                                                                                                                                             |
| ---- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| file | object | The file you want to upload. Your file needs to be encoded as `multipart/form-data` before being uploaded. We recommend using an existing multipart library in your language of choice. |

{% tabs %}
{% tab title="201 Returns the newly created file and a 201 if the call succeeds." %}

```yaml
//
```

{% endtab %}

{% tab title="422 Returns a 422 with an error in the message body and an empty file object if an error occurs." %}

```yaml
//
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
If a filename has characters that would render it invalid, the name will automatically be changed to one that is valid. For example, `file/name.txt` would be changed to `file-name.txt`.
{% endhint %}

## Read a File's Metadata

<mark style="color:blue;">`GET`</mark> `https://ws-api.onehub.com/files/:id`

Retrieves the metadata for the file specified by `:id`.

#### Path Parameters

| Name | Type    | Description                                                   |
| ---- | ------- | ------------------------------------------------------------- |
| :id  | integer | The unique identifier of the file you would like to retrieve. |

{% tabs %}
{% tab title="200 Returns the file object and a 200 if the call succeeds." %}

```yaml
{
  "file": {
    "id": 849607,
    "filename": "onehub-logo.png",
    "created_at": "2016-01-15T16:22:44-08:00",
    "updated_at": "2016-01-15T16:23:20-08:00",
    "user_id": 481,
    "workspace_id": 4137,
    "ancestor_ids": [
      849587,
      849597
    ],
    "errors": {},
    "hidden?": false,
    "size": 6736,
    "thumbnail": {
      "id": 791577,
      "state": "ready",
      "created_at": "2016-01-15T16:22:44-08:00",
      "updated_at": "2016-01-15T16:22:46-08:00",
      "width": 128,
      "height": 33,
      "url": "/thumbnails/791577"
    }
  }
}
```

{% endtab %}
{% endtabs %}

## Download a File

<mark style="color:blue;">`GET`</mark> `https://ws-api.onehub.com/download/:id`

Downloads the file specified via `:id`.

#### Path Parameters

| Name | Type    | Description                                                   |
| ---- | ------- | ------------------------------------------------------------- |
| :id  | integer | The unique identifier of the file you would like to download. |

{% tabs %}
{% tab title="200 Returns the actual contents of the file." %}

```
```

{% endtab %}
{% endtabs %}

## Rename a File

<mark style="color:orange;">`PUT`</mark> `https://ws-api.onehub.com/files/:id`

Renames the file object specified via `:id`.

#### Path Parameters

| Name | Type    | Description                                                 |
| ---- | ------- | ----------------------------------------------------------- |
| :id  | integer | The unique identifier of the file you would like to rename. |

#### Request Body

| Name     | Type   | Description                |
| -------- | ------ | -------------------------- |
| filename | string | The new name for the file. |

{% tabs %}
{% tab title="200 Returns the updated file object and a 200 if the call succeeds." %}

```yaml
{
  "file": {
    "id": 849607,
    "filename": "renamed.png",
    "created_at": "2016-01-15T16:22:44-08:00",
    "updated_at": "2016-01-20T15:24:48-08:00",
    "user_id": 481,
    "workspace_id": 4137,
    "ancestor_ids": [
      849587,
      849597
    ],
    "errors": { },
    "size": 6736,
    "thumbnail": {
      "id": 791577,
      "state": "ready",
      "created_at": "2016-01-15T16:22:44-08:00",
      "updated_at": "2016-01-15T16:22:46-08:00",
      "width": 128,
      "height": 33,
      "url": "/thumbnails/791577"
    }
  }
}
```

{% endtab %}
{% endtabs %}

## Delete a File

<mark style="color:red;">`DELETE`</mark> `https://ws-api.onehub.com/files/:id`

Deletes the file specified via `:id`.

#### Path Parameters

| Name | Type    | Description                                                 |
| ---- | ------- | ----------------------------------------------------------- |
| :id  | integer | The unique identifier of the file you would like to delete. |

{% tabs %}
{% tab title="204 Returns and empty message body and a 204 if the call succeeds." %}

```yaml
//
```

{% endtab %}

{% tab title="404 Returns a 404 with an error in the message body if a non-existent file :id is provided." %}

```yaml
//
```

{% 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://developer.onehub.com/methods/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.