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.

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. Or you can always use one of our SDKs instead of making direct API calls.

Input/Output Format

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. 1.2318237429383e+31

Date Format

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

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.

Suppressing Notifications

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.

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

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. If you are curious what might be coming next, or what has been released recently, you’re welcome to watch the Content-API backlog

Getting Help

Please use the box-api tag on StackOverflow for any questions or suggestions.

Base URL

https://api.box.com/2.0

Upload URL

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

Resources (Sample)

/folders
/folders/{id}
/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. OAuth2 can be a little tricky to get started with, but we try to make it easier if you use our SDKs. Once you have authenticated a user, include an authorization header containing a valid access_token in every request.

Whether you use a SDK, or you want to implement it yourself, you will leverage the same authentication used by Box products (Sync, Box for iOS, etc.). Because you’re building on the same platform Box builds on, you get all the Enterprise-grade features, like working with every Box customer’s integrated SSO systems.

The standard OAuth endpoints are listed below. See here for a more in-depth tutorial.

Note that OAuth2 calls are not made to the same URL as other API calls. OAuth2 calls go to app.box.com, not api.box.com. That’s because your user isn’t authenticated yet.

OAUTH 2 URL

https://app.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. It is recommended that you create and use an anti-forgery token.
    Type: string

  • scope
    What scope the eventual auth token will have. This field is not required. If not specified the application will get the default scope configured. If your application has different kinds of users that may need different types of scope, then you can provide a comma separated list of scopes, to give some users a lower scope if they sign in from different locations. If you are using a Provision-granted application, you must specify the alias: folder_readwrite to use the auth-code grant.
    Type: string

  • folder_id
    Only required for Provision-grant code-grants. Must be set to the alias app_folder to use the auth-code grant.
    Type: string

Example URL

https://app.box.com/api/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&state=security_token%3DKnhMJatFipTAnM0nHlZA

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,refresh_token, or urn:box:oauth2:grant-type:provision 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. In most cases these are valid for 60 days, or until used.
    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

  • username
    Required only if using urn:box:oauth2:grant-type:provision grant
    Type: string

  • box_device_id
    Optional unique ID of this device. Used for applications that want to support device-pinning.
    Type: string

  • box_device_name
    Optional human readable name for this device.
    Type: string

  • box_refresh_token_expires_at
    A timestamp for when you want the Refresh Token to expire. Must be less than the default 60 days.
    Type: unix timestamp

Example Request

curl https://app.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,
    "restricted_to": [],
    "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
request_id
string
a unique ID for this request helpful for troubleshooting

For examples of most of the known detailed error codes and their accompanying messages, see here.

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
503     unavailable

Example Error

{
    "type":"error",
    "status":403,
    "code":"storage_limit_exceeded",
    "help_url":"",
    "message":"Account storage limit reached",
    "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).

If you do not want the standard or the mini formats to be returned, you can optionally use the fields URL parameter to specify a comma-separated list of the specific fields you’d like returned. If you specify the fields parameter ONLY the fields you request are returned along with the ID and item type.  For example, GET /files/{id}?fields=modified_at,path_collection,name is a valid request, but will only return the modified_path, path_collection, name, id, and item_type. Some fields are not included in the standard format, and can only be retrieved if you request them using the fields URL parameter. We show those parameters in green in the object parameters.

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.

Attributes listed in green will not appear in default folder requests and must be explicitly asked for using the fields parameter.

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.
May be null for some folders such as root or trash.
etag
string
A unique string identifying the version of this folder.
May be null for some folders such as root or trash.
name
string
The name of the folder.
created_at
timestamp
The time the folder was created.
May be null for some folders such as root or trash.
modified_at
timestamp
The time the folder or its contents were last modified.
May be null for some folders such as root or trash.
description
string
The description of the folder.
size
integer
The folder size in bytes. Be careful parsing this integer, it can easily go into EE notation: see IEEE754 format.
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.
trashed_at
timestamp
The time the folder or its contents were put in the trash.
May be null for some folders such as root or trash.
purged_at
timestamp
The time the folder or its contents were purged from the trash.
May be null for some folders such as root or trash.
content_created_at
timestamp
The time the folder or its contents were originally created (according to the uploader).
May be null for some folders such as root or trash.
content_modified_at
timestamp
The time the folder or its contents were last modified (according to the uploader).
May be null for some folders such as root or trash.
owned_by
mini user object
The user who owns this folder.
shared_link
object
The shared link for this folder. Null if not set.
folder_upload_email
object
The upload email address for this folder. Null if not set.
parent
mini folder object
The folder that contains this one.
May be null for folders such as root, trash and child folders whose parent is inaccessible.
item_status
string
Whether this item is deleted or not.
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.
has_collaborations
boolean
Whether this folder has any collaborators.
permissions
object
The permissions that the current user has on this folder. The keys are can_download, can_upload, can_rename, can_delete, can_share, can_invite_collaborator, and can_set_share_access. Each value is a boolean.
tags
array of strings
All tags applied to this folder.

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": 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
        }
    },
    "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
    },
    "tags": [
        "approved",
        "ready to publish"
    ]
}

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

