> For the complete documentation index, see [llms.txt](https://developer.onehub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.onehub.com/methods/workspaces.md).

# Workspaces

Workspaces are the top-level organizational structure for [folders](/methods/folders.md) and [files](/methods/files.md). Workspaces are also a [`root_folder`](/methods/folders.md#read-a-root-folder) whose contents can be examined via the [Folders](/methods/folders.md#read-a-root-folder) endpoint.

## Create a Workspace

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

Creates a new Workspace owned by the user.

#### Request Body

| Name                          | Type    | Description                                                                                                                                                |
| ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| workspace\[name]              | string  | The name of the Workspace.                                                                                                                                 |
| workspace\[background\_color] | string  | A CSS hex color value that determines the background color for the Workspace.                                                                              |
| workspace\[data\_room]        | boolean | Activates Data Room mode for the Workspace. Defaults to `false`. Availability of this feature is plan dependent.                                           |
| workspace\[default\_view]     | string  | Determines whether first time visitors should see folders and files displayed as horizontal `rows` or as a grid of large `thumbnails`. Defaults to `rows`. |

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

```yaml
{
  "workspace": {
    "id": 4137,
    "name": "Testing the API",
    "background_color": "#58b28d",
    "updated_at": "2016-01-25T16:39:34-08:00",
    "data_room": false,
    "default_view": "rows",
    "default_sort": "alphabetical",
    "root_folder_id": 849927,
    "owner_id": 481,
    "audit_trail": true,
    "is_owner": true,
    "require_agreement": false,
    "agreement_accepted": false,
    "effective_role": "Administrator",
    "errors": {}
  }
}
```

{% endtab %}
{% endtabs %}

## Read a Workspace

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

Retrieve the Workspace specified via `:id`.

#### Path Parameters

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

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

```yaml
{
  "workspace": {
    "id": 4137,
    "name": "Testing the API",
    "background_color": "#58b28d",
    "updated_at": "2016-01-25T16:39:34-08:00",
    "data_room": false,
    "default_view": "rows",
    "default_sort": "alphabetical",
    "root_folder_id": 849927,
    "owner_id": 481,
    "audit_trail": true,
    "is_owner": true,
    "require_agreement": false,
    "agreement_accepted": false,
    "effective_role": "Administrator",
    "errors": {}
  }
}
```

{% endtab %}

{% tab title="404 Returns a 404 with an error in the message body if an invalid Workspace :id is provided." %}

```yaml
//
```

{% endtab %}
{% endtabs %}

## Update a Workspace

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

Updates the Workspace specified via `:id`.

#### Path Parameters

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

#### Request Body

| Name                          | Type    | Description                                                                                                                                                |
| ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| workspace\[name]              | string  | The name of the Workspace.                                                                                                                                 |
| workspace\[background\_color] | string  | A CSS hex color value that determines the background color for the Workspace.                                                                              |
| workspace\[data\_room]        | boolean | Activates Data Room mode for the Workspace. Defaults to `false`. Availability of this feature is plan dependent.                                           |
| workspace\[default\_view]     | string  | Determines whether first time visitors should see folders and files displayed as horizontal `rows` or as a grid of large `thumbnails`. Defaults to `rows`. |

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

```yaml
{
  "workspace": {
    "id": 4137,
    "name": "Testing the API",
    "background_color": "#58b28d",
    "updated_at": "2016-01-25T16:39:34-08:00",
    "data_room": false,
    "default_view": "thumbnails",
    "default_sort": "alphabetical",
    "root_folder_id": 849927,
    "owner_id": 481,
    "audit_trail": true,
    "is_owner": true,
    "require_agreement": false,
    "agreement_accepted": false,
    "effective_role": "Administrator",
    "errors": {}
  }
}
```

{% endtab %}
{% endtabs %}

## Delete a Workspace

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

Delete the Workspace specified via `:id`.

#### Path Parameters

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

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

```yaml
//
```

{% endtab %}
{% endtabs %}

## List all Workspaces

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

List all Workspaces that the user has been invited to.

{% tabs %}
{% tab title="200 Returns a paginated array of Workspace objects and a 200 if the call succeeds." %}

```yaml
{
  "current_page": 1,
  "total_entries": 1,
  "total_pages": 1,
  "offset": 0,
  "previous_offset": null,
  "next_offset": null,
  "per_page": 30,
  "items": [
    {
      "workspace": {
        "id": 4137,
        "name": "Testing the API",
        "background_color": "#58b28d",
        "updated_at": "2016-01-25T16:54:00-08:00",
        "data_room": false,
        "default_view": "thumbnails",
        "default_sort": "alphabetical",
        "root_folder_id": 849587,
        "owner_id": 481,
        "audit_trail": true,
        "is_owner": true,
        "require_agreement": false,
        "agreement_accepted": false,
        "effective_role": "Administrator",
        "errors": {}
      }
    }
  ]
}
```

{% endtab %}
{% endtabs %}