Files

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.

Create a File

POST 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.

201 Returns the newly created file and a 201 if the call succeeds.

//

422 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.

Read a File's Metadata

GET 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.

200 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"
    }
  }
}

Download a File

GET 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.

200 Returns the actual contents of the file.

Rename a File

PUT 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.

200 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 a File

DELETE 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.

204 Returns and empty message body and a 204 if the call succeeds.

//

404 Returns a 404 with an error in the message body if a non-existent file :id is provided.