The Box Content API

The Box Content API gives you access to the content management features you see in our web app and lets you extend them for use in your own app. It strives to be RESTful and is organized around the main resources you’re familiar with from the Box web interface.

Base URI

https://api.box.com/2.0
Documentation
API Methods
Folders

Folders contain information about the items contained inside of them, including files and other folders. There is also a set of metadata such as who owns the folder and when it was modified that is also returned. When accessing other resources that make reference to folders, a ‘mini folder’ object will be used.

GET /folders/{folderid}/items
POST /folders
GET /folders/{folderId}
PUT /folders/{folderId}
DELETE /folders/{folderId}
POST /folders/{folderId}/copy
Retrieve a Folder’s Items
GET /folders/{folderid}/items

Retrieves the files and/or folders contained within this folder without any other metadata about the folder. Any attribute in the full files or folders objects can be passed in with the fieldsparameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default. Multiple attributes can be passed in separated by commas e.g. fields=name,created_at. Paginated results can be retrieved using thelimit and offset parameters.

Path variables

folderid
string required

Folder identifier

Example:
12345

Request parameters

fields
string optional

Attribute(s) to include in the response

Example:
size
limit
number optional

The number of items to return (default=100, max=1000)

Example:
1
offset
string optional

The item at which to begin the response (default=0)

Example:
0

Responses

200 OK
Body
Object

An collection of items contained in the folder is returned. An error is thrown if the folder does not exist, or if any of the parameters are invalid.

total_count
string
Example:
24
entries
offset
number
Example:
0
limit
number
Example:
2
order
Object

Sorting object

by
string
Example:
type
direction
string
Example:
ASC
Create a New Folder
POST /folders

Used to create a new empty folder. The new folder will be created inside of the specified parent folder

Request body

Object
name
string

The desired name for the folder

Example:
My Documents
parent
Object

The parent folder

id
string

The ID of the parent folder

Example:
12345

Responses

201 Created
Body
Get Information About a Folder
GET /folders/{folderId}

Retrieves the full metadata about a folder, including information about when it was last updated as well as the files and folders contained in it. The root folder of a Box account is always represented by the id “0″.

Path variables

folderId
string required

Responses

200 OK
Body
Update Information About a Folder
PUT /folders/{folderId}

Used to update information about the folder. To move a folder, update the ID of its parent. To enable an email address that can be used to upload files to this folder, update thefolder_upload_email attribute. An optional If-Match header can be included to ensure that client only updates the folder if it knows about the latest version.

Path variables

folderId
string required

Request body

Object

Used to update information about the folder. To move a folder, update the ID of its parent. To enable an email address that can be used to upload files to this folder, update thefolder_upload_email attribute. An optional If-Match header can be included to ensure that client only updates the folder if it knows about the latest version.

name
string

The name of the folder

Example:
My Documents
description
string

The description of the folder.

parent
Object

The parent folder of this file.

id
string

Parent object id

shared_link
Object

An object representing this item’s shared link and associated permissions.

url
string
access
string

The level of access required for this shared link. Can be open,company, collaborators.

unshared_at
string

The day that this link should be disabled at. Timestamps are rounded off to the given day.

permissions

The set of permissions that apply to this link.

folder_upload_email
Object

The email-to-upload address for this folder.

access
string

Can be open or collaborators.

Example:
open
owned_by
Object

The user who owns the folder. Only used when moving a collaborated folder that you are not the owner of to a folder you are the owner of. Not a substitute for changing folder owners, please reference collaborations to accomplish folder ownership changes.

id
string

The ID of the user, should be your own user ID.

Example:
123
sync_state
string

Whether Box Sync clients will sync this folder. Values ofsynced or not_synced can be sent, whilepartially_synced may also be returned.

Example:
partially_synced
tags
string

All tags attached to this folder. To add/remove a tag to/from a folder, you can first get the folder’s current tags (be sure to specify?fields=tags, since the tags field is not returned by default); then modify the list as required; and finally, set the folder’s entire list of tags.

Example:
cool

Responses

200 OK
Body
Delete a Folder
DELETE /folders/{folderId}

Used to delete a folder.

Path variables

folderId
string required

Request parameters

recursive
boolean optional

Whether to delete this folder if it has items inside of it.
A recursive parameter must be included in order to delete folders that have items inside of them. An optional If-Match header can be included to ensure that client only deletes the folder if it knows about the latest version.

Example:
true

Responses

204 No Content
Copy a Folder
POST /folders/{folderId}/copy

Used to create a copy of a folder in another folder. The original version of the folder will not be altered.

Path variables

folderId
string required

Request body

Object
parent
Object

Object representing the new location of the folder

id
string

The ID of the destination folder

Example:
123
name
string