Supported Foldernames: Box only supports folder names of 255 characters or less. Names that will not be supported are those that contain non-printable ascii, / or \, names with leading or trailing spaces, and the special names “.” and “..”.

 

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": 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
        }
    },
    "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": 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
        }
    },
    "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
    }
}

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

 

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 "Authorization: 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": 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
        }
    },
    "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

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 409 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": 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
        }
    },
    "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 get default shared link status, set it to an empty access level, i.e. {"shared_link": {}}. 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, or null to get default share level.
      Type: string
      unshared_at
      The day that this link should be disabled at. Timestamps are rounded off to the given day. This field can only be set if the user is not a free user.
      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": 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
        }
    },
    "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 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
}

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"
}

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

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"
}

Files

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

Supported Filenames: Box only supports file names of 255 characters or less. Names that will not be supported are those that contain non-printable ascii, / or \, names with leading or trailing spaces, and the special names “.” and “..”.

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 containing this file.
item_status
string
Whether this item is deleted or not.
version_number
string
The version of the file.
comment_count
integer
The number of comments on a file.
permissions
object
The permissions that the current user has on this file. The keys are can_download, can_preview, can_upload, can_comment, can_rename, can_delete, can_share, and can_set_share_access. Each value is a boolean.
tags
array of strings
All tags applied to this file.
lock
object
The lock held on the file.
extension
string
Indicates the suffix, when available, on the file. By default, set to an empty string. The suffix usually indicates the encoding (file format) of the file contents or usage.

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",
    "tags": [
        "cropped",
        "color corrected"
    ],
    "lock": {
        "type": "lock",
        "id": "112429",
        "created_by": {
            "type": "user",
            "id": "18212074",
            "name": "Obi Wan",
            "login": "obiwan@box.com"
        },
        "created_at": "2013-12-04T10:28:36-08:00",
        "expires_at": "2012-12-12T10:55:30-08:00",
        "is_download_prevented": false
    }
}

Example Mini File

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

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"
}

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

 

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"
}

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

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: Box only supports file names of 255 characters or less. Names that will not be supported are those that contain non-printable ascii, / or \, names with trailing spaces, and the special names “.” and “..”.

Headers

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

Form Elements

filename
required
The name of the file to be uploaded
Type: string
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"
        }
    ]
}

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

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}; see Update a file’s information.

Headers
If-Match This is in the ‘etag’ field of the file object.
Type: string
Form Elements
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"
            }
        }
    ]
}

Download an Old Version of a File

See Download a File section

Promote an Old Version of a File

If there are previous versions of this file, this method can be used to promote one of the older versions to the top of the stack. This actually mints a copy of the old version and puts it on the top of the versions stack. The file will have the exact same contents, the same SHA1/etag, and the same name as the original. Other properties such as comments do not get updated to their former values.

Alert: Versions are only tracked for Box users with premium accounts.
Request Body Attributes
type
required
Must be ‘file_version’ for this request
Type: string
id
required
The ID of the file_version that you want to make current
Type: string

Returns

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

Method

POST /files/{file id}/versions/current

Example Request

curl https://api.box.com/2.0/files/FILE_ID/versions/current \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"type": "file_version", "id" : "FILE_VERSION_ID"}' \
-X POST

Example Response

{
    "type": "file_version",
    "id": "871399",
    "sha1": "12039d6dd9a7e6eefc78846802e",
    "name": "Stark Family Lineage.doc",
    "size": 11,
    "created_at": "2013-11-20T13:20:50-08:00",
    "modified_at": "2013-11-20T13:26:48-08:00",
    "modified_by": {
        "type": "user",
        "id": "13711334",
        "name": "Eddard Stark",
        "login": "ned@winterfell.com"
    }
}

Delete an Old Version of a File

Discards a specific file version to the trash.

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}/versions/{version_id}

Example Request

curl https://api.box.com/2.0/files/FILE_ID/versions/VERSION_ID  \
-H "Authorization: Bearer ACCESS_TOKEN" \
-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 409 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"
}

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

  • max_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 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.

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}

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 get default shared link status, set it to an empty access level, i.e. {"shared_link": {}}. 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, or null to get default share level.
      Type: string
      unshared_at
      The day that this link should be disabled at. Timestamps are rounded off to the given day. This field can only be set if the user is not a free user.
      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: boolean
        can_preview
        Whether this link allows previewing. Can only be used with open and company
        Type: boolean

 

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"
}

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"
}

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

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"
}

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 the tasks for a file

Retrieves all of the tasks for given file.

URL Parameters
  • None are taken

