Files

Last updated 28 days ago
Files are the heart of the Onehub service and are organized via folders. You can create, read, download, update, and delete files. You can also list all items in a folder.
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.
All Files have Thumbnails. Thumbnails are generated image representations of a file in PNG 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.
post
Create a File
https://ws-api.onehub.com
/workspaces/:workspace_id/folders/:id/files
Uploads a file to the folder specified via :id to the Workspace specified via :workspace_id.
Request
Response
Path Parameters
:workspace_id
required
integer
The unique identifier of the Workspace you would like to upload the file to.
:id
required
integer
The unique identifier of the folder you would like to upload the file to.
Headers
content-type
required
string
Onehub requires file uploads to be sent with the content-type header of multipart/form-data rather than application/json.
boundary
required
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.
Form Data Parameters
file
required
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.
201: Created
Returns the newly created file and a 201 if the call succeeds.
//
422: Unprocessable Entity
Returns a 422 with an error in the message body and an empty file object if an error occurs.
//
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.
get
Read a File
https://ws-api.onehub.com
/workspaces/:workspace_id/files/:id
Retrieves the individual file object specified via :id from the Workspace specified via :workspace_id.
Request
Response
Path Parameters
:workspace_id
required
integer
The unique identifier of the Workspace you would like to retrieve the file from.
:id
required
integer
The unique identifier of the file you would like to retrieve.
200: OK
Returns the file object and a 200 if the call succeeds.
{
  "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"
    }
  }
}
get
Download a File
https://ws-api.onehub.com
/download/:id
Downloads the file specified via :id.
Request
Response
Path Parameters
:id
required
integer
The unique identifier of the file you would like to download.
200: OK
Returns the actual contents of the file.
//
put
Update a File
https://ws-api.onehub.com
/workspaces/:workspace_id/files/:id
Updates the file object specified via :id in the Workspace specified via :workspace_id.
Request
Response
Path Parameters
:workspace_id
required
integer
The unique identifier of the Workspace you would like to update the file in.
:id
required
integer
The unique identifier of the file you would like to update.
Body Parameters
filename
required
string
The name of the file.
200: OK
Returns the updated file object and a 200 if the call succeeds.
{
  "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"
    }
  }
}
delete
Delete a File
https://ws-api.onehub.com
/workspaces/:workspace_id/files/:id
Deletes the file specified via :id in the Workspace specified via :workspace_id.
Request
Response
Path Parameters
:workspace_id
required
integer
The unique identifier of the Workspace you would like to delete the file from.
:id
required
integer
The unique identifier of the file you would like to delete.
204: No Content
Returns and 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 file :id is provided.
//
get
List all Files
https://ws-api.onehub.com
/workspaces/:workspace_id/folders/:id
Lists all folders/files for the Workspace specified via :workspace_id in the folder specified via :id.
Request
Response
Path Parameters
:workspace_id
required
integer
The unique identifier of the Workspace you would like to list files from. 
:id
required
integer
The unique identifier of the folder you would like to list files from.
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-15T16:23:20-08:00",
        "user_id": 481,
        "workspace_id": 4137,
        "ancestor_ids": [
          849587,
          849597
        ],
        "token": "3mxsktkk",
        "token_accessible": false,
        "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-19T16:33:23-08:00",
    "user_id": 481,
    "workspace_id": 4137,
    "ancestor_ids": [
      849587
    ],
    "token": "xmrgbjuq",
    "token_accessible": false,
    "errors": {},
    "hidden?": false,
    "size": 6736
  }
}
Methods - Previous
Events
Next - Methods
Folders
Files

postCreate a File

getRead a File

getDownload a File

putUpdate a File

deleteDelete a File

getList all Files

post
Create a File

get
Read a File

get
Download a File

put
Update a File

delete
Delete a File

get
List all Files
