API Basics

The Box 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.

Before you do anything, you should create a free Box account that you can test the API against and register for an API key so that you can make API calls.

Example Requests

Sample API calls are provided next to each method using cURL, a standard command line tool. All you need to do is drop in your specific parameters, and you can test the calls from the command line. Here is a great tutorial on using cURL with APIs. If the command line isn’t your preference, a great alternative is POSTMAN, an easy-to-use Chrome extension for making HTTP requests.

Input/Output Format

Both request body data and response data are formatted as JSON. Extremely large numbers will be returned in IEEE754 format (the same way doubles are stored in Java), e.g. 1.2318237429383e+31

Date Format

All timestamps (both those sent in requests and those returned in responses) should be formatted as ISO 8601.

gzip

If you would like responses from Box to be compressed for faster response times, simply include an Accept-Encoding header with a value of gzip, deflate, and responses will be gzipped.

CORS

CORS, or cross-origin resource sharing, is a mechanism that allows a web page to make XMLHttpRequests to another domain (i.e. a domain different from the one it was loaded from). CORS is supported in a specific set of modern browsers. The Box API supports CORS on an app-by-app basis. If you’re building an application that needs CORS, please contact us with a description of your use case.

Upcoming Changes

We are always maintaining, fixing, and enhancing our API. As such, you should expect new endpoints to show up, new fields to be added to responses and new error codes to appear. We recommend that you build your code to gracefully ignore things that you aren’t expecting, and to handle errors in standard HTTP-centric ways.

Getting Help

Please utilize the box-api tag on StackOverflow for any questions or suggestions. For more info on v1 of the Box API, please see here

Base URL

https://api.box.com/2.0

Upload URL

https://upload.box.com/api/2.0

Resources

/folders
/folders/{id}/items
/folders/{id}/collaborations
/files
/files/{id}/content
/files/{id}/versions
/shared_items
/comments
/collaborations
/search
/events
/users
/tokens

OAuth 2

The Box API uses OAuth 2 for authentication. An authorization header containing a valid access_token must be included in every request. The standard OAuth endpoints are listed below. Please see here for a more in-depth tutorial.

OAUTH 2 URL

https://www.box.com/api/oauth2

Box Authorization Header

Authorization: Bearer YOUR_ACCESS_TOKEN

Authorize

The URL of Box’s authorization page. This is the URL that your application should forward the user to in first leg of OAuth 2.

  • response_type
    required
    Whether the endpoint returns an authorization code. For web applications, a value of code should be used.
    Type: string

  • client_id
    required
    The client_id of your application
    Type: string

  • redirect_uri
    An HTTPS URI or custom URL scheme where the response will be redirected. Optional if the redirect URI is registered with Box already.
    Type: uri

  • state
    An arbitrary string of your choosing that will be included in the response to your application
    Type: string

Example URL

https://www.box.com/api/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI

Example Callback

YOUR_REDIRECT_URI?code=THE_AUTHORIZATION_CODE

Token

The endpoint that actually returns access tokens.

  • grant_type
    required
    The grant type of this request. Will be authorization_code or refresh_token, depending on
    which is accompanying this request
    Type: string

  • code
    An authorization code you retrieved in the first leg of OAuth 2
    Type: string

  • refresh_token
    A refresh token retrieved in the final leg of OAuth 2
    Type: string

  • client_id
    required
    Your application’s client_id
    Type: string

  • client_secret
    required
    Your application’s client_secret
    Type: string

  • redirect_uri
    Required only if a redirect URI is not configured at box.com/developers/services
    Type: uri

Example Request

curl https://www.box.com/api/oauth2/token \
-d 'grant_type=authorization_code&code=YOUR_AUTH_CODE&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET' \
-X POST

Example Response

{
    "access_token": "T9cE5asGnuyYCCqIZFoWjFHvNbvVqHjl",
    "expires_in": 3600,
    "token_type": "bearer",
    "refresh_token": "J7rxTiWOHMoSC1isKZKBZWizoRXjkQzig5C6jFgCVJ9bUnsUfGMinKBDLZWP9BgR"
}

Revoke

Use this endpoint to revoke active tokens i.e. to ‘log out’ a user.

  • client_id
    required
    Your application’s client_id
    Type: string

  • client_secret
    required
    Your application’s client_secret
    Type: string

  • token
    required
    One of an access_token or refresh_token (both will be revoked)
    Type: string

Example Request

curl https://www.box.com/api/oauth2/revoke \
-d 'client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&token=YOUR_TOKEN' \
-X POST

Example Response

Errors

The Box API communicates errors through standard HTTP status codes paired with error objects. Generally the following pattern will apply:

2xx
The request was successfully received, understood, and accepted
3xx
Further action needs to be taken by the user agent in order to fulfill the request
4xx
An error in the request. Usually a bad parameter.
5xx
The request is fine, but something is wrong on Box’s end

The accompanying error objects are as detailed as possible without being unwieldy

type
string		 for errors is ‘error’
status
int		 the HTTP status of the error response
code
string		 the HTTP code of the error response
help_url
string		 a URL linking to more information about why this error occurred
message
string		 a human readable message about the error that can be passed back to your user
request_id
string		 a unique ID for this request helpful for troubleshooting

HTTP Status Codes

200	success
201	created
202	accepted
204	no_content
302	redirect
304	not_modified
400	bad_request
401	unauthorized
403	forbidden
404	not_found
405	method_not_allowed
409	conflict
412	precondition_failed
429     too_many_requests
500	internal_server_error
507	insufficient_storage

Example Error

{
    "type":"error",
    "status":404,
    "code":"not_found",
    "help_url":"",
    "message":"Folder not found",
    "request_id":"7522414694f97d171b6aea"
}

Fields

By default, each object has a standard and a mini format. The standard format is returned when you request a specific object (e.g. GET /files/{id}). The mini is returned when the object is part of a collection of items (e.g. GET /files/{id}/comments). In either case, you can use the fields URL parameter to specify a comma-separated list of which specific fields you’d like returned. They can be any fields that are a part of the complete object for that particular type. For example, GET /files/{id}?fields=modified_at,path_collection,name is a valid request. Type and ID are always returned regardless of which fields are requested. Some fields are not included in the standard format, but are available by request via the ?fields mechanism.

Fields Support: The fields parameter is not yet supported for GET /events, POST /files/content, and POST /files/{id}/content.

EXAMPLE REQUEST

curl https://api.box.com/2.0/files/FILE_ID?fields=modified_at,path_collection,name
-H "Authorization: Bearer ACCESS_TOKEN"

EXAMPLE RESPONSE

{
    "type": "file",
    "id": "3447956798",
    "etag": "1",
    "modified_at": "2012-10-04T12:34:05-07:00",
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
               	"sequence_id": null,
              	"etag": null,
                "name": "All Files"
           },
           {
               "type": "folder",
               "id": "423404344",
               "sequence_id": "15",
               "etag": "15",
               "name": "General Info"
           }
       ]
   },
   "name": "Org Chart.PDF"
}

If-Match

The Box API supports the HTTP If-Match and If-None-Match headers for certain methods in the files and folders endpoints (Supported methods listed on the right). If-Match headers let you ensure that your app only alters files/folders on Box if you have the current version; similarly, If-None-Match headers ensure that you don’t retrieve unnecessary data if you already have the most current version on-hand.

Etags

Every files and folders object has an etag attribute that is unique across every version of that file or folder. Etags are unique across versions of items, but not across different items.. For example, the first version of File XYZ can have an etag value of “1″, and the first version of File ABC “1″, but any other version of File XYZ must have an etag value that is not “1″.

Etag: You should make no assumptions about the value of etags outside of the fact that they are unique for each version of particular file or folder relative to other versions of that file or folder.

Using If-(None-)Match

The methods that can be used with If-Match are listed on the right. The following tables summarize the behavior you can expect when using If-Match:

If-Match Header Has Most Current Etag
Resource exists HTTP Status of Response: 200
Resource does not exist HTTP Status of Response: 412
If-Match Header Does Not Have Most Current Etag
Resource exists HTTP Status of Response: 412
Resource does not exist HTTP Status of Response: 404

The following behavior will be found with the If-None-Match header:

If-None-Match Header Has Most Current Etag
Resource exists HTTP Status of Response: 304
Resource does not exist HTTP Status of Response: 404
If-None-Match Header Does Not Have Most Current Etag
Resource exists HTTP Status of Response: 200
Resource does not exist HTTP Status of Response: 404

IF-MATCH SUPPORTED METHODS

POST /files/{id}/content
PUT /files/{id}
DELETE /files/{id}
PUT /folders/{id}
DELETE /folder/{id}

IF-NONE-MATCH SUPPORTED METHODS

GET /files/{id}
GET /folders/{id}
GET /shared_items

Rate Limiting

In certain cases, Box needs to enforce rate-limiting in order to prevent abuse by third-party services and/or users. In the event that an excessive level of usage is reached, a standard 429 Too Many Requests error will be returned, with an indication of when to retry the request. In the event that back-to-back 429s are received, an exponential backoff algorithm is recommended.

Retry Header

HTTP/1.1 429 Too Many Requests
Retry-After: {retry time in seconds}

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.

Folder Object

Attributes

type
string 		For folders is ‘folder’
id
string 		The folder’s ID
sequence_id
string 		A unique ID for use with the /events endpoint
etag
string 		A unique string identifying the version of this folder
name
string 		The name of the folder
created_at
timestamp 		The time the folder was created
modified_at
timestamp 		The time the folder or its contents were last modified
description
string 		The description of the folder
size
integer 		The folder size in bytes
path_collection
collection 		The path of folders to this item, starting at the root
created_by
mini user object 		The user who created this folder
modified_by
mini user object 		The user who last modified this folder
owned_by
mini user object 		The user who owns this folder
shared_link
object 		The shared link for this folder
folder_upload_email
object 		The upload email address for this folder
parent
mini folder object

 The folder that contains this one
item_status
string 		Whether this item is deleted or not
item_collection
collection 		A collection of mini file and folder objects contained in this folder
sync_state
string 		Whether this folder will be synced by the Box sync clients or not. Can be synced, not_synced, or partially_synced

Example Folder

{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": "https://www.box.com/shared/static/vspke7y05sb214wjokpk",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "file",
                "id": "5000948880",
                "sequence_id": "3",
                "etag": "3",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
                "name": "tigers.jpeg"
            }
        ],
        "offset": 0,
        "limit": 100
    }
}