An optional new name for the folder

Example:
Documents Copy

Responses

200 OK
Body
Files

File objects represent that metadata about individual files in Box, with attributes describing who created the file, when it was last modified, and other information. The actual content of the file itself is accessible through the /files/{id}/content endpoint. Attributes listed in green will not appear in default file requests and must be explicitly asked for using the fields parameter.

GET /files/{fileId}
POST /files/{fileId}
Get Information About a File
GET /files/{fileId}

Used to retrieve the metadata about a file.

Path variables

fileId
string required

Request parameters

p12 23
string optional

wdgwre

Example:
1342
p5
string optional

wer

Example:
23

Responses

200 OK
Body
Update a file’s information
POST /files/{fileId}

Used to update individual or multiple fields in the file object, including renaming the file, changing it’s description, and creating a shared link for the file. To move a file, change the ID of its parent folder. An optional If-Match header can be included to ensure that client only updates the file if it knows about the latest version.

Path variables

fileId
string required

Request body

Object

Used to update individual or multiple fields in the file object, including renaming the file, changing it’s description, and creating a shared link for the file. To move a file, change the ID of its parent folder. An optional If-Match header can be included to ensure that client only updates the file if it knows about the latest version.

name
string

The name of the file

Example:
new name.jpg
description
string

The new description for the file.

Example:
a picture of tigers
parent
Object

The parent folder of this file.

id
string

Parent folder id

shared_link
Object

An object representing this item’s shared link and associated permissions.

url
string
access
string

The level of access required for this shared link. Can be open,company, collaborators.

unshared_at
string

The day that this link should be disabled at. Timestamps are rounded off to the given day.

permissions

The set of permissions that apply to this link.

tags
string

All tags attached to this file. To add/remove a tag to/from a file, you can first get the file’s current tags (be sure to specify ?fields=tags, since the tags field is not returned by default); then modify the list as required; and finally, set the file’s entire list of tags.

Responses

200 OK
Body
Comments

Comments are messages generated by Box users. Each message is tied to a specific file. You can create comments independently or create them as responses to other comments.

POST /comments/{commentId}
POST /comments
Change a Comment’s Message
POST /comments/{commentId}

Used to update the message of the comment.

Path variables

commentId
string required

cometd

Request parameters

v13
string optional

3r 2 e

Example:
34

Request body

Object

Used to update the message of the comment

message
string

The desired text for the comment message

Example:
These tigers are not really cool!

Responses

200 OK
Body
Add a Comment to an Item
POST /comments

Used to add a comment by the user to a specific file or comment (i.e. as a reply comment).

Request body

Object

Used to add a comment by the user to a specific file or comment (i.e. as a reply comment).

item
Object

The item that this comment will be placed on.

type
string

The type of the item that this comment will be placed on. Can be file or comment

Example:
file
id
string

The id of the item that this comment will be placed on.

message
string

The text body of the comment

Example:
These tigers are cool!

Responses

200 OK
Body
Data Reference
Folder

Folders contain information about the items contained inside of them, including files and other folders. There is also a set of metadata such as who owns the folder and when it was modified that is also returned. When accessing other resources that make reference to folders, a ‘mini folder’ object will be used.

Object
type
string

For folders is ‘folder’

Example:
folder
id
string

The folder’s ID.

Example:
11446498
sequence_id
string

A unique ID for use with the /events endpoint.
May be null for some folders such as root or trash.

Example:
1
etag
string

A unique string identifying the version of this folder.May be null for some folders such as root or trash.

Example:
1
name
string

The name of the folder.

Example:
Pictures
created_at
string

The time the folder was created.
May be null for some folders such as root or trash.

Example:
2012-12-12T10:53:43-08:00
modified_at
string

The time the folder or its contents were last modified.
May be null for some folders such as root or trash.

Example:
2012-12-12T11:15:04-08:00
description
string

The description of the folder.

Example:
Some pictures I took
size
number

The folder size in bytes. Be careful parsing this integer, it can easily go into EE notation: see IEEE754 format.

Example:
629644
path_collection
Object

The path of folders to this item, starting at the root.

total_count
number
Example:
1
entries
Array
Object
type
string
Example:
folder
id
string
Example:
0
sequence_id
string
etag
string
name
string
Example:
All Files
sha1
string
Example:
134b65991ed521fcfe4724b7d814ab8ded5185dc
created_by

The user who created this folder.

modified_by

The user who last modified this folder.

owned_by

The user who owns this folder.

shared_link

The shared link for this folder. Null if not set.

folder_upload_email
Object

The upload email address for this folder. Null if not set.

access
string
Example:
open
email
string
Example:
upload.Picture.k13sdz1@u.box.com
parent

