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.
post
Create a File
https://ws-api.onehub.com/folders/:id/files
Uploads a file to the folder specified via :id.
Request
Response
Request
Path Parameters
: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.
Response
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's Metadata
https://ws-api.onehub.com/files/:id
Retrieves the metadata for the file specified by :id.
Request
Response
Request
Path Parameters
:id
required
integer
The unique identifier of the file you would like to retrieve.
Response
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
Request
Path Parameters
:id
required
integer
The unique identifier of the file you would like to download.
Response
200: OK
Returns the actual contents of the file.
​
put
Rename a File
https://ws-api.onehub.com/files/:id
Renames the file object specified via :id.
Request
Response
Request
Path Parameters
:id
required
integer
The unique identifier of the file you would like to rename.
Body Parameters
filename
required
string
The new name for the file.
Response
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/files/:id
Deletes the file specified via :id.
Request
Response
Request
Path Parameters
:id
required
integer
The unique identifier of the file you would like to delete.
Response
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.
//
Methods - Previous
Events
Next - Methods
Folders
Last updated 10 months ago
Files

postCreate a File

getRead a File's Metadata

getDownload a File

putRename a File

deleteDelete a File

post
Create a File

get
Read a File's Metadata

get
Download a File

put
Rename a File

delete
Delete a File