Example Mini Folder

{
    "type":"folder",
    "id":"301415432",
    "sequence_id":"0",
    "name":"my first sub-folder"
}

Retrieve a Folder’s 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 fields parameter 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 the limit and offset parameters.

fields: ‘id’ and ‘type’ are always returned for each item.
URL Parameters
fields Attribute(s) to include in the response
Type: string
limit The number of items to return
Type: integer (default=100, max=1000)
offset The item at which to begin the response
Type: integer (default=0)

Returns

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.

Order: Each order object will list an attribute (e.g. name) and direction (e.g. ASC).

Method

GET /folders/{folder id}/items

Example Request

curl https://api.box.com/2.0/folders/FOLDER_ID/items?limit=2&offset=0 \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "total_count": 24,
    "entries": [
        {
            "type": "folder",
            "id": "192429928",
            "sequence_id": "1",
            "etag": "1",
            "name": "Stephen Curry Three Pointers"
        },
        {
            "type": "file",
            "id": "818853862",
            "sequence_id": "0",
            "etag": "0",
            "name": "Warriors.jpg"
        }
    ],
    "offset": 0,
    "limit": 2,
    "order": [
        {
            "by": "type",
            "direction": "ASC"
        },
        {
            "by": "name",
            "direction": "ASC"
        }
    ]
}

Create a New Folder

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

 

Request Body Attributes

name
required		 The desired name for the folder
Type: string
parent
required		 The parent folder
Type: object
id
required		 The ID of the parent folder
Type: string

 

Returns

A full folder object is returned if the parent folder ID is valid and if no name collisions occur.

Method

POST /folders

Example Request

curl https://api.box.com/2.0/folders\
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name":"New Folder", "parent": {"id": "0"}}' \
-X POST

Example Response

{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": "https://www.box.com/shared/static/vspke7y05sb214wjokpk",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 0,
        "entries": [],
        "offset": 0,
        "limit": 100
    }
}

Get Information About a Folder

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

Request Body Attributes
None are taken

Returns

A full file object is returned, including the most current information available about it. An error is thrown if the folder does not exist or if the user does not have access to it.

Method

GET /folders/{folder id}

Example Request

curl https://api.box.com/2.0/folders/FOLDER_ID \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": "https://www.box.com/shared/static/vspke7y05sb214wjokpk",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "file",
                "id": "5000948880",
                "sequence_id": "3",
                "etag": "3",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
                "name": "tigers.jpeg"
            }
        ],
        "offset": 0,
        "limit": 100
    }
}

Copy a Folder

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

Request Body Attributes
parent
required 		Object representing the new location of the folder
Type: string
id
required		 The ID of the destination folder
Type: string
name An optional new name for the folder
Type: string

Returns

A full folder object is returned if the ID is valid and if the update is successful. Errors can be thrown if the destination folder is invalid or if a file-name collision occurs. A 403 will be returned if the intended destination folder is the same, as this will cause a name collision.

Method

POST /folders/{folder id}/copy

Example Request

curl https://api.box.com/2.0/folders/FOLDER_ID/copy \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"parent": {"id" : DESTINATION_FOLDER_ID}}' \
-X POST

Example Response

{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": "https://www.box.com/shared/static/vspke7y05sb214wjokpk",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "file",
                "id": "5000948880",
                "sequence_id": "3",
                "etag": "3",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
                "name": "tigers.jpeg"
            }
        ],
        "offset": 0,
        "limit": 100
    }
}

Delete a Folder

Used to delete a folder. 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.

Trash: Depending on the enterprise settings for this user, the item will either be actually deleted from Box or moved to the trash.
Headers
If-Match This is in the ‘etag’ field of the folder object.
Type: string
URL Parameters
recursive Whether to delete this folder if it has items inside of it
Type: boolean

Returns

An empty 204 response will be returned upon successful deletion. An error is thrown if the folder is not empty and the ‘recursive’ parameter is not included.

Method

DELETE /folders/{folder id}

Example Request

curl https://api.box.com/2.0/folders/FOLDER_ID?recursive=true  \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response

Update Information About a Folder

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 the folder_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.

Note: The root folder (0) cannot be updated. Editing of passwords is currently not supported for shared links.

Headers
If-Match This is in the ‘etag’ field of the folder object.
Type: string
Request Body Attributes
name The name of the folder
Type: string
description The description of the folder
Type: string
parent The parent folder of this file
Type: object
id The ID of the parent folder
Type: string
shared_link An object representing this item’s shared link and associated permissions
Type: object
access The level of access required for this shared link. Can be open, company, collaborators
Type: string
unshared_at The day that this link should be disabled at. Timestamps are rounded off to the given day.
Type: timestamp
permissions The set of permissions that apply to this link
Type: object
permissions.can_download Whether this link allows downloads
Type: boolean
permissions.can_preview Whether this link allows previews
Type: boolean
folder_upload_email The email-to-upload address for this folder
Type: object
access Can be open or collaborators
Type: object
owned_by 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.
Type: object
id The ID of the user, should be your own user ID.
Type: string
sync_state Whether Box Sync clients will sync this folder. Values of synced or not_synced can be sent, while partially_synced may also be returned.
Type: string

Returns

The updated folder is returned if the name is valid. Errors generally occur only if there is a name collision.

Method

PUT /folders/{folder id}

Example Request

curl https://api.box.com/2.0/folders/FOLDER_ID \
-H "Bearer ACCESS_TOKEN" \
-d '{"name":"New Folder Name!"}' \
-X PUT

Example Response

{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "New Folder Name!",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": "https://www.box.com/shared/static/vspke7y05sb214wjokpk",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "file",
                "id": "5000948880",
                "sequence_id": "3",
                "etag": "3",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
                "name": "tigers.jpeg"
            }
        ],
        "offset": 0,
        "limit": 100
    }
}

Create a Shared Link for a Folder

Used to create a shared link for this particular folder. Please see here for more information on the permissions available for shared links. In order to disable a shared link, send this same type of PUT request with the value of shared_link set to null, i.e. {"shared_link": null}

Note: Editing of passwords is currently not supported for shared links.

Request Body Attributes

  • shared_link
    An object representing this item’s shared link and associated permissions
    Type: object

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

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

      permissions
      The set of permissions that apply to this link
      Type: object

      • can_download
        Whether this link allows downloads. Can only be used with Open and Company
        Type: string

        can_preview
        Whether this link allows previewing. Can only be used with Open and Company
        Type: string

 

Returns

A full folder object containing the updated shared link is returned if the ID is valid and if the update is successful.

Method

PUT /folders/{folder id}

Example Request

curl https://api.box.com/2.0/folders/FOLDER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"shared_link": {"access": "open"}}' \
-X PUT

Example Response

{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": "https://www.box.com/shared/static/vspke7y05sb214wjokpk",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "file",
                "id": "5000948880",
                "sequence_id": "3",
                "etag": "3",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
                "name": "tigers.jpeg"
            }
        ],
        "offset": 0,
        "limit": 100
    }
}

View a Folder’s Discussions

Retrieves the discussions on a particular folder, if any exist.

URL Parameters
None are taken

Returns

A collection of discussion objects are returned. If there are no discussions on the folder, an empty discussions collection is returned.

Method

GET /folders/{folder id}/discussions

Example Request

curl https://api.box.com/2.0/folders/FOLDER_ID/discussions \
-H "Authorization: Bearer ACCESS_TOKEN" \

Example Response

{
    "total_count": 1,
    "entries": [
        {
            "type": "discussion",
            "id": "602628",
            "name": "heloo world"
        }
    ]
}

View a Folder’s Collaborations

Use this to get a list of all the collaborations on a folder i.e. all of the users that have access to that folder.

URL Parameters
  • None are taken

Returns

A collection of collaboration objects are returned. If there are no collaborations on this folder, an empty collection will be returned.

Method

GET /folders/{id}/collaborations

Example Request

curl https://api.box.com/2.0/folders/FOLDER_ID/collaborations \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "total_count": 1,
    "entries": [
        {
            "type": "collaboration",
            "id": "14176246",
            "created_by": {
                "type": "user",
                "id": "4276790",
                "name": "David Lee",
                "login": "david@box.com"
            },
            "created_at": "2011-11-29T12:56:35-08:00",
            "modified_at": "2012-09-11T15:12:32-07:00",
            "expires_at": null,
            "status": "accepted",
            "accessible_by": {
                "type": "user",
                "id": "755492",
                "name": "Simon Tan",
                "login": "simon@box.net"
            },
            "role": "editor",
            "acknowledged_at": "2011-11-29T12:59:40-08:00",
            "item": null
        }
    ]
}

Get the Items in the Trash

Retrieves the files and/or folders that have been moved to the trash. Any attribute in the full files or folders objects can be passed in with the fields parameter 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 the limit and offset parameters.

fields: ‘id’ and ‘type’ are always returned for each item.
URL Parameters
fields Attribute(s) to include in the response
Type: string
limit The number of items to return
Type: integer (default=100, max=1000)
offset The item at which to begin the response
Type: integer (default=0)

Returns

An collection of items contained in the trash is returned. An error is thrown if any of the parameters are invalid.

Method

GET /folders/trash/items

Example Request

curl https://api.box.com/2.0/folders/trash/items?limit=2&offset=0 \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "total_count": 49542,
    "entries": [
        {
            "type": "file",
            "id": "2701979016",
            "sequence_id": "1",
            "etag": "1",
            "sha1": "9d976863fc849f6061ecf9736710bd9c2bce488c",
            "name": "file Tue Jul 24 145436 2012KWPX5S.csv"
        },
        {
            "type": "file",
            "id": "2698211586",
            "sequence_id": "1",
            "etag": "1",
            "sha1": "09b0e2e9760caf7448c702db34ea001f356f1197",
            "name": "file Tue Jul 24 010055 20129Z6GS3.csv"
        }
    ],
    "offset": 0,
    "limit": 2
}

Restore a Trashed Folder

Restores an item that has been moved to the trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. If that parent folder no longer exists or if there is now an item with the same name in that parent folder, the new parent folder and/or new name will need to be included in the request.

Request Body Attributes
  • name
    The new name for this item
    Type: string

  • parent
    The new parent folder for this item
    Type: object

    • id
      The id of the new parent folder
      Type: string