Returns

A collection of mini task objects is returned. If there are no tasks, an empty collection will be returned.

Method

GET /files/{id}/tasks

Example Request

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

Example Response

{
    "total_count": 1,
    "entries": [
        {
            "type": "task",
            "id": "1786931",
            "item": {
                "type": "file",
                "id": "7026335894",
                "sequence_id": "6",
                "etag": "6",
                "sha1": "81cc829fb8366fcfc108aa6c5a9bde01a6a10c16",
                "name": "API - Persist On-Behalf-Of information.docx"
            },
            "due_at": null
        }
    ]
}

Comments

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

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 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 or comment
      Type: string

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

  • message
    The text body of the comment
    Type: string

  • tagged_message
    The text body of the comment, including @[userid:Username] somewhere in the message to mention the user, which will send them a direct email, letting them know they’ve been mentioned in a 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, you don’t include either a message or a tagged_message, 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"
}

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"
}

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"
}

Delete a Comment

Permanently deletes a comment.

URL Parameters
None are taken

Returns

An empty 204 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 or groups to folders. Box has the following permissions roles:

Available to all accounts:

  • Editor: An Editor has full read/write access to a folder. Once invited to a folder, they will be able to view, download, upload, edit, delete, copy, move, rename, generate shared links, make comments, assign tasks, create tags, and invite/remove collaborators. They will not be able to delete or move root level folders.
  • Viewer: A Viewer has full read access to a folder. Once invited to a folder, they will be able to preview, download, make comments, and generate shared links.  They will not be able to add tags, invite new collaborators, upload, edit, or delete items in the folder.

Available to Enterprise accounts:

  • Previewer: A Previewer has limited read access. They will only be able to preview the items in the folder using the integrated content viewer. They will not be able to share, upload, edit, or delete any content.
  • Uploader: An Uploader has limited write access. They will only be able to upload and see the names of the items in a folder. They will not able to download or view any content.
  • Previewer-Uploader: This access level is a combination of Previewer and Uploader. A user with this access level will be able to preview files using the integrated content viewer as well as upload items into the folder. They will not be able to download, edit, or share, items in the folder.
  • Viewer-Uploader: This access level is a combination of Viewer and Uploader. A Viewer-Uploader has full read access to a folder and limited write access. They are able to preview, download, add comments, generate shared links, and upload content to the folder. They will not be able to add tags, invite new collaborators, edit, or delete items in the folder.
  • Co-Owner: A Co-Owner has all of the functional read/write access that an Editor does. This permission level has the added ability of being able to manage users in the folder. A Co-Owner can add new collaborators, change access levels of existing collaborators, and remove collaborators. However, they will not be able to manipulate the Owner of the folder or transfer ownership to another user.
  • Owner: An Owner has all of the functional capabilities of a Co-Owner. However, they will be able to manipulate the Owner of the folder or transfer ownership to another user.

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 or group object
The user or group who the collaboration applies to
role
string
The level of access this user or group has. Can be editor, viewer, previewer, uploader, previewer uploader, viewer uploader, co-owner, or owner
acknowledged_at
timestamp
When the status of this collab was changed
item
mini folder object
The folder this collaboration 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 or a single group to a folder. Descriptions of the various roles can be found here. Either an email address, a user ID, or a group id can be used to create the collaboration.

URL Parameters
notify Determines if the user, (or all the users in the group) should receive email notification of the collaboration.
Type: boolean
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 or group who this collaboration applies to
Type: object
id The ID of this user or group
Type: string
type Type of collaborator, must be either user or group
Type: string
login An email address (does not need to be a Box user). Omit if this is a group, or if you include the userID above
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", "type": "user" }, "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 204 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
        }
    ]
}

Events

Used to populate our admin reports, as well as power application-side messaging for our sync client. 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 supports 2 fundamentally different things: Admin Events and User Events

User events are focused on delivering to you a low latency, highly reliable list of all the events relevant to a users 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 across our data centers, and our preference for delivering events to you as soon as we know about them.

Admin events are focused on delivering the full history of an enterprise account, and are useful for loading tools like Splunk, GoodData, or other Analytics tools. Admin events mirror the events available in our admin-logs, and support filtering by events type (User events do not support filtering).

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 a user 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 (User) 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, 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
CHANGE_ADMIN_ROLE When an admin role changes for a user
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
ITEM_ACCEPT_COLLABORATION 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 folders
Type: string (default=all):
limit Limits the number of events returned
Type: integer (default=100 max=800)

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
    }
}
    ]
}

Long polling

To get real-time notification of activity in a Box account, use the long poll feature of the /events API. To do so, first call the /events API with an OPTIONS call to retrieve the long poll URL to use. Next, make a GET request to the provided URL to begin listening for events. If an event occurs within an account you are monitoring, you will receive a response with the value new_change. It’s important to note that this response 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 sending this response, the server will close the connection and you will need to repeat the long poll process to begin listening for events again.

