discard

Search results for "{{ search.query }}"

No results found for "{{search.query}}". Ask about it in support.

Overview

The Box Content API gives you access to secure content management and content experience features 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.

 

Box Content API Basics

The Box Content API gives you access to secure content management and content experience features 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.

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

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

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

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

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

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

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

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 with the correct "Edit settings for your company" permission) then you can suppress both email and webhook notifications by including a Box-Notifications header with the value off. This can be used, for example, for a virus-scanning tool to download copies of everyone’s files in an enterprise, without every collaborator on the file getting an email saying “The Acme-Virus-scanner just downloaded your “Acme exploding tennis balls instructions”. All actions will still appear in users updates feed and the audit-logs.

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

User creation, comment, and task assignment notifications can not be suppressed at this time.

Pagination

Endpoints that return collections support limit and offset or marker as URL parameters. Limit defines the maximum number of records that will be returned on a page. The number of records is not guaranteed to be the number specified as visibility rules may filter out items. To avoid duplicates being returned we recommend the following logic:

  1. To retrieve the next page, set offset=offset+limit
  2. If total count from previous response is >= the new offset, you are done, no need to ask for another page

Note that offset is zero based, defaults for limit vary by endpoint.

Getting Help

To get in touch with our API experts directly, please submit a support ticket.

For community support, please use the box-api tag on StackOverflow for any questions or suggestions.

Errors

The Box API communicates errors through standard HTTP status codes with details supplied in JSON objects. Generally the following pattern applies:

 

2xx

Box received, understood, and accepted a request.

3xx

The user agent must take further action in order to complete the request.

4xx

An error occurred in handling the request. The most common cause of this error is an invalid parameter.

5xx

Box received and accepted the request, but an error occurred in the Box service while handling it.

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

Error Code Response

Name
Error

type

string

"error" in error responses.

status

int

The HTTP status of the response.

code

string

The HTTP code of the response.

context_info

object

Additional context information describing the error.

context_info.errors

array

An array of error objects giving context for the error; each object includes reason, name, and message properties.

help_url

string

A URL that links to more information about why the error occurred.

message

string

A human-readable message describing the error.

request_id

string

A unique ID that identifies this request. The ID can be helpful when troubleshooting requests.

EXAMPLE ERROR

{
    "type": "error",
    "status": 409,
    "code": "conflict",
    "context_info": {
        "errors": [
            {
                "reason": "invalid_parameter",
                "name": "group_tag_name",
                "message": "Invalid value 'All Box '. A resource with value 'All Box ' already exists"
            }
        ]
    },
    "help_url": "http://developers.box.com/docs/#errors",
    "message": "Resource with the same name already exists",
    "request_id": "2132632057555f584de87b7"
}

Detailed Error Codes

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

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

status
error_code
message

400

bad_request

400

item_name_invalid

Item name invalid

400

terms_of_service_required

User must accept custom terms of service before action can be taken

400

requested_preview_unavailable

Requested preview unavailable

400

folder_not_empty

Cannot delete – folder not empty

400

invalid_request_parameters

Invalid input parameteres in request

400

user_already_collaborator

User is already a collaborator

400

cannot_make_collaborated_subfolder_private

Cannot move a collaborated subfolder to a private folder unless the new owner is explicitly specified

400

item_name_too_long

Item name too long

400

collaborations_not_available_on_root_folder

Root folder cannot be collaborated

400

sync_item_move_failure

Cannot move a synced item

400

requested_page_out_of_range

Requested representation page out of range

400

cyclical_folder_structure

Folder move creates cyclical folder structure

400

bad_digest

The specified Content-MD5 did not match what we received

400

invalid_collaboration_item

Item type must be specified and set to ‘folder’

400

task_assignee_not_allowed

Assigner does not have sufficient privileges to assign task to assignee

400

invalid_status

You can change the status only if the collaboration is pending

401

unauthorized

Unauthorized

403

forbidden

403

storage_limit_exceeded

Account storage limit reached

403

access_denied_insufficient_permissions

Access denied – insufficient permission

403

access_denied_item_locked

Access denied – item locked

403

file_size_limit_exceeded

File size exceeds the folder owner’s file size limit

403

incorrect_shared_item_password

403

access_from_location_blocked

You’re attempting to log in to Box from a location that has not been approved by your admin. Please talk to your admin to resolve this issue.

404

not_found

404

preview_cannot_be_generated

Preview cannot be generated

404

trashed

Item is trashed

404

not_trashed

Item is not trashed

405

method_not_allowed

Method Not Allowed

409

item_name_in_use

Item with the same name already exists

409

conflict

A resource with this value already exists

409

user_login_already_used

User with the specified login already exists

409

recent_similar_comment

A similar comment has been made recently

412

sync_state_precondition_failed

The resource has been modified. Please retrieve the resource again and retry

412

precondition_failed

The resource has been modified. Please retrieve the resource again and retry

429

rate_limit_exceeded

Request rate limit exceeded, please try again later

500

internal_server_error

Internal Server Error

503

unavailable

Unavailable

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. These fields are listed as italicized in the object definitions.

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

As-User

Used for enterprise administrators to make API calls for their managed users. To use this header, pass in the header As-User: USER_ID to impersonate the user within the enterprise. These API calls require the requests to come from an admin or a co-admin to be successful. To enable this functionality, please contact us with your API key.

 

Note:

Admins can use As-User to impersonate any managed users including co-admins. Co-admins can use As-User to impersonate managed users, but cannot impersonate any admin or co-admin. A 403 Forbidden error will be returned.

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.

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

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}

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.

OAUTH 2 URL

https://api.box.com/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. Note that for this authorize call, you want the user to go to https://account.box.com/api, not api.box.com.

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

required

An HTTPS URI or custom URL scheme where the response will be redirected. Must be https and also be registered within the Box app management console. In development, local http hosts are also accepted as outlined in the tutorial.

Type: uri

state

required

An arbitrary string of your choosing that will be included in the response to your application. It is recommended that you create and include 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.

Type: string

Note that the authorize call is not made to the same URL as other API calls. This call goes to app.box.com/api, not api.box.com. That’s because your user isn’t really calling the API when we show them authentication screens.

EXAMPLE URL

https://account.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 returns access tokens.

grant_type

required

The grant type of this request. Will be authorization_code or refresh_token depending on which is accompanying this request

Type: string

code

An authorization code you retrieved in the first leg of OAuth 2

Type: string

refresh_token

A refresh token retrieved in the final leg of OAuth 2. 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

Required to be configured within your application at box.com/developers/services

Type: uri

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_access_token_expires_at

A timestamp for when you want the Access Token to expire. Must be less than the default 60 minutes

Type: unix timestamp

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://api.box.com/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://api.box.com/oauth2/revoke \
-d 'client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&token=YOUR_TOKEN' \
-X POST

Folder Object

 

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

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

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.

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 folder, 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 will be 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.

can_non_owners_invite

boolean

Whether non-owners can invite collaborators to this folder.

is_externally_owned

boolean

Whether this folder is owned by a user outside of the enterprise

allowed_shared_link_access_levels

string

Access level settings for shared links set by administrator. Can be collaborators, open, or company.

allowed_invitee_roles

string

Folder collaboration collaboration settings allowed by the enterprise administrator.

{
    "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"
    ]
}
{
    "type":"folder",
    "id":"301415432",
    "sequence_id":"0",
    "etag":"0",
    "name":"my first sub-folder"
}

Get Folder's Info

Retrieves the full information 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”.

 
get/folders/FOLDER_ID
No code samples available
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "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
    }
}
 

Returns

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

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

 
get/folders/FOLDER_ID/items

Query Params

fields
string

Attribute(s) to include in the response

limit
integer

The maximum number of items to return in a page. The default is 100 and the max is 1000.

offset
string

The offset at which to begin the response. An offset of value of 0 will start at the beginning of the folder-listing. Note: If there are hidden items in your previous response, your next offset should be = offset + limit, not the # of records you received back. The default is 0.

 

Returns

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

Request

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

Results