Returns

The full item will be returned with a 201 Created status. By default it is restored to the parent folder it was in before it was trashed.

Errors
  • 403
    The user doesn’t have access to the folder the item is being restored to or the user doesn’t have permission to restore items from the trash

  • 405
    The item is not in the trash

  • 409
    There is an item with the same name in the folder the item is being restored to

Method

POST /folders/{folder id}

Example Request

curl https://api.box.com/2.0/folders/FOLDER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name":"non-conflicting-name"}' \
-X POST

Example Response

{
    "type": "folder",
    "id": "588970022",
    "sequence_id": "2",
    "etag": "2",
    "name": "heloo world",
    "created_at": "2013-01-15T16:15:27-08:00",
    "modified_at": "2013-02-07T13:26:00-08:00",
    "description": "",
    "size": 0,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "trashed_at": null,
    "purged_at": null,
    "content_created_at": "2013-01-15T16:15:27-08:00",
    "content_modified_at": "2013-02-07T13:26:00-08:00",
    "owned_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "shared_link": null,
    "folder_upload_email": null,
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active"
}

Permanently Delete a Trashed Folder

Permanently deletes an item that is in the trash. The item will no longer exist in Box. This action cannot be undone.

URL Paremeters
  • None are taken

Returns

An empty 204 No Content response will be returned upon successful deletion

Errors
  • 404
    The item is not in the trash

Method

DELETE /folders/{folder id}/trash

Example Request

curl https://api.box.com/2.0/folders/FOLDER_ID/trash \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response

Get a Trashed Folder

Retrieves an item that has been moved to the trash.

URL Parameters
  • None are taken

Returns

The full item will be returned, including information about when the it was moved to the trash.

Errors
  • 404
    The item is no longer in the trash.

Method

GET /folders/{folder id}/trash

Example Request

curl https://api.box.com/2.0/folders/FOLDER_ID/trash \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "type": "folder",
    "id": "588970022",
    "sequence_id": "1",
    "etag": "1",
    "name": "heloo world",
    "created_at": "2013-01-15T16:15:27-08:00",
    "modified_at": "2013-01-17T13:48:23-08:00",
    "description": "",
    "size": 0,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "1",
                "sequence_id": null,
                "etag": null,
                "name": "Trash"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "trashed_at": "2013-02-07T12:53:32-08:00",
    "purged_at": "2013-03-09T12:53:32-08:00",
    "content_created_at": "2013-01-15T16:15:27-08:00",
    "content_modified_at": "2013-01-17T13:48:23-08:00",
    "owned_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "shared_link": null,
    "folder_upload_email": null,
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "trashed"
}

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.

File Object

Attributes

type
string 		For files is ‘file’
id
string 		Box’s unique string identifying this file
sequence_id
string 		A unique ID for use with the /events endpoint
etag
string 		A unique string identifying the version of this file.
sha1
string 		The sha1 hash of this file
name
string 		The name of this file
description
string 		The description of this file
size
integer 		Size of this file in bytes
path_collection
collection 		The path of folders to this item, starting at the root
created_at
timestamp 		When this file was created on Box’s servers
modified_at
timestamp 		When this file was last updated on the Box servers
trashed_at
timestamp 		When this file was last moved to the trash
purged_at
timestamp 		When this file will be permanently deleted
content_created_at
timestamp 		When the content of this file was created (more info)
content_modified_at
timestamp 		When the content of this file was last modified (more info)
created_by
mini user object 		The user who first created file
modified_by
mini user object 		The user who last updated this file
owned_by
mini user object 		The user who owns this file
shared_link
object 		The shared link object for this file
parent
mini folder object 		The folder this file is contained in
item_status
string 		Whether this item is deleted or not

Example File

{
    "type": "file",
    "id": "5000948880",
    "sequence_id": "3",
    "etag": "3",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "tigers.jpeg",
    "description": "a picture of tigers",
    "size": 629644,
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            }
        ]
    },
    "created_at": "2012-12-12T10:55:30-08:00",
    "modified_at": "2012-12-12T11:04:26-08:00",
    "trashed_at": null,
    "purged_at": null,
    "content_created_at": "2013-02-04T16:57:52-08:00",
    "content_modified_at": "2013-02-04T16:57:52-08:00",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
    },
    "item_status": "active"
}

Example Mini File

{
    "sequence_id": "0",
    "etag": "d9efb63902768a30c9e6225ebff46d15cde82476",
    "type": "file",
    "id": "2631999573",
    "name":"IMG_1312.JPG"
}

Upload a File

Use the Uploads API to allow users to add a new file. The user can then upload a file by specifying the destination folder for the file. If the user provides a file name that already exists in the destination folder, the user will receive an error.

A different Box URL, https://upload.box.com/api/2.0/files/content, handles uploads. This API uses the multipart post method to complete all upload tasks. You can optionally specify a Content-MD5 header with the SHA1 hash of the file to ensure that the file is not corrupted in transit.

Supported Filenames: Filenames with characters \ / ” : < > | * ? and filenames with leading or trailing whitespace or periods are not allowed.

Headers

Content-MD5 The SHA1 hash of the file
Type: string

Form Elements

filename
required 		The name of the file to be uploaded
Type: file
parent_id
required 		The ID of folder where this file should be uploaded
Type: string
content_created_at The time this file was created on the user’s machine. See here for more details.
Type: timestamp
content_modified_at The time this file was last modified on the user’s machine. See here for more details.
Type: timestamp

Returns

A full file object is returned inside of a collection if the ID is valid and if the update is successful. An error is thrown when a name collision occurs.

Method

POST https://upload.box.com/api/2.0/files/content

Example Request

curl https://upload.box.com/api/2.0/files/content \
-H "Authorization: Bearer ACCESS_TOKEN" \
-F filename=@FILE_NAME \
-F parent_id=PARENT_FOLDER_ID

Example Response

{
    "total_count": 1,
    "entries": [
        {
            "type": "file",
            "id": "5000948880",
            "sequence_id": "3",
            "etag": "3",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
            "name": "tigers.jpeg",
            "description": "a picture of tigers",
            "size": 629644,
            "path_collection": {
                "total_count": 2,
                "entries": [
                    {
                        "type": "folder",
                        "id": "0",
                        "sequence_id": null,
                        "etag": null,
                        "name": "All Files"
                    },
                    {
                        "type": "folder",
                        "id": "11446498",
                        "sequence_id": "1",
                        "etag": "1",
                        "name": "Pictures"
                    }
                ]
            },
            "created_at": "2012-12-12T10:55:30-08:00",
            "modified_at": "2012-12-12T11:04:26-08:00",
            "trashed_at": null,
            "purged_at": null,
            "content_created_at": "2013-02-04T16:57:52-08:00",
            "content_modified_at": "2013-02-04T16:57:52-08:00",
            "created_by": {
                "type": "user",
                "id": "17738362",
                "name": "sean rose",
                "login": "sean@box.com"
            },
            "modified_by": {
                "type": "user",
                "id": "17738362",
                "name": "sean rose",
                "login": "sean@box.com"
            },
            "owned_by": {
                "type": "user",
                "id": "17738362",
                "name": "sean rose",
                "login": "sean@box.com"
            },
            "shared_link": null,
            "parent": {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            },
            "item_status": "active"
        }
    ]
}

Download a File

Retrieves the actual data of the file. An optional version parameter can be set to download a previous version of the file.

URL Parameters

version The ID specific version of this file to download.
Type: string

Returns

If the file is available to be downloaded, the response will be a 302 Found to a URL at dl.boxcloud.com. The dl.boxcloud.com URL is not persistent. Clients will need to follow the redirect in order to actually download the file. The raw data of the file is returned unless the file ID is invalid or the user does not have access to it.

If the file is not ready to be downloaded (i.e. in the case where the file was uploaded immediately before the download request), a response with an HTTP status of 202 Accepted will be returned with a Retry-After header indicating the time in seconds after which the file will be available for the client to download.

Sample Call: For convenience, the sample cURL request includes a -L flag that will automatically follow the redirect to boxcloud.com. To change this behavior, simply remove the -L from the sample call.

Method

GET /files/{file id}/content

Example Request

curl -L https://api.box.com/2.0/files/FILE_ID/content \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

Raw text of a text file I just downloaded

Get Information About a File

Used to retrieve the metadata about a file.

URL Parameters

None are taken

Returns

A full file object is returned if the ID is valid and if the user has access to the file.

Method

GET /files/{file id}

Example Request

curl https://api.box.com/2.0/files/FILE_ID
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "type": "file",
    "id": "5000948880",
    "sequence_id": "3",
    "etag": "3",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "tigers.jpeg",
    "description": "a picture of tigers",
    "size": 629644,
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            }
        ]
    },
    "created_at": "2012-12-12T10:55:30-08:00",
    "modified_at": "2012-12-12T11:04:26-08:00",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
    },
    "item_status": "active"
}

Upload a New Version of a File

Note that uploads are handled through https://upload.box.com. This method is used to upload a new version of an existing file in a user’s account. Similar to regular file uploads, these are performed as multipart form uploads An optional If-Match header can be included to ensure that client only overwrites the file if it knows about the latest version. The filename on Box will remain the same as the previous version. To update the file’s name, use PUT /files/{id}

Supported Filenames: Filenames with characters \ / ” : < > | * ? and filenames with leading or trailing whitespace or periods are not allowed.
Headers
If-Match This is in the ‘etag’ field of the file object.
Type: string
Form Elements
name
required		 The name of the file to be uploaded
Type: string
content_modified_at The time this file was last modified on the user’s machine. See here for more details.
Type: timestamp

Returns

The updated file object will be returned inside of a file collection. Errors may occur due to bad filenames and invalid file IDs.

Method

POST https://upload.box.com/api/2.0/files/{file id}/content

Example Request

curl https://upload.box.com/api/2.0/files/FILE_ID/content \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "If-Match: ETAG_OF_ORIGINAL" \
-F filename=@FILE_NAME

Example Response