If no events occur for a period of time after you make the GET request to the long poll URL, you will receive a response with the value reconnect. When you receive this response, you’ll make another OPTIONS call to the /events endpoint and repeat the long poll process.

If you receive no events in retry_timeout seconds, you should make another GET request to the real time server (i.e. URL in the response). This might be necessary in case you do not receive the reconnect message in the face of network errors.

If you receive max_retries error when making GET requests to the real time server, you should make another OPTIONS request.

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
        }
    ]
}

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 max=500)
stream_position The starting position for fetching the events. This is used in combination with the limit to determine which events to return to the caller. Use the results from the next_stream_position of your last call to get the next set of events.
Type: string (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&limit=3&stream_position=28893260 \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "chunk_size": 3,
    "next_stream_position": "28893355",
    "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
        }
    ]
}

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 a shared resource doesn’t necessarily have to be in the account of the user accessing it. The actual shared link itself is used along with a normal access token.

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": 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
        }
    },
    "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 for Content

The search endpoint provides a powerful way of finding items that are accessible by a single user or an entire enterprise. Leverage the parameters listed below to generate targeted advanced searches.

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

    scope
    The scope for which you want to limit your search to. Can be user_content for a search limited to only the current user or enterprise_content for the entire enterprise. To enable the enterprise_content scope for an administrator, please contact us.
    Type: string

    file_extensions
    Limit searches to specific file extensions like pdf,png,doc. Requires one or a set of comma delimited file extensions: file_extension_1,file_extension_2,....
    Type: string

    created_at_range
    The date for when the item was created. Specify the date range by using ISO-8601 variables separated by a comma: from_date,to_date. Trailing from_date, and leading ,to_date commas are also accepted, where the current date and earliest known date will be designated respectively.
    Type: ISO 8601 Language Code

    updated_at_range
    The date for when the item was last updated. Specify the date range by using ISO-8601 variables separated by a comma: from_date,to_date.Trailing from_date, and leading ,to_date commas are also accepted, where the current date and earliest known date will be designated respectively.
    Type: ISO 8601 Language Code

    size_range
    Filter by a file size range. Specify the file size range in bytes separated by a comma:lower_bound_size,upper_bound_size, where 1MB is equivalent to 1000000 bytes. Trailing lower_bound_size, and leading ,upper_bound_size commas are also accepted as parameters.
    Type: integer

    owner_user_ids
    Search by item owners. Requires one or a set of comma delimited user_ids: user_id_1,user_id_2,...
    Type: string

    ancestor_folder_ids
    Limit searches to specific parent folders. Requires one or a set of comma delimited folder_ids: folder_id_1,folder_id_2,.... Parent folder results will also include items within subfolders.
    Type: string

    content_types
    Limit searches to specific Box designated content types. Can be name, description, file_content, comments, or tags. Requires one or a set of comma delimited content_types: content_type_1,content_type_2,....
    Type: string

    type
    The type you want to return in your search. Can be file, folder, or web_link.
    Type: string

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

    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=sales&file_extensions=pdf&updated_at_range=2014-05-15T13:35:01-07:00,2014-05-17T13:35:01-07:00 \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "total_count": 1,
    "entries": [
        {
            "type": "file",
            "id": "172245607",
            "sequence_id": "1",
            "etag": "1",
            "sha1": "f89d97c5eea0a68e2cec911s932eca34a52355d2",
            "name": "Box for Sales - Empowering Your Mobile Worker White paper 2pg (External).pdf",
            "description": "This is old and needs to be updated - but general themes still apply",
            "size": 408979,
            "path_collection": {
                "total_count": 2,
                "entries": [
                    {
                        "type": "folder",
                        "id": "0",
                        "sequence_id": null,
                        "etag": null,
                        "name": "All Files"
                    },
                    {
                        "type": "folder",
                        "id": "2150506",
                        "sequence_id": "1",
                        "etag": "1",
                        "name": "Marketing Active Work"
                    }
		 ]
            },
            "created_at": "2014-05-17T12:59:45-07:00",
            "modified_at": "2014-05-17T13:00:20-07:00",
            "trashed_at": null,
            "purged_at": null,
            "content_created_at": "2014-05-17T12:58:58-07:00",
            "content_modified_at": "2014-05-17T12:58:58-07:00",
            "created_by": {
                "type": "user",
                "id": "19551097",
                "name": "Ted Blosser",
                "login": "ted@box.com"
            },
            "modified_by": {
                "type": "user",
                "id": "19551097",
                "name": "Ted Blosser",
                "login": "ted@box.com"
            },
            "owned_by": {
                "type": "user",
                "id": "19551097",
                "name": "Ted Blosser",
                "login": "ted@box.com"
            },
            "shared_link": null,
            "parent": {
                        "type": "folder",
                        "id": "2150506",
                        "sequence_id": "1",
                        "etag": "1",
                        "name": "Marketing Active Work"
            },
            "item_status": "active"
        }
    ],
    "limit": 30,
    "offset": 0
}

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.
timezone
tz Database timezones
The timezone 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 her contact list.
is_sync_enabled
boolean
Whether or not this user can use Box Sync.
is_external_collab_restricted
boolean
Whether this user is allowed to collaborate with users outside her enterprise.
status
string
Can be active, inactive. cannot_delete_edit, or cannot_delete_edit_upload.
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.
my_tags
array of strings
Tags for all files and folders owned by this user.

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",
    "timezone": "Africa/Bujumbura",
    "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"
    },
    "my_tags": [
        "important",
        "needs review"
    ]
}

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"
}

