Content API Basics
The Box Content API gives you access to the content management features you see in our web app and lets you extend them for use in your own app. It strives to be RESTful and is organized around the main resources you’re familiar with from the Box web interface.
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. 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) will be returned in IEEE754 format (the same way doubles are stored in Java), e.g.
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
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).
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, 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.
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 or group admins) 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”.
Please also be aware that we don’t suppress email notifications for comments or task assignments…ever. And all actions will still appear in users updates feed and the audit-logs.
Endpoints that return arrays support
offset as URL parameters.
Limit defines the maximum number of records that will be returned on a page. The number of records is not guaranteed to be the number specified as visibility rules may filter out items. To avoid duplicates being returned we recommend the following logic:
- to retrieve the next page, set offset=offset+limit
- if total count from previous response is >= the new offset, you are done, no need to ask for another page
offset is zero based, defaults for
limit vary by endpoint.
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. If you are curious what might be coming next, or what has been released recently, you’re welcome to watch the Content-API backlog
Please use the box-api tag on StackOverflow for any questions or suggestions.