{
  "total_count": 1,
  "entries": [
    {
      "type": "file",
      "id": "5000948880",
      "sequence_id": "3",
      "etag": "3",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
      "name": "tigers.jpeg",
      "description": "a picture of tigers",
      "size": 629644,
      "path_collection": {
        "total_count": 2,
        "entries": [
          {
            "type": "folder",
            "id": "0",
            "sequence_id": null,
            "etag": null,
            "name": "All Files"
          },
          {
            "type": "folder",
            "id": "11446498",
            "sequence_id": "1",
            "etag": "1",
            "name": "Pictures"
          }
        ]
      },
      "created_at": "2012-12-12T10:55:30-08:00",
      "modified_at": "2012-12-12T11:04:26-08:00",
      "trashed_at": null,
      "purged_at": null,
      "content_created_at": "2013-02-04T16:57:52-08:00",
      "content_modified_at": "2013-02-04T16:57:52-08:00",
      "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
      },
      "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
      },
      "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
      },
      "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
          "can_download": true,
          "can_preview": true
        }
      },
      "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
      },
      "item_status": "active"
    }
  ]
}

View Versions of a File

If there are previous versions of this file, this method can be used to retrieve metadata about the older versions.

Alert: Versions are only tracked for Box users with premium accounts.

URL Parameters

None are taken

Returns

An array of version objects are returned. If there are no previous versions of this file, then an empty array will be returned.

Method

GET /files/{file id}/versions

Example Request

curl https://api.box.com/2.0/files/FILE_ID/versions \
-H "Authorization: Bearer ACCESS_TOKEN" \

Example Response

{
    "total_count": 1,
    "entries": [
        {
            "type": "file_version",
            "id": "672259576",
            "sha1": "359c6c1ed98081b9a69eb3513b9deced59c957f9",
            "name": "Dragons.js",
            "size": 92556,
            "created_at": "2012-08-20T10:20:30-07:00",
            "modified_at": "2012-11-28T13:14:58-08:00",
            "modified_by": {
                "type": "user",
                "id": "183732129",
                "name": "sean rose",
                "login": "sean+apitest@box.com"
            }
        }
    ]
}

Update a file’s information

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.

Note: Editing of passwords is currently not supported for shared links.

Headers
If-Match This is in the ‘etag’ field of the file object.
Type: string

Request Body Attributes

name The new name for the file
Type: string
description The new description for the file
Type: string
parent The parent folder of this file
Type: object
id The ID of the parent folder
Type: string
shared_link An object representing this item’s shared link and associated permissions
Type: object
access The level of access required for this shared link. Can be open, company, collaborators
Type: string
unshared_at The day that this link should be disabled at. Timestamps are rounded off to the given day.
Type: timestamp
permissions The set of permissions that apply to this link
Type: object
permissions.download Whether this link allows downloads
Type: boolean
permissions.preview Whether this link allows previews
Type: boolean

Returns

A full file object is returned if the ID is valid and if the update is successful.

Method

PUT /files/{file id}

Example Request

curl https://api.box.com/2.0/files/FILE_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name":"new name.jpg"}' \
-X PUT

Example Response

{
    "type": "file",
    "id": "5000948880",
    "sequence_id": "3",
    "etag": "3",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "new name.jpg",
    "description": "a picture of tigers",
    "size": 629644,
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            }
        ]
    },
    "created_at": "2012-12-12T10:55:30-08:00",
    "modified_at": "2012-12-12T11:04:26-08:00",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
    },
    "item_status": "active"
}

Delete a file

Discards a file to the trash. The etag of the file can be included as an ‘If-Match’ header to prevent race conditions.

Trash: Depending on the enterprise settings for this user, the item will either be actually deleted from Box or moved to the trash.
Headers
If-Match The etag of the file. This is in the ‘etag’ field of the file object.
Type: string

Returns

An empty 204 response is sent to confirm deletion of the file. If the If-Match header is sent and fails, a ’412 Precondition Failed’ error is returned.

Method

DELETE /files/{file id}

Example Request

curl https://api.box.com/2.0/files/FILE_ID  \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "If-Match: a_unique_value" \
-X DELETE

Example Response

Copy a File

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

Request Body Attributes
parent
required 		Folder object representing the new location of the file
Type: string
id
required 		The ID of the destination folder
Type: string
name An optional new name for the file
Type: string

Returns

A full file object is returned if the ID is valid and if the update is successful. Errors can be thrown if the destination folder is invalid or if a file-name collision occurs. A 403 will be returned if the intended destination folder is the same, as this will cause a name collision.

Method

POST /files/{file id}/copy

Example Request

curl https://api.box.com/2.0/files/FILE_ID/copy \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"parent": {"id" : FOLDER_ID}}' \
-X POST

Example Response

{
    "type": "file",
    "id": "5000948880",
    "sequence_id": "3",
    "etag": "3",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "tigers.jpeg",
    "description": "a picture of tigers",
    "size": 629644,
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            }
        ]
    },
    "created_at": "2012-12-12T10:55:30-08:00",
    "modified_at": "2012-12-12T11:04:26-08:00",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
    },
    "item_status": "active"
}

Create a Shared Link for a File

Used to create a shared link for this particular file. Please see here for more information on the permissions available for shared links. In order to disable a shared link, send this same type of PUT request with the value of shared_link set to null, i.e. {"shared_link": null}

Note: Editing of passwords is currently not supported for shared links.

Request Body Attributes

  • shared_link
    An object representing this item’s shared link and associated permissions
    Type: object

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

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

      permissions
      The set of permissions that apply to this link
      Type: object

      • can_download
        Whether this link allows downloads. Can only be used with Open and Company
        Type: string

        can_preview
        Whether this link allows previewing. Can only be used with Open and Company
        Type: string

 

Returns

A full file object containing the updated shared link is returned if the ID is valid and if the update is successful.

Method

PUT /files/{file id}

Example Request

curl https://api.box.com/2.0/files/FILE_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"shared_link": {"access": "open"}}' \
-X PUT

Example Response

{
    "type": "file",
    "id": "5000948880",
    "sequence_id": "3",
    "etag": "3",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "tigers.jpeg",
    "description": "a picture of tigers",
    "size": 629644,
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            }
        ]
    },
    "created_at": "2012-12-12T10:55:30-08:00",
    "modified_at": "2012-12-12T11:04:26-08:00",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
    },
    "item_status": "active"
}

View the Comments on a File

Retrieves the comments on a particular file, if any exist.

URL Parameters
None are taken

Returns

A collection of comment objects are returned. If there are no comments on the file, an empty comments array is returned.

Method

GET /files/{file id}/comments

Example Request

curl https://api.box.com/2.0/files/FILE_ID/comments \
-H "Authorization: Bearer ACCESS_TOKEN" \

Example Response

{
    "total_count": 1,
    "entries": [
        {
            "type": "comment",
            "id": "191969",
            "is_reply_comment": false,
            "message": "These tigers are cool!",
            "created_by": {
                "type": "user",
                "id": "17738362",
                "name": "sean rose",
                "login": "sean@box.com"
            },
            "created_at": "2012-12-12T11:25:01-08:00",
            "item": {
                "id": "5000948880",
                "type": "file"
            },
            "modified_at": "2012-12-12T11:25:01-08:00"
        }
    ]
}

Get a Thumbnail for a File

Retrieves a thumbnail, or smaller image representation, of this file. Sizes of 32x32,
64x64, 128x128, and 256x256 can be returned. Currently thumbnails are only available in .png format and will only be generated for image file formats.

URL Parameters
  • min_height
    The minimum height of the thumbnail
    Type: integer

  • min_width
    The minimum width of the thumbnail
    Type: integer

  • max_height
    The maximum height of the thumbnail
    Type: integer

  • min_width
    The maximum width of the thumbnail
    Type: integer

Returns

There are three success cases that your application needs to account for:

If the thumbnail isn’t available yet, a 202 Accepted HTTP status will be returned, including a Location header pointing to a placeholder graphic that can be used until the thumbnail is returned. A Retry-After header will also be returned, indicating the time in seconds after which the thumbnail will be available. Your application should only attempt to get the thumbnail again after Retry-After time.

If Box can’t generate a thumbnail for this file type, a 302 Found response will be returned, redirecting to a placeholder graphic in the requested size for this particular file type, e.g. this for a CSV file).

If the thumbnail is available, a 200 OK response will be returned with the contents of the thumbnail in the body

If there are any bad parameters sent in, a standard 400 Bad Request will be returned.

Method

GET /files/{file id}/thumbnail.extension

Example Request

curl https://api.box.com/2.0/files/FILE_ID/thumbnail.png?min_height=256&min_width=256 \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{a thumbnail image}

Get a Trashed File

Retrieves an item that has been moved to the trash.

URL Parameters
  • None are taken

Returns

The full item will be returned, including information about when the it was moved to the trash.

Errors
  • 404
    The item is no longer in the trash.

Method

GET /files/{file id}/trash

Example Request

curl https://api.box.com/2.0/files/FILE_ID/trash \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "type": "file",
    "id": "5859258256",
    "sequence_id": "2",
    "etag": "2",
    "sha1": "4bd9e98652799fc57cf9423e13629c151152ce6c",
    "name": "Screenshot_1_30_13_6_37_PM.png",
    "description": "",
    "size": 163265,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "1",
                "sequence_id": null,
                "etag": null,
                "name": "Trash"
            }
        ]
    },
    "created_at": "2013-01-30T18:43:56-08:00",
    "modified_at": "2013-01-30T18:44:00-08:00",
    "trashed_at": "2013-02-07T10:49:34-08:00",
    "purged_at": "2013-03-09T10:49:34-08:00",
    "content_created_at": "2013-01-30T18:43:56-08:00",
    "content_modified_at": "2013-01-30T18:44:00-08:00",
    "created_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "shared_link": {
        "url": null,
        "download_url": null,
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "trashed"
}

Restore a Trashed Item

Restores an item that has been moved to the trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. If that parent folder no longer exists or if there is now an item with the same name in that parent folder, the new parent folder and/or new name will need to be included in the request.

Request Body Attributes
  • name
    The new name for this item
    Type: string

  • parent
    The new parent folder for this item
    Type: object

    • id
      The id of the new parent folder
      Type: string

Returns

The full item will be returned with a 201 Created status. By default it is restored to the parent folder it was in before it was trashed.

Errors
  • 403
    The user doesn’t have access to the folder the item is being restored to or the user doesn’t have permission to restore items from the trash

  • 405
    The item is not in the trash

  • 409
    There is an item with the same name in the folder the item is being restored to

Method

POST /files/{file id}

Example Request

