Folders

Folders are the organization structure for files in Workspaces. You can create, update, download, and delete folders. You can also list all items in a folder.
Workspaces contain a special folder which is referred to as the root folder, which you can read. This folder contains all items found in the root of a Workspace.
post
Create a Folder
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.
Request
Response
Request
Path Parameters
:workspace_id
required
integer
The unique identifier of the Workspace you would like to create the folder in.
:folder_id
optional
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.
Body Parameters
filename
required
string
The name of the folder.
Response
201: Created
Returns the newly create folder and a 201 if the call succeeds.
{
  "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
  }
}
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.
get
Read a Root Folder
https://ws-api.onehub.com/workspaces/:id/folders
Reads the root folder for the Workspace specified via :id.
Request
Response
Request
Path Parameters
:id
required
integer
The unique identifier of the Workspace you would like to read the root folder from.
Response
200: OK
Returns the root folder object and a 200 if the call succeeds.
{
  "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
      }
    }
  ]
}
get
List Folder Contents
https://ws-api.onehub.com/folders/:id
Lists all folders/files in the folder specified via :id.
Request
Response
Request
Path Parameters
:id
required
integer
The unique identifier of the folder you would like to list nested folders from.
Query Parameters
query
optional
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
optional
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.
Response
200: OK
Returns a paginated array of folder/file objects, along with the containing folder object, and a 200 if the call succeeds.
{
  "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
  }
}
get
Download a Folder
https://ws-api.onehub.com/folders/:id/archive
Downloads a zip archive of the folder specified by :id.
Request
Response
Request
Path Parameters
:id
required
integer
The unique identifier of the folder you would like to download.
Response
200: OK
Returns a zip archive of the folder and its contents.
​
put
Rename a Folder
https://ws-api.onehub.com/folders/:id
Renames the folder object specified via :id.
Request
Response
Request
Path Parameters
:id
required
integer
The unique identifier of the folder you would like to update.
Body Parameters
filename
required
string
The new name for the folder.
Response
200: OK
Returns the updated folder object and a 200 if the call succeeds.
{
  "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
  }
}
delete
Delete a Folder
https://ws-api.onehub.com/folders/:id
Deletes the folder object specified via :id.
Request
Response
Request
Path Parameters
:id
required
integer
The unique identifier of the folder you would like to delete.
Response
200: OK
Returns an empty message body and a 204 if the call succeeds.
//
404: Not Found
Returns a 404 with an error in the message body if a non-existent folder :id is provided.
//