# Introduction

The Onehub API enables developers to access data from the Onehub Service on behalf of a client. The API is organized around [REST](http://en.wikipedia.org/wiki/Representational_state_transfer). Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. Where appropriate, the API provides the four basic functions of persistent storage — **create**, **read**, **update**, and **delete**. In general, most API resources will accept an `index` request and return a [paginated](/api/pagination) set of all available items.


# Getting Started

## Create a Developer Account

In order to access the Onehub API, you will need to create a Onehub Developer account. Developer accounts are the only accounts that can create Onehub API keys. Developer accounts have limited resources for day-to-day use and beyond creating API keys are only meant for testing.

After creating your API keys, you will be able to authenticate against the API as a different Onehub user in order to access your paid account's data. See the [Authorization](/api/authorization) section for more information.

{% hint style="info" %}
Make sure you sign out of any existing Onehub accounts before clicking the link below.

* [Sign Up for a Onehub Developer Account](https://ws.onehub.com/signups/new?plan_name=developer\&return_to=%2Fhome)
  {% endhint %}

## Create Your API Keys

You’ll need to create an OAuth Client that represents your application when communicating with our OAuth Server. Your API keys carry many privileges, so be sure to keep them secret!

* Visit the [Developer section](https://ws.onehub.com/oauth2_clients) of your account
* Click the **Create OAuth Client** button
* Fill in your application information and click **Create Client**
* Store your generated **Client ID** and **Client Secret** in a safe place

{% hint style="warning" %}
Your secret will not be retrievable after leaving the confirmation screen.
{% endhint %}


# Important Information

## API Endpoint

```
https://ws-api.onehub.com
```

## Example URL

```
https://ws-api.onehub.com/[resource]/[id]
```

## Default Format

{% hint style="info" %}
The default format returned from the Onehub API is [JSON](http://www.json.org/).
{% endhint %}

JSON will be returned in all responses from the API, including [errors](/api/errors). If you are unable to set an `Accept: application/json` header in your request, you may apply a suffix of `.json` to ensure JSON is returned.

```
https://ws-api.onehub.com/workspaces.json
```


# Authorization

The Onehub API uses [OAuth 2.0 Draft 10](http://tools.ietf.org/html/draft-ietf-oauth-v2-10) for both authorization and authentication. Authorize your account when using the API by including your client ID and secret along with your preferred OAuth 2 authorization method.

We recommend using an [existing OAuth 2 library](http://oauth.net/2) in your language of choice.

{% hint style="warning" %}
All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Requests made over plain HTTP will results in an [error](/api/errors). Requests made without authorization will also result in an [error](/api/errors).
{% endhint %}

### Supported OAuth 2.0 Grant Types

#### Authorization

Primarily used in the context of integrating your app with Onehub and allowing users to grant it access to their data via a web-based authorization flow. More information on this grant type can be [found here](https://oauth.net/2/grant-types/authorization-code/).

#### Password

Used for directly authenticating as a user. Use this grant type if you want to access your own Onehub data via the API. More information on this grant type can be [found here](https://oauth.net/2/grant-types/password/).

## Authorization Endpoint

```
https://ws-api.onehub.com/oauth/authorize
```

## Password Grant Examples

* [Ruby](https://github.com/onehub/api-examples/blob/master/ruby/password_grant_REPL.rb)
* [Java](https://github.com/onehub/api-examples/tree/master/java/oauth2)


# Errors

Onehub uses conventional [HTTP response codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) to indicate success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that resulted from the information provided, and codes in the `5xx` range indicate an error with Onehub’s servers.

Not all errors map cleanly onto HTTP response codes. For example, a **302 Found** will be returned when a non-HTTPS request is made against the API. In that example, the *Location* header in the response will contain the corrected URI, which should be used in a follow-up request.

{% hint style="info" %}
We strive to include helpful information with all of our responses. However, if you think something useful is missing, [let us know](mailto:support@onehub.com) and we'll consider adding it.
{% endhint %}


# Pagination

API methods that return a large number of items, will return them inside a paginated array. Onehub utilizes offset-based pagination. Some methods will respond to an `offset` parameter. To retrieve a complete set of paginated results, you perform multiple requests while increasing the `offset`. This can be passed in the body of the request or by appending `?offset=` to the endpoint.

## Pagination Example

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

#### Path Parameters

| Name      | Type   | Description                                  |
| --------- | ------ | -------------------------------------------- |
| :endpoint | string | The endpoint for the method you are hitting. |

#### Query Parameters

| Name   | Type    | Description                                                                                                                            |
| ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| offset | integer | The number of items you want to move past in the response. Typically, this will be specified as a multiplier of the `per_page` amount. |

#### Request Body

| Name   | Type    | Description                                                                                                                            |
| ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| offset | integer | The number of items you want to move past in the response. Typically, this will be specified as a multiplier of the `per_page` amount. |

{% tabs %}
{% tab title="200 " %}

```yaml
{
  "total_entries": 42,
  "current_page": 2,
  "total_pages": 2,
  "per_page": 30,
  "items": [
  ...
  ]
}
```

{% endtab %}
{% endtabs %}


# Roles

Onehub uses an advanced role-based permission system to control access and abilities for individual users. Roles are set via [invitations](/methods/invitations), enforced via [rolemaps](/methods/rolemaps), and can be changed at any time by an Administrator or Moderator.

{% hint style="info" %}
For more information about roles and their subsequent permissions, check out [Understanding Roles & Permissions](https://onehub.desk.com/customer/en/portal/articles/283687-understanding-roles-permissions?b_id=904) on our Support site.
{% endhint %}

## Available Roles

| Role Name                | Abilities                                                                                                                                                                                                                                          |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Administrator**        | Can edit the Workspace pages, modify the logo and colors, and modify the Workspace security settings.                                                                                                                                              |
| **Moderator**            | Can upload, edit and delete any file or folder. Can invite other users to the Workspace, invite users to a file and folder, create secure links, and edit all comments in the Workspace.                                                           |
| **Collaborator**         | Can upload, edit and delete any file or folder. Cannot invite users to the Workspace, files, or folders. Cannot create secure links or edit other user’s comments. Useful to allow users to use Onehub Sync without letting them invite new users. |
| **Creator**              | Can view previews, print, and download files. Can upload files to a folder or Workspace and delete folders and files they created. Can view and add comments to files, folders and messages. Can post Messages to a Workspace.                     |
| **Downloader** (Default) | Can view previews, print and download files. Cannot view or add comments to items. Downloader is the default role unless it has been overridden on a folder or file.                                                                               |
| **Printer**              | Can view previews and print but cannot download files. Cannot view or add comments to items.                                                                                                                                                       |
| **Viewer**               | Can view previews of files but cannot print or download files. Cannot view or add comments to items.                                                                                                                                               |


# Comments

Comments are discussions around content and can be added to a folder or file in Onehub. You can **create**, **delete**, and **list** comments. Comments are identified by a unique, random ID.

## Create a Comment

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

Creates a comment on the `:item` (folder or file) specified via `:item_id`.

#### Path Parameters

| Name      | Type    | Description                                                                     |
| --------- | ------- | ------------------------------------------------------------------------------- |
| :item     | string  | The type of item. Can either be `folders` or `files`.                           |
| :item\_id | integer | The unique identifier of the item that you would like to create the comment on. |

#### Request Body

| Name | Type   | Description              |
| ---- | ------ | ------------------------ |
| body | string | The text of the comment. |

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

```yaml
{
  "comment": {
    "id": 9417,
    "user_id": 481,
    "discussion_id": 468087,
    "body": "This is an example comment.",
    "updated_at": "2016-01-15T16:24:37-08:00",
    "user_name": "Matthew Anderson",
    "owner_type": "file",
    "owner_id": 849607
  }
}
```

{% endtab %}

{% tab title="422 Returns a 422 with an error in the message body it a non-existent id is provided." %}

```yaml
// 
```

{% endtab %}
{% endtabs %}

## Delete a Comment

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

Deletes the comment specified via `:id` from the `:item` (folder or file) specified via `:item_id`.

#### Path Parameters

| Name      | Type    | Description                                                                  |
| --------- | ------- | ---------------------------------------------------------------------------- |
| :item     | string  | The type of item. Can either be `folders` or `files`.                        |
| :item\_id | integer | The unique identifier of the item you would like to delete the comment from. |
| :id       | integer | The unique identifier of the comment you would like to delete.               |

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

```
```

{% endtab %}
{% endtabs %}

## List all Comments

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

Lists all comment for the `:item` (folder or file) specified via `:item_id`.

#### Path Parameters

| Name      | Type    | Description                                                                  |
| --------- | ------- | ---------------------------------------------------------------------------- |
| :item     | string  | The type of item. Can either be `folders` or `files`.                        |
| :item\_id | integer | The unique identifier of the item that you would like to list comments from. |

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

```yaml
{
  "total_entries": 1,
  "current_page": 1,
  "total_pages": 1,
  "per_page": 15,
  "items": [
    {
      "comment": {
        "id": 9417,
        "user_id": 481,
        "discussion_id": 468087,
        "body": "This is an example comment.",
        "updated_at": "2016-01-15T16:24:37-08:00",
        "user_name": "Matthew Anderson",
        "owner_type": "file",
        "owner_id": 849607
      }
    }
  ]
}
```

{% endtab %}
{% endtabs %}


# Events

Events document an action taken by a user in the system. They provide metadata about the action and a string representation suitable for display. You can **list** all events for a user or a file.

## List all Events for a User

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

List all events for a user across all of their Workspaces.

#### Request Body

| Name         | Type    | Description                                                                                                                                                       |
| ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| workspaces   | array   | The id of the Workspace(s) to list events for as an array of integers.                                                                                            |
| verbs        | array   | The action(s) taken in the events. Available verbs are create, upload, read, download, update, delete, and invite.                                                |
| filter\_self | boolean | Should the users' own events be removed? Defaults to false.                                                                                                       |
| actor        | integer | The id of the user to list events for.                                                                                                                            |
| start\_time  | string  | The earliest time you would like to see events from. Timestamps should be specified in RFC-2822 format and will assume the same time zone as the requesting user. |
| end\_time    | string  | The latest time you would like to see events from. Timestamps should be specified in RFC-2822 format and will assume the same time zone as the requesting user.   |

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

```yaml
{
  "total_entries": 0,
  "current_page": 1,
  "total_pages": 0,
  "per_page": 30,
  "items": [
    {
      "event": {
        "id": 5063247,
        "updated_at": "2016-01-18T11:16:53-08:00",
        "detail": "<subject>Matthew Anderson</subject> <predicate>viewed</predicate> the <object><a href=\"/workspaces/4137/files/849607\">onehub-logo.png</a> File</object> <complement>(7 KB)</complement> in the <object><a href=\"/workspaces/4137\">Testing the API</a> Workspace</object>",
        "workspace_id": 4137,
        "user_id": 481
      }
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## List all Events for a File

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

Lists all events for the file specified via `:id`. This resource is only available to users with a role of **Moderator** or above.

#### Path Parameters

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

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

```yaml
{
  "total_entries": 1,
  "current_page": 1,
  "total_pages": 1,
  "per_page": 30,
  "items": [
    {
      "event": {
        "id": 5062927,
        "updated_at": "2016-01-15T16:22:45-08:00",
        "detail": "<subject>Matthew Anderson</subject> <predicate>uploaded</predicate> the <object><a href=\"/workspaces/4137/files/849607\">Onehub_Med_RGB.png</a> File</object> <complement>(7 KB)</complement> to the <object><a href=\"/workspaces/4137\">Testing the API</a> Workspace</object>",
        "workspace_id": 4137,
        "user_id": 481
      }
    }
  ]
}
```

{% endtab %}

{% tab title="403 Returns a 403 with an error in the message body if the user has a role lower than Moderator in the specified Workspace." %}

```yaml
//
```

{% endtab %}
{% endtabs %}


# Files

Files are the heart of the Onehub service and are organized via [folders](/methods/folders). 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 %}


# Folders

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


# Invitations

Invitations are placeholders for [rolemap](/methods/rolemaps) objects. You cannot create a rolemap directly because, sometimes, user approval is required. Invitations are sent to users via email and, once accepted, create a rolemap on the object they were invited to with the requested [role](/api/roles).

## Create an Invitation

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

Create an invitation to the `:item` (Workspace, folder, or file) specified via `:id`.

#### Path Parameters

| Name  | Type    | Description                                                                  |
| ----- | ------- | ---------------------------------------------------------------------------- |
| :item | string  | The type of item. Can be `workspaces`, `folders`, or `files`.                |
| :id   | integer | The unique identifier of the item you would like to create an invitation to. |

#### Request Body

| Name       | Type   | Description                                                                                                                      |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| invitation | object | This is the top level object that contains the `emails` and `role_name` keys described below.                                    |
| emails     | string | The email addresses you would like to invite to the item. Multiple email addresses should be comma delimited in a single string. |
| role\_name | string | The effective role granted to the user(s).                                                                                       |

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

```yaml
{
  "share": {
    "emails": "",
    "email_errors": [],
    "join_errors": [],
    "invited_emails": [
      { "first-user@example.com": 5967 },
      { "second-user@example.com": 5977 }
    ],
    "errors": {}
  }
}
```

{% endtab %}

{% tab title="422 Returns a 422 with an error in the message body if an invalid email is provided or if a limit is reached." %}

```yaml
//
```

{% endtab %}
{% endtabs %}

#### Example Request Body

```javascript
{
  "invitation": {
    "emails": "first-user@example.com, second-user@example.com",
    "role_name": "Creator"
  }
}
```

{% hint style="info" %}
If a `role_name` is not provided, or is invalid, the [default role](/api/roles#available-roles) will be used.
{% endhint %}


# Links

Links are obscured, secure URLs to Onehub folders and files. They are created via unique tokens and are designed to provide shortcuts to Onehub content without requiring an account. You can **read** and **update** links.

## Read a Link

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

Retrieves the link object from an `:item` (folder or file) specified via `:item_id`.

#### Path Parameters

| Name      | Type    | Description                                                                 |
| --------- | ------- | --------------------------------------------------------------------------- |
| :item     | integer | The type of item. Can either be `folders` or `files`.                       |
| :item\_id | integer | The unique identifier of the item you would like to retrieve the link from. |

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

```yaml
{
  "content_item_link": {
    "token": "3mxsktkk",
    "token_accessible": false,
    "token_expires": false,
    "token_expires_at": null,
    "require_password": false,
    "role_id": null,
    "link": "/files/3mxsktkk",
    "url": "/files/849607/link"
  }
}
```

{% endtab %}
{% endtabs %}

## Update a Link

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

Updates the link object on the `:item` (folder or file) specified via `:item_id`.

#### Path Parameters

| Name      | Type    | Description                                                             |
| --------- | ------- | ----------------------------------------------------------------------- |
| :item     | integer | The type of item. Can either be `folders` or `files`.                   |
| :item\_id | integer | The unique identifier of the item you would like to update the link on. |

#### Request Body

| Name              | Type    | Description                                                                                                               |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| require\_password | boolean | Should a password be required to access the link? Defaults to `false`.                                                    |
| password          | string  | Set the required password that must be entered before the link can be accessed. Required if `require_password` is `true`. |
| token\_accessible | boolean | Is the link enabled? Defaults to `false`.                                                                                 |

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

```yaml
{
  "content_item_link": {
    "token": "3mxsktkk",
    "token_accessible": true,
    "token_expires": false,
    "token_expires_at": null,
    "require_password": true,
    "role_id": null,
    "link": "/files/3mxsktkk",
    "url": "/files/849607/link"
  }
}
```

{% endtab %}
{% endtabs %}


# Rolemaps

Rolemaps are join objects that relate users to [Workspaces](/methods/workspaces), [folders](/methods/folders), or [files](/methods/files). A rolemap grants a user access to an object via a [role](/api/roles). You can **read**, **update**, **delete**, and **list** rolemaps.

{% hint style="info" %}
You create rolemaps via [invitations](/methods/invitations).
{% endhint %}

{% hint style="warning" %}
Interacting with the rolemaps endpoint requires the `id` for a specific rolemap. You can find the appropriate rolemap `id` by first [listing all rolemaps](/methods/rolemaps#list-all-rolemaps) for a given object.
{% endhint %}

## Read a Rolemap

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

Retrieves the rolemap specified via `:id`.

#### Path Parameters

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

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

```yaml
{
  "rolemap": {
    "id": 20967,
    "state": "pending",
    "updated_at": "2016-05-03T13:46:48-07:00",
    "activated_at": null,
    "suspended_at": null,
    "deleted_at": null,
    "object_type": "Workspace",
    "role_name": "Creator",
    "available_roles": [
      "Administrator",
      "Moderator",
      "Collaborator",
      "Creator",
      "Downloader",
      "Printer",
      "Viewer",
      "Access Denied"
    ],
    "user_id": 6057,
    "user": {
      "id": 6057,
      "first_name": null,
      "last_name": null,
      "email": "user@example.com",
      "address": null,
      "profile_photo_url": "https://ws.example.com/assets/contact-ace461e8659e9aebf598e2c81fa125bb.png"
    }
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Rolemaps with an `object_type` of `Account`  were automatically granted to an account-level user and indicate access to all other object types within the account. Whereas, `Workspace`, `Folder`, and `File` rolemaps indicate access only to the object retrieved.
{% endhint %}

## Update a Rolemap

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

Updates the rolemap specified via `:id`.

#### Path Parameters

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

#### Request Body

| Name       | Type   | Description                                                                                       |
| ---------- | ------ | ------------------------------------------------------------------------------------------------- |
| role\_name | string | The effective role granted to the user. This can only be updated to one of the `available_roles`. |

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

```yaml
//
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Endpoint context is assumed for all update actions. If you update an `Account` rolemap from the `/workspaces` endpoint, the API will automatically create a new `Workspace` rolemap on the specified Workspace, versus modifying that user’s account role.
{% endhint %}

## Delete a Rolemap

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

Deletes the rolemap specified via `:id`.

#### Path Parameters

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

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

```yaml
//
```

{% endtab %}

{% tab title="422 Returns a 422 with an error in the message body if you attempt to delete an Account rolemap." %}

```yaml
//
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
Deleting a rolemap will revoke access to the rolemap's object.
{% endhint %}

{% hint style="warning" %}
Endpoint context is assumed for all delete actions. If you attempt to delete an `Account` rolemap from the `/workspaces` endpoint, the call will fail.
{% endhint %}

## List all Rolemaps

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

Lists all rolemaps for the `:object` (Workspace, folder, or file) specified via `:id`.

#### Path Parameters

| Name    | Type    | Description                                                                    |
| ------- | ------- | ------------------------------------------------------------------------------ |
| :object | string  | The type of object. Can be either `workspaces`, `folders`, or `files`.         |
| :id     | integer | The unique identifier of the object that you would like to list rolemaps from. |

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

```yaml
{
  "current_page": 1,
  "total_entries": 12,
  "total_pages": 1,
  "offset": 0,
  "previous_offset": null,
  "next_offset": null,
  "per_page": 30,
  "items": [
    {
      "rolemap": {
        "id": 20967,
        "state": "pending",
        "updated_at": "2016-05-03T13:46:48-07:00",
        "activated_at": null,
        "suspended_at": null,
        "deleted_at": null,
        "object_type": "Workspace",
        "role_name": "Creator",
        "available_roles": [
          "Administrator",
          "Moderator",
          "Collaborator",
          "Creator",
          "Downloader",
          "Printer",
          "Viewer",
          "Access Denied"
        ],
        "user_id": 6057,
        "user": {
          "id": 6057,
          "first_name": null,
          "last_name": null,
          "email": "user@example.com",
          "address": null,
          "profile_photo_url": "https://ws.example.com/assets/contact-ace461e8659e9aebf598e2c81fa125bb.png"
        }
      }
    }
  ]
}
```

{% endtab %}
{% endtabs %}


# Workspaces

Workspaces are the top-level organizational structure for [folders](/methods/folders) and [files](/methods/files). Workspaces are also a [`root_folder`](/methods/folders#read-a-root-folder) whose contents can be examined via the [Folders](/methods/folders#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 %}