As-User

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

As-User has replaced the previous On-Behalf-Of functionality. As-User is more robust because it is tied to a static user_id instead of a dynamic email address that may change. On-Behalf-Of functionality will continue to be supported, but we recommend migrating to the As-User header.

Headers
As-User The user_id of the 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 "As-User: 10543463" 

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"
            }
        ]
    }
}

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",
            "language": "en",
            "space_amount": 5368709120,
            "space_used": 52947,
            "max_upload_size": 104857600,
            "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
timezone
tz Database timezones
The timezone of this user.
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
timezone
tz Database timezones
The timezone of this user.
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 204 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

Move Folder into Another User’s Folder

Moves all of the owned 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 and the ‘source’ user owns the folders. 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": 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
        }
    },
    "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
    }
}

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"
        }
    ]
}

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

Groups

Groups contain a set of users, and can be used in place of users in some operations, such as collaborations

Supported group names: Box only supports group names of 255 characters or less. Names that will not be supported are the name “none” or a null name.

Group Object

Attributes

type
string
For groups is ‘group’
id
string
Box’s unique string identifying this group
name
string
The name of this group
created_at
timestamp
When this groups was created on Box’s servers
modified_at
timestamp
When this group was last updated on the Box servers

Example Group

{
    "total_count": 1,
    "entries": [
        {
            "type": "group",
            "id": "1786931",
            "name": "friends"
        }
    ],
    "limit": 100,
    "offset": 0
}

Get all Groups

Retrieves all of the groups for given user.

URL Parameters
none are taken

Returns

A collection of mini group objects is returned. If there are no groups, an empty collection will be returned.

Method

GET /groups

Example Request

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

Example Response

{
    "total_count": 1,
    "entries": [
        {
            "type": "group",
            "id": "1786931",
            "name": "friends"
        }
    ],
    "limit": 100,
    "offset": 0
}

Create a Group

Used to create a group.

Request Body Attributes
  • name
    required
    The name of the new group to be created
    Type: object

Returns

A new group object will be returned upon success.

Method

POST /groups

Example Request

curl https://api.box.com/2.0/groups \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name": "family"}' \
-X POST

Example Response

{
    "type": "group",
    "id": "119720",
    "name": "family",
    "created_at": "2013-05-16T15:27:57-07:00",
    "modified_at": "2013-05-16T15:27:57-07:00"
}

Update a Group

Updates a specific group.

Request Body Attributes
  • name
    The name of the group
    Type: string

Returns

The updated group object will be returned upon success.

Method

PUT /groups/{id}

Example Request

curl https://api.box.com/2.0/groups/GROUP_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name": "framily"}' \
-X PUT

Example Response

{
    "type": "group",
    "id": "119720",
    "name": "framily",
    "created_at": "2013-05-16T15:27:57-07:00",
    "modified_at": "2013-05-16T15:27:57-07:00"
}

Delete a Group

Permanently deletes a specific group.

URL Parameters
  • None are taken

Returns

An empty 204 response will be returned upon success.

Method

DELETE /groups/{id}

Example Request

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

Example Response

Get the Membership list for a Group

Retrieves all of the members for a given group.

URL Parameters
  • None are taken

Returns

A collection of group membership objects will be returned upon success.

Method

GET /groups/{id}/memberships

Example Request

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

Example Response

{
    "total_count": 2,
    "entries": [
        {
            "type": "group_membership",
            "id": "1560354",
            "user": {
                "type": "user",
                "id": "13130906",
                "name": "Alice",
                "login": "alice@gmail.com"
            },
            "group": {
                "type": "group",
                "id": "119720",
                "name": "family"
            },
            "role": "member"
        },
        {
            "type": "group_membership",
            "id": "1560356",
            "user": {
                "type": "user",
                "id": "192633962",
                "name": "rabbit",
                "login": "rabbit@gmail.com"
            },
            "group": {
                "type": "group",
                "id": "119720",
                "name": "family"
            },
            "role": "member"
        }
    ],
    "offset": 0,
    "limit": 100
}

