# Folders

Folders are the organization structure for [files](https://developer.onehub.com/methods/files) in [Workspaces](https://developer.onehub.com/methods/workspaces). You can **create**, **update**, **download**, and **delete** folders. You can also **list** all items in a folder.

{% hint style="info" %}
Workspaces contain a special folder which is referred to as the [*root folder*](#read-a-root-folder), which you can **read**. This folder contains all items found in the root of a Workspace.
{% endhint %}

## Create a Folder

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

Creates a folder nested within the folder specified via `:folder_id` in the Workspace specified via `:workspace_id`. To create a folder at the root-level of the Workspace you can either pass the `root_folder_id` or post to the `/folders` endpoint without specifying a `:folder_id`.

#### Path Parameters

| Name           | Type    | Description                                                                                                                                                                                |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| :workspace\_id | integer | The unique identifier of the Workspace you would like to create the folder in.                                                                                                             |
| :folder\_id    | integer | The unique identifier of the folder you would like to nest the folder within. If a `:folder_id` is not provided, the API will assume that you want to create the folder at the root-level. |

#### Request Body

| Name     | Type   | Description             |
| -------- | ------ | ----------------------- |
| filename | string | The name of the folder. |

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

```yaml
{
  "folder": {
    "id": 849837,
    "filename": "New Folder",
    "created_at": "2016-01-20T16:45:48-08:00",
    "updated_at": "2016-01-20T16:45:48-08:00",
    "user_id": 481,
    "workspace_id": 4137,
    "ancestor_ids": [
      849587
    ],
    "errors": {},
    "hidden?": false,
    "size": 0
  }
}
```

{% endtab %}
{% endtabs %}

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

## Read a Root Folder

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

Reads the root folder for the Workspace specified via `:id`.

#### Path Parameters

| Name | Type    | Description                                                                         |
| ---- | ------- | ----------------------------------------------------------------------------------- |
| :id  | integer | The unique identifier of the Workspace you would like to read the root folder from. |

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

```yaml
{
  "items": [
    {
      "folder": {
        "id": 849587,
        "filename": "Testing the API",
        "created_at": "2016-01-15T15:19:06-08:00",
        "updated_at": "2016-01-20T16:53:45-08:00",
        "user_id": null,
        "workspace_id": 4137,
        "ancestor_ids": [],
        "errors": {},
        "hidden?": false,
        "size": 6736
      }
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## List Folder Contents

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

Lists all folders/files in the folder specified via `:id`.

#### Path Parameters

| Name | Type    | Description                                                                     |
| ---- | ------- | ------------------------------------------------------------------------------- |
| :id  | integer | The unique identifier of the folder you would like to list nested folders from. |

#### Query Parameters

| Name  | Type   | Description                                                                                                                                                                                                           |
| ----- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query | string | A portion of the folder name, filename, or extension you would like to scope your results to. Can be any concurrent string of supported characters.                                                                   |
| sort  | string | The criteria you would like to sort the response by. Case sensitive. Can either be `alphabetical`, `modified`, `size`, or `type`. If Data Room mode and Automatic Indexing are enabled, you can also sort by `index`. |

{% tabs %}
{% tab title="200 Returns a paginated array of folder/file objects, along with the containing folder object, and a 200 if the call succeeds." %}

```yaml
{
  "current_page": 1,
  "total_entries": 0,
  "total_pages": 0,
  "offset": 0,
  "previous_offset": null,
  "next_offset": null,
  "per_page": 60,
  "items": [
    {
      "folder": {
        "id": 849647,
        "filename": "Nested Folder",
        "created_at": "2016-01-18T17:00:54-08:00",
        "updated_at": "2016-01-18T17:00:54-08:00",
        "user_id": 481,
        "workspace_id": 4137,
        "ancestor_ids": [
          849587,
          849597
        ],
        "errors": {},
        "hidden?": false,
        "size": 0
      }
    },
    {
      "file": {
        "id": 849607,
        "filename": "onehub-logo.png",
        "created_at": "2016-01-15T16:22:44-08:00",
        "updated_at": "2016-01-20T16:09:25-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"
        }
      }
    }
  ],
  "folder": {
    "id": 849597,
    "filename": "Parent Folder",
    "created_at": "2016-01-15T15:19:20-08:00",
    "updated_at": "2016-01-20T16:09:25-08:00",
    "user_id": 481,
    "workspace_id": 4137,
    "ancestor_ids": [
      849587
    ],
    "errors": {},
    "hidden?": false,
    "size": 6736
  }
}
```

{% endtab %}
{% endtabs %}

## Download a Folder

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

Downloads a zip archive of the folder specified by `:id`.

#### Path Parameters

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

{% tabs %}
{% tab title="200 Returns a zip archive of the folder and its contents." %}

```
```

{% endtab %}
{% endtabs %}

## Rename a Folder

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

Renames the folder object specified via `:id`.

#### Path Parameters

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

#### Request Body

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

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

```yaml
{
  "folder": {
    "id": 849597,
    "filename": "Renamed Folder",
    "created_at": "2016-01-15T15:19:20-08:00",
    "updated_at": "2016-01-21T11:55:32-08:00",
    "user_id": 481,
    "workspace_id": 4137,
    "ancestor_ids": [
      849587
    ],
    "errors": {},
    "hidden?": false,
    "size": 6736
  }
}
```

{% endtab %}
{% endtabs %}

## Delete a Folder

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

Deletes the folder object specified via `:id`.

#### Path Parameters

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

{% tabs %}
{% tab title="200 Returns an 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 folder :id is provided." %}

```yaml
//
```

{% endtab %}
{% endtabs %}