{
    "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 Folder

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

 
post/folders

Body JSON

name
string
required

The desired name for the folder

parent
required

The parent folder

id
string
required

Child of parent. The ID of the parent folder

 

Supported Folder Names:

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 trailing spaces, and the special names “.” and “..”.

Returns

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

Request

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

Results

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

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

 
put/folders/FOLDER_ID

Body JSON

If-Match
string

This is in the ‘etag’ field of the folder object.

name
string

The name of the folder.

description
string

The description of the folder.

parent

The parent folder of this file.

id
string

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

shared_link

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

access
string

Child of folder_upload_email. Can be open or collaborators.

unshared_at
string

Child of shared_link. The day that this link should be disabled at. RFC-3339 valid date-timestamps are rounded off to the given day.

permissions

Child of shared_link. The set of permissions that apply to this link.

can_download
boolean

Child of permissions. Whether this link allows downloads.

can_preview
boolean

Child of permissions. Whether this link allows previews.

folder_upload_email

The email-to-upload address for this folder. Set to “null” to disable or set access to "open" to enable.

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.

sync_state
string

Whether Box Sync clients will sync this folder. Values of synced or not_synced can be sent, while partially_synced may also be returned.

tags
array

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.

 

Returns

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

Request

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

Results

{
 "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 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.

 
delete/folders/FOLDER_ID

Body JSON

If-Match
string

This is in the ‘etag’ field of the folder object.

recursive
boolean

Whether to delete this folder if it has items inside of it.

 

Trash:

Depending on the enterprise settings for this user, the item will either be actually deleted from Box or moved to the trash.

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.

Request

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

Results

Copy Folder

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

 
post/folders/FOLDER_ID/copy

Body JSON

parent
required

Object representing the new location of the folder.

id
string
required

Child of parent. The ID of the destination folder.

name
string

An optional new name for the folder.

 

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.

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

Results

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

Get Folder 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.

 
get/folders/FOLDER_ID/collaborations

Query Params

fields
string

Attribute(s) to include in the response

limit
integer

The maximum number of items to return in a page. The default is 100 and the max is 1000.

offset
integer

The item at which to begin the response

 

Returns

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

Request

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

Results

{
    "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 Trashed Items

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.

 
get/folders/trash/items

Query Params

fields
string

Attribute(s) to include in the response

limit
integer

The maximum number of items to return

offset
integer

The item at which to begin the response

 

fields:

‘id’ and ‘type’ are always returned for each item.

Returns

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

Request

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

Results

{
    "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 Trashed Folder

Retrieves an folder that has been moved to the trash.

 
get/folders/FOLDER_ID/trash

Query Params

fields
string

Attribute(s) to include in the response

 

Returns

The full folder will be returned, including information about when the it was moved to the trash. A 404 will be returned if the folder is not in the trash.

Errors

404

The folder is not in the trash

Request

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

Results

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

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

 
delete/folders/FOLDER_ID/trash
 

Returns

An empty 204 No Content response will be returned upon successful deletion. A 404 will be returned if the item is not in the trash.

Request

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

Results

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

 
post/folders/FOLDER_ID

Body JSON

name
string

The new name for this item

parent

The new parent folder for this item

id
string

Child of parent. The id of the new parent folder

 

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

Request

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

Results

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

File Object

 

File information describe file objects in Box, with attributes like who created the file, when it was last modified, and other information. The actual content of the file itself is accessible through the /files/{id}/content endpoint. Italicized attributes are not returned by default and must be retrieved through the fields parameter.

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

type

string

For files is ‘file’.

id

string

Box’s unique string identifying this file.

file_version

object

The version information of the 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 number 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.

is_package

boolean

Whether the file is a package. Used for Mac Packages used by iWorks.

expiring_embed_link

string

An expiring URL for an embedded preview session in an iframe. This URL will expire after 60 seconds and the session will expire after 60 minutes.

{
    "type": "file",
    "id": "5000948880",
    "file_version": {
        "type": "file_version",
        "id": "26261748416",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc "
    },
    "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
    }
}
 
{
    "sequence_id": "0",
    "etag": "d9efb63902768a30c9e6225ebff46d15cde82476",
    "type": "file",
    "id": "2631999573",
    "name":"IMG_1312.JPG"
}

Get File's Info

Used to retrieve the metadata about a file.

 
get/files/FILE_ID

Query Params

fields
string

Attribute(s) to include in the response

 

Returns

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

Request

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

Results

{
    "type": "file",
    "id": "5000948880",
    "file_version": {
        "type": "file_version",
        "id": "26261748416",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "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 File Info

Used to update individual or multiple fields in the file object, including renaming the file, changing its 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 prevent race conditions.

 
put/files/FILE_ID

Body JSON

name
string

The new name for the file.

description
string

The new description for the file.

parent
string

The parent folder of this file.

id
string

Child of parent. The ID of the parent folder.

shared_link

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

access
string

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

unshared_at
string

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

permissions

Child of shared_link. The set of permissions that apply to this link.

download
boolean

Child of permissions. Whether this link allows downloads.

preview
boolean

Child of permissions. Whether this link allows previews.

tags
array

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.

Headers

If-Match
string

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

 

Note:

Editing of passwords is currently not supported for shared links.

Returns

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

Request

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

Results

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

Lock and Unlock

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

 
put/files/FILE_ID

Body JSON

lock
required

The lock object

type
string
required

Child of lock. Can be lock or unlock.

expires_at
string

Child of lock. The time the lock expires.

is_download_prevented
boolean

Child of lock. Whether or not the file can be downloaded while locked.

 

Request

curl https://api.box.com/2.0/files/FILE_ID  \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"lock": { "type": "lock","expires_at": "2015-12-12T10:55:30-08:00","is_download_prevented": false}}' \
-X PUT
curl https://api.box.com/2.0/files/FILE_ID  \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"lock": null}' \
-X PUT

Results

Download File

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

 
get/files/FILE_ID/content

Query Params

Range
string

The range value in bytes. Format should be bytes={start_range}-{end_range}

version
string

The ID specific version of this file to download.

BoxApi
string

The shared link for this item. Format should be shared_link=SHARED_LINK

 

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.

Request

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

Results

Redirected to secured download at dl.boxcloud.com

Preflight Check

 
optionshttps://api.box.com/2.0/files/content

Body JSON

name
string
required

The name of the file to be uploaded

parent

The parent folder of this file.

id
string

Child of parent. The ID of the parent folder.

size
string
required

The size of the file in bytes. Specify 0 for unknown file-sizes

 

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

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

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

Supported File Names:

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

Returns

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

Request

curl https://api.box.com/2.0/files/content \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name": "Wolves owners.ppt", "parent": {"id": "1523432"}, "size": 15243}' \
-X OPTIONS

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

 
posthttps://upload.box.com/api/2.0/files/content

Body JSON

attributes
required

File attributes

name
string
required

Name of the file

parent
required

Folder object being uploaded into

id
string
required

Child of parent. Designates folder_id of parent object. Use 0 for the root folder.

content_created_at
string

See content times for formatting

content_modified_at
string

See content times for formatting

Headers

Content-MD5
string

The SHA1 hash of the file

 

Supported File Names:

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

Returns

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

Note that the file bytes should come after the JSON for best performance.

Request

curl https://upload.box.com/api/2.0/files/content \
  -H "Authorization: Bearer ACCESS_TOKEN" -X POST \
  -F attributes='{"name":"tigers.jpeg", "parent":{"id":"11446498"}}' \
  -F file=@myfile.jpg

Results

{
    "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 File

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

 
delete/files/FILE_ID

Headers

If-Match
string

The etag of the file. This is in the ‘etag’ field of the file object.

 

Trash:

Depending on the enterprise settings for this user, the item will either be actually deleted from Box or moved to the trash.

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.

Request

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

Update File

Uploading a new file version is performed in the same way as uploading a file. 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 prevent race conditions. The filename on Box will remain the same as the previous version. To update the file’s name, use PUT /files/{id}.

 
posthttps://upload.box.com/api/2.0/files/FILE_ID/content

Headers

If-Match
string

This is in the ‘etag’ field of the file object.

 

Note that uploads are handled through https://upload.box.com.

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

Results

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

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

 
get/files/FILE_ID/versions

Query Params

fields
string

Attribute(s) to include in the response

 

Alert:

Versions are only tracked for Box users with premium accounts.

Returns

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

Request

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

Results

{
 "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 Version

 

Use version url parameter referenced in Download a File section

Promote Version

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.

 
post/files/FILE_ID/versions/current

Body JSON

type
string
required

Must be ‘file_version’ for this request

id
string
required

Child of type. The ID of the file_version that you want to make current

 

Alert:

Versions are only tracked for Box users with premium accounts.

Returns

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

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

Results

{
    "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 Old Version

Discards a specific file version to the trash.

 
delete/files/file id/versions/VERSION_ID

Headers

If-Match
string

The etag of the file. This is in the ‘etag’ field of the file object.

 

Trash:

Depending on the enterprise settings for this user, the item will either be actually deleted from Box or moved to the trash.

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.

Request

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

Copy File

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

 
post/files/FILE_ID/copy

Body JSON

parent
required

Folder object representing the new location of the file

id
string
required

Child of parent. The ID of the destination folder

name
string

An optional new name for the file

 

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.

Request

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

Results

{
    "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 Thumbnail

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

 
get/files/FILE_ID/thumbnail.extension

Query Params

min_height
integer

The minimum height of the thumbnail

min_width
integer

The minimum width of the thumbnail

max_height
integer

The maximum height of the thumbnail

max_width
integer

The maximum width of the thumbnail

 

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.

Request

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

Results

Contents of thumbnail

Get Trashed File

Retrieves an item that has been moved to the trash.

 
get/files/FILE_ID/trash
 

Returns

The full item will be returned, including information about when the it was moved to the trash. A 404 will be returned if the item is not in the trash.

Request

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

Results

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

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

 
delete/files/FILE_ID/trash
 

Returns

An empty 204 No Content response will be returned upon successful deletion. A 404 will be returned if the item is not in the trash.

Request

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

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

 
post/files/FILE_ID

Body JSON

name
string

The new name for this item

parent

The new parent folder for this item

id
string

Child of parent. The id of the new parent folder

 

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

404

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

Request

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

Results

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

Get File's Comments

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

 
get/files/FILE_ID/comments

Query Params

fields
string

Attribute(s) to include in the response

 

Returns

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

Request

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

Results

{
    "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 File's Tasks

Retrieves all of the tasks for given file.

 
get/files/FILE_ID/tasks

Query Params

fields
string

Attribute(s) to include in the response

 

Returns

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

Request

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

Results

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

Metadata Object

Metadata allows users and applications to define and store custom data associated with their files/folders. Metadata consists of key:value pairs that belong to files/folders. For example, an important contract may have key:value pairs of "clientNumber":"820183" and "clientName":"bioMedicalCorp".

 

Metadata can be used for many purposes. Enterprises may want to have a better way to organize their digital assets for their marketing teams or developers may want to provide advanced content functionality such as facilitating workflows or approvals. Metadata is also visible in the Box Web Application. To learn more, please visit the help documentation.

Templates

Metadata that belongs to a file/folder is grouped by templates. Templates allow the metadata service to provide a multitude of services, such as pre-defining sets of key:value pairs or schema enforcement on specific fields. For example, a marketingCollateral template may define where and when specific marketing content should be used. You can also see the representation of the template in the Box web application while navigating to a file preview. Currently, metadata associated with folders does not show in the web application.

Each file/folder can have multiple distinct template instances associated with it, such as a marketingCollateral and retentionPolicy template instances. Template instances are also grouped by scopes. Currently, the only scopes support are enterprise and global. Enterprise scopes are defined on a per enterprises basis, whereas global scopes are Box application-wide. Attribute order within template instances is not guaranteed.

Currently, there are four attributes supported by templates: string, enum, float, and date (RFC 3339).

Metadata templates are currently set up through the Box team. Please email metadata@box.com for access.

Global Properties Template

In addition to enterprise scoped templates, every file on Box has access to the global properties template. The Properties template is a bucket of free form key:value string pairs, with no additional schema associated with it. Properties are ideal for scenarios where applications want to write metadata to file objects in a flexible way, without pre-defined template structure.

Properties follow all the conventions of standard templates, except for being located at a different endpoint. All requests made to the properties template must be made to /files/{file_id}/metadata/global/properties.

Object

$template

string

The key of the template. Together with "$parent" and "$scope", this forms a unique identifier for the metadata instance.

$scope

string

The scope of the object. Global and enterprise scopes are currently supported. The Global scope represent the properties template currently, while the enterprise scope pertains to custom template within the enterprise. The id of the enterprise will be appended to the enterprise scope in this format: {scope}_{ENTERPRISE_ID}

$parent

string

The object ID the metadata object belongs to. Currently, both file and folder objects are supported. Updating metadata does not directly affect the parent object, such as changing the modified_at field for a file/folder.

$version

integer

The version of the object. Starts at 0 and increases every time a user-defined property is modified.

$id

string

36 character UUID to identify the metadata object.

$type

string

A unique identifier for the "type" of this instance. This is an internal system property and should not be used by a client application.

$typeVersion

integer

The last-known version of the template of the object. This is an internal system property and should not be used by a client application.

key(s)

string

Custom value(s) defined by the template. These values also have a corresponding display name that are viewable in applications like the Box web application. The total char limit for a template instance can not exceed 16384 char. Since the $ char is reserved for metadata service keys, custom values can not be prefixed with the $ char.

Metadata Templates

 

Templates

Metadata that belongs to a file is grouped by templates. Templates allow the metadata service to provide a multitude of services, such as pre-defining sets of key:value pairs or schema enforcement on specific fields. For example, a marketingCollateral template may define where and when specific marketing content should be used. You can also see the representation of the template in the Box web application while navigating to a file preview. Currently, metadata associated with folders does not show in the Box web application.

Each file can have multiple distinct template instances associated with it, such as a marketingCollateral and retentionPolicy template instances. Template instances are also grouped by scopes. Currently, the only scopes support are enterprise and global. Enterprise scopes are defined on a per enterprises basis, whereas global scopes are Box application-wide. Attribute order within template instances is not guaranteed.

Currently, there are four attributes supported by templates: string, enum, float, and date (RFC 3339).

Metadata templates can be set up in the Admin Console.

Template Object

template

string

A unique identifier for the template. The identifier must be unique across the scope of the enterprise to which the metadata template is being applied. The character limit is 64 and is validated by this regex: ^[a-zA-Z][-a-zA-Z0-9]*$

scope

string

The scope of the object. Global and enterprise scopes are currently supported. The Global scope represent the properties template currently, while the enterprise scope pertains to custom template within the enterprise. The id of the enterprise will be appended to the enterprise scope in this format: {scope}_{ENTERPRISE_ID}

displayName

string

The display name of the template. The character limit is 4096.

hidden

boolean

Whether this template is hidden in the UI

fields

Collection
Template Field objects

The ordered set of key:value pairs for the template.

Template Fields Object

type

string

The data type of the field's value. Currently, there are four attributes supported by templates: "string", "enum", "float", and "date" (RFC 3339).

key

string

A unique identifier for the field. The identifier must be unique within the template to which it belongs. The character limit is 256. All characters are allowed.

displayName

string

The display name of the field. The character limit is 4096. All characters are allowed.

description

string

A description of the field. The character limit is 4096. All characters are allowed.

hidden

boolean

Whether this template is hidden in the UI

options

array of strings

For type "enum", a list of all possible values.

key

string

Child of options. For type "enum", one of the potential values. The character limit is 4096.

Global Properties Template

In addition to enterprise scoped templates, every file on Box has access to the global properties template. The Properties template is a bucket of free form key:value string pairs, with no additional schema associated with it. Properties are ideal for scenarios where applications want to write metadata to file objects in a flexible way, without pre-defined template structure.

Properties follow all the conventions of standard templates, except for being located at a different endpoint. All requests made to the properties template must be made to /files/{file_id}/metadata/global/properties.

Create Metadata Template

Used to create a new metadata template with the specified schema.

 
post/metadata_templates/schema

Body JSON

scope
string
required

The scope of the object. Only the enterprise scope is currently supported.

templateKey
string

A unique identifier for the template. The identifier must be unique across the scope of the enterprise to which the metadata template is being applied to. Defaults to a string derived from the displayName if no value is provided.

displayName
string
required

Child of fields. The display name of the field.

hidden
boolean

Whether this template is hidden in the UI. Defaults to false.

fields
array

The ordered set of key:value pairs for the template.

type
string
required

Child of fields. The data type of the field's value. Currently, there are four attributes supported by templates: string, enum, float, and date (RFC 3339).

key
string
required

Child of options. For type "enum", one of the potential values.

options
array

Child of fields. For type "enum", a list of all possible values.

 

Template Delete Not Supported

Once created, a template cannot be deleted. In order to hide the template from the UI, set the "hidden" flag to true. The template will still appear in the API.

Available in Beta

As with any Beta, you may encounter issues with functionality. Box reserves the right to make changes which may improve, impair, add or remove functionality with these APIs.
If you would like to provide any feedback, please email metadata-feedback@box.com. We would love to hear from you.

Returns

The schema representing the metadata template created.

Errors

400

Request body contains invalid metadata schema.

403

Request body contains a scope that the user is not allowed to create a template for.

Request

curl https://api.box.com/2.0/metadata_templates/schema \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "templateKey": "customer",
  "scope": "enterprise",
  "displayName": "Customer",
  "fields": [
    {
      "type": "string",
      "key": "customerTeam",
      "displayName": "Customer team"
    },
    {
      "type": "string",
      "key": "category",
      "displayName": "Category"
    },
    {
      "type": "string",
      "key": "brand",
      "displayName": "Brand"
    },
    {
      "type": "enum",
      "key": "fy",
      "displayName": "FY",
      "options": [
        {"key": "FY11"},
        {"key": "FY12"},
        {"key": "FY13"},
        {"key": "FY14"},
        {"key": "FY15"}
    ]},
    {
      "type": "enum",
      "key": "qtr",
      "displayName": "Qtr",
      "options": [
        {"key": "First"},
        {"key": "Second"},
        {"key": "Third"},
        {"key": "Fourth"}
    ]}
  ]}' \
-X POST

Results

{
    "templateKey": "customer",
    "scope": "enterprise_490685",
    "displayName": "Customer",
    "fields": [
        {
            "type": "string",
            "key": "customerTeam",
            "displayName": "Customer team",
            "hidden": false
        },
        {
            "type": "string",
            "key": "category",
            "displayName": "Category",
            "hidden": false
        },
        {
            "type": "string",
            "key": "brand",
            "displayName": "Brand",
            "hidden": false
        },
        {
            "type": "enum",
            "key": "fy",
            "displayName": "FY",
            "options": [
                {
                    "key": "FY11"
                },
                {
                    "key": "FY12"
                },
                {
                    "key": "FY13"
                },
                {
                    "key": "FY14"
                },
                {
                    "key": "FY15"
                }
            ],
            "hidden": false
        },
        {
            "type": "enum",
            "key": "qtr",
            "displayName": "Qtr",
            "options": [
                {
                    "key": "First"
                },
                {
                    "key": "Second"
                },
                {
                    "key": "Third"
                },
                {
                    "key": "Fourth"
                }
            ],
            "hidden": false
        }
    ]
}
{
    "type": "error",
    "status": 400,
    "code": "bad_request",
    "help_url": "http://developers.box.com/docs/#errors",
    "message": "\"displayName\" is required and not set",
    "request_id": "616776114571858dc4ab8f"
}
{
    "type": "error",
    "status": 403,
    "code": "forbidden",
    "help_url": "http://developers.box.com/docs/#errors",
    "message": "Forbidden",
    "request_id": "616776114571858dc4ab8f"
}

Get Metadata Template

Used to retrieve the schema for a given metadata template.

 
get/metadata_templates/SCOPE/TEMPLATE/schema
 

RETURNS

The schema representing the metadata template queried

Request

curl https://api.box.com/2.0/metadata_templates/enterprise/productInfo/schema \
-H "Authorization: Bearer ACCESS_TOKEN"

Results

{
    "templateKey": "productInfo",
    "scope": "enterprise_12345",
    "displayName": "Product Info",
    "hidden": false,
    "fields": [
        {
            "type": "float",
            "key": "skuNumber",
            "displayName": "SKU Number",
            "hidden": false
        },
        {
            "type": "string",
            "key": "description",
            "displayName": "Description",
            "hidden": false
        },
        {
            "type": "enum",
            "key": "department",
            "displayName": "Department",
            "hidden": false,
            "options": [
                {
                    "key": "Beauty"
                },
                {
                    "key": "Shoes"
                },
                {
                    "key": "Accessories"
                },
                {
                    "key": "Clothing"
                },
                {
                    "key": "Handbags"
                },
                {
                    "key": "Bedding"
                },
                {
                    "key": "Watches"
                }
            ]
        },
        {
            "type": "date",
            "key": "displayDate",
            "displayName": "Display Date",
            "hidden": false
        }
    ]
}
{}

Update Metadata Template

Used to update the schema of an existing template.

 
put/metadata_templates/SCOPE/TEMPLATE/schema

Body JSON

op
string
required

The operation name. The list of possible operations is detailed below.

data

The data for the operation. Can vary depending on the operation.

fieldKey
string

For operations that affect a specific field, the key of the field to be affected.

fieldKeys
array

For operations that affect multiple fields, the keys of the fields to be affected.

enumOptionKeys
string

For operations that affect multiple enum options, the keys of the enum options to be affected.

 

Only Non-Breaking Changes Supported

This API only supports non-breaking changes (listed below). A non-breaking change is a change that does not affect the values of existing metadata instances. To hide a template or a field from the UI, set the "hidden" flag to true at the template or field level. The template or field will still appear in the API.

Available in Beta

As with any Beta, you may encounter issues with functionality. Box reserves the right to make changes which may improve, impair, add or remove functionality with these APIs.
If you would like to provide any feedback, please email metadata-feedback@box.com. We would love to hear from you.

Possible Template Operations:

  • addEnumOption: Adds an enum option at the end of the enum option list for the specified field
    Params:
    data: JSON object of the enum option to be added
    fieldKey: The key of the field to add the enum option. Must refer to an enum field
    Example: {"op":"addEnumOption","fieldKey":"category","data":{"key":"Technology"}}. This will add a new enum option Technology under the field category.

  • addField: Adds a field at the end of the field list for the template
    Params:
    data: JSON object of the field to be added.
    Example: {"op":"addField","data":{"displayName":"Category","key":"category","hidden":false,"type":"string"}}. This will add a new non-hidden string field with a displayName and key of category.

  • editField: Edits any number of the base properties of a field: displayName, hidden
    Params:
    data: JSON object of the properties to be changed and their new values.
    fieldKey: The key of the field to be edited
    Example: {"op":"editField","fieldKey":"category","data":{"displayName":"Customer Group"}}. This will update the field category to have a new display name of Customer Group.

  • editTemplate: Edits any number of the base properties of a template: displayName, hidden
    Params:
    data: JSON object of the properties to be changed and their new values.
    Example: {"op":"editTemplate","data":{"displayName":"Client"}}. This will update the template to have a new display name of Client.

  • reorderEnumOptions: Reorders the enum option list to match the requested enum option list
    Params:
    fieldKey: The key of the field to reorder enum options. Must refer to an enum field.
    enumOptionKeys: The new list of enum option keys in the requested order
    Example: {"op":"reorderEnumOptions","fieldKey":"category","enumOptionKeys":["option2","option1","option3"]}. This will reorder the enum options for field category to have option2 first, followed by option1, then option3.

  • reorderFields: Reorders the field list to match the requested field list
    Params:
    fieldKeys: The new list of field keys in the requested order
    Example: {"op":"reorderFields","fieldKeys":["field2","field1","field3"]}. This will reorder the fields for the template to have field2 first, followed by field1, then field3.

Returns

The schema representing the updated metadata template.

Error code

400

Request body contains invalid metadata schema.

403

Request body contains a scope that the user is not allowed to create templates for.

404

Requested template is not found.

Request

curl https://api.box.com/2.0/metadata_templates/enterprise/customer/schema \
-H "Authorization: Bearer ACCESS_TOKEN"
-H "Content-Type: application/json" \
-d '[{"op":"editField","fieldKey":"category","data":{"displayName":"Customer Group"}}]' \
-X PUT

Results

{
    "templateKey": "customer",
    "scope": "enterprise_490685",
    "displayName": "Customer",
    "fields": [
        {
            "type": "string",
            "key": "customerTeam",
            "displayName": "Customer team",
            "hidden": false
        },
        {
            "type": "string",
            "key": "category",
            "displayName": "Customer Group",
            "hidden": false
        },
        {
            "type": "string",
            "key": "brand",
            "displayName": "Brand",
            "hidden": false
        },
        {
            "type": "enum",
            "key": "fy",
            "displayName": "FY",
            "options": [
                {
                    "key": "FY11"
                },
                {
                    "key": "FY12"
                },
                {
                    "key": "FY13"
                },
                {
                    "key": "FY14"
                },
                {
                    "key": "FY15"
                }
            ],
            "hidden": false
        },
        {
            "type": "enum",
            "key": "qtr",
            "displayName": "Qtr",
            "options": [
                {
                    "key": "First"
                },
                {
                    "key": "Second"
                },
                {
                    "key": "Third"
                },
                {
                    "key": "Fourth"
                }
            ],
            "hidden": false
        }
    ]
}
{
    "type": "error",
    "status": 400,
    "code": "bad_request",
    "help_url": "http://developers.box.com/docs/#errors",
    "message": "\"displayName\" is required and not set",
    "request_id": "616776114571858dc4ab8f"
}
{
    "type": "error",
    "status": 403,
    "code": "forbidden",
    "help_url": "http://developers.box.com/docs/#errors",
    "message": "Forbidden",
    "request_id": "616776114571858dc4ab8f"
}

Get Enterprise Metadata

Used to retrieve all metadata templates within a user's enterprise. Currently only the enterprise scope is supported.

 
get/metadata_templates/SCOPE
 

Returns

All the templates within an enterprise and their corresponding schema

Request

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

Results

{
    "limit": 100,
    "entries": [
        {
            "templateKey": "documentFlow",
            "scope": "enterprise_12345",
            "displayName": "Document Flow",
            "hidden": false,
            "fields": [
                {
                    "type": "string",
                    "key": "currentDocumentStage",
                    "displayName": "Current Document Stage",
                    "hidden": false,
                    "description": "What stage in the process the document is in"
                },
                {
                    "type": "string",
                    "key": "needsApprovalFrom",
                    "displayName": "Needs Approval From",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "nextDocumentStage",
                    "displayName": "Next Document Stage",
                    "hidden": false,
                    "description": "Next document stage after approval is given"
                },
                {
                    "type": "float",
                    "key": "maximumDaysAllowedInCurrentStage",
                    "displayName": "Maximum Days Allowed In Current Stage",
                    "hidden": false,
                    "description": "Maximum number of days that the document is allowed to be in this stage."
                }
            ]
        },
        {
            "templateKey": "marketingCollateral",
            "scope": "enterprise_12345",
            "displayName": "Marketing Collateral",
            "hidden": false,
            "fields": [
                {
                    "type": "string",
                    "key": "audience1",
                    "displayName": "Audience",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "documentType",
                    "displayName": "Document Type",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "competitiveDocument",
                    "displayName": "Competitive Document",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "status",
                    "displayName": "Status",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "author",
                    "displayName": "Author",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "editor",
                    "displayName": "Editor",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "currentState",
                    "displayName": "Current State",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "previousState",
                    "displayName": "Previous State",
                    "hidden": false
                }
            ]
        },
        {
            "templateKey": "productInfo",
            "scope": "enterprise_12345",
            "displayName": "Product Info",
            "hidden": false,
            "fields": [
                {
                    "type": "float",
                    "key": "skuNumber",
                    "displayName": "SKU Number",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "description",
                    "displayName": "Description",
                    "hidden": false
                },
                {
                    "type": "enum",
                    "key": "department",
                    "displayName": "Department",
                    "hidden": false,
                    "options": [
                        {
                            "key": "Beauty"
                        },
                        {
                            "key": "Shoes"
                        },
                        {
                            "key": "Accessories"
                        },
                        {
                            "key": "Clothing"
                        },
                        {
                            "key": "Handbags"
                        },
                        {
                            "key": "Bedding"
                        },
                        {
                            "key": "Watches"
                        }
                    ]
                },
                {
                    "type": "date",
                    "key": "displayDate",
                    "displayName": "Display Date",
                    "hidden": false
                }
            ]
        }
    ],
    "next_marker": null,
    "prev_marker": null
}

Metadata on Files and Folders

 

Template Instance Object

$template

string

The key of the template. Together with "$parent" and "$scope", this forms a unique identifier for the metadata instance.

$scope

string

The scope of the object. Global and enterprise scopes are currently supported. The Global scope represent the properties template currently, while the enterprise scope pertains to custom template within the enterprise. The id of the enterprise will be appended to the enterprise scope in this format: {scope}_{ENTERPRISE_ID}

$parent

string

The object ID the metadata object belongs to. Currently, both file and folder objects are supported. Updating metadata does not directly affect the parent object, such as changing the modified_at field for a file/folder.

$version

integer

The version of the object. Starts at 0 and increases every time a user-defined property is modified.

$id

string

36 character UUID to identify the metadata object.

$type

string

A unique identifier for the "type" of this instance. This is an internal system property and should not be used by a client application.

$typeVersion

integer

The last-known version of the template of the object. This is an internal system property and should not be used by a client application.

key(s)

string

Custom value(s) defined by the template. These values also have a corresponding display name that are viewable in applications like the Box web application. The total char limit for a template instance can not exceed 16384 char. Since the $ char is reserved for metadata service keys, custom values can not be prefixed with the $ char.

Create Metadata on File

Used to create the metadata template instance for a corresponding Box file. When creating metadata, only values that adhere to the metadata template schema will be accepted.

 
post/files/FILE_ID/metadata/SCOPE/TEMPLATE

Body JSON

Content-Type
string
required

Must be application/json

custom-defined-key(s)
string
required

Custom value(s) defined by a user or application

 

Returns

An instance of the template that includes key:value pairs defined by a user or application. If the template instance already exists, a 409 HTTP status code of conflict will be returned and the update method should be used.

Request

curl https://api.box.com/2.0/files/5010739061/metadata/enterprise/marketingCollateral \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "audience1": "internal", "documentType": "Q1 plans", "competitiveDocument": "no", "status": "active", "author": "Jones", "currentState": "proposal"}' \
-X POST

Results

{
    "audience1": "internal",
    "documentType": "Q1 plans",
    "competitiveDocument": "no",
    "status": "active",
    "author": "Jones",
    "currentState": "proposal",
    "$type": "marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe",
    "$parent": "file_5010739061",
    "$id": "2094c584-68e1-475c-a581-534a4609594e",
    "$version": 0,
    "$typeVersion": 0,
    "$template": "marketingCollateral",
    "$scope": "enterprise_12345"
}

Get Metadata on File

Used to retrieve the metadata template instance for a corresponding Box file.

 
get/files/FILE_ID/metadata/SCOPE/TEMPLATE
 

Returns

An instance of the template that includes key:value pairs defined by a user or application. If there is no template instance present, a 404 HTTP status code of not_found will be returned.

Request

curl https://api.box.com/2.0/files/5010739061/metadata/enterprise/bandInfo \
-H "Authorization: Bearer ACCESS_TOKEN"

Results

{
    "audience1": "internal",
    "documentType": "Q1 plans",
    "competitiveDocument": "no",
    "status": "active",
    "author": "Jones",
    "currentState": "proposal",
    "$type": "marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe",
    "$parent": "file_5010739061",
    "$id": "2094c584-68e1-475c-a581-534a4609594e",
    "$version": 0,
    "$typeVersion": 0,
    "$template": "marketingCollateral",
    "$scope": "enterprise_12345"
}

Update Metadata on File

Used to update the template instance. The request body must follow the JSON-Patch specification, which is represented as a JSON array of operation objects (see examples for more details). Updates can be either add, replace, remove , test, move, or copy. The template instance can only be updated if the template instance already exists. When editing metadata, only values that adhere to the metadata template schema will be accepted.

The update is applied atomically. If any errors occur during the application of the update operations, the metadata instance remains unchanged.

 
put/files/FILE_ID/metadata/SCOPE/TEMPLATE

Body JSON

Content-Type
string
required

Must be application/json-patch+json

op
string
required

The operation type. Must be add, replace, remove , test, move, or copy.

path
string
required

The path that designates the key, in the format of a JSON-Pointer. Since all keys are located at the root of the metadata instance, the key must be prefixed with a /. Special characters ~ and / in the key must be escaped according to JSON-Pointer specification. The value at the path must exist for the operation to be successful.

value
string

The value to be set or tested. Required for add, replace, and test operations. For add, if value already exists, then previous value will be overwritten by the new value. For replace, the metadata value must exist before replacing.For test, the value of the existing metadata instance must match the specified value.

from
string

Required for move or copy. The path that designates the source key, in the format of a JSON-Pointer, formatted in the same way as path. Used in conjunction with path: from specifies the source, path specifies the destination.

 

Returns

An instance of the template that includes key:value pairs defined by a user or application. If there is no template instance present, a 404 HTTP status code of not_found will be returned

Request

curl https://api.box.com/2.0/files/5010739061/metadata/enterprise/marketingCollateral \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json-patch+json" \
-d '[{"op": "test", "path": "/competitiveDocument", "value": "no"},
{"op": "remove", "path": "/competitiveDocument"},
{"op": "test", "path": "/status", "value": "active"},
{"op": "replace", "path": "/status", "value": "inactive"},
{"op": "test", "path":"/author", "value":"Jones"},
{"op": "copy", "from":"/author", "path":"/editor"},
{"op": "test", "path":"/currentState", "value":"proposal"},
{"op": "move", "from":"/currentState", "path": "/previousState"},
{"op": "add", "path":"/currentState", "value": "reviewed"}]' \
-X PUT

Results

{
    "audience1": "internal",
    "documentType": "Q1 plans",
    "status": "inactive",
    "author": "Jones",
    "$type": "marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe",
    "$parent": "file_5010739061",
    "$id": "2094c584-68e1-475c-a581-534a4609594e",
    "$version": 1,
    "$typeVersion": 0,
    "editor": "Jones",
    "previousState": "proposal",
    "currentState": "reviewed",
    "$template": "marketingCollateral",
    "$scope": "enterprise_12345"
}

Delete Metadata on File

Used to delete the template instance. To delete custom key:value pairs within a template instance, you should refer to the updating metadata section.

 
delete/files/FILE_ID/metadata/SCOPE/TEMPLATE
 

Returns

An empty HTTP 204 response to confirm the deletion of the template instance.

Request

curl https://api.box.com/2.0/files/5010739061/metadata/enterprise/marketingCollateral \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Get all Metadata on File

Used to retrieve all metadata associated with a given file

 
get/files/FILE_ID/metadata/
 

Returns

An array of metadata instances associated with the file.

Request

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

Results

{
    "entries": [
        {
            "currentDocumentStage": "Init",
            "$type": "documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f",
            "$parent": "file_5010739061",
            "$id": "50ba0dba-0f89-4395-b867-3e057c1f6ed9",
            "$version": 4,
            "$typeVersion": 2,
            "needsApprovalFrom": "Smith",
            "$template": "documentFlow",
            "$scope": "enterprise_12345"
        },
        {
            "$type": "productInfo-9d7b6993-b09e-4e52-b197-e42f0ea995b9",
            "$parent": "file_5010739061",
            "$id": "15d1014a-06c2-47ad-9916-014eab456194",
            "$version": 2,
            "$typeVersion": 1,
            "skuNumber": 45334223,
            "description": "Watch",
            "$template": "productInfo",
            "$scope": "enterprise_12345"
        },
        {
            "Popularity": "25",
            "$type": "properties",
            "$parent": "file_5010739061",
            "$id": "b6f36cbc-fc7a-4eda-8889-130f350cc057",
            "$version": 0,
            "$typeVersion": 2,
            "$template": "properties",
            "$scope": "global"
        },

    ],
    "limit": 100
}

Create Metadata on Folder

Used to create the metadata template instance for a corresponding Box folder. When creating metadata, only values that adhere to the metadata template schema will be accepted.

 
post/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE

Body JSON

Content-Type
string
required

Must be application/json

JSON formatted metadata value(s)
string
required

JSON formatted value(s) for the specific metadata template

 

Returns

Available in Beta

As with any Beta, you may encounter issues with functionality. Box reserves the right to make changes which may improve, impair, add or remove functionality with these APIs.
If you would like to provide any feedback, please email metadata-feedback@box.com. We would love to hear from you.

Folder metadata operations on folder ID 0 (zero) are not allowed.

Attempts to perform Folder metadata operations on folder ID 0 (zero) will result in a 403 HTTP status code.

An instance of the template that includes key:value pairs defined by a user or application. If the template instance already exists, a 409 HTTP status code of conflict will be returned and the update method should be used.

Request

curl https://api.box.com/2.0/folders/998951261/metadata/enterprise/documentFlow \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"currentDocumentStage": "initial vetting", "needsApprovalFrom": "vetting team", "nextDocumentStage": "prioritization"}' \
-X POST

Results

{
    "currentDocumentStage": "initial vetting",
    "needsApprovalFrom": "vetting team",
    "nextDocumentStage": "prioritization",
    "$type": "documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f",
    "$parent": "folder_998951261",
    "$id": "e57f90ff-0044-48c2-807d-06b908765baf",
    "$version": 0,
    "$typeVersion": 0,
    "$template": "documentFlow",
    "$scope": "enterprise_12345"
}

Get Metadata on Folder

Used to retrieve the metadata template instance for a corresponding Box folder.

 
get/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE
 

Returns

Available in Beta

As with any Beta, you may encounter issues with functionality. Box reserves the right to make changes which may improve, impair, add or remove functionality with these APIs.
If you would like to provide any feedback, please email metadata-feedback@box.com. We would love to hear from you.

Folder metadata operations on folder ID 0 (zero) are not allowed.

Attempts to perform Folder metadata operations on folder ID 0 (zero) will result in a 403 HTTP status code.

An instance of the template that includes key:value pairs defined by a user or application. If there is no template instance present, a 404 HTTP status code of not_found will be returned.

Request

curl https://api.box.com/2.0/folders/998951261/metadata/enterprise/documentFlow \
-H "Authorization: Bearer ACCESS_TOKEN"

Results

{
    "currentDocumentStage": "initial vetting",
    "needsApprovalFrom": "vetting team",
    "nextDocumentStage": "prioritization",
    "$type": "documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f",
    "$parent": "folder_998951261",
    "$id": "e57f90ff-0044-48c2-807d-06b908765baf",
    "$version": 0,
    "$typeVersion": 2,
    "$template": "documentFlow",
    "$scope": "enterprise_12345"
}

Update Metadata on Folder

Used to update the template instance. Updates can be either add, replace, remove , or test. The template instance can only be updated if the template instance already exists. When editing metadata, only values that adhere to the metadata template schema will be accepted.

 
put/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE

Body JSON

Content-Type
string
required

Must be application/json-patch+json

op
string
required

The operation type. Must be add, replace, remove , or test.

path
string
required

The path that designates the key. Must be prefixed with a /

value
string

The value to be set. If value already exists, then previous value will be overwritten by the new value. Required for add and replace operations.

 

Returns

Available in Beta

As with any Beta, you may encounter issues with functionality. Box reserves the right to make changes which may improve, impair, add or remove functionality with these APIs.
If you would like to provide any feedback, please email metadata-feedback@box.com. We would love to hear from you.

Folder metadata operations on folder ID 0 (zero) are not allowed.

Attempts to perform Folder metadata operations on folder ID 0 (zero) will result in a 403 HTTP status code.

An instance of the template that includes key:value pairs defined by a user or application. If there is no template instance present, a 404 HTTP status code of not_found will be returned

Request

curl https://api.box.com/2.0/folders/998951261/metadata/enterprise/documentFlow \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json-patch+json" \
-d '[{"op": "test", "path":"/currentDocumentStage", "value": "initial vetting" },
	{"op": "replace", "path":"/currentDocumentStage", "value": "prioritization" },
  {"op": "test", "path":"/needsApprovalFrom", "value": "vetting team" },
  {"op": "replace", "path":"/needsApprovalFrom", "value": "planning team" },
	{"op": "add", "path":"/maximumDaysAllowedInCurrentStage", "value": 5},
  {"op": "test", "path":"/nextDocumentStage", "value": "prioritization" },
	{"op": "remove", "path":"/nextDocumentStage"}]' \
-X PUT

Results

{
    "currentDocumentStage": "prioritization",
    "needsApprovalFrom": "planning team",
    "$type": "documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f",
    "$parent": "folder_998951261",
    "$id": "e57f90ff-0044-48c2-807d-06b908765baf",
    "$version": 1,
    "$typeVersion": 2,
    "maximumDaysAllowedInCurrentStage": 5,
    "$template": "documentFlow",
    "$scope": "enterprise_12345"
}

Delete Metadata on Folder

Used to delete the template instance. To delete custom key:value pairs within a template instance, you should refer to the updating metadata section.

 
delete/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE
 

Returns

Available in Beta

As with any Beta, you may encounter issues with functionality. Box reserves the right to make changes which may improve, impair, add or remove functionality with these APIs.
If you would like to provide any feedback, please email metadata-feedback@box.com. We would love to hear from you.

Folder metadata operations on folder ID 0 (zero) are not allowed.

Attempts to perform Folder metadata operations on folder ID 0 (zero) will result in a 403 HTTP status code.

An empty HTTP 204 response to confirm the deletion of the template instance.

Request

curl https://api.box.com/2.0/folders/998951261/metadata/enterprise/documentFlow \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Get All Metadata on Folder

Used to retrieve all metadata associated with a given folder

 
get/folders/FOLDER_ID/metadata
 

Returns

Available in Beta

As with any Beta, you may encounter issues with functionality. Box reserves the right to make changes which may improve, impair, add or remove functionality with these APIs.

If you would like to provide any feedback, please email metadata-feedback@box.com. We would love to hear from you.

Folder metadata operations on folder ID 0 (zero) are not allowed.

Attempts to perform Folder metadata operations on folder ID 0 (zero) will result in a 403 HTTP status code.

An array of metadata instances associated with the folder.

Request

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

Results

{
    "entries": [
        {
            "currentDocumentStage": "prioritization",
            "needsApprovalFrom": "planning team",
            "$type": "documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f",
            "$parent": "folder_998951261",
            "$id": "e57f90ff-0044-48c2-807d-06b908765baf",
            "$version": 1,
            "$typeVersion": 2,
            "maximumDaysAllowedInCurrentStage": 5,
            "$template": "documentFlow",
            "$scope": "enterprise_12345"
        },
        {
            "skuNumber": 45234522115075,
            "description": "Hat",
            "department": "Accessories",
            "$type": "productInfo-9d7b6993-b09e-4e52-b197-e42f0ea995b9",
            "$parent": "folder_998951261",
            "$id": "0dd54220-8340-4ea1-bd3f-59a23c68ccdd",
            "$version": 0,
            "$typeVersion": 1,
            "$template": "productInfo",
            "$scope": "enterprise_12345"
        }
    ],
    "limit": 100
}

Collection Object

Collections contain information about the items contained inside of them, including files and folders. The only collection available currently is a “Favorites” collection. The contents of the collection are discovered in a similar way in which the contents of a folder are discovered.

 

type

string

For collections is ‘collection’.

id

string

Box’s unique string identifying this collection. This will never change once created

name

string

The name of this collection. The only collection currently available is named “Favorites”

collection_type

string

The type of the collection. This is used to determine the proper visual treatment for Box-internally created collections. Initially only “favorites” collection-type will be supported.

{
    "type": "collection",
    "id": "5880",
    "name": "Favorites",
    "collection_type": "favorites",
}

Get Collections

Retrieves the collections for the given user. Currently, only the favorites collection is supported.

 
get/collections
 

Request

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

Results

{
    "total_count": 1,
    "entries": [
        {
            "type": "collection",
            "id": "405151",
            "name": "Favorites",
            "collection_type": "favorites"
        }
    ],
    "limit": 100,
    "offset": 0
}

Get Collection Items

Retrieves the files and/or folders contained within this collection. Collection item lists behave a lot like getting a folder’s items.

 
get/collections/COLLECTION_ID/items

Query Params

fields
string

Attribute(s) to include in the response

limit
integer

The maximum number of items to return in a page.

offset
string

The offset at which to begin the response. An offset of value of 0 will start at the beginning of the folder-listing. Offset of 2 would start at the 2nd record, not the second page. Note: If there are hidden items in your previous response, your next offset should be = offset + limit, not the # of records you received back.

 

Retrieves the files and/or folders contained within this collection. Collection item lists behave a lot like getting a folder’s items.

  • Paginated results can be retrieved using the limit and offset parameters.
  • Sub-object fields can be requested via the ?fields parameter

Returns

An array of items contained in the collection is returned. An error is thrown if the collection 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).

Request

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

Results

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

Create or Delete

To add or remove an item from a collection, you do a PUT on that item and change the list of collections it belongs to. Philosophically, this is similar to the way “move” operations work on files and folders: you do a PUT on the item and change its parent. It’s the same idea with collections, except you’re changing which collection(s) the item belongs to instead of the folder it belongs to. Currently the only collection available is the favorites collection, and you’ll need to know it’s ID for the user that is making the API call, since every user has a different favorites collection_id.

The Add/Remove API handling will check all ids passed in before performing any add/removal operations. If any collection ids are malformed or do not exist in the user’s account, the API call will throw a 400. Only if all of the collection ids are valid will the adds and removals be carried out.

 
put/folders/FOLDER_ID
 

Request

curl https://api.box.com/2.0/folders/FOLDER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"collections": [{"id":"123"}]}' \
-X PUT

Results

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

Searching for Content

The search endpoint provides a powerful way to find Box content. Use the parameters described in this section to control what you search for.

 
get/search?query=SEARCH_QUERY

Query Params

query
string
required

The string to search for. Box matches the search string against object names, descriptions, text contents of files, and other data.

scope
string

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

file_extensions
string

Limit searches to specific file extensions like pdf,png, or doc. The value can be a single file extension or a comma-delimited list of extensions. For example: png,md,pdf

created_at_range
string

The date when the item was created. Specify the date range using RFC3339 timestamps separated by a comma. For example: `2014-05-15T13:35:01-07:00,2014-05-17T13:35:01-07:00. Either the beginning date or the ending date may be empty, but the separating comma is required. For example, if you omit the beginning date, then the ending date must begin with a comma.

updated_at_range
string

The date when the item was last updated. Specify the date range using RFC3339 timestamps separated by a comma. For example: `2014-05-15T13:35:01-07:00,2014-05-17T13:35:01-07:00. Either the beginning date or the ending date may be empty, but the separating comma is required. For example, if you omit the beginning date, then the ending date must begin with a comma.

size_range
integer

Return only files within a stated size range. Specify the range in bytes with lower and upper bounds separated by a comma, like so:lower_bound_size,upper_bound_size, where 1MB is 1000000 bytes. You can specify only the lower bound if you end this parameter with a comma. You can specify only the upper bound by placing a comma at the beginning of the number.

owner_user_ids
string

Search for objects by owner. Requires a user ID or a set of comma-delimited user IDs, like so: user_id_1,user_id_2,...

ancestor_folder_ids
string

Search for the contents of specific folders (and folders within them). Requires a folder ID or a set of comma-delimited folder IDs, like so: folder_id_1,folder_id_2,....

content_types
string

Search for objects of specified content types. The types can be name, description, file_content, comments, or tags. Requires a content type or a set of comma-delimited content_types, like so: content_type_1,content_type_2,....

type
string

The type of objects you want to include in the search results. The type can be file, folder, or web_link.

trash_content
string

Controls whether to search in the trash. The value can be trashed_only or non_trashed_only. Searches without this parameter default to searching non_trashed_only.

mdfilters
string

Searches for objects with a specific metadata object association. The filters must be placed in a single JSON object in a JSON array (see the tab labeled "Search with metadata" in the Request example). NOTE: For searches with the mdfilters parameter, a query string is not required.

templateKey
string

A child value of the mdfilters parameter. The key name of the template you want to search for. Currently you can search only for one template at a time.

scope
string

A child value of the mdfilters parameter. Specifies the scope of the template searched for. Currently, the scopes enterprise and global are supported.

filters
string

Child of mdfilters. Keys and values of the template you want to search within. For floats and dates, you can include an (inclusive) upper bound parameter lt or (inclusive) lower bound parameter gt or both bounds. An example filter for a “contractExpiration” on or before 08-01-16 would be listed as {"contractExpiration":{"lt":"2016-08-01T00:00-00:00"}}

limit
integer

The number of search results to return. The default is 30 and the maximum is 200.

offset
integer

The search result at which to start the response. The default is 0.

 

Limit and offset

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

Note:

If an item is added to Box then it becomes accessible through the search endpoint after ten minutes.

Returns

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

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"
##Request before URL Encoding

https://api.box.com/2.0/search?mdfilters=[{"templateKey":"marketingCollateral", "scope":"enterprise", "filters":{"documentType": "datasheet"}}]

##cURL Request after URL encoding

curl https://api.box.com/2.0/search?mdfilters=%5B%7B%22templateKey%22%3A%22marketingCollateral%22%2C%20%22scope%22%3A%22enterprise%22%2C%20%22filters%22%3A%7B%22documentType%22%3A%20%22datasheet%22%7D%7D%5D \
-H "Authorization: Bearer ACCESS_TOKEN" 

Results

{
    "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
}
{
    "total_count": 2,
    "entries": [
        {
            "type": "file",
            "id": "27201036412",
            "sequence_id": "0",
            "etag": "0",
            "sha1": "71402e9009892ceb7210558abbe720a8e068bd8a",
            "name": "boxdev.png",
            "description": "",
            "size": 6708,
            "path_collection": {
                "total_count": 2,
                "entries": [
                    {
                        "type": "folder",
                        "id": "0",
                        "sequence_id": null,
                        "etag": null,
                        "name": "All Files"
                    },
                    {
                        "type": "folder",
                        "id": "575496314",
                        "sequence_id": "3",
                        "etag": "3",
                        "name": "Marketing Materials"
                    }
                ]
            },
            "created_at": "2015-03-08T20:34:51-07:00",
            "modified_at": "2015-03-08T20:34:51-07:00",
            "trashed_at": null,
            "purged_at": null,
            "content_created_at": "2015-03-08T14:41:58-07:00",
            "content_modified_at": "2015-03-08T14:41:58-07:00",
            "created_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "modified_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "owned_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "shared_link": null,
            "parent": {
                "type": "folder",
                "id": "575496314",
                "sequence_id": "3",
                "etag": "3",
                "name": "Marketing Materials"
            },
            "item_status": "active"
        },
        {
            "type": "file",
            "id": "26776387434",
            "sequence_id": "3",
            "etag": "3",
            "sha1": "72d773345dbba9cfb012c4a889a4fc6840e59bfa",
            "name": "2014 Companies.xlsx",
            "description": "",
            "size": 91821,
            "path_collection": {
                "total_count": 3,
                "entries": [
                    {
                        "type": "folder",
                        "id": "0",
                        "sequence_id": null,
                        "etag": null,
                        "name": "All Files"
                    },
                    {
                        "type": "folder",
                        "id": "575496314",
                        "sequence_id": "3",
                        "etag": "3",
                        "name": "Marketing Materials"
                    },
                    {
                        "type": "folder",
                        "id": "606618154",
                        "sequence_id": "0",
                        "etag": "0",
                        "name": "West"
                    }
                ]
            },
            "created_at": "2015-02-26T22:20:44-08:00",
            "modified_at": "2015-02-26T22:23:15-08:00",
            "trashed_at": null,
            "purged_at": null,
            "content_created_at": "2015-02-06T16:38:26-08:00",
            "content_modified_at": "2015-02-06T16:38:26-08:00",
            "created_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "modified_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "owned_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "shared_link": null,
            "parent": {
                "type": "folder",
                "id": "606618154",
                "sequence_id": "0",
                "etag": "0",
                "name": "West"
            },
            "item_status": "active"
        }
    ],
    "limit": 30,
    "offset": 0
}

Collaboration Object

 

Collaborations are Box’s equivalent of access control lists. They can be used to set and apply permissions for users or groups to folders.

The collaboration roles that are currently available are editor, viewer, previewer, uploader, previewer uploader, viewer uploader, co-owner, or owner. For a full description of what each role entails, please reference our support documentation.

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

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

Create Collaboration

Used to add a collaboration for a single user or a single group to a folder. Either an email address, a user ID, or a group id can be used to create the collaboration. If the collaboration is being created with a group, access to this endpoint is granted based on the group's invitability_level.

 
post/collaborations

Body JSON

fields
string

Attribute(s) to include in the response

notify
boolean

URL Parameter. Determines if the user, (or all the users in the group) should receive email notification of the collaboration.

item
required

The item to add the collaboration on

id
string

Child of accessible_by. The ID of this user or group

type
string

Child of accessible_by. Type of collaborator, must be either user or group

accessible_by
required

The user or group who this collaboration applies to

login
string

Child of accessible_by. An email address (does not need to be a Box user). Omit if this is a group, or if you include the userID above

role
string
required

The access level of this collaboration. Can be editor, viewer, previewer, uploader, previewer uploader, viewer uploader, co-owner, or owner

 

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.

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

Results

{
    "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 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.

 
get/collaborations/COLLAB_ID

Query Params

fields
string

Attribute(s) to include in the response

status
string

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.

Request

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

Results

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

Update Collaboration

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

 
put/collaborations/COLLAB_ID

Body JSON

role
string
required

The access level of this collaboration (see above for roles)

status
string

Whether this collaboration has been accepted

expires_at
string

The time in the future this collaboration will expire

 

Status:

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

Returns

The updated collaboration object is returned. If the role is changed to owner, the collaboration is deleted with a new one created for the previous owner and a 204 is returned.

Errors may occur if the IDs are invalid or if the user does not have permissions to edit the collaboration.

Request

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

Results

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

Delete Collaboration

Used to delete a single collaboration.

 
delete/collaborations/COLLAB_ID
 

Returns

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

Request

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

Pending Collaborations

Used to retrieve all pending collaboration invites for this user.

 
get/collaborations?status=pending

Query Params

fields
string

Attribute(s) to include in the response

status
string
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.

Request

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

Results

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

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/shared_items

Query Params

BoxApi
string
required

See Values below

shared_link
string
required

The shared link for this item

shared_link_password
string

Child of shared_link. The password for this shared link

 

Used to retrieve the metadata about a shared item when only given a shared link. Because of varying permission 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.

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.

Request

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

Results

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

Comment Object

 

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.

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

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

Create Comment

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

 
post/comments

Body JSON

item
required

The item that this comment will be placed on.

type
string
required

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

id
string
required

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

message
string

The text body of the comment

tagged_message
string

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.

 

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.

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

Results

{
    "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 Comment

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

 
get/comments/COMMENT_ID
 

Returns

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

Request

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

Results

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

Update Comment

Used to update the message of the comment.

 
put/comments/COMMENT_ID

Body JSON

message
string
required

The desired text for the comment message

 

Returns

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

Request

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

Results

{
    "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 Comment

Permanently deletes a comment.

 
delete/comments/COMMENT_ID
 

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.

Request

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

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.

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

Note:

Tagged messages are not included in the task object.

{
    "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 Task

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

 
post/tasks

Body JSON

item
required

The item this task is for

type
string
required

Child of item. The type of the item this task is for (currently only file is supported)

id
string
required

Child of item. The ID of the item this task is for

action
string

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

message
string

An optional message to include with the task

due_at
string

The day at which this task is due

 

Returns

A new task object will be returned upon success.

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

Results

{
    "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 Task

Fetches a specific task.

 
get/tasks/TASK_ID
 

Returns

The specified task object will be returned upon success.

Request

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

Results

{
    "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 Task

Updates a specific task.

 
put/tasks/TASK_ID

Body JSON

action
string

The action the task assignee will be prompted to do. Can be review

message
string

An optional message to include with the task

due_at
string

The day at which this task is due

 

Returns

The updated task object will be returned upon success.

Request

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

Results

{
    "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 Task

Permanently deletes a specific task.

 
delete/tasks/TASK_ID
 

Returns

An empty 204 response will be returned upon success.

Request

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

Get Assignments

Retrieves all of the assignments for a given task.

 
get/tasks/TASK_ID/assignments
 

Returns

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

Request

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

Results

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

Get Task Assignment

Fetches a specific task assignment.

 
get/task_assignments/TASK_ASSIGNMENT_ID
 

Returns

The specified task assignment object will be returned upon success.

Request

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

Results

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

Create Task Assignment

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

 
post/task_assignments

Body JSON

task
required

The task this assignment is for

type
string
required

Child of task. Must be task

id
string

Child of assign_to. The ID of the user this assignment is for.

assign_to
required

The user this assignment is for. At least one of id or login is required in this object.

login
string

Child of assign_to. The login email address for the user this assignment is for.

 

Returns

A new task assignment object will be returned upon success.

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

Results

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

Update Task Assignment

Used to update a task assignment.

 
put/task_assignments/TASK_ASSIGNMENT_ID

Body JSON

message
string

A message from the assignee about this task

resolution_state
string

Can be completed, incomplete, approved, or rejected

 

Returns

A new task assignment object will be returned upon success.

Request

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

Results

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

Delete Task Assignment

Deletes a specific task assignment.

 
delete/task_assignments/TASK_ASSIGNMENT_ID
 

Returns

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

Request

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

Events Overview

 

When something changes in a Box user's account, Box logs an event for the user. The event is a description of the object that changed and what caused it to change. The object can be any Box object that the user owns or collaborates on. Box records events in admin reports and uses them to send messages to the Box sync client about account activity.

Box provides an API endpoint at /events that presents a stream of two different types of events, called user events and admin events.

Admin events are those events that are retrieved when you request a stream_type of "admin-logs". User events are all other events.

When you request user events, Box delivers a low-latency, highly reliable list of all events related to the user's account. Because of its emphasis on returning complete results quickly, Box may return duplicate events, and events may delivered out of order.

When you request admin events, Box delivers the full history of an enterprise account, suitable for use with analytic tools like Splunk and GoodData, limited by the parameters that you provide. The events returned are the same events that appear in Box administrative logs. Unlike requests for user events, requests for admin events support filters by event type. Because the emphasis is on completeness and not on low latency, Box may deliver admin events with much higher latencies.

See the "Enterprise Events" section below for a description of all supported parameters.

To retrieve events, send a request to the /events endpoint with no stream_position parameter. The absence of the stream_position signals to Box that it should return a list of all events. To limit the number of results, pass a count in the chunk_size parameter; Box returns all events or chunk_size events, whichever is less.

If Box returns fewer than all available events, then the results object contains a stream_position field that identifies the next event that has not yet been returned. To retrieve the next available events, make another request to the /events endpoint, passing the stream_position value that you receive from Box.

If you requested user events then the result list may contain duplicates. Compare the event_id fields of event objects to identify and remove duplicates.

Important

Events occasionally arrive out of order. As an example, a File-upload event might show up before the corresponding Folder-create event. You may need to buffer events and reorder them chronologically.

You can begin retrieving events in either of two ways:

  • send a request to the /events endpoint with stream_position=now
  • send a request to the /events endpoint with no stream_position parameter

If you send stream_position=now then Box returns an empty list and the parameter stream_position with the latest stream position as its value. Using stream_position=now works only when the stream_type is not admin_logs.

If you send no stream_position parameter then Box send all available events, beginning with the oldest stream position.

Important

Box does not store all events for all time on a user account. We store events for between 2 weeks and 2 months, after which they are removed.

The result object that Box returns contains a stream_position field whose value is the stream position of the next unreturned event. Make another request, passing this value as the value for stream_position, to retrieve the next batch of events. Repeat until you have retrieved all the events you need.

Important

Box responds to the created_before and created_after parameters only if the stream_position parameter is not included.

Box keeps track of a certain set of events, and defined 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. If a locked file is deleted, the source file will be null.

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_ROLE_CHANGE

A collaborator had their role changed

COLLAB_INVITE_COLLABORATOR

A collaborator was invited on a folder

COLLAB_REMOVE_COLLABORATOR

A collaborator was removed from 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

Enterprise Events

The following events are defined only for the admin_logs stream_type:

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_ADD_FILE

Granted file access

GROUP_REMOVE_USER

Removed from group

GROUP_REMOVE_FOLDER

Removed folder access

GROUP_REMOVE_FILE

Removed file access

ADMIN_LOG

Admin login

ADD_DEVICE_ASSOCIATION

Added device association

FAILED_LOGIN

Failed login

LOGIN

Login

REMOVE_DEVICE_ASSOCIATION

Removed device association

TERMS_OF_SERVICE_AGREE

Agreed to terms

TERMS_OF_SERVICE_REJECT

Rejected terms

FILE_MARKED_MALICIOUS

Virus found on a file. Event is only received by enterprises that have opted in to be notified.

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

ITEM_SHARED_UPDATE

Share links settings updated

UPDATE_SHARE_EXPIRATION

Extend shared link expiration

SHARE_EXPIRATION

Set shared link expiration

UNSHARE

Unshared links

COLLABORATION_ACCEPT

Accepted invites

COLLABORATION_ROLE_CHANGE

Changed user roles

UPDATE_COLLABORATION_EXPIRATION

Extend collaborator expiration

COLLABORATION_REMOVE

Removed collaborators

COLLABORATION_INVITE

Invited

COLLABORATION_EXPIRATION

Set collaborator expiration

ITEM_SYNC

Synced folder

ITEM_UNSYNC

Un-synced folder

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

CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION

A collaborator violated an admin-set upload policy

Event Object

 

When you use the /events endpoint to retrieve Box events, Box sends you a JSON object that contains an array of event objects. This section describes these results.

Collection Attributes

The result object that contains the array of events also contains the following fields:

chunk_size

integer

The number of event records contained in the object.

next_stream_position

string

The next position in the Box event stream. Use this position in your next request to get the next set of events.

Event Attributes

Events returned in an event object have the following fields:

type

string

"event"

event_id

string

The Box ID of the event. You can use the ID to remove duplicate events.

created_by

user

The user that performed the action represented by the event. Some events may be performed by users not logged into Box. In that case, not all attributes of the object are populated and the event is attributed to a unknown user (user_id = 2).

event_type

event

One of the event types described in the previous section.

session_id

string

The session ID of the user who performed the action represented by the event. Not all events populate this field.

source

type (varies)

The object modified by the event. See object definitions for appropriate types of object, including file, folder, comment. Not all events populate this field.

additional_details

type (varies)

Additional information about the event. This information can include how a user performed the event or information used to correlate events to external Keysafe logs. Not all events populate this field. This field appears only in Enterprise Events.

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

User Events

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.

 
get/events?stream_position=0

Query Params

stream_position
string

The location in the event stream from which you want to start receiving events. You can specify the special value now to get 0 events and the latest stream_position value.

stream_type
string

Restricts the types of events returned: all returns all events, changes returns events that change the file tree, sync returns changes to sync folders and their contents.

limit
integer

Limits the number of events returned.

 

Returns

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

Request

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

Results

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

Enterprise Events

Retrieves up to a year' 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.

 
get/events?stream_type=admin_logs

Query Params

stream_type
string
required

admin_logs

limit
integer

Limits the number of events returned.

stream_position
string

The location in the event stream from which you want to start receiving events. Box returns up to limit events.

event_type
string

A comma-separated list of event types. Only matching events are returned.

created_after
string

A lower bound on the timestamp of the events returned.

created_before
string

An upper bound on the timestamp of the events returned.

 

Requires Admin:

This API call will only work with an auth token from an enterprise admin account.

Request

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

Results

{
  "chunk_size": 2,
  "next_stream_position": "1449078091829;1a4ade15-b1ff-4cc3-89a8-955e1522557c",
  "entries": [
    {
      "source": {
        "type": "user",
        "id": "222853849",
        "name": "Nick Lee",
        "login": "nlee+demo4@box.com"
      },
      "created_by": {
        "type": "user",
        "id": "222853849",
        "name": "sean rose",
        "login": "sean+awesome@box.com"
      },
      "created_at": "2015-12-02T09:41:31-08:00",
      "event_id": "b9a2393a-20cf-4307-90f5-004110dec209",
      "event_type": "ADD_LOGIN_ACTIVITY_DEVICE",
      "ip_address": "Unknown IP",
      "type": "event",
      "session_id": null,
      "additional_details": null
    },
    {
      "source": {
        "type": "user",
        "id": "222853849",
        "name": "sean rose",
        "login": "sean+awesome@box.com"
      },
      "created_by": {
        "type": "user",
        "id": "222853849",
        "name": "Nick Lee",
        "login": "nlee+demo4@box.com"
      },
      "created_at": "2015-12-02T09:41:31-08:00",
      "event_id": "1a4ade15-b1ff-4cc3-89a8-955e1522557c",
      "event_type": "LOGIN",
      "ip_address": "Unknown IP",
      "type": "event",
      "session_id": null,
      "additional_details": null
    }
  ]
}

Long polling

 
options/events
 

To get real-time notification of activity in a Box account you can use the long poll feature of the /events API. Long polling means opening an HTTP request and keeping it open until the server sends a response, then repeating the process over and over to receive updated responses.

To use long polling, first send an OPTIONS request to the /events endpoint to retrieve the long poll URL. Next, make a GET request to the provided URL to begin listening for events. If an event occurs in an account you are monitoring you will receive a response with the value "new_change". The response contains no other details; it simply serves as a prompt to take further action such as sending a request to the /events endpoint with the last known stream_position. After the server sends this response it closes the connection. You must now repeat the long poll process to begin listening for events again.

If no events occur for a while after you send the GET request to the long-poll URL then 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 then you must make another GET request to the real-time server (that is, URL in the response). Sending another GET request might be necessary in case you do not receive the reconnect message because of network errors.

If you receive a "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.

Request

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

Results

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

Overview of Webhooks V2

 

Feature in Beta

Webhooks V2 is BETA software. Please be aware that this software is in testing, and has not yet been finally released.

If you would like use webhooks with App Users please email Box at webhooks-v2-feedback@box.com.

Introduction

Webhooks enable you to attach event triggers to Box files and folders. Event triggers monitor events on Box objects and notify your application when they occur. A webhook notifies your application by sending HTTP requests to a URL of your choosing.

The Webhooks v2 API defines GET, POST, PUT, and DELETE methods you can use to create webhooks, define the events that trigger notifications, set the URLs they communicate with, and remove them when they are no longer needed. Because every aspect of webhooks can be controlled through the API your application can create webhooks on files and folders as they're needed and remove them when they aren't.

For a basic introduction to using Webhooks V2, see Getting Started with Webhooks V2

This reference describes the Webhooks V2 API, how to create and configure webhooks, and the options and data structures you'll use to work with them.

Event Triggers

 

Webhooks activate when events occur. When you create a webhook you define a list of event triggers that activate it. Each event trigger names a type of event that can affect the file or folder object that is the target of the webhook. When any of those events occur the webhook sends a notification to a URL that you specify.

The table below lists all the events that webhooks can respond to and describes the circumstances that signal each event.

An event can affect a file or a folder. Some events affect only files; some only folders. Events that support webhooks on Files have a "Yes" in the Files? column. Events that support webhooks on folders have a "Yes" in the Folders? column.

Note

When the permissions on a file prevent an action from occurring, no notification is sent for the attempted action.

Event name
Triggered when
File?
Folder?

FILE.UPLOADED

A file is uploaded

No

Yes

FILE.PREVIEWED

A file is previewed

Yes

Yes

FILE.DOWNLOADED

A file is downloaded

Yes

Yes

FILE.TRASHED

A file is moved to the trash

Yes

Yes

FILE.DELETED

A file is permanently deleted

Yes

Yes

FILE.RESTORED

A file is restored from the trash

Yes

Yes

FILE.COPIED

A file is copied

Yes

Yes

FILE.MOVED

A file is moved from one folder to another

Yes

Yes

FILE.LOCKED

A file is locked

Yes

Yes

FILE.UNLOCKED

A file is unlocked

Yes

Yes

COMMENT.CREATED

A comment object is created

Yes

Yes

COMMENT.UPDATED

A comment object is edited

Yes

Yes

COMMENT.DELETED

A comment object is removed

Yes

Yes

TASK_ASSIGNMENT.CREATED

A task is created

Yes

Yes

TASK_ASSIGNMENT.UPDATED

A task assignment is changed

Yes

Yes

METADATA_INSTANCE.CREATED

A new metadata template instance is associated with a file or folder

Yes

Yes

METADATA_INSTANCE.UPDATED

An attribute (value) is updated/deleted for an existing metadata template instance associated with a file or folder

Yes

Yes

METADATA_INSTANCE.DELETED

An existing metadata template instance associated with a file or folder is deleted

Yes

Yes

FOLDER.CREATED

A folder is created

No

Yes

FOLDER.DOWNLOADED

A folder is downloaded

No

Yes

FOLDER.RESTORED

A folder is restored from the trash

No

Yes

FOLDER.DELETED

A folder is permanently removed

No

Yes

FOLDER.COPIED

A copy of a folder is made

No

Yes

FOLDER.MOVED

A folder is moved to a different folder

No

Yes

WEBHOOK.DELETED

When a webhook is deleted

No

No

Webhook Notifications

 

A webhook sends a notification by making an HTTP request to a URL that you specify when creating the webhook. The following sections section the structure of the notifications that Box sends, how it sends them, and how your application can handle them.

Sending Notifications

When Box observes an event that a webhook is watching, it sends an HTTP request to the webhook's notification URL. The notification URL is a valid HTTPS URL that you specify when you create the webhook. The URL must use the standard HTTPS port (443). The notification URL should be the endpoint of a service provided by your application for capturing and handling webhook notifications. To signal that your service has accepted the notification, it should return an HTTP status in the range 200-299 within 30 seconds of receiving the notification.

Retries

If delivery of a notification fails, Box resends it. Delivery has failed if Box does not receive an HTTP response in the range 200-299 within 30 seconds of sending the notification.

Box uses an exponential back-off strategy when retrying notifications in order to avoid overloading the destination server with traffic. Exponential backoff means that after each failure to deliver, Box waits longer than the last time.

The Notification Payload

 

This section describes the structure of the notification payload.

Notification Headers

A notification request sent by a webhook has the following Box-specific headers:

Header
Description

BOX-DELIVERY-ID

A unique ID assigned by Box that identifies the delivered notification. If Box tries more than once to deliver the notification then the ID in the body of the notification is the same in each message, but the BOX-DELIVERY-ID is different.

BOX-DELIVERY-TIMESTAMP

An RFC-3339 timestamp that identifies the time that the notification was sent (see Date Format).

BOX-SIGNATURE-PRIMARY

A hash message authentication code (HMAC) created using the primary signature key configured for this webhook.

BOX-SIGNATURE-SECONDARY

A hash message authentication code (HMAC) created using the secondary signature key configured for this webhook.

BOX-SIGNATURE-VERSION

1

BOX-SIGNATURE-ALGORITHM

"SHA256"

Notification Body

The body of a webhook notification message is a JSON object that describes the webhook's target and the event trigger that sent the notification. The structure of the body is as follows:

{"id": A_NOTIFICATION_ID,
 "type": "webhook_event",
 "webhook": A_WEBHOOK_OBJECT,
 "created_by": A_USER,
 "created_at": AN_RFC3339_TIMESTAMP,
 "trigger": AN_EVENT_NAME,
 "source": A_BOX_OBJECT
}

Example Payload

The following example shows the payload for a notification sent by a FILE.UPLOADED webhook. The details of the header and body values are only examples; they will be different in your notifications.

Headers

Box-Delivery-Id: 673a081b-bb4b-4d45-b4f1-4131a29c1d07
Box-Delivery-Timestamp: 2016-07-11T10:10:33-07:00
Box-Signature-Algorithm: HmacSHA256
Box-Signature-Primary: isCeDp7mLR41/MjcSEFLag9bWmpJkgmN80Je4VIESdo=
Box-Signature-Secondary: 1UbiiKS7/2o5vNIlyMh7e5QGCHq8lflWFgEF+YWBugI=
Box-Signature-Version: 1
Cache-Control: max-age=259200
Connection: close
Content-Length: 1590
Content-Type: application/json; charset=UTF-8
Host:
Surrogate-Capability: web-proxy2002.sv2.box.net="Surrogate/1.0 ESI/1.0"
User-Agent: Box-WH-Client/0.1

Body

{
  "type":"webhook_event",
   "id":"eb0c4e06-751f-442c-86f8-fd5bb404dbec",
   "created_at":"2016-07-11T10:10:32-07:00",
   "trigger":"FILE.UPLOADED",
   "webhook":{
      "id":"53",
      "type":"webhook"
   },
   "created_by":{
      "type":"user",
      "id":"226067247",
      "name":"John Q. Developer",
      "login":"johnq@dev.name"
   },
   "source":{
      "id":"73835521473",
      "type":"file",
      "file_version":{
         "type":"file_version",
         "id":"78096737033",
         "sha1":"2c61623e86bee78e6ab444af456bccc7a1164095"
      },
      "sequence_id":"0",
      "etag":"0",
      "sha1":"2c61623e86bee78e6ab444af456bccc7a1164095",
      "name":"Test-Image-3.png",
      "description":"",
      "size":26458,
      "path_collection":{
         "total_count":4,
         "entries":[
            {
               "type":"folder",
               "id":"0",
               "sequence_id":null,
               "etag":null,
               "name":"All Files"
            },
            {
               "type":"folder",
               "id":"2614853901",
               "sequence_id":"4",
               "etag":"4",
               "name":"Testing"
            },
            {
               "type":"folder",
               "id":"8290186265",
               "sequence_id":"0",
               "etag":"0",
               "name":"Webhooks Base"
            },
            {
               "type":"folder",
               "id":"8290188973",
               "sequence_id":"0",
               "etag":"0",
               "name":"Webhooks"
            }
         ]
      },
      "created_at":"2016-07-11T10:10:32-07:00",
      "modified_at":"2016-07-11T10:10:32-07:00",
      "trashed_at":null,
      "purged_at":null,
      "content_created_at":"2016-06-08T11:14:04-07:00",
      "content_modified_at":"2016-06-08T11:14:04-07:00",
      "created_by":{
         "type":"user",
         "id":"226067247",
         "name":"John Q. Developer",
         "login":"johnq@dev.name"
      },
      "modified_by":{
         "type":"user",
         "id":"226067247",
         "name":"John Q. Developer",
         "login":"johnq@dev.name"
      },
      "owned_by":{
         "type":"user",
         "id":"226067247",
         "name":"John Q. Developer",
         "login":"johnq@dev.name"
      },
      "shared_link":null,
      "parent":{
         "type":"folder",
         "id":"8290188973",
         "sequence_id":"0",
         "etag":"0",
         "name":"Webhooks"
      },
      "item_status":"active"
   },
   "additional_info":[

   ]
}

Payload without Authentication

If the application that authenticates a webhook has no active OAuth session—that is, if its login has expired—then the webhook sends a notification with a minimal payload. This minimal notification carries less data than a full notification, but serves to inform the notification URL that the webhook has been activated.

The headers and body structure of a minimal notification are the same as a full notification, but with less information. Below is an example of a minimal notification. The values of fields in your notifications will be different.

Headers

Box-Delivery-Id: 462fc1b2-7bc5-4e50-bda3-c094daf12f99
Box-Delivery-Timestamp: 2016-07-12T13:14:19-07:00
Box-Signature-Algorithm: HmacSHA256
Box-Signature-Primary: m2zzDEo888sLGDiQ+5a0fj3Fc3LF8awRsKLO/ZtGClk=
Box-Signature-Secondary: IBgiKXC+5vwpoEdZWtXvb+LqAQEeZ9UXoIu0ejR72uA=
Box-Signature-Version: 1
Cache-Control: max-age=259200
Connection: close
Content-Length: 316
Content-Type: application/json; charset=UTF-8
Host:
Surrogate-Capability: web-proxy2004.sv2.box.net="Surrogate/1.0 ESI/1.0"
User-Agent: Box-WH-Client/0.1

Body

{
  "type":"webhook_event",
   "id":"0f46a6ca-86bf-44ab-8cf5-f08e1e02876b",
   "created_at":"2016-07-12T13:14:19-07:00",
   "trigger":"NO_ACTIVE_SESSION",
   "webhook":{
      "id":"53",
      "type":"webhook"
   },
   "created_by":{
      "type":"user",
      "id":"2",
      "name":"Anonymous User",
      "login":""
   },
   "source":{
      "id":"73835521473",
      "type":"file"
   },
   "additional_info":[

   ]
}

Handling Notifications

 

To handle a webhooks notification your application must process HTTP POST requests sent to the notification URL defined for each active webhook. The requests that you receive will be structured according to the description in the previous section. You can examine the headers and the JSON body of the notification and compare it to your application's requirements in order to decide how to handle it.

To ensure that notifications are valid and that they haven't been tampered with en route, follow the advice in the "Signatures" section.

If your application examines a notification and considers it valid and acceptable, it should respond within 30 seconds with an HTTP status code in the range 200-299.

The Webhook Object

 

When you create or retrieve a webhook a JSON object representing the webhook is returned to you. This JSON object's fields contain the name and ID of the webhook, along with configuration details such as its target and its notification URL.

Fields of the Webhook Object

The following table describes all fields of the Webhook Object. The target object and the created_by object are included inline:

Field
Type
Description

id

string

The unique ID string assigned to the webhook by Box.

type

string

'webhook'

target.id

string

The unique ID string assigned by Box to the target of the webhook. The target is the file or folder that the webhook monitors.

target.type

string

'file' or 'folder'

created_by.id

string

The unique ID string assigned by Box to the user who created the webhook.

created_by.type

string

'user'

created_by.name

string

The human-readable name of the user who created the webhook.

created_by.login

string

The login name of the user who created the webhook.

created_at

timestamp

An RFC-3339 timestamp identifying the time that the webhook was created.

address

URL

The notification URL of the webhook. The notification URL is the URL used by Box to send a notification when the webhook is triggered.

triggers

array of strings

An array of event names. The events that webhooks support are listed in the "Event Triggers" section.

Example Webhook Object

The example below shows what a webhook object looks like. The values shown for IDs, user data, and URLs are fictional values of the right type. Replace them with values that are correct for your application.

{"id": "123456789",
 "type": "webhook",
 "target": {"id": "987654321",
            "type": "file"},
 "created_by": {"id": "234567890",
                "type": "user",
                "name": "John Q. Developer",
                "login": "johnq"},
 "created_at": "2016-07-16T11:04:26-08:00",
 "address": "https://dev.name/box-notification",
 "triggers": ["FILE.SHARED","COMMENT.UPDATED"]}

Signatures

 

You can configure webhooks to use signatures to protect them against attacks. When you configure a webhook to use a signature, Box generates a cryptographic digest of the notification's body and attaches it in a header. When your application receives the notification it can compute the same digest and compare it to the one attached to the message. If the digests are not the same then you should not trust the notification; it may have been tampered with by a malicious party.

Using signatures you can ensure that a notification was really sent by Box and that it hasn't been tampered with in transit. Signatures greatly reduce the likelihood of a successful man-in-the-middle or replay attack.

Signatures provide stronger protection if you frequently change the keys used to generate them, but what happens if you change the key while interactions are happening? Your application might receive a valid notification with a signature that is no longer valid.

Webhooks V2 provides a procedure for updating keys that uses two keys and two signatures to avoid that problem.

Configuring an Application to Generate Signatures

In order to attach signatures to an application's notifications you must first generate signature keys for the application. A signature key is a string used by Box to compute the cryptographic digest of each notification. Each application has two signature keys in order to support signature rotation. See the next section, "Rotating Signatures," for a description of how they're used.

To configure your application's keys, begin by logging in to the developer console and Clicking the My Applications link. Edit the application you wish to configure.

In the Webhooks v2 section of the page, find the buttons labeled "Generate primary key" and "Generate secondary key." Click each button to generate the keys that will be used to compute digests of your application's notification messages.

You'll use the data generated by these buttons in your application code to verify received notifications.

Rotating Signatures

Update only one of your application's signature keys at a time. Box always sends two signatures. Your application can trust a notification as long as at least one of its signatures is valid.

If you update only one key at a time, then even if your application receives a notification with one invalid signature, it can still trust the notification as long as the other signature is valid.

These instructions assume that you have already created a primary and secondary key.

To change the primary key, simply generate a new primary key, but not a new secondary key, using the instructions in the previous section.

To change the secondary key, wait for some time to pass first—enough time to be confident that no notifications using the old primary key are still in flight. Then generate a new secondary key (but not a new primary key!).

Make sure that when you use the developer console to generate a new primary or secondary key, you also remember to change your application's notification handler to use the new key in its verification code.

Verifying Signatures

To protect your application against attacks, you must verify signatures included with notifications. Verification ensures that the notifications were actually sent by Box and not by some malicious party, and that the contents of the notification haven't been changed.

The sample Python code below shows how to verify a signature. The steps it illustrates are:

  1. Ensure that the timestamp given in the BOX-DELIVERY-TIMESTAMP header is no older than ten minutes.
  2. Extract the text of the UTF-8 payload as an array of bytes.
  3. Append the UTF-8 value of the BOX-DELIVERY-TIMESTAMP header, as an array of bytes, to the end of the payload array.
  4. Compute a SHA256 HMAC digests for the array of bytes collected in steps 2 and 3. Compute one digest using the application's primary key and one using the secondary key. Copy these keys from the configuration page of your application.
  5. Encode both digests using Base64 encoding.
  6. Compare the encoded digest that you computed using your application's primary key to the value of the BOX-SIGNATURE-PRIMARY header. Compare the one you computed using your application's Secondary Key to the value of the BOX-SIGNATURE-Secondary header. At least one of the computed digests must exactly match its corresponding header value; if not, then the notification may be compromised and should not be trusted.

The following sample code illustrates how to perform these steps in Python:

#!/usr/bin/env python
import hashlib
import hmac
import base64

def base64HmacSha256(messageBytes, keyString):
        keyBytes = bytes(keyString).encode('utf-8')
        return base64.b64encode(hmac.new(keyBytes, messageBytes, digestmod=hashlib.sha256).digest()) if keyString else None

if __name__ == "__main__":
        notificationPayload = r"""{"type":"webhook_event","id":"b786f983-a85e-4c10-9219-214ddf1a74bc","created_at":"2016-07-06T10:40:52-07:00","trigger":"COMMENT.DELETED","webhook":{"id":"113","type":"webhook"},"created_by":{"type":"user","id":"2030334537","name":"Dev OO","login":"dev+oo+e@box.com"},"source":{"id":"53937","type":"comment","is_reply_comment":false,"message":"Test\n","created_by":{"type":"user","id":"2030334537","name":"Dev OO","login":"dev+oo+e@box.com"},"created_at":"2016-07-06T10:40:18-07:00","item":{"id":"5026688373","type":"file"},"modified_at":"2016-07-06T10:40:18-07:00"},"additional_info":[]}"""
        deliveryTimestamp = r"2016-07-06T10:40:52-07:00"

        primaryKey = "1GUSMETgaD9qUHyADAGuOADryxFbCunT"
        secondaryKey = None

        message = bytes(notificationPayload).encode('utf-8') + bytes(deliveryTimestamp).encode('utf-8')

        primarySignature = base64HmacSha256(message, primaryKey)
        secondarySignature = base64HmacSha256(message, secondaryKey)

        print "Primary Signature   : %s" % primarySignature
        print "Secondary Signature : %s" % secondarySignature

Deleting a Webhook

 

You can use the Webhooks v2 API to delete a webhook by ID, but that's not the only way a webhook can be deleted. Deleting a Box application also deletes all webhooks that are associated with it. In addition, if you revoke all access tokens associated with a webhook then the webhook is deleted.

Finally, Box automatically deletes webhooks if they aren't able to deliver their notifications for a system-determined amount of time. When Box automatically removes a webhook, it sends a WEBHOOK.DELETED notification to your registered notification URL.

Following is an example of the information supplied in the payload of a WEBHOOK.DELETED notification:

"additional_info": {
  "reason": "auto_cleanup"
}

Using the API

 

Everything that can be done with Webhooks v2 can be done using its REST API, including creating and configuring them.

Using the API means sending GET, POST, PUT, and DELETE requests to Box to create, retrieve, update, and remove webhooks.

Structure of Webhooks v2 requests

Webhooks v2 GET and DELETE requests send parameters in path or the query string of the URL. POST and PUT requests send their parameters in the form of a JSON object in the body of the request, referred to as the parameters object.

Webhooks v2 endpoint

Webhooks v2 API requests should be sent to the endpoint

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

POST and PUT bodies

POST and PUT requests transport parameters as the values of fields in a JSON object. This object is called the parameters object. A parameters object looks like this:

{"id": "AN_ID_STRING",
 "type": "A_TYPE_STRING",
 "target": {"id": "AN_ID_STRING",
            "type": "A_TYPE_STRING"},
 "created_by": {"id": "AN_ID_STRING",
                "type": "A_TYPE_STRING",
                "name": "A_STRING",
                "login": "A_STRING"},
 "created_at": "A_TIMESTAMP",
 "address": "A_URL_STRING",
 "triggers": "AN_ARRAY_OF_TRIGGER_NAMES"}

The values shown in this example are placeholders. The following sections describe the fields of the parameters object in more detail.

In the reference sections for API calls, Webhooks v2 parameters for POST and PUT calls are given as the names of fields in the parameters object. In those sections, when the text refers to a field of the target or created_by object, those fields are shown using JSON dot notation. For example, when describing the id field of the target object, the reference section will call it the target.id field.

The parameters object

The following table describes the types and values of the fields of the JSON object used to represent parameters in POST and PUT requests:

Parameter name
Parameter type
Description

id

string

The string identifier of the webhook, assigned by Box

type

string

The type of the webhook. This value must always be "webhook".

target

JSON object

A JSON object that identifies the Box object (file or folder) to which the webhook is attached. See the table Target Object, below.

created_by

JSON object

A JSON object that identifies the Box user who created the webhook. See the table Created-by Object, below.

created_at

string

An RFC-3339 timestamp that identifies when the webhook was created.

address

string

The URL to which Webhooks notifications are to be sent.

triggers

array of strings

An array of Event Trigger names. See the section Event Triggers.

Target Object

A target object is a JSON object that describe the target of a webhook. It is passed in Webhooks v2 requests in the target field of the parameters object.

Parameter name
Parameter type
Description

id

string

The string identifier of the target object (file or folder), assigned by Box

type

string

The name of the target object's type. This value must be be either "file" or "folder".

Created-by Object

A created-by object is a JSON object that describe the Box user who created a webhook. It is passed in Webhooks v2 requests in the created_by field of the parameters object.

Parameter name
Parameter type
Description

id

string

The string identifier of the Box user who created the webhook, assigned by Box

type

string

The type of the object that represents the user. This value must always be "user".

name

string

The user's name.

login

string

The user's login name.

Examples

Here's an example of an API request to retrieve a webhook that was previously defined. The call to get a webhook uses a GET request and passes its parameters in the URL path:

GET /api/2.0/webhooks/4137 HTTP/1.1

The following example requests all defined webhooks, with a limit of 3 per page. It passes its parameter in the URL query string:

GET /api/2.0/webhooks?limit=3 HTTP/1.1

The following example shows one of the API requests that passes parameters in the request body in the form of a JSON object. This is a request to create a webhook:

POST /api/2.0/webhooks HTTP/1.1
Host: me.example.net
Authorization: Bearer kn6F8iARsLkKlfftIC67WK6zxlC0vcJh
Cache-Control: no-cache

{
  "target": {
    "type": "file",
    "id": "5018848529"
  },
  "address": "https://me.example.net/actions/file_changed",
  "triggers": ["FILE.DOWNLOADED", "FILE.PREVIEWED"]
}

Responses

All Webhooks APIs return responses in the form of JSON objects, with the exception of the request to delete a webhook, which returns 204 No Content. See the reference section for each individual API request for a description of the response objects they return.

Limitations and Restrictions

 

One Webhook per Object

There's a limit of one webhook per object in a given application for a given user. An object is either a file or a folder. Once you have set a webhook on a target object, you cannot add a second one for that application and user, even if the second one would respond to a different event.

For example, let's suppose you create a FILE.UPLOADED webhook on the folder Junk for use with the application MyGreatApp for the user Fred. You cannot now add a FILE.DOWNLOADED webhook on the same folder, unless you add it for a different application or a different user.

What if you want to change the webhook? You can use the Update request to change the event and other parameters of the webhook (see the Update Webhook section of this reference).

No More Than 1000 Webhooks

There is a limit of 1000 webhooks on each combination of application and user. In other words, you can create up to 1000 webhooks on a particular application for user Alice, but not more. On the other hand, if there are already 1000 webhooks on the app for Alice, you can still create new webhooks on the same app for user Bob, up to another 1000.

Restrictions on the Notification URL

The notification URL for a webhook must be a valid HTTPs URL that resolves to a valid IP address. The IP address must be accessible from the Internet and it most not be a Box.com address. The port used in the URL must be the standard HTTPS port, 443; if you use a different port then your notifications will not be delivered.

Create Webhook

 
post/webhooks

Body JSON

target

The target file or folder

triggers
array

Event types that trigger notifications for the target.

 

Returns

Returns a webhook object if creation succeeds.

Errors

Target could not be found
Signaled if there is no target with the supplied ID, or if you don't have access to the target.

Insufficient permissions
Signaled if you don't have permission to perform the event that the webhook observes.

Target not supported
Signaled if you try to create a webhook on an object other than a file or folder.

Address invalid
Signaled if the notification URL is not an HTTPS URL.

Event name invalid
Signaled if the event name is unrecognized or unsupported by Webhooks V2.

Unsupported target type
Signaled if the event type is not supported on the target object's type. For example, you can set a FILE.UPLOADED webhook on a folder, but not on a file.

Required field missing
Signaled if a required field is missing from the request. For example, submitting a request in which the target address is missing signals this error.

Webhook already exists
Signaled if you try to create a webhook when a matching one already exists. You can only create one webhook for each combination of target, application, and user. If you want to replace one webhook with another, use the Update request to change the webhook.

Request

curl https://api.box.com/2.0/webhooks \
-H "Authorization: Bearer <DEVELOPER_TOKEN>" \
-H "Content-Type: application/json" -X POST \
-d '{"target": {"id": "<TARGET_ID>", "type": "folder"}, "address": "<NOTIFICATION_URL>", "triggers": ["FILE.UPLOADED","FILE.DOWNLOADED"]}'

Results

{
  "id": "4165",
  "type": "webhook",
  "target": {
    "id": "5016243669",
    "type": "file"
  },
  "created_by": {
    "type": "user",
    "id": "2030392653",
    "name": "John Q. Developer",
    "login": "johnq@dev.name"
  },
  "created_at": "2016-05-09T17:41:27-07:00",
  "address": "https://dev.name/actions/file_changed",
  "triggers": [
    "FILE.DOWNLOADED",
    "FILE.UPLOADED"
  ]
}

Get Webhook

 
get/webhooks/ID
 

Returns

Returns a webhook object.

Errors

Webhook ID not found
Signaled if no webhook exists with the supplied ID.

Insufficient permissions
Signaled if you lack permission to access the webhook.

Request

curl https://api.box.com/2.0/webhooks/{id} \
-H "Authorization: Bearer <DEVELOPER_TOKEN>" \
-H Cache-Control: no-cache

Response

{
  "id": "4137",
  "type": "webhook",
  "target": {
    "id": "5018848529",
    "type": "file"
  },
  "created_by": {
    "type": "user",
    "id": "2030392653",
    "name": "John Q. Developer",
    "login": "johnq@example.net"
  },
  "created_at": "2016-05-04T18:51:45-07:00",
  "address": "https://example.net/actions/file_changed",
  "triggers": [
    "FILE.PREVIEWED"
  ]
}

Get Webhooks

 
get/webhooks?limit=AN_INTEGER&marker=A_STRING
 

Usage

The limit and marker parameters are optional.

Box returns all defined webhooks for the requesting application and user, up to the limit. If no limit is supplied then Box uses the default limit of 100. The maximum limit per page of results is 200.

If more than limit webhooks are defined then Box returns the webhooks in batches. When the results are batched, Box sends limit webhooks along with a next_marker field in the response object. The value of the next_marker field is a marker string that you can use in later requests to tell Box which batch to send next.

When you send a request that includes a marker string, Box sends the next batch of webhooks, beginning after the last webhook of the previous batch. When the response contains the last of the defined webhooks, Box omits the next_marker field from its response.

You can use limit and marker together with the marker string returned in the next_marker field to paginate lists of webhooks.

Request

Returns

Returns a response object. The response object has the following structure:

{
  "entries": "AN_ARRAY_OF_WEBHOOKS",
  "limit": "AN_INTEGER",
  "next_marker": "A_MARKER_STRING"
}

See the "Usage" section above for explanations of the limit and next_marker fields.

Errors

Insufficient permissions
Signaled if you lack permission to access webhooks for the application.

curl https://api.box.com/2.0/webhooks?limit=3&marker=A_STRING \
-H "Authorization: Bearer ACCESS_TOKEN"
-H Cache-Control: no-cache

Response

{
  "entries": [
    {
      "id": "4161",
      "type": "webhook",
      "target": {
        "id": "5018326685",
        "type": "folder"
      }
    },
    {
      "id": "4165",
      "type": "webhook",
      "target": {
        "id": "5016243669",
        "type": "file"
      }
    }
  ],
  "limit": 3
}

Update Webhook

 
put/webhooks/ID

Body JSON

address
string

The notification URL to which Box sends messages when monitored events occur.

triggers
array

An array of event names identifying the events that will trigger notification.

 

Returns

Returns the updated webhook object.

Errors

Address invalid
Signaled if the notification URL is not valid. The notification URL must be an HTTPS URL that resolves to a valid IP address that is accessible from the Internet, and which is not a Box address.

Event name invalid
Signaled if the event name is unrecognized or unsupported.

Unsupported target type
Signaled if the event type is not supported on the target object's type. For example, you can set or update a FILE.UPLOADED webhook on a folder, but not on a file.

Request

curl https://api.box.com/2.0/webhooks/{ID} \
-H "Authorization: Bearer j1hwkAMi7B2wUZaDjjFmYxW47quHbzKc" \
-d '{ "address": "https://notification.example.net", "triggers":  ["FILE.PREVIEWED", "FILE.DOWNLOADED"]}' \
-X PUT

Response

{
  "id": "4133",
  "type": "webhook",
  "target": {
    "id": "1000605797",
    "type": "folder"
  },
  "created_by": {
    "type": "user",
    "id": "2030392653",
    "name": "John Q. Developer",
    "login": "john2@example.net"
  },
  "created_at": "2016-05-04T18:51:17-07:00",
  "address": "https://notification.example.net",
  "triggers": [
    "FILE.PREVIEWED", "FILE.DOWNLOADED"
  ]
}

Delete Webhook

 
delete/webhooks/ID
 

Returns

204 No Content

Errors

Webhook ID not found
Signaled if no webhook exists with the supplied ID.

Insufficient permissions
Signaled if you lack permission to delete the webhook.

Request

curl https://api.box.com/2.0/webhooks/{ID} \
-H "Authorization: Bearer j1hwkAMi7B2wUZaDjjFmYxW47quHbzKc" \
-X DELETE

User Object

 

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. Italicized attributes are not returned by default and must be retrieved through the fields parameter.

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.

The language of this user.

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.

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.

role

string

This user’s enterprise role. Can be admin, coadmin, or user.

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.

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.

hostname

string

The root (protocol, subdomain, domain) of any links that need to be generated for this 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"
    ]
}
{
        "type": "user",
        "id": "181216415",
        "name": "sean rose",
        "login": "sean+awesome@box.com"
}

Create User

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

 
post/users

Body JSON

login
string
required

The email address this user uses to login

name
string
required

The name of this user

role
string

This user’s enterprise role. Can be coadmin or user

language
string

The language of this user

is_sync_enabled
boolean

Whether or not this user can use Box Sync

job_title
string

The user’s job title

phone
string

The user’s phone number

address
string

The user’s address

space_amount
integer

The user’s total available space amount in bytes

tracking_codes
array

An array of key/value pairs set by the user’s admin

can_see_managed_users
string

Can be active, inactive, cannot_delete_edit, or cannot_delete_edit_upload.

timezone
string

The timezone of this user

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

 

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.

Request

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

Results

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

Get Current User

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

 
get/users/me
 

Returns

Returns a single complete user object.

Request

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

Results

{
    "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://app.box.com/api/avatar/large/17738362"
}

Get User's Info

Retrieves information about a user in the enterprise. Requires enterprise administration authorization.

 
get/users/USER_ID
 

Returns

Returns a single complete user object.

Note:

The GET /users{id} endpoint also returns a limited set of information for external users who are collaborated on content owned by the enterprise for certain admin scopes/users. Disallowed fields will return null.

Request

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

Results

{
    "type": "user",
    "id": "10543463",
    "name": "Arielle Frey",
    "login": "ariellefrey@box.com",
    "created_at": "2011-01-07T12:37:09-08:00",
    "modified_at": "2014-05-30T10:39:47-07:00",
    "language": "en",
    "timezone": "America/Los_Angeles",
    "space_amount": 10737418240,
    "space_used": 558732,
    "max_upload_size": 5368709120,
    "status": "active",
    "job_title": "",
    "phone": "",
    "address": "",
    "avatar_url": "https://blosserdemoaccount.app.box.com/api/avatar/large/10543465"
}

Get Enterprise Users

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

 
get/users

Query Params

filter_term
string

A string used to filter the results to only users starting with the filter_term in either the name or the login.

limit
integer

The number of records to return. The default is 100 and the max is 1000.

offset
integer

The record at which to start. The default is 0.

user_type
string

The type of user to search for. Valid values are all, external or managed. If nothing is provided, the default behavior will be managed only

 

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.

Note:

The user_type only applies when also including the login as a filter. It should also be noted that for external users, we will only be matching against login (not name) and will only be doing full matches, no partial matches (so if I call /users?filter_term=joy@box&user_type=external, it will not return joy@box.com).

If the user passes in all, it will return any exact match for external users in addition to partial matches for managed users (but again, only exact login matches for external users).

Note:

For external user, the endpoint will return null for all fields except type, id, name, login, language, timezone, avatar_url, enterprise (if requested via fields).

Request

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

Results

{
    "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://app.box.com/api/avatar/large/181216415"
        }
    ]
}

Update User

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

 
put/users/USER_ID

Body JSON

notify
boolean

Whether the user should receive an email when they are rolled out of an enterprise

enterprise
string

Setting this to null will roll the user out of the enterprise and make them a free user. When passing a null value, do not pass this value as a string.

name
string

The name of this user

role
string

This user’s enterprise role. Can be coadmin or user

language
string

The language of this user

is_sync_enabled
boolean

Whether or not this user can use Box Sync

job_title
string

The user’s job title

phone
string

The user’s phone number

address
string

The user’s address

space_amount
integer

The user’s total available space amount in byte. A value of -1 grants unlimited storage.

tracking_codes
array

An array of key/value pairs set by the user’s admin

can_see_managed_users
boolean

Whether this user can see other enterprise users in its contact list

status
string

Can be active, inactive, cannot_delete_edit, or cannot_delete_edit_upload.

timezone
string

The timezone of this user.

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

is_password_reset_required
boolean

Whether or not the user is required to reset password

 

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.

Request

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

Results

{
    "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 User

Deletes a user in an enterprise account.

 
delete/users/USER_ID

Body JSON

notify
boolean

Determines if the destination user should receive email notification of the transfer.

force
boolean

Whether or not the user should be deleted even if this user still own files.

 

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.

Request

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

Invite User

Invites an existing user to join an Enterprise. The existing user can not be part of another Enterprise and must already have a Box account. Once invited, the user will receive an email and prompt to accept the invitation within the Box web application. This method requires the "Manage An Enterprise" scope for the enterprise, which can be enabled within your developer console.

 
post/invites

Body JSON

enterprise
required

The enterprise the user will be invited to

id
integer
required

Child of enterprise. The enterprise ID

actionable_by
required

The user that will receive the invitation

login
string
required

Child of actionable_by. The login of the user that will receive the invitation

 

Returns

A new invite object will be returned if successful. The status of the invite can also be queried by retrieving the invite object. This can be done by making a GET request to /invites/{invite_id}.

Request

curl https://api.box.com/2.0/invites \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{ "enterprise" : { "id" : "42500" } , "actionable_by" : { "login" : "freeuser@box.com" } }' \
-X POST

Results

{
    {
    "type": "invite",
    "id": "238632",
    "invited_to": {
        "type": "enterprise",
        "id": "42500",
        "name": "Blosser Account"
    },
    "actionable_by": {
        "type": "user",
        "id": "229667663",
        "name": "Lleyton Hewitt",
        "login": "freeuser@box.com"
    },
    "invited_by": {
        "type": "user",
        "id": "10523870",
        "name": "Ted Blosser",
        "login": "ted@box.com"
    },
    "status": "pending",
    "created_at": "2014-12-23T12:55:53-08:00",
    "modified_at": "2014-12-23T12:55:53-08:00"
}

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

 
put/users/USER_ID/folders/FOLDER_ID

Body JSON

owned_by
required

The user who the folder will be transferred to

id
string
required

Child of owned_by. The ID of the user who the folder will be transferred to

notify
boolean

Determines if the destination user should receive email notification of the transfer.

 

folder_id:

Currently only moving of the root folder (0) is supported.

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.

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

Results

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

Change User's Login

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

 
put/users/USER_ID

Body JSON

login
string
required

The email alias to become the primary email

 

Returns

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

Request

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

Results

{
    "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 Email Aliases

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.

 
get/users/USER_ID/email_aliases
 

Returns

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

Request

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

Results

{
    "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 Email Alias

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

 
post/users/USER_ID/email_aliases

Body JSON

email
string
required

The email address to add to the account as an alias

 

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.

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

Results

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

Delete Email Alias

Removes an email alias from a user.

 
delete/users/USER_ID/email_aliases/EMAIL_ALIAS_ID
 

Returns

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

Request

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

Group Object

 

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.

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

provenance

string

Keeps track of which external source this group is coming from (e.g. "Active Directory", "Google Groups", "Facebook Groups"). This should be a human-readable identifier up to 255 characters long. Setting this will also prevent Box users from editing this group directly through Box. This is desirable for one-way syncing of groups. Needs to be accessed via the fields parameter.

external_sync_identifier

string

An arbitrary identifier that can be used by external group sync tools to link this Box Group to an external group. Example values of this field could be an Active Directory Object ID or a Google Group ID. We recommend use of this field in order to avoid issues when group names are updated in either Box or external systems. Needs to be accessed via the fields parameter.

description

string

Human readable description of this Group. This can be up to 255 characters long. Needs to be accessed via the fields parameter.

invitability_level

string

Specifies who can invite this group to collaborate on folders (Create Collaboration).

admins_only Master Admin, Coadmins, group's Group Admin.

admins_and_members Admins listed above and group members.

all_managed_users All managed users in the enterprise.

member_viewability_level

string

Specifies who can view the members of this group (Get Memberships for Group).

admins_only Master Admin, Coadmins, group's Group Admin.

admins_and_members Admins and group members.

all_managed_users All managed users in the enterprise.

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

Create Group

Used to create a group.

 
post/groups

Body JSON

name
string
required

The name of the new group to be created

provenance
string

Typically used to track the external source where the group is coming from. Retrieved through the fields parameter.

external_sync_identifier
string

Typically used as a group identifier for groups coming from an external source. Retrieved through the fields parameter.

description
string

Description of the group. Retrieved through the fields parameter.

invitability_level
string

Specifies who can invite this group to folders. Retrieved through the fields parameter.

member_viewability_level
string

Specifies who can view the members of this group. Retrieved through the fields parameter.

 

Returns

A new group object will be returned upon success.

Request

curl https://api.box.com/2.0/groups \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name": "Box Employees", "provenance": "Google", "external_sync_identifier": "Google-Box-Users", "description": "All box Users", "invitability_level": "admins_and_members", "member_viewability_level": "admins_only"}' \
-X POST

Results

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

Get Group

Used to get information about a group.

 
get/groups/GROUP_ID
 

Returns

A group object that was requested.

Request

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

Results

{
    "type": "group",
    "id": "255224",
    "name": "Everyone",