The Box API gives you access to a set of secure content management features for use in your own app, such as file storage, preview, search, commenting, and metadata. It strives to be RESTful and is organized around the main resources 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.

If you are building custom applications for users with a Box account, you can follow the authentication instructions using OAuth 2.

If you are building custom applications and wish to leverage the Box API without requiring a Box account, you will need to use Box Platform. You can find a tutorial for building with Box Platform here.

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. If the command line isn’t your preference, a great alternative is Postman, an easy-to-use Chrome extension for making HTTP requests. Or you can always use one of our SDKs instead of making direct API calls.

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

All timestamps (both those sent in requests and those returned in responses) should be formatted as shown in our examples. We support RFC 3339 timestamps. The preferred way to pass in a date is by converting the time to UTC such as this: 2013-04-17T09:12:36-00:00.

In cases where timestamps are rounded to a given day, you may omit the time component. So instead of 2013-04-17T13:35:01+05:00 you can use 2013-04-17. If a time (and not just a date) however, is specified in a request then the calendar date in the Pacific timezone at the moment specified is the day that is accepted.

Box supports the subset of dates after the start of the Unix epoch: 1970-01-01T00:00:00+00:00 (00:00:00 UTC on January 1, 1970).

As a note, the timestamp you receive from the Box API is based on the settings in the Admin console. If you are a part of an enterprise, it will be the default user settings set by your admin.

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.

If you have any questions or feedback, please post on the Box developer forum.

If you are making administrative API calls (that is, your application has “Manage an Enterprise” scope, and the user signing in is a co-admin with the correct "Edit settings for your company" permission) then you can suppress both email and webhook notifications by including a Box-Notifications header with the value off. This can be used, for example, for a virus-scanning tool to download copies of everyone’s files in an enterprise, without every collaborator on the file getting an email saying “The Acme-Virus-scanner just downloaded your “Acme exploding tennis balls instructions”. All actions will still appear in users updates feed and the audit-logs.

Notification suppression is available to be turned on for approved applications only. Contact us to explain your application’s use of notification suppression.

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. You can add a comma separated list of origins that can make CORS requests to the API, through the developer console.

A quick tutorial can be found here.

APIs that can return large numbers of objects return the results using a paging mechanism. Some APIs use offset-based paging and some use marker-based paging.

APIs that use offset-based paging use the offset and limit query parameters. The API returns an object that contains the set of results in the entries array, as well as returning the offset, limit, and total_count fields.

To fetch the first set of entries, call the API with offset = 0 and limit = <your-limit>.

To fetch the next set of entries, call the API with offset = <previous-offset> + <previous-limit>. Note that you should increment the offset by the previous limit -- not by the size of the entries array (which may be less than limit). Use the value of limit that is returned in the response object rather than the value you passed in the query parameter.

If <previous-offset> + <previous-limit> >= total_count, then you have retrieved all of the entries and there are no more to fetch. The total number of entries in the entire collection may be less than total_count. Note that the total_count may change between API calls, so always use the most recent value.

Query Parameters:

Response Object:

Offset-based paging is used in the following APIs:

• Get Versions
• Get File's Comments
• Get Folder’s Items
• Get Trashed Items
• Searching for Content
• Get Enterprise Users
• Get Memberships for Group
• Get Memberships for User
• Get Groups for an Enterprise
• Get Collaborations for Group
• Pending Collaborations
• Get Collection Items

APIs that use marker-based paging use the marker and limit query parameters. The API returns an object that contains the set of results in the entries array, as well as returning the next_marker and limit fields.

To fetch the first set of entries, call the API with limit = <your-limit>.

To fetch the next set of entries, call the API with marker = <next_marker> and limit = <your-limit>.

If next_marker is empty, then you have retrieved all of the entries and there are no more to fetch. Note that you have reached the end if the next_marker is not present, equal to null, or equal to "".

With marker-based paging there is no way to determine the total number of entries in the collection except by fetching them all. Applications should not retain the markers long-term, since the internal implementation of the markers may change over time.

Query Parameters:

Response Object:

Marker-based paging is used in the following APIs:

• Get File Collaborations
• Get Enterprise Templates
• Get Webhooks
• Get Enterprise Device Pins

• 2xx - Box received, understood, and accepted a request.
• 3xx - The user agent must take further action in order to complete the request.
• 4xx - An error occurred in handling the request. The most common cause of this error is an invalid parameter.
• 5xx- Box received and accepted the request, but an error occurred in the Box service while handling it.