Get all Group Memberships for a User

Retrieves all of the group memberships for a given enterprise. Note this is only available to group admins. To get a users groups use the users/me/memberships endpoint.

URL Parameters
  • None are taken

Returns

A collection of group membership objects will be returned upon success.

Method

GET /users/{id}/memberships

Example Request

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

Example Response

{
    "total_count": 1,
    "entries": [
        {
            "type": "group_membership",
            "id": "1560354",
            "user": {
                "type": "user",
                "id": "13130406",
                "name": "Alison Wonderland",
                "login": "alice@gmail.com"
            },
            "group": {
                "type": "group",
                "id": "119720",
                "name": "family"
            },
            "role": "member"
        }
    ],
    "limit": 100,
    "offset": 0
}

Get a Group Membership Entry

Fetches a specific group membership entry.

URL Parameters
  • None are taken

Returns

The specified group_membership object will be returned upon success.

Method

GET /group_memberships/{id}

Example Request

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

Example Response

{
    "type": "group_membership",
    "id": "1560354",
    "user": {
        "type": "user",
        "id": "13130406",
        "name": "Alison Wonderland",
        "login": "alice@gmail.com"
    },
    "group": {
        "type": "group",
        "id": "119720",
        "name": "family"
    },
    "role": "member",
    "created_at": "2013-05-16T15:27:57-07:00",
    "modified_at": "2013-05-16T15:27:57-07:00"
}

Add a Member to a Group

Used to add a member to a Group.

Request Body Attributes
  • user
    required
    The user to assign to a group
    Type: object

    • id
      required
      The ID of the user to add to the group
      Type: string

  • group
    required
    The group this user is to be added to
    Type: object

    • id
      The ID of the group to add the user into.
      Type: string

  • role
    The role of the user in the group. Default is “member” option for “admin”
    Type: string

Returns

A new group membership object will be returned upon success.

Method

POST /group_memberships

Example Request

curl https://api.box.com/2.0/group_memberships \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{ "user": { "id": "1992432"}, "group": { "id": "1992432" } }' \
-X POST

Example Response

{
            "type": "group_membership",
            "id": "1560354",
            "user": {
                "type": "user",
                "id": "13130406",
                "name": "Alison Wonderland",
                "login": "alice@gmail.com"
            },
            "group": {
                "type": "group",
                "id": "119720",
                "name": "family"
            },
            "role": "member"
        }

Update a Group Membership

Used to update a group membership.

Request Body Attributes
  • role
    The role for the user in the group
    Type: string

Returns

A new group membership object will be returned upon success.

Method

PUT /group_memberships/{id}

Example Request

curl https://api.box.com/2.0/group_memberships \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{ "role": "submaster" }' \
-X POST

Example Response

{
    "type": "group_membership",
    "id": "1560354",
    "user": {
        "type": "user",
        "id": "13130406",
        "name": "Alison Wonderland",
        "login": "alice@gmail.com"
    },
    "group": {
        "type": "group",
        "id": "119720",
        "name": "family"
    },
    "role": "submaster",
    "created_at": "2013-05-16T15:27:57-07:00",
    "modified_at": "2013-05-16T15:27:57-07:00"
}

Delete a Group Membership

Deletes a specific group membership.

URL Parameters
  • None are taken

Returns

An empty 204 No Content response will be returned upon success.

Method

DELETE /group_memberships/{id}

Example Request

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

Example Response

Get All Collaborations for a Group

Retrieves all of the group collaborations for a given group. Note this is only available to group admins.

URL Parameters
  • None are taken

Returns

A collection of collaboration objects will be returned upon success.

Method

GET /groups/{id}/collaborations

Example Request

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

Example Response

{
    "total_count": 1,
    "entries": [
        {
            "type": "collaboration",
            "id": "52123184",
            "created_by": {
                "type": "user",
                "id": "13130406",
                "name": "Eddard Stark",
                "login": "ned@winterfell.com"
            },
            "created_at": "2013-11-14T16:16:20-08:00",
            "modified_at": "2013-11-14T16:16:20-08:00",
            "expires_at": null,
            "status": "accepted",
            "accessible_by": {
                "type": "group",
                "id": "160018",
                "name": "Hand of the King inner counsel"
            },
            "role": "viewer",
            "acknowledged_at": "2013-11-14T16:16:20-08:00",
            "item": {
                "type": "folder",
                "id": "541014843",
                "sequence_id": "0",
                "etag": "0",
                "name": "People killed by Ice"
            }
        }
    ],
    "offset": 0,
    "limit": 100
}

Tasks

Task Object

Tasks enabled file-centric workflows in Box. User can create tasks on files and assign them to collaborators on Box. You can read more about tasks in Box here.

