# 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 %}


---

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