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.

//

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.

{
  "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.

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.

{
  "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.

//

Last updated