curl https://api.box.com/2.0/files/FILE_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name":"non-conflicting-name.jpg"}' \
-X POST

Example Response

{
    "type": "file",
    "id": "5859258256",
    "sequence_id": "3",
    "etag": "3",
    "sha1": "4bd9e98652799fc57cf9423e13629c151152ce6c",
    "name": "Screenshot_1_30_13_6_37_PM.png",
    "description": "",
    "size": 163265,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_at": "2013-01-30T18:43:56-08:00",
    "modified_at": "2013-02-07T10:56:58-08:00",
    "trashed_at": null,
    "purged_at": null,
    "content_created_at": "2013-01-30T18:43:56-08:00",
    "content_modified_at": "2013-02-07T10:56:58-08:00",
    "created_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "shared_link": {
        "url": "https://seanrose.box.com/s/ebgti08mtmhbpb4vlp55",
        "download_url": "https://seanrose.box.com/shared/static/ebgti08mtmhbpb4vlp55.png",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 4,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active"
}

Permanently Delete a Trashed File

Permanently deletes an item that is in the trash. The item will no longer exist in Box. This action cannot be undone.

URL Paremeters
  • None are taken

Returns

An empty 204 No Content response will be returned upon successful deletion

Errors
  • 404
    The item is not in the trash

Method

DELETE /files/{file id}/trash

Example Request

curl https://api.box.com/2.0/files/FILE_ID/trash \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response

Comments

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

Comment Object

Attributes

type
string 		For comments is ‘comment’
id
string 		A unique string identifying this comment
is_reply_comment
boolean 		Whether or not this comment is a reply to another comment
message
string 		The comment text that the user typed
tagged_message
string 		The string representing the comment text with @mentions included. @mention format is @[id:username]. Field is not included by default.
created_by
mini user object 		A mini user object representing the author of the comment
created_at
timestamp 		The time this comment was created
item
object 		The object this comment was placed on
modified_at
timestamp 		The time this comment was last modified

Example Comment

{
    "type": "comment",
    "id": "191969",
    "is_reply_comment": false,
    "message": "These tigers are cool!",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "created_at": "2012-12-12T11:25:01-08:00",
    "item": {
        "id": "5000948880",
        "type": "file"
    },
    "modified_at": "2012-12-12T11:25:01-08:00"
}

Add a Comment to an Item

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

Request Body Attributes
  • item
    required
    The item that this comment will be placed on.
    Type: object

    • type
      required
      The type of the item that this comment will be placed on. Can be file, discussion, or comment
      Type: string

    • id
      required
      The id of the item that this comment will be placed on.
      Type: string

  • message
    required
    The text body of the comment
    Type: string

Returns

The new comment object is returned. Errors may occur if the item id is invalid, the item type is invalid/unsupported, or if the user does not have access to the item being commented on.

Method

POST /comments

Example Request

curl https://api.box.com/2.0/comments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"item": {"type": "file", "id": "FILE_ID"}, "message": "YOUR_MESSAGE"}' \
-X POST

Example Response

{
    "type": "comment",
    "id": "191969",
    "is_reply_comment": false,
    "message": "These tigers are cool!",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "created_at": "2012-12-12T11:25:01-08:00",
    "item": {
        "id": "5000948880",
        "type": "file"
    },
    "modified_at": "2012-12-12T11:25:01-08:00"
}

Get Information About a Comment

Used to retrieve the message and metadata about a specific comment. Information about the user who created the comment is also included.

Request Body Attributes
None are accepted

Returns

A full comment object is returned is the ID is valid and if the user has access to the comment.

Method

GET /comments/{comment id}

Example Request

curl https://api.box.com/2.0/comments/COMMENT_ID
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "type": "comment",
    "id": "191969",
    "is_reply_comment": false,
    "message": "These tigers are cool!",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "created_at": "2012-12-12T11:25:01-08:00",
    "item": {
        "id": "5000948880",
        "type": "file"
    },
    "modified_at": "2012-12-12T11:25:01-08:00"
}

Change a Comment’s Message

Used to update the message of the comment.

Request Body Attributes
message
required 		The desired text for the comment message
Type: string

Returns

The full updated comment object is returned if the ID is valid and if the user has access to the comment.

Method

PUT /comments/{comment id}

Example Request

curl https://api.box.com/2.0/comments/COMMENT_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"message":"My New Message"}' \
-X PUT

Example Response

{
    "type": "comment",
    "id": "191969",
    "is_reply_comment": false,
    "message": "These tigers are cool!",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "created_at": "2012-12-12T11:25:01-08:00",
    "item": {
        "id": "5000948880",
        "type": "file"
    },
    "modified_at": "2012-12-12T11:25:01-08:00"
}

Delete a Comment

Permanently deletes a comment.

URL Parameters
None are taken

Returns

An empty 200 response is returned to confirm deletion of the comment. Errors can be thrown if the ID is invalid or if the user is not authorized to delete this particular comment.

Method

DELETE/comments/{comment id}

Example Request

curl https://api.box.com/2.0/comments/COMMENT_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response

Collaborations

Collaborations are Box’s equivalent of access control lists. They can be used to set and apply permissions for users to folders. Read more about those permissions here.

Collaboration Object

Attributes

type
string 		For collaborations is ‘collaboration’
id
string 		A unique string identifying this collaboration
created_by
mini user object 		The user who created this collaboration
created_at
timestamp 		The time this collaboration was created
modified_at
timestamp 		The time this collaboration was last modified
expires_at
timestamp 		The time this collaboration will expire
status
string 		The status of this collab. Can be accepted, pending, or rejected
accessible_by
mini user object 		The user who the collaboration applies to
role
string 		The level of access this user has. Can be editor, viewer, previewer, uploader, previewer uploader, viewer uploader, or co-owner
acknowledged_at
timestamp 		When the status of this collab was changed
item
mini folder object 		The folder this discussion is related to

Example Collaboration

{
    "type": "collaboration",
    "id": "791293",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "created_at": "2012-12-12T10:54:37-08:00",
    "modified_at": "2012-12-12T11:30:43-08:00",
    "expires_at": null,
    "status": "accepted",
    "accessible_by": {
        "type": "user",
        "id": "18203124",
        "name": "sean",
        "login": "sean+test@box.com"
    },
    "role": "editor",
    "acknowledged_at": "2012-12-12T11:30:43-08:00",
    "item": {
        "type": "folder",
        "id": "11446500",
        "sequence_id": "0",
        "etag": "0",
        "name": "Shared Pictures"
    }
}

Add a Collaboration

Used to add a collaboration for a single user to a folder. Descriptions of the various roles can be found here. Either an email address or a user ID can be used to create the collaboration.

Transferring ownership: To transfer ownership of a folder (as the current owner of the folder), first create a collaboration for the new user with any role. Then update that collaboration with a role of ‘owner’.
Request Body Attributes
item
required 		The item to add the collaboration on
Type: folder object
id
required 		The ID of the item to add the collaboration on
Type: string
type
required 		Must be folder
Type: string
accessible_by
required 		The user who this collaboration applies to
Type: object
id The ID of this user
Type: string
login An email address (does not need to be a Box user)
Type: string
role
required 		The access level of this collaboration (see above for roles)
Type: string

Returns

The new collaboration object is returned. Errors may occur if the IDs are invalid or if the user does not have permissions to create a collaboration.

Method

POST /collaborations

Example Request

curl https://api.box.com/2.0/collaborations \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"item": { "id": "FOLDER_ID", "type": "folder"}, "accessible_by": { "id": "USER_ID"}, "role": "editor"}' \
-X POST

Example Response

{
    "type": "collaboration",
    "id": "791293",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "created_at": "2012-12-12T10:54:37-08:00",
    "modified_at": "2012-12-12T11:30:43-08:00",
    "expires_at": null,
    "status": "accepted",
    "accessible_by": {
        "type": "user",
        "id": "18203124",
        "name": "sean",
        "login": "sean+test@box.com"
    },
    "role": "editor",
    "acknowledged_at": "2012-12-12T11:30:43-08:00",
    "item": {
        "type": "folder",
        "id": "11446500",
        "sequence_id": "0",
        "etag": "0",
        "name": "Shared Pictures"
    }
}

Edit a Collaboration

Used to edit an existing collaboration. Descriptions of the various roles can be found here.

status: This can be set to ‘accepted’ or ‘rejected’ by the ‘accessible_by’ user if the status is ‘pending’

Request Body Attributes
role The access level of this collaboration (see above for roles)
Type: string
status Whether this collaboration has been accepted
Type: string

Returns

The updated collaboration object is returned. Errors may occur if the IDs are invalid or if the user does not have permissions to edit the collaboration.

Method

PUT /collaborations/{id}

Example Request

curl https://api.box.com/2.0/collaborations/COLLAB_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '"role": "viewer" ' \
-X PUT

Example Response

{
    "type": "collaboration",
    "id": "791293",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "created_at": "2012-12-12T10:54:37-08:00",
    "modified_at": "2012-12-12T11:30:43-08:00",
    "expires_at": null,
    "status": "accepted",
    "accessible_by": {
        "type": "user",
        "id": "18203124",
        "name": "sean",
        "login": "sean+test@box.com"
    },
    "role": "viewer",
    "acknowledged_at": "2012-12-12T11:30:43-08:00",
    "item": {
        "type": "folder",
        "id": "11446500",
        "sequence_id": "0",
        "etag": "0",
        "name": "Shared Pictures"
    }
}

Remove a Collaboration

Used to delete a single collaboration.

Request Body Attributes
None are taken

Returns

A blank 200 response is returned if the ID is valid, and the user has permissions to remove the collaboration.

Method

DELETE /collaborations/{id}

Example Request

curl https://api.box.com/2.0/collaborations/COLLAB_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response

Retrieve a Collaboration

Used to get information about a single collaboration. All collaborations for a single folder can be retrieved through GET /folders/{id}/collaborations. A complete list of the user’s pending collaborations can also be retrieved.

URL Parameters
status Can only be pending

Returns

The collaboration object is returned. Errors may occur if the IDs are invalid or if the user does not have permissions to see the collaboration.

Method

GET /collaborations/{id}

Example Request