EXAMPLE ERROR

The following table lists the most common error responses you are likely to see when developing Box applications. This list is not exhaustive; additional errors can occur. If your application handles all of these responses, though, then it's likely to be a robust application that gracefully handles the majority of user interactions and internet issues.

Box recommends that you begin by handling the most generic errors (for example, error codes 401 and 403), and then gradually add handling for more and more specific errors.

Each object has "standard" and "mini" formats, which include a certain set of fields:

• The standard format is returned when you request a specific object (e.g. GET /files/{id}).
• The mini format is returned when the object is part of a set of items (e.g. GET /files/{id}/comments).
• Less-frequently used fields are not included in either the standard or mini format. These are listed in italics in the object definitions.

In addition to the standard and mini formats, you can have the API return a specific set of fields using the fields query parameter. Specify a comma-separated list of the field names (with no spaces after the commas). Only the fields you request are returned, as well as the type and id fields (which are always returned). For example, if you call GET /files/{id}?fields=modified_at,path_collection,name, it will return the type, id, modified_at, path_collection, and name fields.

EXAMPLE REQUEST

EXAMPLE RESPONSE

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

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

If-Match Header Does Not Have Most Current Etag

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

If-None-Match Header Has Most Current Etag

If-None-Match Header Does Not Have Most Current Etag

IF-MATCH SUPPORTED METHODS

IF-NONE-MATCH SUPPORTED METHODS

EXAMPLE REQUEST (with standard OAuth 2.0)

EXAMPLE RESPONSE

RETRY HEADER

Box uses OAuth 2.0 to authenticate connections that use the Box APIs. OAuth 2 is an open protocol for authentication used with web, mobile, and desktop applications. Every use of Box APIs requires authentication so that Box can ensure that only authorized users can interact with Box content. OAuth 2 is the protocol that Box uses for such authentication.

Box uses the standard OAuth 2 three-legged authentication process, which proceeds as follows:

1. The application asks an authentication service to present a login request to a user.
2. After a successful login, the authentication service returns an authorization code to the application.
3. The application exchanges the authorization code for an access token.

The application can then use the access token with API requests to gain access to the user's resources by including the token in an authorization header named access_token.

The Box HTTP APIs provide full access to standard OAuth 2 authentication. You can use API calls to implement authentication for your applications. In addition, Box also provides several SDKs that manage OAuth 2 authentication for you, simplifying the authentication process for applications that are built on the SDKs.

For machine-to-machine use cases, such as applications that use Box services for back-end storage, but which provide their own user-inteface, Box extends OAuth 2 with JSON Web Tokens (JWT). Authentication using JWT enables your application to authenticate itself directly to Box without needing to display any Box user interface elements.

Whether you use plain OAuth 2 authentication and the Box login screen, or OAuth2 with JWT and your own user interface, and whether you use a Box SDK or build your authentication using direct API requests, your application uses the same authentication services used by Box products. You inherit all Box features, including the ability to work with single sign-on systems that support Box.

The HTTP endpoint for Box authentication is:

Following in the format of a Box authorization header:

You must replace <MY_ACCESS_TOKEN> with a valid access token returned to your application by Box.

https://account.box.com/api/oauth2/authorize

This is the URL of the Box login endpoint. To begin the process of authenticating and authorizing an application to work with the Box APIs, send an HTTP request like the following:

This request passes the following parameters:

Using the Authorize URL

Example Response

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

This is the URL of the Box token endpoint, the endpoint that returns access tokens. An access token is a data string that enables Box to verify that a request belongs to an authorized session. In the normal order of operations you will begin by requesting authentication from the Box authorize endpoint and Box will send you an authorization code. You will then send the authorization code to the token endpoint in a request for an access token. You can then use the returned access token to make Box API calls.

To exchange an authorization code for an access token, send a request like the following:

The parameters used in this request are as follows:

Using the Token URL

Example Response

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

This is the URL of the Box revoke endpoint, the endpoint that revokes access tokens, or to put it another way, the endpoint that ends sessions, logging users out.

To revoke an access token, ending the session and loggingthe user out of Box, send a request like the following:

The parameters sent with this request are as follows:

File information describe file objects in Box, with attributes like 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. Italicized attributes are not returned by default and must be retrieved through the fields parameter.

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

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.

