# Folders

Folders are the organization structure for [files](/methods/files.md) in [Workspaces](/methods/workspaces.md). 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*](/methods/folders.md#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 %}


---

# 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/folders.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.