curl https://api.box.com/2.0/collaborations/COLLAB_ID \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "type": "collaboration",
    "id": "791293",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "created_at": "2012-12-12T10:54:37-08:00",
    "modified_at": "2012-12-12T11:30:43-08:00",
    "expires_at": null,
    "status": "accepted",
    "accessible_by": {
        "type": "user",
        "id": "18203124",
        "name": "sean",
        "login": "sean+test@box.com"
    },
    "role": "editor",
    "acknowledged_at": "2012-12-12T11:30:43-08:00",
    "item": {
        "type": "folder",
        "id": "11446500",
        "sequence_id": "0",
        "etag": "0",
        "name": "Shared Pictures"
    }
}

Get Pending Collaborations

Used to retrieve all pending collaboration invites for this user.

URL Parameters
status
required 		Must be pending

Returns

Pending Collaboration Item: As the user does not yet have access to the item they’re being invited to, the returned item will be null.

A collection of pending collaboration objects are returned. If the user has no pending collaborations, the collection will be empty.

Method

GET /collaborations?status=pending

Example Request

curl https://api.box.com/2.0/collaborations?status=pending \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "total_count": 1,
    "entries": [
        {
            "type": "collaboration",
            "id": "27513888",
            "created_by": {
                "type": "user",
                "id": "11993747",
                "name": "sean",
                "login": "sean@box.com"
            },
            "created_at": "2012-10-17T23:14:42-07:00",
            "modified_at": "2012-10-17T23:14:42-07:00",
            "expires_at": null,
            "status": "Pending",
            "accessible_by": {
                "type": "user",
                "id": "181216415",
                "name": "sean rose",
                "login": "sean+awesome@box.com"
            },
            "role": "Editor",
            "acknowledged_at": null,
            "item": null
        }
    ]
}

Users

The users endpoint is used for managing a user and its content. For an individual user, this includes their own user information and content. For an enterprise admin, this includes both the individual user and any other users in the admin’s enterprise account. Attributes listed in green will not appear in default user requests and must be explicitly asked for using the fields parameter.

User Object

Attributes

type
string 		For users is ‘user’
id
string 		A unique string identifying this user
name
string 		The name of this user
login
string 		The email address this user uses to login
created_at
timestamp 		The time this user was created
modified_at
timestamp 		The time this user was last modified
role
string 		This user’s enterprise role. Can be admin, coadmin, or user
language
ISO 639-1 Language Code 		The language of this user
space_amount
integer 		The user’s total available space amount in bytes
space_used
integer 		The amount of space in use by the user
max_upload_size
integer 		The maximum individual file size in bytes this user can have
tracking_codes
array 		An array of key/value pairs set by the user’s admin
can_see_managed_users
boolean 		Whether this user can see other enterprise users in its contact list
is_sync_enabled
boolean 		Whether or not this user can use Box Sync
status
string 		Can be active or inactive
job_title
string 		The user’s job title
phone
string 		The user’s phone number
address
string 		The user’s address
avatar_url
string 		URL of this user’s avatar image
is_exempt_from_device_limits
boolean 		Whether to exempt this user from Enterprise device limits
is_exempt_from_login_verification
boolean 		Whether or not this user must use two-factor authentication
enterprise
object 		Mini representation of this user’s enterprise, including the ID of its enterprise

Example User

{
    "type": "user",
    "id": "181216415",
    "name": "sean rose",
    "login": "sean+awesome@box.com",
    "created_at": "2012-05-03T21:39:11-07:00",
    "modified_at": "2012-11-14T11:21:32-08:00",
    "role": "admin",
    "language": "en",
    "space_amount": 11345156112,
    "space_used": 1237009912,
    "max_upload_size": 2147483648,
    "tracking_codes": [],
    "can_see_managed_users": true,
    "is_sync_enabled": true,
    "status": "active",
    "job_title": "",
    "phone": "6509241374",
    "address": "",
    "avatar_url": "https://www.box.com/api/avatar/large/181216415",
    "is_exempt_from_device_limits": false,
    "is_exempt_from_login_verification": false,
    "enterprise": {
        "type": "enterprise",
        "id": "17077211",
        "name": "seanrose enterprise"
    }
}

Example Mini User

{
        "type": "user",
        "id": "181216415",
        "name": "sean rose",
        "login": "sean+awesome@box.com"
}

Get the Current User’s Information

Retrieves information about the user who is currently logged in i.e. the user for whom this auth token was generated.

Returns

Returns a single complete user object. An error is returned if a valid auth token is not included in the API request.

Method

GET /users/me

Example Request

curl https://api.box.com/2.0/users/me
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "type": "user",
    "id": "17738362",
    "name": "sean rose",
    "login": "sean@box.com",
    "created_at": "2012-03-26T15:43:07-07:00",
    "modified_at": "2012-12-12T11:34:29-08:00",
    "language": "en",
    "space_amount": 5368709120,
    "space_used": 2377016,
    "max_upload_size": 262144000,
    "status": "active",
    "job_title": "Employee",
    "phone": "5555555555",
    "address": "555 Office Drive",
    "avatar_url": "https://www.box.com/api/avatar/large/17738362"
}

Get All Users in an Enterprise

Returns a list of all users for the Enterprise along with their user_id, public_name, and login.

URL Parameters
filter_term A string used to filter the results to only users starting with the filter_term in either the name or the login
Type: string
limit The number of records to return.
Type: integer (default=100, max=1000)
offset The record at which to start
Type: integer (default=0)

Returns

Returns the list of all users for the Enterprise with their user_id, public_name, and login if the user is an enterprise admin.

Method

GET /users

Example Request

curl https://api.box.com/2.0/users
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "total_count": 1,
    "entries": [
        {
            "type": "user",
            "id": "181216415",
            "name": "sean rose",
            "login": "sean+awesome@box.com",
            "created_at": "2012-05-03T21:39:11-07:00",
            "modified_at": "2012-08-23T14:57:48-07:00",
            "role": "user",
            "language": "en",
            "space_amount": 5368709120,
            "space_used": 52947,
            "max_upload_size": 104857600,
            "tracking_codes": [],
            "see_managed_users": false,
            "sync_enabled": true,
            "status": "active",
            "job_title": "",
            "phone": "5555551374",
            "address": "10 Cloud Way Los Altos CA",
            "avatar_url": "https://api.box.com/api/avatar/large/181216415"
        }
    ]
}

Create an Enterprise User

Used to provision a new user in an enterprise. This method only works for enterprise admins.

Request Body Attributes
login
required 		The email address this user uses to login
Type: string
name
required 		The name of this user
Type: string
role This user’s enterprise role. Can be coadmin or user
Type: string
language The language of this user
Type: ISO 639-1 Language Code
is_sync_enabled Whether or not this user can use Box Sync
Type: boolean
job_title The user’s job title
Type: string
phone The user’s phone number
Type: string
address The user’s address
Type: string
space_amount The user’s total available space amount in bytes
Type: float
tracking_codes An array of key/value pairs set by the user’s admin
Type: array
can_see_managed_users Whether this user can see other enterprise users in its contact list
Type: boolean
status Can be active or inactive
Type: string
is_exempt_from_device_limits Whether to exempt this user from Enterprise device limits
Type: boolean
is_exempt_from_login_verification Whether or not this user must use two-factor authentication
Type: boolean

Returns

Returns the full user object for the newly created user. Errors may be thrown when the fields are invalid or this API call is made from a non-admin account.

Method

POST /users

Example Request

curl https://api.box.com/2.0/users \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"login": "eddard@box.com", "name": "Ned Stark"}' \
-X POST

Example Response

{
    "type": "user",
    "id": "187273718",
    "name": "Ned Stark",
    "login": "eddard@box.com",
    "created_at": "2012-11-15T16:34:28-08:00",
    "modified_at": "2012-11-15T16:34:29-08:00",
    "role": "user",
    "language": "en",
    "space_amount": 5368709120,
    "space_used": 0,
    "max_upload_size": 2147483648,
    "tracking_codes": [],
    "can_see_managed_users": true,
    "is_sync_enabled": true,
    "status": "active",
    "job_title": "",
    "phone": "555-555-5555",
    "address": "555 Box Lane",
    "avatar_url": "https://www.box.com/api/avatar/large/187273718",
    "is_exempt_from_device_limits": false,
    "is_exempt_from_login_verification": false
}

Update a User’s Information

Used to edit the settings and information about a user. This method only works for enterprise admins. To roll a user out of the enterprise (and convert them to a standalone free user), update the special enterprise attribute to be null

URL Parameters
notify Whether the user should receive an email when they are rolled out of an enterprise
Request Body Attributes
enterprise Setting this to null will roll the user out of the enterprise and make them a free user
name The name of this user
Type: string
role This user’s enterprise role. Can be coadmin or user
Type: string
language The language of this user
Type: ISO 639-1 Language Code
is_sync_enabled Whether or not this user can use Box Sync
Type: boolean
job_title The user’s job title
Type: string
phone The user’s phone number
Type: string
address The user’s address
Type: string
space_amount The user’s total available space amount in byte. A value of -1 grants unlimited storage.
Type: float
tracking_codes An array of key/value pairs set by the user’s admin
Type: array
can_see_managed_users Whether this user can see other enterprise users in its contact list
Type: boolean
status Can be active or inactive
Type: string
is_exempt_from_device_limits Whether to exempt this user from Enterprise device limits
Type: boolean
is_exempt_from_login_verification Whether or not this user must use two-factor authentication
Type: boolean
is_password_reset_required Whether or not the user is required to reset password
Type: boolean

Returns

Returns the a full user object for the updated user. Errors may be thrown when the fields are invalid or this API call is made from a non-admin account.

Method

PUT /users/{id}

Example Request

curl https://api.box.com/2.0/users/USER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name": "sean"}' \
-X PUT

Example Response

{
    "type": "user",
    "id": "181216415",
    "name": "sean",
    "login": "sean+awesome@box.com",
    "created_at": "2012-05-03T21:39:11-07:00",
    "modified_at": "2012-12-06T18:17:16-08:00",
    "role": "admin",
    "language": "en",
    "space_amount": 5368709120,
    "space_used": 1237179286,
    "max_upload_size": 2147483648,
    "tracking_codes": [],
    "can_see_managed_users": true,
    "is_sync_enabled": true,
    "status": "active",
    "job_title": "",
    "phone": "6509241374",
    "address": "",
    "avatar_url": "https://www.box.com/api/avatar/large/181216415",
    "is_exempt_from_device_limits": false,
    "is_exempt_from_login_verification": false
}