The folder that contains this one.
May be null for folders such as root, trash and child folders whose parent is inaccessible.

item_status
string

Whether this item is deleted or not.

Example:
active
item_collection
Object

A collection of mini file and folder objects contained in this folder.

total_count
number
Example:
1
entries
Array
Object
type
string
Example:
folder
id
string
Example:
0
sequence_id
string
etag
string
name
string
Example:
All Files
sha1
string
Example:
134b65991ed521fcfe4724b7d814ab8ded5185dc
offset
number
Example:
0
limit
number
Example:
100
tags
Array of string

All tags applied to this folder.

Example:
approved
sync_state
string

Whether this folder will be synced by the Box sync clients or not. Can besynced, not_synced, or partially_synced.

has_collaborations
boolean

Whether this folder has any collaborators.

Example:
false
permissions

The permissions that the current user has on this folder.

UserMini
Object
type
string
Example:
user
id
string
Example:
17738362
name
string
Example:
sean rose
login
string
Example:
sean@box.com
FolderMini
Object
type
string
Example:
folder
id
string
Example:
0
sequence_id
unknown
etag
unknown
name
string
Example:
All Files
Permissions
Object
can_download
boolean
Example:
true
can_preview
boolean
Example:
true
can_upload
boolean
Example:
false
can_rename
boolean
Example:
false
can_delete
boolean
Example:
false
can_share
boolean
Example:
false
can_invite_collaborator
boolean
Example:
false
can_set_share_access
boolean
Example:
false
File

File objects represent that metadata about individual files in Box, with attributes describing who created the file, when it was last modified, and other information. The actual content of the file itself is accessible through the /files/{id}/content endpoint

Object
type
string

For files is ‘file’

Example:
file
id
string

The folder’s ID.

Example:
11446498
sequence_id
string

A unique ID for use with the /events endpoint.
May be null for some folders such as root or trash.

Example:
1
etag
string

A unique string identifying the version of this folder.May be null for some folders such as root or trash.

Example:
1
name
string

The name of this file.

Example:
Pictures
created_at
string

When this file was created on Box’s servers.

Example:
2012-12-12T10:53:43-08:00
modified_at
string

When this file was last updated on the Box servers.

Example:
2012-12-12T11:15:04-08:00
description
string

The description of the file.

Example:
Some pictures I took
size
number

Size of this file in bytes.

Example:
629644
path_collection
Object

The path of folders to this item, starting at the root.

total_count
number
Example:
1
entries
Array of FolderMini
created_by

The user who created this folder.

modified_by

The user who last modified this folder.

owned_by

The user who owns this folder.

shared_link

The shared link for this folder. Null if not set.

parent

The folder that contains this one.
May be null for folders such as root, trash and child folders whose parent is inaccessible.

item_status
string

Whether this item is deleted or not.

Example:
active
tags
Array of string

All tags applied to this folder.

Example:
approved
permissions

The permissions that the current user has on this folder.

sha1
string

The sha1 hash of this file.

Example:
134b65991ed521fcfe4724b7d814ab8ded5185dc
trashed_at
string

When this file was last moved to the trash.

purged_at
string

When this file will be permanently deleted.

content_created_at
string

When the content of this file was created (more info).

Example:
2013-02-04T16:57:52-08:00
content_modified_at
string

When the content of this file was last modified (more info).

Example:
2013-02-04T16:57:52-08:00
version_number
number

The version of the file.

Example:
1
comment_count
number

The number of comments on a file.

Example:
10

Shared link

Object
url
string
Example:
https://www.box.com/s/vspke7y05sb214wjokpk
download_url
string
Example:
https://www.box.com/shared/static/vspke7y05sb214wjokpk
vanity_url
unknown
is_password_enabled
boolean
Example:
false
unshared_at
unknown
download_count
number
Example:
0
preview_count
number
Example:
0
access
string
Example:
open
permissions
Types: File Folder
Comment

Comments are messages generated by Box users. Each message is tied to a specific file. You can create comments independently or create them as responses to other comments.

Object
type
string

For comments is ‘comment’

Example:
comment
id
string

A unique string identifying this comment

Example:
191969
is_reply_comment
boolean

Whether or not this comment is a reply to another comment

Example:
false
message
string

The comment text that the user typed

Example:
These tigers are cool!
created_by

A mini user object representing the author of the comment

created_at
string
Example:
2012-12-12T11:25:01-08:00
item
Object

The object this comment was placed on

id
string
Example:
5000948880
type
string
Example:
file
modified_at
string
Example:
2012-12-12T11:25:01-08:00
tagged_message
string

The string representing the comment text with @mentions included. @mention format is @[id:username]. Field is not included by default.

Example:
This tiger @[id,hehe] are cool!