Attributes

  • type
    string
    For tasks is task

  • id
    string
    The unique ID of this task

  • item
    mini file object
    The file associated with this task

  • due_at
    timestamp
    The date at which this task is due

  • action
    string
    The action the task assignee will be prompted to do. Must be review

  • message
    string
    A message that will be included with this task

  • task_assignment_collection
    collection
    A collection of mini task_assignment objects associated with this task

  • is_completed
    boolean
    Whether or not this task has been completed

  • created_by
    mini user object
    The user who created this task

  • created_at
    timestamp
    When this task was created

Example Task

{
    "type": "task",
    "id": "1839355",
    "item": {
        "type": "file",
        "id": "7287087200",
        "sequence_id": "0",
        "etag": "0",
        "sha1": "0bbd79a105c504f99573e3799756debba4c760cd",
        "name": "box-logo.png"
    },
    "due_at": "2014-04-03T11:09:43-07:00",
    "action": "review",
    "message": "REVIEW PLZ K THX",
    "task_assignment_collection": {
        "total_count": 0,
        "entries": []
    },
    "is_completed": false,
    "created_by": {
        "type": "user",
        "id": "11993747",
        "name": "☁ sean ☁",
        "login": "sean@box.com"
    },
    "created_at": "2013-04-03T11:12:54-07:00"
}

Create a Task

Used to create a single task for single user on a single file.

Request Body Attributes
  • item
    required
    The item this task is for
    Type: object
    • type
      required
      The type of the item this task is for (currently only file is supported)
      Type: string
      id
      required
      The ID of the item this task is for
      Type: string
  • action
    The action the task assignee will be prompted to do. Must be review
    Type: string
  • message
    An optional message to include with the task
    Type: string
  • due_at
    The day at which this task is due
    Type: timestamp

Returns

A new task object will be returned upon success.

Method

POST /tasks

Example Request

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

Example Response

{
    "type": "task",
    "id": "1839355",
    "item": {
        "type": "file",
        "id": "7287087200",
        "sequence_id": "0",
        "etag": "0",
        "sha1": "0bbd79a105c504f99573e3799756debba4c760cd",
        "name": "box-logo.png"
    },
    "due_at": "2014-04-03T11:09:43-07:00",
    "action": "review",
    "message": "REVIEW PLZ K THX",
    "task_assignment_collection": {
        "total_count": 0,
        "entries": []
    },
    "is_completed": false,
    "created_by": {
        "type": "user",
        "id": "11993747",
        "name": "☁ sean ☁",
        "login": "sean@box.com"
    },
    "created_at": "2013-04-03T11:12:54-07:00"
}

Get a Task

Fetches a specific task.

URL Parameters
  • None are taken

Returns

The specified task object will be returned upon success.

Method

GET /tasks/{id}

Example Request

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

Example Response

{
    "type": "task",
    "id": "1839355",
    "item": {
        "type": "file",
        "id": "7287087200",
        "sequence_id": "0",
        "etag": "0",
        "sha1": "0bbd79a105c504f99573e3799756debba4c760cd",
        "name": "box-logo.png"
    },
    "due_at": "2014-04-03T11:09:43-07:00",
    "action": "review",
    "message": "REVIEW PLZ K THX",
    "task_assignment_collection": {
        "total_count": 0,
        "entries": []
    },
    "is_completed": false,
    "created_by": {
        "type": "user",
        "id": "11993747",
        "name": "☁ sean ☁",
        "login": "sean@box.com"
    },
    "created_at": "2013-04-03T11:12:54-07:00"
}

Update a Task

Updates a specific task.

Request Body Attributes
  • action
    The action the task assignee will be prompted to do. Can be review
    Type: string
  • message
    An optional message to include with the task
    Type: string
  • due_at
    The day at which this task is due
    Type: timestamp

Returns

The updated task object will be returned upon success.

Method

PUT /tasks/{id}

Example Request

curl https://api.box.com/2.0/tasks/TASK_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"message": "REVIEW PLZ K THX"}' \
-X PUT

Example Response

{
    "type": "task",
    "id": "1839355",
    "item": {
        "type": "file",
        "id": "7287087200",
        "sequence_id": "0",
        "etag": "0",
        "sha1": "0bbd79a105c504f99573e3799756debba4c760cd",
        "name": "box-logo.png"
    },
    "due_at": "2014-04-03T11:09:43-07:00",
    "action": "review",
    "message": "REVIEW PLZ K THX",
    "task_assignment_collection": {
        "total_count": 0,
        "entries": []
    },
    "is_completed": false,
    "created_by": {
        "type": "user",
        "id": "11993747",
        "name": "☁ sean ☁",
        "login": "sean@box.com"
    },
    "created_at": "2013-04-03T11:12:54-07:00"
}

Delete a Task

Permanently deletes a specific task.

URL Parameters
  • None are taken

Returns

An empty 204 response will be returned upon success.

Method

DELETE /tasks/{id}

Example Request

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

Example Response

Get the Assignments for a Task