Delete an Enterprise User

Deletes a user in an enterprise account.

URL Parameters
notify Determines if the destination user should receive email notification of the transfer.
Type: boolean
force Whether or not the user should be deleted even if this user still own files.
Type: boolean

Returns

An empty 200 response is sent to confirm deletion of the user. If the user still has files in their account and the ‘force’ parameter is not sent, an error is returned.

Method

DELETE /users/{user id}

Example Request

curl https://api.box.com/2.0/users/USER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response

Add an Email Alias for a User

Adds a new email alias to the given user’s account.

Request Body Attributes
  • email
    required
    The email address to add to the account as an alias
    Type: string

Returns

Returns the newly created email_alias object. Errors will be thrown if the user_id is not valid or the particular user’s email alias cannot be modified.

Method

POST /users/{user id}/email_aliases

Example Request

curl https://api.box.com/2.0/users/USER_ID/email_aliases \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"email: "dglover2@box.com"}'
-X POST

Example Response

{
  "type":"email_alias",
  "id":"1234",
  "is_confirmed":true,
  "email": "dglover2@box.com"
}

Remove an Email Alias from a User

Removes an email alias from a user.

URL Parameters
  • None are taken

Returns

If the user has permission to remove this email alias, an empty 204 No Content response will be returned to confirm deletion.

Method

DELETE /users/{user id}/email_aliases/{email alias id}

Example Request

curl https://api.box.com/2.0/users/USER_ID/email_aliases/EMAIL_ALIAS_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Example Response

Changing a User’s Primary Login

Used to convert one of the user’s confirmed email aliases into the user’s primary login.

Request Body Attributes
  • login
    required
    The email alias to become the primary email
    Type: string

Returns

If the user_id is valid and the email address is a confirmed email alias, the updated user object will be returned.

Example Request

curl https://api.box.com/2.0/users/USER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"login": "dglover2@box.com"}' ]
-X PUT

Example Response

{
    "type":"user",
    "id":"18180156",
    "name":"Dan Glover",
    "login":"dglover2@box.com",
    "created_at":"2012-09-13T10:19:51-07:00",
    "modified_at":"2012-09-21T10:24:51-07:00",
    "role":"user",
    "language":"en",
    "space_amount":5368709120,
    "space_used":0,
    "max_upload_size":1073741824,
    "tracking_codes":[],
    "see_managed_users":false,
    "sync_enabled":false,
    "status":"active",
    "job_title":"",
    "phone":"",
    "address":"",
    "avatar_url":""
}

Get All Email Aliases for a User

Retrieves all email aliases for this user. The collection of email aliases does not include the primary login for the user; use GET /users/USER_ID to retrieve the login email address.

URL Parameters
  • None are taken

Returns

If the user_id is valid a collection of email aliases will be returned.

Method

GET /users/{user id}/email_aliases

Example Request

curl https://api.box.com/2.0/users/USER_ID/email_aliases \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "total_count": 1,
    "entries": [
        {
            "type": "email_alias",
            "id": "1234",
            "is_confirmed": true,
            "email": "dglover2@box.com"
        },
        {
            "type": "email_alias",
            "id": "1235",
            "is_confirmed": true,
            "email": "dglover3@box.com"
        }
    ]
}

On-Behalf-Of Enterprise User

Used for enterprise administrators to make API calls on behalf of their managed users. To enable this functionality, please contact us with your API key.

Headers
On-Behalf-Of The email address of the managed user
Type: string

Returns

Response codes will vary depending on which API method you use.

Example Request

 curl https://api.box.com/2.0/folders/0?fields=item_collection,name \
-H "Authorization: Bearer ACCESS_TOKEN_OF_THE_ADMIN" \
-H "On-Behalf-Of: mike@box.com"

Example Response

{
 "type": "folder",
    "id": "0",
    "etag": null,
    "name": "All Files",
    "item_collection": {
        "total_count": 4,
        "entries": [
            {
                "type": "folder",
                "id": "494447198",
                "etag": "0",
                "name": "Archive"
            },
            {
                "type": "folder",
                "id": "611745226",
                "etag": "1",
                "name": "Customer Info"
            },
            {
                "type": "folder",
                "id": "329767175",
                "etag": "0",
                "name": "Vendors"
            },
            {
                "type": "folder",
                "id": "632559865",
                "etag": "0",
                "name": "Human Resources"
            }
        ],
        "offset": 0,
        "limit": 100,
        "order": [
            {
                "by": "type",
                "direction": "ASC"
            },
            {
                "by": "name",
                "direction": "ASC"
            }
        ]
    }
}

Move Folder into Another User’s Folder

Moves all of the content from within one user’s folder into a new folder in another user’s account. You can move folders across users as long as the you have administrative permissions. To move everything from the root folder, use “0″ which always represents the root folder of a Box account

folder_id: Currently only moving of the root folder (0) is supported.
Request Body Attributes
owned_by
required 		The user who the folder will be transferred to
Type: object
id
required 		The ID of the user who the folder will be transferred to
Type: string
URL Parameters
notify Determines if the destination user should receive email notification of the transfer.
Type: boolean

Returns

Returns the information for the newly created destination folder.. An error is thrown if you do not have the necessary permissions to move the folder

Method

PUT /users/{user_id}/folders/{folder_id}

Example Request

curl https://api.box.com/2.0/users/USER_ID/folders/FOLDER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"owned_by": {"id": "USER_ID"}}' \
-X PUT

Example Response

{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": "https://www.box.com/shared/static/vspke7y05sb214wjokpk",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "file",
                "id": "5000948880",
                "sequence_id": "3",
                "etag": "3",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
                "name": "tigers.jpeg"
            }
        ],
        "offset": 0,
        "limit": 100
    }
}

Search

Searching a User’s Account

The search endpoint provides a simple way of finding items that are accessible in a given user’s Box account.

Parsing Search Results: We’ll be adding more types of items returned as search results and more filters on search queries, so as you’re parsing the results, be prepared to skip over any types of items your app does not recognize.
URL Parameters
  • query
    required
    The string to search for; can be matched against item names, descriptions, text content of a file, and other fields of the different item types.
    Type: string

    limit
    Number of search results to return
    Type: integer (default=30)

    offset
    The search result at which to start the response
    Type: integer (default=0)

offset: Both limit and offset must be included for either to be used. Offset must be a multiple of limit.

Returns

A collection of search results is returned. If there are no matching search results, the entries array will be empty.

Method

GET /search?query=SEARCH_QUERY

Example Request

curl https://api.box.com/2.0/search?query=football&limit=1&offset=0 \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "total_count": 4,
    "entries": [
        {
            "type": "file",
            "id": "1874102965",
            "sequence_id": "0",
            "etag": "0",
            "sha1": "63a112a4567fb556f5269735102a2f24f2cbea56",
            "name": "football.jpg",
            "description": "",
            "size": 260271,
            "path_collection": {
                "total_count": 1,
                "entries": [
                    {
                        "type": "folder",
                        "id": "0",
                        "sequence_id": null,
                        "etag": null,
                        "name": "All Files"
                    }
                ]
            },
            "created_at": "2012-03-22T18:25:07-07:00",
            "modified_at": "2012-10-25T14:40:05-07:00",
            "created_by": {
                "type": "user",
                "id": "175065494",
                "name": "Andrew Luck",
                "login": "aluck@colts.com"
            },
            "modified_by": {
                "type": "user",
                "id": "175065494",
                "name": "Andrew Luck",
                "login": "aluck@colts.com"
            },
            "owned_by": {
                "type": "user",
                "id": "175065494",
                "name": "Andrew Luck",
                "login": "aluck@colts.com"
            },
            "shared_link": null,
            "parent": {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            "item_status": "active"
        }
    ],
    "offset": 0,
    "limit": 1
}

Shared Items

Shared items are any files or folders that are represented by a shared link. Shared items are different from other API resources in that they don’t necessarily need the user to be authenticated. The actual shared link itself is used along with or instead of a normal auth token. See here for tips on how to use this endpoint.

Get A Shared Item

Used to retrieve the metadata about a shared item when only given a shared link. Because of varying permission levels for shared links, a password may be required to retrieve the shared item. Once the item has been retrieved, you can make API requests against the actual resource (/files/{id} or /folders/{id} as long as the shared link and optional password are in the header.

Headers

BoxApi
required 		See Values below
Type: string
shared_link
required 		The shared link for this item
Type: string
shared_link_password The password for this shared link
Type: string

Returns

A full file or folder object is returned if the shared link is valid and the user has access to it. An error may be returned if the link is invalid, if a password is required, or if the user does not have access to the file.

Method

GET /shared_items

Example Request

curl https://api.box.com/2.0/shared_items
-H "Authorization: Bearer ACCESS_CODE"
-H "BoxApi: shared_link=SHARED_LINK"

Example Response

{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": "https://www.box.com/shared/static/vspke7y05sb214wjokpk",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "file",
                "id": "5000948880",
                "sequence_id": "3",
                "etag": "3",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
                "name": "tigers.jpeg"
            }
        ],
        "offset": 0,
        "limit": 100
    }
}

Events

Used to populate our admin reports, as well as power application-side messaging. When something changes in a user’s Box account, either in folders they own or folders they collaborate on, Box logs an ‘event’ for the user.

Box’s /events endpoint is focused on delivering to you a low latency, highly reliable list of all the events relevant to your Box account. Events are registered against a time-sequenced list we call the stream_position. When you do a GET against /events API and pass in a stream_position we respond to you with the events that happened slightly before that stream position, up to the current stream_position, or the chunk_size, whichever is lesser. Due to timing lag across our multiple datacenters, and our preference of low-latency and insurance to make sure you don’t miss some event, you may receive duplicate events when you call the /events API. You should use the event_id field in each returned event to check for duplicate events and discard ones that you have already processed. You may also receive events that are ‘before’ events that you’ve already received by roughly 5-15 seconds. This is simply due to the variability in when events get recorded, and our preference for delivering events to you as soon as we know about them.

Events will occasionally arrive out of order.   For example a file-upload might show up before the Folder-create event.  You may need to buffer events and apply them in a logical order.

To initialize your client to use the /events endpoint, you should call /events with either stream_position=now or no stream_position parameter set at all. If you send now then you will get exactly zero events, and the latest stream_position. If you do not send in a stream_position, we default to 0, so you will get a list of all the events that we have in our event cache for your account.