The request body uses the "multipart/form-data" format to transmit two "parts". The first part is called "attributes" and contains a JSON object with information about the file, including the name of the file and the ID of the parent folder. The second part contains the contents of the file. (Note that the name of the second "part" is ignored.)

A 201 will be received on successful upload. A file object is returned inside of a collection if the ID is valid and if the update is successful. Additionally, a 409 error is thrown when a name collision occurs.

The request body uses the "multipart/form-data" format to transmit two "parts". The first part is called "attributes" and contains a JSON object with optional information about the file. The second part contains the contents of the file version. (Note that the name of the second "part" is ignored.)

The Pre-flight check API will verify that a file will be accepted by Box before you send all the bytes over the wire. It can be used for both first-time uploads, and uploading new versions of an existing File (on /files/[id]/content). If the call returns a 200, then you can proceed with a standard upload call. Preflight checks verify all permissions as if the file was actually uploaded including:

• Folder upload permission
• File name collisions
• File size caps
• Folder and file name restrictions*
• Folder and account storage quota

A 200 response does not guarantee that your upload call will succeed. In practice, it has been shown to reduce failed uploads by more than 99%. Highly active folders, common filenames, and accounts near their quota limits may get a 200 for the preflight, and then have a real conflict during the actual upload. Error handling is key to making your application behave well for your users. Errors returned are the same as for file uploads.

A 200 is returned if the upload would be successful. An error is thrown when any of the preflight conditions are not met.

To move a file, change the ID of its parent folder. An optional If-Match header can be included to prevent race conditions.

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

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

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.

The original version of the file will not be altered.

A 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 409 will be returned if the intended destination folder is the same, as this will cause a name collision.

To lock and unlock files, you execute a PUT operation on the /files/{file id} endpoint and set or clear the lock properties on the file.

Sizes of 32x32, 64x64, 128x128, and 256x256 can be returned in the .png format and sizes of 32x32, 94x94, 160x160, and 320x320 can be returned in the .jpg format. Thumbnails can be generated for the image and video file formats listed here.

The thumbnail image in the specified size and format.

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 Box is unable to generate a thumbnail for this particular file, a 404 Not Found response will be returned with a code of preview_cannot_be_generated. If there are any bad parameters sent in, a standard 400 Bad Request will be returned.

The URL will expire after 60 seconds and the preview session will expire after 60 minutes.

Returns a file object with the expiring embed link with the url as an attribute on the JSON object.

A response with the "expiring_embed_link" field if the ID is valid and if the user has access to the file. This field is a JSON object with another field called "url". The "url" value is the url to your generated iFrame viewer. The rendering of the file will contain a header bar with the Box logo.

Customizing your Preview Experience via the Get Embed Link Endpoint
Developers can customize their preview experience by adding query parameters to the end of the generated embed URL. By default, all customizations are turned off. To customize your generated embed URL, append the appropriate query parameter to the end of the embed URL as “?[query parameter]=true”

So your final embed URL will look like:
https://app.box.com/preview/expiring_embed/[HASH]?[query_parameter]=true

The query parameters supported by the Get Embed Link endpoint can be found in the table below.

Query Parameters For The Get Embed Link Endpoint

Custom Branding
If you are a Box paid customer, you have the option to change the Box logo in the file Preview to your own custom logo. Please contact your Customer Success Manager to enable custom branding in the platform Preview experience. The logo is inherited from your Enterprise Settings and can be set by following the instructions here.

Enabling Full Screen Capabilities
To enable full screen capabilities for the Box Preview embed, include the parameter allowfullscreen in the HTML body as shown below:

This feature is only available on desktop browsers.

Returns all of the file's collaborations using marker-based paging.

Each collaboration object has details on which user or group has access to the file and with what role.

Returns all of the comments on the file using offset-based paging.

Returns all of the tasks for the file. This API does not support paging -- it always returns all of the tasks.

Returns all of the previous versions of the file using offset-based paging. The results do not include the current version of the file.

The newly promoted file_version object is returned, along with a ‘201 Created’ status

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.

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. The 'mini folder' object will return type, id, sequence_id, etag, and name.

Italicized attributes are not returned by default and must be retrieved through the fields parameter.

The root folder of a Box account is always represented by the ID “0”.

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

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.

Returns all of the items contained in the folder using offset-based paging.

An error is returned if the folder does not exist, or if any of the parameters are invalid. The total_count returned may not match the number of entries when using the enterprise scope, because external folders are excluded from the list of entries.