Retrieves all of the assignments for a given task.

URL Parameters
  • None are taken

Returns

A collection of task assignment mini objects will be returned upon success.

Method

GET /tasks/{id}/assignments

Example Request

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

Example Response

{
    "total_count": 1,
    "entries": [
        {
            "type": "task_assignment",
            "id": "2485961",
            "item": {
                "type": "file",
                "id": "7287087200",
                "sequence_id": "0",
                "etag": "0",
                "sha1": "0bbd79a105c504f99573e3799756debba4c760cd",
                "name": "box-logo.png"
            },
            "assigned_to": {
                "type": "user",
                "id": "193425559",
                "name": "Rhaegar Targaryen",
                "login": "rhaegar@box.com"
            }
        }
    ]
}

Create a Task Assignment

Used to assign a task to a single user. There can be multiple assignments on a given task.

Request Body Attributes
  • task
    required
    The task this assignment is for
    Type: object
    • type
      required
      Must be task
      Type: string
      id
      required
      The ID of the task this assignment is for
      Type: string
  • assign_to
    required
    The user this assignment is for. At least one of id or login is required in this object.
    Type: object
    • id
      The ID of the user this assignment is for.
      Type: string
      login
      The login email address for the user this assignment is for.
      Type: string

Returns

A new task assignment object will be returned upon success.

Method

POST /task_assignments

Example Request

curl https://api.box.com/2.0/task_assignments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{ "task": { "id": "1992432", "type": "task" }, "assign_to": { "id": "1992432" } }' \
-X POST

Example Response

{
    "type": "task_assignment",
    "id": "2698512",
    "item": {
        "type": "file",
        "id": "8018809384",
        "sequence_id": "0",
        "etag": "0",
        "sha1": "7840095ee096ee8297676a138d4e316eabb3ec96",
        "name": "scrumworksToTrello.js"
    },
    "assigned_to": {
        "type": "user",
        "id": "1992432",
        "name": "rhaegar@box.com",
        "login": "rhaegar@box.com"
    },
    "message": null,
    "completed_at": null,
    "assigned_at": "2013-05-10T11:43:41-07:00",
    "reminded_at": null,
    "resolution_state": "incomplete",
    "assigned_by": {
        "type": "user",
        "id": "11993747",
        "name": "☁ sean ☁",
        "login": "sean@box.com"
    }
}

Get a Task Assignment

Fetches a specific task assignment.

URL Parameters
  • None are taken

Returns

The specified task assignment object will be returned upon success.

Method

GET /task_assignments/{id}

Example Request

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

Example Response

{
    "type": "task_assignment",
    "id": "2698512",
    "item": {
        "type": "file",
        "id": "8018809384",
        "sequence_id": "0",
        "etag": "0",
        "sha1": "7840095ee096ee8297676a138d4e316eabb3ec96",
        "name": "scrumworksToTrello.js"
    },
    "assigned_to": {
        "type": "user",
        "id": "1992432",
        "name": "rhaegar@box.com",
        "login": "rhaegar@box.com"
    },
    "message": null,
    "completed_at": null,
    "assigned_at": "2013-05-10T11:43:41-07:00",
    "reminded_at": null,
    "resolution_state": "incomplete",
    "assigned_by": {
        "type": "user",
        "id": "11993747",
        "name": "☁ sean ☁",
        "login": "sean@box.com"
    }
}

Delete a Task Assignment

Deletes a specific task assignment.

URL Parameters
  • None are taken

Returns

An empty 204 No Content response will be returned upon success.

Method

DELETE /task_assignments/{id}

Example Request

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

Example Response

Update a Task Assignment

Used to update a task assignment.

Request Body Attributes
  • message
    A message from the assignee about this task
    Type: string
  • resolution_state
    Can be completed, incomplete, approved, or rejected
    Type: string

Returns

A new task assignment object will be returned upon success.

Method

PUT /task_assignments/{id}

Example Request

curl https://api.box.com/2.0/task_assignments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{ "message": "hello!!!" }' \
-X PUT

Example Response

{
    "type": "task_assignment",
    "id": "2698512",
    "item": {
        "type": "file",
        "id": "8018809384",
        "sequence_id": "0",
        "etag": "0",
        "sha1": "7840095ee096ee8297676a138d4e316eabb3ec96",
        "name": "scrumworksToTrello.js"
    },
    "assigned_to": {
        "type": "user",
        "id": "1992432",
        "name": "rhaegar@box.com",
        "login": "rhaegar@box.com"
    },
    "message": "hello!!!",
    "completed_at": null,
    "assigned_at": "2013-05-10T11:43:41-07:00",
    "reminded_at": null,
    "resolution_state": "incomplete",
    "assigned_by": {
        "type": "user",
        "id": "11993747",
        "name": "☁ sean ☁",
        "login": "sean@box.com"
    }
}