Box does not store all events for all time on your account.   We store somewhere between 2 weeks and 2 months of events

You are then expected to call the /events endpoint with ever increasing stream_position values, as given back to you with each response, until you get no events.

A great feature of the /events API is that you can be offline for quite a while, and then find out about all the activity that has happened since the last time you were online.

Box keeps track of a certain set of events and defines them as follows:

Standard Events

ITEM_CREATE A folder or File was created
ITEM_UPLOAD A folder or File was uploaded
COMMENT_CREATE A comment was created on a folder, file, discussion, or other comment
ITEM_DOWNLOAD A file or folder was downloaded
ITEM_PREVIEW A file was previewed
ITEM_MOVE A file or folder was moved
ITEM_COPY A file or folder was copied
TASK_ASSIGNMENT_CREATE A task was assigned
LOCK_CREATE A file was locked
LOCK_DESTROY A file was unlocked
ITEM_TRASH A file or folder was marked as deleted
ITEM_UNDELETE_VIA_TRASH A file or folder was recovered out of the trash
COLLAB_ADD_COLLABORATOR A collaborator was added to a folder
COLLAB_INVITE_COLLABORATOR A collaborator was invited on a folder
ITEM_SYNC A folder was marked for sync
ITEM_UNSYNC A folder was un-marked for sync
ITEM_RENAME A file or folder was renamed
ITEM_SHARED_CREATE A file or folder was enabled for sharing
ITEM_SHARED_UNSHARE A file or folder was disabled for sharing
ITEM_SHARED A folder was shared
TAG_ITEM_CREATE A Tag was added to a file or folder
ADD_LOGIN_ACTIVITY_DEVICE A user is logging in from a device we haven’t seen before
REMOVE_LOGIN_ACTIVITY_DEVICE We invalidated a user session associated with an app
More events?: Want another event about something important to your application? Please contact us and tell us about your use-case. We plan to add other events, but your feedback can help us prioritize which ones we add sooner.

The following events are defined only for the admin_logs stream_type.

Enterprise Events

GROUP_ADD_USER Added user to group
NEW_USER Created user
GROUP_CREATION Created new group
GROUP_DELETION Deleted group
DELETE_USER Deleted user
GROUP_EDITED Edited group
EDIT_USER Edited user
GROUP_ADD_FOLDER Granted folder access
GROUP_REMOVE_USER Removed from group
GROUP_REMOVE_FOLDER Removed folder access
ADD_TRUSTED_DEVICE Added trusted application
ADMIN_LOGIN Admin login
ADD_DEVICE_ASSOCIATION Added device association
FAILED_LOGIN Failed login
LOGIN Login
REMOVE_TRUSTED_DEVICE Removed trusted application
REMOVE_DEVICE_ASSOCIATION Removed device association
TERMS_OF_SERVICE_AGREE Agreed to terms
TERMS_OF_SERVICE_REJECT Rejected terms
COPY Copied
DELETE Deleted
DOWNLOAD Downloaded
EDIT Edited
LOCK Locked
MOVE Moved
PREVIEW Previewed
RENAME Renamed
STORAGE_EXPIRATION Set file auto-delete
UNDELETE Undeleted
UNLOCK Unlocked
UPLOAD Uploaded
SHARE Enabled shared links
UPDATE_SHARE_EXPIRATION Extend shared link expiration
SHARE_EXPIRATION Set shared link expiration
UNSHARE Unshared links
COLLABORATION_ACCEPT Accepted invites
COLLABORATION_ROLE_CHANGE Changed user roles
UPDATE_COLLABORATION_EXPIRATION Extend collaborator expiration
COLLABORATION_REMOVE Removed collaborators
COLLABORATION_INVITE Invited
COLLABORATION_EXPIRATION Set collaborator expiration
ITEM_SYNC Synced folder
ITEM_UNSYNC Un-synced folder

Event Object

Collection Attributes

chunk_size
integer		 The number of event records returned
next_stream_position
integer		 The next position in the event stream that you should request in order to get the next events
Event Attributes
type
string		 For events is ‘event’
event_id
type (sha1)		 The id of the event, used for de-duplication purposes
created_by
type (user)		 The user that performed the action
event_type
type (event)		 One of the above listed event types
session_id
string		 The session of the user that performed the action
source
type (varies)		 The object that was modified. See Object definitions for appropriate object: file, folder, comment, etc. Not all events have a source object.

Example Event

{
    "type": "event",
    "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "recorded_at": "2012-12-12T10:53:48-08:00",
    "event_type": "ITEM_CREATE",
    "session_id": "70090280850c8d2a1933c1",
    "source": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "0",
        "etag": "0",
        "name": "Pictures",
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "description": null,
        "size": 0,
        "created_by": {
            "type": "user",
            "id": "17738362",
            "name": "sean rose",
            "login": "sean@box.com"
        },
        "modified_by": {
            "type": "user",
            "id": "17738362",
            "name": "sean rose",
            "login": "sean@box.com"
        },
        "owned_by": {
            "type": "user",
            "id": "17738362",
            "name": "sean rose",
            "login": "sean@box.com"
        },
        "shared_link": null,
        "parent": {
            "type": "folder",
            "id": "0",
            "sequence_id": null,
            "etag": null,
            "name": "All Files"
        },
        "item_status": "active",
        "synced": false
    }
}

Get Events for a User

Use this to get events for a given user. A chunk of event objects is returned for the user based on the parameters passed in. Parameters indicating how many chunks are left as well as the next stream_position are also returned.

URL Parameters


stream_position The location in the event stream at which you want to start receiving events. Can specify special case ‘now’ to get 0 events and the latest stream position for initialization.
Type: string (default=0)
stream_type Limits the type of events returned
• all: returns everything
• changes: returns tree changes
• sync: returns tree changes only for sync foldersType: string (default=all):
limit Limits the number of events returned
Type: integer (default=100)

Returns

A collection of events is returned. See the above table for descriptions of the event types.

Method

GET /events?stream_position=0

Example Request

curl https://api.box.com/2.0/events \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "chunk_size": 1,
    "next_stream_position": 1348790499819,
    "entries": [
        {
    "type": "event",
    "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "recorded_at": "2012-12-12T10:53:48-08:00",
    "event_type": "ITEM_CREATE",
    "session_id": "70090280850c8d2a1933c1",
    "source": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "0",
        "etag": "0",
        "name": "Pictures",
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "description": null,
        "size": 0,
        "created_by": {
            "type": "user",
            "id": "17738362",
            "name": "sean rose",
            "login": "sean@box.com"
        },
        "modified_by": {
            "type": "user",
            "id": "17738362",
            "name": "sean rose",
            "login": "sean@box.com"
        },
        "owned_by": {
            "type": "user",
            "id": "17738362",
            "name": "sean rose",
            "login": "sean@box.com"
        },
        "shared_link": null,
        "parent": {
            "type": "folder",
            "id": "0",
            "sequence_id": null,
            "etag": null,
            "name": "All Files"
        },
        "item_status": "active",
        "synced": false
    }
}
    ]
}

Get Events in an Enterprise

Retrieves events for all users in an enterprise. Upper and lower bounds as well as filters can be applied to the results. A list of valid values for event_type can be found here.

Requires Admin: This API call will only work with an auth token from an enterprise admin account.
URL Parameters
stream_type
Required		 Must be admin_logs
Type: string
limit Limits the number of events returned
Type: integer (default=100)
offset The item at which to start
Type: integer (default=0)
event_type A comma-separated list of events to filter by
Type: string
created_after A lower bound on the timestamp of the events returned
Type: timestamp
created_before An upper bound on the timestamp of the events returned
Type: timestamp

Method

GET /events?stream_type=admin_logs

Example Request

curl https://api.box.com/2.0/events?stream_type=admin_logs \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "chunk_size": 3,
    "entries": [
        {
            "source": null,
            "created_by": {
                "type": "user",
                "id": "181216415",
                "name": "sean rose",
                "login": "sean+awesome@box.com"
            },
            "created_at": "2012-12-12T10:53:43-08:00",
            "event_id": "28893270",
            "event_type": "ADD_LOGIN_ACTIVITY_DEVICE",
            "ip_address": "67.218.117.3",
            "type": "event",
            "session_id": null
        },
        {
            "source": null,
            "created_by": {
                "type": "user",
                "id": "181216415",
                "name": "sean rose",
                "login": "sean+awesome@box.com"
            },
            "created_at": "2012-12-12T10:53:43-08:00",
            "event_id": "28893272",
            "event_type": "LOGIN",
            "ip_address": "67.218.117.3",
            "type": "event",
            "session_id": null
        },
        {
            "source": {
                "type": "folder",
                "id": "387630341",
                "sequence_id": "0",
                "name": "A BNE"
            },
            "created_by": {
                "type": "user",
                "id": "181216415",
                "name": "sean rose",
                "login": "sean+awesome@box.com"
            },
            "created_at": "2012-12-12T10:53:43-08:00",
            "event_id": "28893354",
            "event_type": "UPLOAD",
            "ip_address": "67.218.117.3",
            "type": "event",
            "session_id": null
        }
    ]
}

Long polling

If you want to have the least latency in your tracking of activity on a Box account, you can use the long poll portion of the /events API. To do so, you need to first call the /events API with an OPTIONS call to retrieve your long poll URL. Next, you will want to make a GET request to the provided URL to begin listening for events. If an event happens within an account you are monitoring, you will receive a message with the value new_change. It’s important to note that this message will not come with any other details, but should serve as a prompt to take further action such as calling the /events endpoint with your last known stream_position. After you receive this message, you will need to repeat this process to begin listening for events again.

If no events occur after you make the GET request to the long poll URL, you will receive a message requesting you to reconnect. When you receive this message, you’ll want to make another OPTIONS call to the /events endpoint and repeat the process.

For a better understanding of the long poll process, please review this short tutorial.

Method

OPTIONS /events

Example Request

curl https://api.box.com/2.0/events \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X OPTIONS

Example Response

{
    "chunk_size":1,
    "entries":[
        {
            "type":"realtime_server",
            "url":"http:\/\/2.realtime.services.box.net\/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all",
            "ttl":"10",
            "max_retries":"10",
            "retry_timeout":610
        }
    ]
}