The Box API gives you access to a set of secure content management features for use in your own app, such as file storage, preview, search, commenting, and metadata. It strives to be RESTful and is organized around the main resources from the Box web interface.

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

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

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

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

Getting Help

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

Suggest Edits

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.

Note

User creation, comment, collaboration creation, change user's login, and task assignment notifications cannot be suppressed using this header.

CORS, or cross-origin resource sharing, is a mechanism that allows a web page to make XMLHttpRequests to another domain (i.e. a domain different from the one it was loaded from). CORS is supported in a specific set of modern browsers. The Box API supports CORS on an app-by-app basis. You can add a comma separated list of origins that can make CORS requests to the API, through the developer console.

A quick tutorial can be found here.

CORS-Like Errors

Some browsers will return a CORS-like error, even when CORS is enabled for your application. In these scenarios, an HTTP response code will often be included (e.g. 400 or 401) which will provide further direction where you may want to focus troubleshooting. No further CORS enablement is done in the Box backend.

Suggest Edits

Pagination

 

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

Offset-based Paging

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

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

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

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

Query Parameters:

offset

integer

The 0-based offset of the first entry to return. The default is 0.

limit

integer

The maximum number of entries to return. Each API has a default and maximum value. If the value exceeds the maximum, then the maximum value will be used and returned in the limit field in the response.

Response Object:

entries

array

The array of objects for the current set of results. It will be an empty array if there are no results.

offset

integer

The 0-based offset of the first entry in this set. This will be the same as the offset query parameter.

limit

integer

The limit that was used for these entries. This will be the same as the limit query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.

total_count

integer

One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than total_count.

Marker-based Paging

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

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

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

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

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

Query Parameters:

marker

string

The position to return results from. This should be a value that was returned in next_marker in a previous call to this API.

limit

integer

The maximum number of entries to return. Each API has a default and maximum value. If the value exceeds the maximum, then the maximum value will be used and returned in the limit field in the response.

Response Object:

entries

array

The array of objects for the current set of results. It will be an empty array if there are no results.

next_marker

string

The value to pass as the marker query parameter to fetch the next set of entries. If the next_marker field is not present or equal to null or "" then there are no more entries.

limit

integer

The limit that was used for these entries. This will be the same as the limit query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.

Suggest Edits

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

A specific Box error code listed here

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": "item_name_in_use",
  "context_info": {
    "conflicts": [
      {
        "type": "folder",
        "id": "871642494",
        "sequence_id": "0",
        "etag": "0",
        "name": "New Folder"
      }
    ]
  },
  "help_url": "http://developers.box.com/docs/#errors",
  "message": "Item with the same name already exists",
  "request_id": "170397861659135cc65a65"
}

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

409

operation_blocked_temporary

The operation is blocked by another ongoing operation.

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. There are two limits. The first is a limit of 10 API calls per second per user. The second limit is 4 uploads per second per user.

500

internal_server_error

Internal Server Error

503

unavailable

Unavailable

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

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

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

EXAMPLE REQUEST

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

Supported APIs

The fields parameter is not supported for the GET /events, POST /files/content, and POST /files/{id}/content APIs.

Suggest Edits

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 are listed below). 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 /folders/{id}

IF-NONE-MATCH SUPPORTED METHODS

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

As-User

The As-User header is used by enterprise administrators to make API calls for their managed users. It can also be used by a Service Account to make API calls for managed users or app users.

You will have to 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, a Co-admin, or a Service Account to be successful.

To enable this functionality for applications using OAuth2, please file a support ticket with your API key.

To enable this functionality for applications using OAuth2 with JWT, please navigate to the Advanced Features section in the developer console and enable the "Perform actions on behalf of users" permission.

 

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 (with standard OAuth 2.0)

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

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.

There are two limits. The first is a limit of 10 API calls per second per user. The second limit is 4 uploads per second per user.

 

RETRY HEADER

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

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

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

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

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

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

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

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

OAuth Endpoint

The HTTP endpoint for Box authentication is:

https://api.box.com/oauth2

Authorization Header

Following in the format of a Box authorization header:

Authorization: Bearer <MY_ACCESS_TOKEN>

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

Suggest Edits

Authorize

 

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

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

https://account.box.com/api/oauth2/authorize?response_type=code&client_id=<MY_CLIENT_ID>&redirect_uri=<MY_REDIRECT_URL>&state=<MY_SECURITY_TOKEN>

This request passes the following parameters:

Parameter
Type
Description

response_type

String

The type of OAuth 2 grant you are requesting. Use the value code.

client_id

String

The client ID of the application requesting authentication. To get the client ID for your application, log in to your Box developer console and click the Edit Application link for the application you're working with. In the OAuth 2 Parameters section of the configuration page, find the item labeled "client_id". The text of that item is your application's client ID.

redirect_uri

URI

The URL to which Box redirects the browser when authentication completes. The user's actual interaction with your application begins when Box redirects to this URL. You must supply the redirect URL in the configuration page of your application. It must be a valid HTTPS URL that resolves to a valid IP address. The IP address must not be a Box address, and there must be a working web service or application accessible at the address that can correctly handle Box requests.

state

String

A text string that you choose. Box sends the same string to your redirect URL when authentication is complete. This parameter is provided for your use in protecting against hijacked sessions and other attacks.

scope optional

String

This optional parameter identifies the Box scopes available to the application once it's authenticated. If you don't supply this parameter then Box grants access to the default scopes configured for the application in its configuration page. You can limit the scopes available to the application by passing a space delimited list of Box scopes.

Note

The authorize endpoint uses a different URL from other Box API calls: account.box.com/api instead of api.box.com.

Example

Using the Authorize URL

https://account.box.com/api/oauth2/authorize?response_type=code&client_id=MY_CLIENT_ID&redirect_uri=MY_REDIRECT_URL&state=security_token%3DKnhMJatFipTAnM0nHlZA

Example Response

<MY_REDIRECT_URL>?code=<AUTHORIZATION_CODE>

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

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

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

curl https://api.box.com/oauth2/token \
-d 'grant_type=authorization_code' \
-d 'code=<MY_AUTH_CODE>' \
-d 'client_id=<MY_CLIENT_ID>' \
-d 'client_secret=<MY_CLIENT_SECRET>' \
-X POST
const grantType = 'authorization_code';
const code = '<MY_AUTH_CODE>';
const clientId = '<MY_CLIENT_ID>';
const clientSecret = '<MY_CLIENT_SECRET>';

fetch('https://api.box.com/oauth2/token', {
  method: 'POST',
  body: `grant_type=${grantType}&code=${code}&client_id=${clientId}&client_secret=${clientSecret}`,
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8'
  }
})

The parameters used in this request are as follows:

Parameter
Type
Description

grant_type

String

authorization_code

code

String

The authorization code returned by Box in response to a successfull authentication request.

client_id

String

The client ID of the application requesting authentication. To get the client ID for your application, log in to your Box developer console and click the Edit Application link for the application you're working with. In the OAuth 2 Parameters section of the configuration page, find the item labeled "client_id". The text of that item is your application's client ID.

client_secret

String

The client secret of the application requesting authentication. To get the client secret for your application, log in to your Box developer console and click the Edit Application link for the application you're working with. In the OAuth 2 Parameters section of the configuration page, find the item labeled "client_secret". The text of that item is your application's client secret.

Example

Using the Token URL

curl https://api.box.com/oauth2/token \
-d 'grant_type=authorization_code' \
-d 'code=<MY_AUTH_CODE>' \
-d 'client_id=<MY_CLIENT_ID>' \
-d 'client_secret=<MY_CLIENT_SECRET>' \
-X POST

Example Response

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

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

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

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

curl https://api.box.com/oauth2/revoke \
-d 'client_id=MY_CLIENT_ID' \
-d 'client_secret=MY_CLIENT_SECRET' \
-d 'token=MY_TOKEN' \
-X POST

The parameters sent with this request are as follows:

Parameter
Type
Description

client_id

String

The client ID of the application requesting revocation. To get the client ID for your application, log in to your Box developer console and click the Edit Application link for the application you're working with. In the OAuth 2 Parameters section of the configuration page, find the item labeled "client_id". The text of that item is your application's client ID.

client_secret

String

The client secret of the application requesting authentication. To get the client secret for your application, log in to your Box developer console and click the Edit Application link for the application you're working with. In the OAuth 2 Parameters section of the configuration page, find the item labeled "client_secret". The text of that item is your application's client secret.

token

String

An access token or refresh token supplied by Box in response to a token request. When either token is supplied with this request, both will be revoked.

Suggest Edits

Downscope Token

A mechanism to exchange a "parent token" for a more granularly-scoped "child token."

 

Token Exchange is a mechanism to exchange a parent token (Managed/App User, Service Account or App Token) for a child token, which is scoped down to the the minimum set of required permissions so it can be securely sent down to the client without elevating client privileges.

The primary use case for Token Exchange is to generate lower-scoped tokens for a client making an API request acting on a resource such as a file or folder. For example, if you are leveraging the Box UI Elements in your application, you'll need to pass an access token to the client. However, a child token can also be used server-side if your application needs to grant access to a less secure or untrusted service.

Token Exchange is a new grant_type in the that is supported by Box's standard Token endpoint of the Box Content API. This grant_type takes in the "parent token", a list of scopes, and optionally a file/folder ID as the input arguments, and returns a token that is scoped down to those exact set of scopes and the respective file/folder ID, if present in the input arguments.

<br />How the Token Exchange API works


How the Token Exchange API works

Token Exchange can be used via a request to Box's standard Token endpoint, as shown below:

curl https://api.box.com/oauth2/token \
-d 'subject_token=PARENT_TOKEN' \
-d 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \
-d 'scope=item_upload item_preview base_explorer' \
-d 'resource=https://api.box.com/2.0/folders/123456' \
-d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
-X POST

The parameters used in this request are as follows:

Parameter
Type
Description

subject_token

Required

string

Fully-scoped access token. This can be an OAuth (Managed User), JWT (App User or Service Account) or an App Token (New Box View) token.

subject_token_type

Required

string

Always set to: “urn:ietf:params:oauth:token-type:access_token”

scope

Required

string

Scope or scopes that you want to apply to the resulting token. Requested by a space-delimited string.

Here you can find all scopes that Box currently supports.

If you are using Token Exchange for Box UI Elements, we have Special Scopes for the Box UI Elements that we recommend using.

Note: you need to make sure that all scopes requested as part of the Token Exchange call are contained in the parent token. Else, the call will error with a 401.

resource

Optional

string

Full url path to the file that the token should be generated for, eg: "https://api.box.com/2.0/files/{file_id}”

grant_type

Required

string

Always: “urn:ietf:params:oauth:grant-type:token-exchange”

The Token endpoint of the Box Content API will generate the following response.

{
    "access_token": "1!OhzmV1rtsxHwyLIlaooRQII470kDPC_1UZ-77oZosPSV55lxPThEl3PfsIqdmUoLu9z8cb3MvIWIhmfr7c7VsTQhZhBJLgG7fDhjtdK8wlq0wtPHlyBXqQf2pMLK1cWegkI2Fj4ECqYBO-mCPMQ2UyWmlBXY_jVusczOqG1AorkRejsKEjblDd0sW-7scFPjQlaVw1qGmoADp5Z7Q2n3lBzZtPMfJb334wCVmSfjt_iQIByFVJpR3Vuq4ICkQGt0M1ly7tdfafr6CAcNT5lPN_DHa7k_ZtsbQQSiO4ZE6bIVa2fZnlVmBjFohqnT_Ahpl-kbHngYT8ISGkIEgXGduxH5KVRg6QTVdlH8bXBjinj3GHwi2KOiTDCp5i75pzeffUE77Sfy97YCN2EvcdqcblSnd_pvCBBGIjtuM_K4HkTk0SC5sZg_9EhJayPEOg82",
    "expires_in": 3964,
    "token_type": "bearer",
    "restricted_to": [
        {
            "scope": "item_preview",
            "object": {
                "type": "file",
                "id": "5391641209",
                "file_version": {
                    "type": "file_version",
                    "id": "619573369",
                    "sha1": "c85ef6489c090ff71cda537bfbac47f1df721bba"
                },
                "sequence_id": "0",
                "etag": "0",
                "sha1": "c85ef6489c090ff71cda537bfbac47f1df721bba",
                "name": "finland.JPG"
            }
        },
        {
            "scope": "item_upload",
            "object": {
                "type": "file",
                "id": "5391641209",
                "file_version": {
                    "type": "file_version",
                    "id": "619573369",
                    "sha1": "c85ef6489c090ff71cda537bfbac47f1df721bba"
                },
                "sequence_id": "0",
                "etag": "0",
                "sha1": "c85ef6489c090ff71cda537bfbac47f1df721bba",
                "name": "finland.JPG"
            }
        }
    ],
    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

Scopes

Any scope that exists on the subject token can be requested in the scope parameter of the request. A strict subset of scopes must be requested, meaning the subject token must contain a larger set of scopes than those requested in the token exchange, a subject token cannot be exchanged for another token with the exact same set of scopes.

The root_readwrite scope, available on all applications, is a natural super set of permissions allowing a developer to view, edit, and delete a file or folder. This scope can be reduced to item-specific scopes. The table below shows the scopes available for exchange when root readwrite is set as a scope on the subject token.

Parent Scope
Available Scopes

root_readwrite

item_read
item_readwrite
item_preview
item_upload
item_share
item_delete
item_download

Suggest Edits

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

file

id

string

The ID of the file object

file_version

object

The version information of the file

sequence_id

string

A unique ID for use with the /events endpoint

etag

string

The entity tag of this file object. Used with If-Match headers.

sha1

string

The SHA-1 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

object

The path of folders to this item, starting at the root

created_at

date-time

When this file was created on Box’s servers

modified_at

date-time

When this file was last updated on the Box servers. This is a read-only field.

trashed_at

date-time

When this file was last moved to the trash

purged_at

date-time

When this file will be permanently deleted

content_created_at

date-time

When the content of this file was created (more info)

content_modified_at

date-time

When the content of this file was last modified (more info). This is a read-only field.

created_by

mini user object

The user who first created this 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. Will be null if no shared link has been created.

parent

mini folder object

The folder containing this file

item_status

string

Whether this item is deleted or not. Values include active, trashed if the file has been moved to the trash, and deleted if the file has been permanently deleted

version_number

string

The version number of this file

comment_count

integer

The number of comments on this file

permissions

object

An object containing the permissions that the current user has on this file. The keys are can_download, can_preview, can_upload, can_comment, can_rename, can_invite_collaborator,can_delete, can_share, and can_set_share_access. Each key has a boolean value.

tags

array of strings

All tags applied to this file

lock

object

The lock held on this file. If there is no lock, this can either be null or have a timestamp in the past.

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.

watermark_info

object

Information about the watermark status of this file. See Watermarking for additional endpoints.

Fields:
is_watermarked (boolean): Whether the file is watermarked or not.

allowed_invitee_roles

array of strings

File collaboration roles allowed by the enterprise administrator.

is_externally_owned

boolean

Whether this file is owned by a user outside of the enterprise.

has_collaborations

boolean

Whether this file has any collaborators.

metadata.<scope>.<templateKey>

object

Specific metadata on the file, identified by scope and templateKey. The limit of metadata instances to be requested this way is 3.

{
    "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": "0",
    "type": "file",
    "id": "2631999573",
    "name":"IMG_1312.JPG"
}
Suggest Edits

Get File Info

Get information about a file.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id

Path Params

file_id
string
required

Query Params

fields
string

Comma-separated list of fields to include in the response

Note

The shared_link.download_url is only returned for paid accounts.

Returns

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

curl https://api.box.com/2.0/files/FILE_ID
-H "Authorization: Bearer 
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "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"
}
Suggest Edits

Download File

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

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/content

Path Params

file_id
string
required

Query Params

version
string

Optional file version ID to download (defaults to the current version)

Headers

Range
string

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

BoxApi
string

Use the format shared_link=SHARED_LINK_URL or shared_link=SHARED_LINK_URL&shared_link_password=PASSWORD

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.

Downloading a file using JavaScript in the browser

Due to the above 302 redirect, downloading via CORS is not supported. Browsers will fail to download the file using the above approach. However a workaround for this can be seen here https://codepen.io/box-platform/pen/dRqjbB

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

public class BoxFile

public URL getDownloadURL()

public void downloadRange(OutputStream output, long rangeStart, long rangeEnd, ProgressListener listener)

public void download(OutputStream output, ProgressListener listener)
Files.prototype.getDownloadURL = function(fileID, qs, callback)

Files.prototype.getReadStream = function(fileID, qs, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<Stream> DownloadStreamAsync(string id, string versionId = null, TimeSpan? timeout = null)
  
public async Task<Uri> GetDownloadUriAsync(string id, string versionId = null)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
Redirected to secured download at dl.boxcloud.com
Suggest Edits

Upload File

Use the Upload 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 SHA-1 hash of the file to ensure that the file is not corrupted in transit.

For large files (files above 50MB in size), we recommend using the Chunked Uploads API.

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

Body Params

name
string
required

The name of the file

parent
object
parent.id
string
required

The ID of the parent folder. Use "0" for the root folder.

content_created_at
date-time

The creation date of the file. See content times for formatting.

content_modified_at
date-time

The last modification date of the file

Headers

Content-MD5
string

The SHA-1 hash of the file

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

Returns

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

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

Name Collision

If you receive a name collision you can use the SHA-1 that is returned with the file to check if the existing file is identical to the one you are trying to upload.

Upload Limits

Upload limits are dictated by the type of account you have. More information can be found here

Note

The "attributes" (JSON) part must come before the file part of the multipart form data.

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

public class BoxFolder

public BoxFile.Info uploadFile(FileUploadParams uploadParams)
Files.prototype.uploadFile = function(parentFolderID, filename, content, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxFile> UploadAsync(BoxFileRequest fileRequest, Stream stream, List<string> fields = null, TimeSpan? timeout = null, byte[] contentMD5 = null, bool setStreamPositionToZero = true, Uri uploadUri = null)
  
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "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"
        }
    ]
}
Suggest Edits

Upload File Version

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, you can specify a new name for the file in the POST by setting the name field in the body.

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

Path Params

file_id
string
required

Body Params

name
string

An optional new name for the file. If specified, the file will be renamed when the new version is uploaded.

content_modified_at
date-time

The last modification date of the file version. See content times for formatting.

Headers

If-Match
string

The etag field of the file object

Content-MD5
string

The SHA-1 hash of the file version

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

Note that upload requests are processed by https://upload.box.com.

When uploading a new file version that has a different file type, use the name field to update the file extension. For example, when uploading Image.jpg as a new version of Image.png.

curl https://upload.box.com/api/2.0/files/FILE_ID/content \
-H "Authorization: Bearer " \
-H "If-Match: ETAG_OF_ORIGINAL" \
-F file=@FILE_NAME
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
  "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"
    }
  ]
}
Suggest Edits

Chunked Upload

 

This API provides a way to reliably upload large files to Box by chunking them into a sequence of parts. When using this API instead of the single file upload API, a request failure means a client only needs to retry upload of a single part instead of the entire file. Parts can also be uploaded in parallel allowing for potential performance improvement.

Overview

A client creates an upload session, uploads chunks of the file to that session, then commits the session to finally create the file in Box.

The Chunked Upload API is intended for large files with a minimum size of 20MB.

This API does not support re-uploading or overwriting of parts in a session. Once a part has been uploaded, it is immutable.

The lifetime of an upload session is 7 days. During this time, the client can upload parts at their own pace. For example, they may upload some parts, pause for a while due to interrupted connectivity, then resume uploading parts a few hours later. To avoid wasting resources, and avoid potential data corruption, a client should make sure that the underlying file has not been changed on disk since beginning the upload.

Common Errors

These are errors that may be returned from any chunked upload API request

Status Code
Description

400 Bad Request

Check extended error message in body for more details.

401 Unauthorized

Authorization token is not authorized, check extended error message in body for more details.

403 Forbidden

Client does not have permission to upload to this session. Only the user who initiated the upload session may upload to it.

404 Not Found

Can’t find upload session with given upload session ID. Check extended error message in body for more details.

410 Gone

The upload session is in an unrecoverable failed state and cannot continue. Check extended error message in body for details.

411 Length Required

Content-Length header was required, but not provided.

429 Too Many Requests

Client is performing operations too quickly and has been rate limited. Client is advised to retry their request after the amount of time specified by the Retry-After header.

500 Internal Server

Client should retry using exponential back-off strategy

502 Bad Gateway

Client should retry using exponential back-off strategy

503 Service Unavailable

Client should retry using exponential back-off strategy

The client is advised to retry on 5XX status codes till they get a valid success/error response, exponential back-off should be used in retries. Server disconnects should be handled as 5XX and get retried.

Extended Error Information

In some scenarios, an extended error code will be sent in a JSON body format with a more detailed error reason. For example:

{
	"code":  "something",
	"message":  "blah",
	"context_info": {
		/* Optional. Stuff specific to the individual error */
	},
	"request_id": "abcdef"
}

The following table contains descriptions of each of the JSON fields in the error message body.

Field Name
Type
Description

code

String

One of the codes from the error tables throughout this spec.

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.

context_info

Object

Optional. Additional context information describing the error. Unlike message, this is intended to be machine readable.

The contents of this object are specific to the type of error specified by code.

The following table contains extended errors that can be returned from any chunked upload API request. Errors specific to a specific API endpoint are listed in the documentation for that endpoint.

HTTP Status Code
Code
Description

400 Bad Request

invalid_upload_session_id

The upload session ID provided in the URL is not of a valid format.

404 Not Found

not_found

No session was found for the given upload session ID.

410 Gone

session_expired

The upload session associated with the given upload session ID has expired and can no longer be accessed.

410 Gone

upload_failed

The upload session is in an unrecoverable failed state and cannot continue. This or other requests have resulted in the upload session reaching a bad state (e.g. parts overlapping). Possible situations where this may arise:

  • Maximum number of parts has been exceeded
  • Overlapping parts have been uploaded
Suggest Edits

Create Session: New File

Create an upload session for uploading a new file.

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

Body Params

folder_id
string

A JSON string. folder_id is the id of the folder that will contain the new file. Required when uploading a new file. Prohibited when uploading a new version.

file_size
int32

A JSON number. Required. The total number of bytes in the file to be uploaded.

file_name
string

A JSON string. Name of new file. Required when uploading a new file. Optional when uploading a new version. If provided for a new version upload, the file name will be changed to this value upon successful upload.

Headers

Authorization
string

Required. The access token that will be used to authorize the request

Content-Type
string

Error status codes:

The following error status codes can be returned from the service:

Status Code
Description

409 Conflict

Check extended error message for details

412 Precondition Failed

Check extended error message for details

413 Request entity too large

If request bytes are more than allowed range. See extended error message for details.

Error response body

In some scenarios, an extended error code will be sent in a JSON body format with a more detailed error reason.

HTTP Status Code
Code
Description

400 Bad Request

missing_destination

No file_id or folder_id was provided

400 Bad Request

multiple_destinations

Both file_id and folder_id were provided

400 Bad Request

invalid_folder_id

Folder_id is invalid

400 Bad Request

invalid_file_name

File name is invalid

400 Bad Request

missing_file_size

file_size was not provided

400 Bad Request

invalid_file_size

file_size was not a valid number

400 Bad Request

file_size_too_small

file_size is below minimum file size for uploads via this API

400 Bad Request

missing_file_name

file_name was not provided for new file upload

Remarks

The request body is JSON (Content-Type: application/json)

All future requests for this upload session must come from the same user that made this request.

This API also performs the preflight check described by https://developer.box.com/reference#preflight-check. Any error response from the preflight check will be proxied directly as the response of the create session request, and not result in the creation of a new session.

This request takes in information about the file, but does not actually create any file record in Box. The file only exists in Box after a successful “commit” request.

curl -i -X POST https://upload.box.com/api/2.0/files/upload_sessions \
-H "authorization: Bearer fEw9FPUVT3SJGaSBu4Q07VFyqdYd3ODc" \
-H "Content-Type: application/json" \
-d '{ "folder_id": "0", "file_size": 100000000, "file_name": "Upload Session API example"}'# This is part 1 of 4 example commands to use the Chunked Uploads endpoint. Please run them in order. 
# Cache token so commands are easier to paste
TOKEN=<your developer token>

# Create session for a 20MB upload and write the response to a file.
# Output is printed twice, once raw with headers, and once pretty printed with jq.
# NOTE: jq 1.5 or later is required (https://stedolan.github.io/jq/)
curl -i -X POST https://upload.box.com/api/2.0/files/upload_sessions \
 -H "authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Expect:" \
-d "{ \"folder_id\": \"0\", \"file_size\": 20000000, \"file_name\": \"chunked-uploads-api-test `date`\"}" \
-o /tmp/create_session_response \
&& cat /tmp/create_session_response \
&& jq -R 'fromjson?' /tmp/create_session_response
curl -i -X POST https://upload.box.com/api/2.0/files/upload_sessions \
-H "authorization: Bearer fEw9FPUVT3SJGaSBu4Q07VFyqdYd3ODc" \
-H "Content-Type: application/json" \
-d '{ "folder_id": "0", "file_size": 100000000, "file_name": "Upload Session API example"}'
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
HTTP/1.1 201 Created
Date: Mon, 10 Apr 2017 22:24:58 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 795
Connection: keep-alive

{
  "total_parts": 3,
  "part_size": 8388608,
  "session_endpoints": {
    "list_parts": "https://upload.box.com/api/2.0/files/upload_sessions/D5E3F7ADA11A38F0A66AD0B64AACA658/parts",
    "commit": "https://upload.box.com/api/2.0/files/upload_sessions/D5E3F7ADA11A38F0A66AD0B64AACA658/commit",
    "log_event": "https://upload.box.com/api/2.0/files/upload_sessions/D5E3F7ADA11A38F0A66AD0B64AACA658/log",
    "upload_part": "https://upload.box.com/api/2.0/files/upload_sessions/D5E3F7ADA11A38F0A66AD0B64AACA658",
    "status": "https://upload.box.com/api/2.0/files/upload_sessions/D5E3F7ADA11A38F0A66AD0B64AACA658",
    "abort": "https://upload.box.com/api/2.0/files/upload_sessions/D5E3F7ADA11A38F0A66AD0B64AACA658"
  },
  "session_expires_at": "2017-11-09T21:59:16Z",
  "id": "D5E3F7ADA11A38F0A66AD0B64AACA658",
  "type": "upload_session",
  "num_parts_processed": 0
}
HTTP/1.1 201 Created
Date: Mon, 10 Apr 2017 22:24:58 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 795
Connection: keep-alive

{
    "total_parts": 2,
    "part_size": 8388608,
    "session_endpoints": {
        "list_parts": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts",
        "commit": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit",
        "upload_part": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
        "status": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
        "abort": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD"
    },
    "session_expires_at": "2017-04-18T01:45:15Z",
    "id": "F971964745A5CD0C001BBE4E58196BFD",
    "type": "upload_session",
    "num_parts_processed": 0
}
Suggest Edits

Create Session: New Version

Create an upload session for uploading a new file version.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/files/fileid/upload_sessions

Path Params

file_id
string
required

Body Params

file_size
int32

A JSON number. Required. The total number of bytes in the file to be uploaded.

file_name
string

A JSON string. Name of new file. Required when uploading a new file. Optional when uploading a new version. If provided for a new version upload, the file name will be changed to this value upon successful upload.

Headers

Authorization
string

Required. The access token that will be used to authorize the request

Content-Type
string

Error status codes:

The following error status codes can be returned from the service:

Status Code
Description

409 Conflict

Check extended error message for details

412 Precondition Failed

Check extended error message for details

413 Request entity too large

If request bytes are more than allowed range. See extended error message for details.

Error response body

In some scenarios, an extended error code will be sent in a JSON body format with a more detailed error reason.

HTTP Status Code
Code
Description

400 Bad Request

missing_destination

No file_id or folder_id was provided

400 Bad Request

multiple_destinations

Both file_id and folder_id were provided

400 Bad Request

invalid_folder_id

Folder_id is invalid

400 Bad Request

invalid_file_name

File name is invalid

400 Bad Request

missing_file_size

file_size was not provided

400 Bad Request

invalid_file_size

file_size was not a valid number

400 Bad Request

file_size_too_small

file_size is below minimum file size for uploads via this API

400 Bad Request

missing_file_name

file_name was not provided for new file upload

Remarks

The request body is JSON (Content-Type: application/json)

All future requests for this upload session must come from the same user that made this request.

This API also performs the preflight check described by https://developer.box.com/reference#preflight-check. Any error response from the preflight check will be proxied directly as the response of the create session request, and not result in the creation of a new session.

This request takes in information about the file, but does not actually create any file record in Box. The file only exists in Box after a successful “commit” request.

curl -X POST \
  https://upload.box.com/api/2.0/files/12345/upload_sessions \
-H "authorization: Bearer fEw9FPUVT3SJGaSBu4Q07VFyqdYd3ODc" \
-H "Content-Type: application/json" \
-d '{ "folder_id": "0", "file_size": 100000000, "file_name": "Upload Session API example"}'
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
HTTP/1.1 201 Created
Date: Mon, 10 Apr 2017 22:24:58 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 795
Connection: keep-alive

{
    "total_parts": 2,
    "part_size": 8388608,
    "session_endpoints": {
        "list_parts": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts",
        "commit": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit",
        "upload_part": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
        "status": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
        "abort": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD"
    },
    "session_expires_at": "2017-04-18T01:45:15Z",
    "id": "F971964745A5CD0C001BBE4E58196BFD",
    "type": "upload_session",
    "num_parts_processed": 0
}
Suggest Edits

Upload Part

Upload a part of the file to this session.

 
puthttps://upload.box.com/api/2.0/files/upload_sessions/sessionId

Path Params

[sessionId]
int32
required

Required. The session id of the upload session that this part belongs to. Upload session id can be created to initiate a chunked file upload by calling the create upload session API.

Headers

Authorization
string

Required. Access token to authorize the API.

Content-Type
string

Required. Should be Application/octet-stream

Digest
string

Required. The message digest of the part body, formatted as specified by RFC 3230. Currently only SHA-1 is supported. As per RFC 3230, the output from SHA-1 algorithm must be Base64 encoded.

Content-Range
string

Required. Byte range of part within overall file. Must not overlap with the range of a part already uploaded to this session.

Error status codes:

The following error status code can be returned from the service:

Status Code
Description

409 Conflict

Check extended error message for details

412 Precondition Failed

Check extended error message for details

413 Request entity too large

If request bytes are more than allowed range. See extended error information in response body for details

416 Requested Range Not Satisfiable

Check extended error message for details

Error response body

In some scenarios, an extended error code will be sent in a JSON body format with more a detailed error reason.

HTTP Status Code
Code
Description

400 Bad Request

missing_range

Content-Range header was not provided

400 Bad Request

invalid_range

Content-Range header was invalid. Possible reasons include:
The header value was not of proper format (proper format is e.g.: Content-Range: bytes 0-4194303/104857600)
Or
The length portion of the Content-Range doesn’t match the file size specified during session creation.

400 Bad Request

missing_digest

Digest header was expected, but not provided

400 Bad Request

invalid_digest

Digest header was not a valid format as per http://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml.
or
Digest header used algorithm other than SHA-1
or
Digest header did not provide a valid SHA-1.

400 Bad Request

request_size_mismatch

Size of request body contents does not match expectations from Content-Range header. It was either too small or too large.

400 Bad Request

digest_mismatch

The computed digest of the part body does not match the Digest header

400 Bad Request

out_of_bounds

The part's range does not sit within the file size specified in the create upload session request

Remarks

Part size
Each part’s size must be exactly equal in size to the part size specified in the response to the create session request. The last part of the file is exempt from this restriction and is allowed to be smaller.

Note that, as a result, the lower bound of Content-Range of each part upload request must be a multiple of part size.

If a part upload request fails with any error code except ‘range_overlaps_existing_part’, the client should assume that the part was not persisted to the session, and the range specified by Content-Range is still free.

In the case of 'range_overlaps_existing_part' error, the client is recommended to check whether the part object in context_info.conflicting_part field of the returned JSON is for the same byte range as the part the client attempted to upload. If so, the client should treat the part as having been already successfully uploaded and use the returned part information later on in the commit request.

The client is recommended to hang on to the JSON responses from all part upload requests and use them to build the request body for the commit request.

Parts SHOULD be uploaded in order (e.g. parts with lower byte offset before higher byte offset) as much as possible. Uploading multiple parts in parallel is fine. The recommended approach is to upload 3-5 parts in parallel from a queue of parts, ordered by byte offset. If a part upload fails, it should be retried before later parts (e.g. by adding it back to the FRONT of the queue).

# This is part 2 of 4 example commands to use the Chunked Uploads endpoint. Please run them in order. 
# Upload parts of size specified in create session response, until we've uploaded 20MB.
# File contents are read from /dev/zero
# NOTE: jq 1.5 or later is required (https://stedolan.github.io/jq/)
(
UPLOAD_SESSION_ID=`jq -R 'fromjson?' /tmp/create_session_response | jq -r '.id'`; \
PART_SIZE=`jq -R 'fromjson?' /tmp/create_session_response | jq '.part_size'`; \
UPLOAD_PART_URL=`jq -R 'fromjson?' /tmp/create_session_response | jq -r '.session_endpoints.upload_part'`; \
FROM=0; \
while (( FROM < 20000000 )); do
    let TO=FROM+PART_SIZE
    TO=$(($TO > 20000000 ? 20000000 : $TO))
    let LENGTH=TO-FROM
    let TO=TO-1

    dd if=/dev/zero of=/tmp/part bs=$LENGTH count=1
    SHA1_BASE64=`sha1sum /tmp/part | xxd -r -p | base64`

    curl -X PUT $UPLOAD_PART_URL \
    -H "authorization: Bearer $TOKEN" \
    -H "content-range: bytes $FROM-$TO/20000000" \
    -H "content-type: application/octet-stream" \
    -H "digest: sha=$SHA1_BASE64" \
    -H "Expect:" \
    --data-binary @/tmp/part >> /tmp/${UPLOAD_SESSION_ID}
    let FROM=FROM+PART_SIZE
done
cat /tmp/${UPLOAD_SESSION_ID} | jq -r
)
# Example request
# These examples upload the 2 parts of the 10MB file.  First we can create the files on our local file system:
# $ printf 'a%.0s' {1..8388608} > /tmp/part1
# $ printf 'b%.0s' {1..1611392} > /tmp/part2

# Part 1: 
curl -X PUT \ https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD \
  -H 'authorization: Bearer fEw9FPUVT3SJGaSBu4Q07VFyqdYd3ODc' \
  -H 'content-range: bytes 0-8388607/100000000' \
  -H 'content-type: application/octet-stream' \
  -H 'digest: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=' \
  --data-binary @/tmp/part1

# Part 2: 
curl -X PUT \ https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD \
  -H 'authorization: Bearer fEw9FPUVT3SJGaSBu4Q07VFyqdYd3ODc' \
  -H 'content-range: bytes 8388608-9999999/100000000' \
  -H 'content-type: application/octet-stream' \
  -H 'digest: sha=Oj0SVJEpmxvBarOzs9hkUuPIoOM=' \
  --data-binary @/tmp/part2
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
  "part": {
    "part_id": "CFEB4BA9",
    "offset": 0,
    "size": 8388608,
    "sha1": "5fde1cce603e6566d20da811c9c8bcccb044d4ae"
  }
}
{
  "part": {
    "part_id": "4DBB872D",
    "offset": 8388608,
    "size": 8388608,
    "sha1": "5fde1cce603e6566d20da811c9c8bcccb044d4ae"
  }
}
{
  "part": {
    "part_id": "6F2D3486",
    "offset": 16777216,
    "size": 3222784,
    "sha1": "fd6dbf76dc8adf1aad674ff2a547d62066c08f25"
  }
}
/** Part 1: **/
HTTP/1.1 200 OK
Date: Tue, 11 Apr 2017 02:18:56 GMT
Content-Type: application/json; charset=UTF-8 
Content-Length: 107
Connection: keep-alive

{
  "part": {
    "part_id": "BFDF5379",
    "offset": 0,
    "size": 8388608,
    "sha1": "7e94728397954257ad759a8429a165ab00572733"
  }
}

/** Part 2: **/
HTTP/1.1 200 OK
Date: Tue, 11 Apr 2017 02:18:56 GMT
Content-Type: application/json; charset=UTF-8 
Content-Length: 107
Connection: keep-alive

{
  "part": {
    "part_id": "E8A3ED8E",
    "offset": 8388608,
    "size": 1611392,
    "sha1": "3a3d125491299b1bc16ab3b3b3d86452e3c8a0e3"
  }
}
Suggest Edits

List Parts

Return the list of parts uploaded so far. This API follows the standard conventions for offset-based paging in other Box APIs (see https://developer.box.com/reference#offset-based-paging)

 
gethttps://upload.box.com/api/2.0/files/upload_sessions/sessionId/parts

Path Params

{sessionId}
string
required

Required. The upload session id which this part belongs to. Upload session id can be created to initiate a chunked file upload by calling the create upload session API.

Query Params

offset
string

Optional. Zero-based index of first part to return. Defaults to zero. NOTE: The name “offset” is used here to be consistent with naming of other Box APIs. However, in all other multiput API calls, offset is used to represent byte offset as opposed to an index.

limit
string

Optional. How many parts to return. Defaults to 1000, which is also the maximum value allowed. A request with limit value above 1000 will be treated as if limit was set to 1000.

Headers

Authorization
string

Required. The access token that will be used to authorize the request.

Error status codes:

There are no error status codes specific only to this API call. Any of the errors common to all API calls may be returned.

Error response body:

In some scenarios, an extended error code will be sent in a JSON body format with a more detailed error reason.

HTTP Status Code
Code
Description

400 Bad Request

invalid_offset

Offset is not a valid number

400 Bad Request

invalid_limit

Limit is not a valid number

# This is part 3 of 4 example commands to use the Chunked Uploads endpoint. Please run them in order. 
# List the parts we've uploaded
# NOTE: jq 1.5 or later is required (https://stedolan.github.io/jq/)
(
LIST_PARTS_URL=`jq -R 'fromjson?' /tmp/create_session_response | jq -r '.session_endpoints.list_parts'`;
curl -i $LIST_PARTS_URL -H "Authorization: Bearer $TOKEN" | jq -R 'fromjson?' -r
)
curl -X GET \ https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts \
  -H 'authorization: Bearer fEw9FPUVT3SJGaSBu4Q07VFyqdYd3ODc' 
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
  "entries": [
    {
      "part_id": "CFEB4BA9",
      "offset": 0,
      "size": 8388608,
      "sha1": null
    },
    {
      "part_id": "4DBB872D",
      "offset": 8388608,
      "size": 8388608,
      "sha1": null
    },
    {
      "part_id": "6F2D3486",
      "offset": 16777216,
      "size": 3222784,
      "sha1": null
    }
  ],
  "offset": 0,
  "total_count": 3,
  "limit": 1000
}
HTTP/1.1 200 OK
Date: Tue, 11 Apr 2017 02:18:56 GMT
Content-Type: application/json; charset=UTF-8 
Content-Length: 300

{
  "entries": [
    {
      "part_id": "BFDF5379",
      "offset": 0,
      "size": 8388608,
      "sha1": null
    },
    {
      "part_id": "E8A3ED8E",
      "offset": 8388608,
      "size": 1611392,
      "sha1": null
    }
  ]
}
Suggest Edits

Commit Upload

 
posthttps://upload.box.com/api/2.0/files/upload_sessions/sessionId/commit

Path Params

{sessionId}
string
required

Required. The upload session id which this part belongs to. Upload session id can be created to initiate a chunked file upload by calling the create upload session API.

Body Params

parts
string
required

Required. An array of Part JSON objects. MUST be ordered by offset.

attributes
string

Optional. An array of attributes to set on the created file. See https://box-content.readme.io/reference#file-object. “name” and “parent” attributes should not be sent. If they are, their values MUST match what was provided in the create session step.

part_id
string

The part id for the uploaded part

offset
string

Byte offset

size
string

Part size

Headers

Authorization
string
required

Required. Access token to authorize the API

Content-Type
string
required

Required. application/json

Digest
string
required

Required. SHA digest is required; SHA-1 should be used to compute the SHA digest. Will be verified before file creation.

If-Match
string
If-Non-Match
string

Error status codes:

The following error status code can be returned specifically for this API call. Any of the errors common to all API calls may also be returned.

Status code
Description

409 Conflict

Check extended error message for details

412 Precondition Failed

Check extended error message for details

413 Request entity too large

If request size is more than allowed maximum. See extended error details for more info

Error response body

In some scenarios, an extended error code will be sent in a JSON body format with a more detailed error reason.

HTTP Status Code
Code
Description

400 Bad Request

missing_digest

Digest header was expected, but not provided.

400 Bad Request

invalid_digest

Digest header was not a valid format as per http://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml.
or
Digest header used algorithm other than SHA-1
or
Digest header did not provide a valid SHA-1.

400 Bad Request

invalid_json

The request body was not valid JSON

400 Bad Request

request_size_too_long

The request Content-Length exceeds the maximum allowed

400 Bad Request

request_size_mismatch

Size of request body does not match Content-Length header

400 Bad Request

missing_parts_field

No "parts" field was present in the request body JSON or Parts information was not in the required format

400 Bad Request

invalid_parts_field

Parts list is not ordered by offset or there are gaps or overlaps in the byte ranges of the parts or any part except the last part has a size less than the minimum part size.

400 Bad Request

parts-mismatch

The parts list provided does not match the state of the parts uploaded or the overall size of the parts list does not match the file size given when creating an upload session

400 Bad Request

invalid_attributes

attributes is not a JSON Object or attributes contains a forbidden attribute

Remarks

If the response status code to commit has 202 status code, it means the server has not yet finished processing all the parts. In this case the client should retry their commit request after the number of seconds specified in the response's "Retry-After" header.

# This is part 4 of 4 example commands to use the Chunked Uploads endpoint. Please run them in order. 
# Create the file from the uploaded parts.
# NOTE: jq 1.5 or later is required (https://stedolan.github.io/jq/)
(
UPLOAD_SESSION_ID=`jq -R 'fromjson?' /tmp/create_session_response | jq -r '.id'`; \
COMMIT_URL=`jq -R 'fromjson?' /tmp/create_session_response | jq -r '.session_endpoints.commit'`; \
PARTS=`jq '.part' /tmp/${UPLOAD_SESSION_ID}`; \
curl -i -X POST $COMMIT_URL \
-H "authorization: Bearer $TOKEN" \
-H 'content-type: application/json' \
-H 'digest: sha=WcxhSjlc5bMFG7eLUdZyDCgxjJY=' \
-H "Expect:" \
-d "{\"parts\": [ $PARTS ]}" | jq -R 'fromjson?' -r
)
curl -X POST \
  https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit \
  -H 'authorization: Bearer spSSvCEepjG4PX3fO5IkcZe5h1nQYXfn' \
  -H 'content-type: application/json' \
  -H 'digest: sha=DhIcpd61HctMIGTMu7tyY54Da2U=' \
  -d '{
	"parts":[
		{"part_id": "BFDF5379","offset": 0,"size": 8388608},
		{"part_id": "E8A3ED8E","offset": 8388608,"size": 1611392}
	],
	"attributes":{"content_modified_at":"2017-04-08T00:58:08Z"}
}'
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
  "total_count": 1,
  "entries": [
    {
      "type": "file",
      "id": "243696906120",
      "file_version": {
        "type": "file_version",
        "id": "257047849608",
        "sha1": "59cc614a395ce5b3051bb78b51d6720c28318c96"
      },
      "sequence_id": "0",
      "etag": "0",
      "sha1": "59cc614a395ce5b3051bb78b51d6720c28318c96",
      "name": "chunked-uploads-api-test Thu Nov  2 14:59:24 PDT 2017",
      "description": "",
      "size": 20000000,
      "path_collection": {
        "total_count": 1,
        "entries": [
          {
            "type": "folder",
            "id": "0",
            "sequence_id": null,
            "etag": null,
            "name": "All Files"
          }
        ]
      },
      "created_at": "2017-11-02T15:04:38-07:00",
      "modified_at": "2017-11-02T15:04:38-07:00",
      "trashed_at": null,
      "purged_at": null,
      "content_created_at": "2017-11-02T15:04:38-07:00",
      "content_modified_at": "2017-11-02T15:04:38-07:00",
      "created_by": {
        "type": "user",
        "id": "226901453",
        "name": "Karthik Kailash",
        "login": "kkailash@box.com"
      },
      "modified_by": {
        "type": "user",
        "id": "226901453",
        "name": "Karthik Kailash",
        "login": "kkailash@box.com"
      },
      "owned_by": {
        "type": "user",
        "id": "226901453",
        "name": "Karthik Kailash",
        "login": "kkailash@box.com"
      },
      "shared_link": null,
      "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
      },
      "item_status": "active"
    }
  ]
}
HTTP/1.1 201 Created
Content-Length: 1126
Content-Type: application/json; charset=UTF-8
Date: Tue, 11 Apr 2017 03:10:43 GMT

{
  "type": "file",
  "id": "158056092206",
  "file_version": {
    "type": "file_version",
    "id": "168026296366",
    "sha1": "0e121ca5deb51dcb4c2064ccbbbb72639e036b65"
  },
  "sequence_id": "0",
  "etag": "0",
  "sha1": "0e121ca5deb51dcb4c2064ccbbbb72639e036b65",
  "name": " upload session API example ",
  "description": "",
  "size": 10000000,
  "path_collection": {
    "total_count": 1,
    "entries": [
      {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
      }
    ]
  },
  "created_at": "2017-04-10T20:10:44-07:00",
  "modified_at": "2017-04-10T20:10:44-07:00",
  "trashed_at": null,
  "purged_at": null,
  "content_created_at": "2017-04-07T17:58:08-07:00",
  "content_modified_at": "2017-04-07T17:58:08-07:00",
  "created_by": {
    "type": "user",
    "id": "2313123123",
    "name": "testuser@box.com",
    "login": "testuser@box.com"
  },
  "modified_by": {
    "type": "user",
    "id": "2313123123",
    "name": "testuser@box.com",
    "login": "testuser@box.com"
  },
  "owned_by": {
    "type": "user",
    "id": "2313123123",
    "name": "testuser@box.com",
    "login": "testuser@box.com"
  },
  "shared_link": null,
  "parent": {
    "type": "folder",
    "id": "0",
    "sequence_id": null,
    "etag": null,
    "name": "All Files"
  },
  "item_status": "active"
}
deletehttps://upload.box.com/api/2.0/files/upload_sessions/sessionId

Path Params

{sessionId}
string
required

Required. The upload session id which this part belongs to. Upload session id can be created to initiate a chunked file upload by calling the create upload session API.

Headers

Authorization
string
required

Required. The access token that will be used to authorize the request

Abort the upload session and discard all data uploaded. This cannot be reversed.

Error status codes:

There are no error status codes specific only to this API call. Any of the errors common to all API calls may be returned.

curl -X DELETE \ https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD \
  -H 'authorization: Bearer fEw9FPUVT3SJGaSBu4Q07VFyqdYd3ODc' 
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
HTTP/1.1 204 No Content
Date: Tue, 11 Apr 2017 02:18:56 GMT
Suggest Edits

Get Session

 
gethttps://upload.box.com/api/2.0/files/upload_sessions/sessionId

Path Params

{sessionId}
string
required

Required. The upload session id which this part belongs to. Upload session id can be created to initiate a chunked file upload by calling the create upload session API.

Headers

Authorization
string
required

Required. The access token that will be used to authorize the request

Error status codes:

There are no error status codes specific only to this API call. Any of the errors common to all API calls may be returned.

curl -X GET \ https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD \
  -H 'authorization: Bearer spSSvCEepjG4PX3fO5IkcZe5h1nQYXfn'
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
HTTP/1.1 200 OK
Date: Tue, 11 Apr 2017 02:18:56 GMT
Content-Type: application/json; charset=UTF-8 
Content-Length: 864

{
  "total_parts": 2,
  "part_size": 8388608,
  "session_endpoints": {
    "list_parts": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts",
    "commit": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit",
    "log_event": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log",
    "upload_part": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "status": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "abort": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD"
  },
  "session_expires_at": "2017-04-18T01:45:15Z",
  "id": "F971964745A5CD0C001BBE4E58196BFD",
  "type": "upload_session",
  "num_parts_processed": 2
}
Suggest Edits

Update File Info

Update the information about a file, including renaming or moving the file.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
puthttps://api.box.com/2.0/files/file_id

Path Params

file_id
string
required

Query Params

fields
string

Comma-separated list of fields to include in the response

Body Params

name
string

The new name for the file

description
string

The new description for the file

parent
object
 
parent.id
string

The ID of the parent folder

shared_link
object
 
shared_link.access
string

The level of access. Can be open ("People with the link"), company ("People in your company"), or collaborators ("People in this folder"). If you omit this field then the access level will be set to the default access level specified by the enterprise admin.

shared_link.password
string

The password required to access the shared link. Set to null to remove the password.

shared_link.unshared_at
date-time

The date-time that this link will become disabled. This field can only be set by users with paid accounts.

shared_link.permissions
object
 
shared_link.permissions.can_download
boolean

Whether the shared link allows downloads. Can only be set with access levels open and company (not collaborators).

tags
array of strings

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.

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

Note:

Editing passwords is not supported for shared links.

Returns

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

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

public class BoxFile

public void updateInfo(BoxFile.Info info)
Files.prototype.update = function(fileID, options, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxFile> UpdateInformationAsync(BoxFileRequest fileRequest, string etag = null, List<string> fields = null)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "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"
}
Suggest Edits

Preflight Check

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
optionshttps://api.box.com/2.0/files/content

Body Params

name
string
required

The name of the file

parent
object
 
parent.id
string
required

The ID of the parent folder. Use "0" for the root folder.

size
int32

The size of the file in bytes

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.

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

public class BoxFolder

public void canUpload(String name, long fileSize)

public class BoxFile

public void canUploadVersion(String name, long fileSize, String parentID)
Files.prototype.preflightUploadFile = function(parentFolderID, fileData, qs, callback)

Files.prototype.preflightUploadNewFileVersion = function(fileID, fileData, qs, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxPreflightCheck> PreflightCheck(BoxPreflightCheckRequest preflightCheckRequest)
  
public async Task<BoxPreflightCheck> PreflightCheckNewVersion(string fileId, BoxPreflightCheckRequest preflightCheckRequest)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
Try the API to see results
Suggest Edits

Delete File

Move a file to the trash.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
deletehttps://api.box.com/2.0/files/file_id

Path Params

file_id
string
required

Headers

If-Match
string

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

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

Permanent Deletion

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.

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

public class BoxFile

public void delete()
Files.prototype.delete = function(fileID, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<bool> DeleteAsync(string id, string etag=null)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
Try the API to see results
Suggest Edits

Copy File

Copy a file.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/files/file_id/copy

Path Params

file_id
string
required

Query Params

fields
string

Comma-separated list of fields to include in the response

Body Params

parent
object
 
parent.id
string
required

The ID of the destination folder

version
string

An optional file version ID if you want to copy a specific file version

name
string

An optional new name for the file

The original version of the file will not be altered.

Returns

A file object is returned if the ID is valid and if the update is successful. Errors can be thrown if the destination folder is invalid or if a file name collision occurs.

A 409 will be returned if the intended destination folder is the same, as this will cause a name collision.

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

public class BoxFile

public BoxFile.Info copy(BoxFolder destination)
  
public BoxFile.Info copy(BoxFolder destination, String newName)
Files.prototype.copy = function(fileID, newParentID, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxFile> CopyAsync(BoxFileRequest fileRequest, List<string> fields = null)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "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"
}
Suggest Edits

Lock and Unlock

Lock or unlock a file.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
puthttps://api.box.com/2.0/files/file_id

Path Params

file_id
string
required

Query Params

fields
string

Comma-separated list of fields to include in the response. Set to lock to get back lock information.

Body Params

lock
object
 
lock.type
string
required

The type of the lock object is "lock"

lock.expires_at
date-time

The time the lock expires

lock.is_download_prevented
boolean

Whether or not the file can be downloaded while locked

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.

curl https://api.box.com/2.0/files/FILE_ID  \
-H "Authorization: Bearer " \
-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
package com.box.sdk

public class BoxFile

public BoxLock lock(Date expiresAt, boolean isDownloadPrevented)

public void unlock()
Not Supported
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxFileLock> UpdateLockAsync(BoxFileLockRequest lockFileRequest, string Id)
  
public async Task<bool> UnLock(string id)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
  "type": "file",
  "id": "76017730626",
  "etag": "2",
  "lock": {
    "type": "lock",
    "id": "2126286840",
    "created_by": {
      "type": "user",
      "id": "277699565",
      "name": "Sanjay Padval",
      "login": "spadval+integration@box.com"
    },
    "created_at": "2017-03-06T22:00:53-08:00",
    "expires_at": null,
    "is_download_prevented": false
  }
}
Suggest Edits

Get Thumbnail

Get a thumbnail image for a file.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/thumbnail.extension

Path Params

file_id
string
required
extension
string
required

png or jpg with no "."

Query Params

min_height
int32

The minimum height of the thumbnail

min_width
int32

The minimum width of the thumbnail

max_height
int32

The maximum height of the thumbnail

max_width
int32

The maximum width of the thumbnail

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.

Returns

The thumbnail image in the specified size and format.

Note:

Thumbnails are only available for images and video file formats. You can also specify min=max in order to guarantee the thumbnail size requested.

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

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

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

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

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

The API for getting the thumbnail returns binary data. If you would like to show the thumbnail via an <img> tag in HTML, refer to this example https://codepen.io/box-platform/pen/MoxzbY

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

public class BoxFile

public byte[] getThumbnail(ThumbnailFileType fileType, int minWidth, int minHeight, int maxWidth, int maxHeight)
Files.prototype.getThumbnail = function(fileID, qs, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<Stream> GetThumbnailAsync(string id, int? minHeight = null, int? minWidth = null, int? maxHeight = null, int? maxWidth = null, bool throttle = true, bool handleRetry = true)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
Contents of thumbnail
Suggest Edits

Get File Collaborations

Get all of the collaborations on a file (i.e. all of the users that have access to that file).

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/collaborations

Path Params

file_id
string
required

Query Params

fields
string

Comma-separated list of fields to include in the response

marker
string

The position marker at which to begin the response. See marker-based paging for details.

limit
int32

The maximum number of items to return

Returns

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

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

curl https://api.box.com/2.0/files/FILE_ID/collaborations \
-H "Authorization: Bearer "
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "next_marker": "ZmlQZS0xLTE%3D",
    "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
        }
    ]
}
Suggest Edits

Get File Comments

Get all of the comments on a file.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/comments

Path Params

file_id
string
required

Query Params

fields
string

Comma-separated list of fields to include in the response

offset
int32

The offset of the item at which to begin the response. See offset-based paging for details.

limit
int32

The maximum number of items to return. The default is 100 and the maximum is 1,000.

Returns

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

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

public class BoxFile

public List<BoxComment.Info> getComments()
Files.prototype.getComments = function(fileID, qs, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxCollection<BoxComment>> GetCommentsAsync(string id, List<string> fields = null)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "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"
        }
    ]
}
Suggest Edits

Get File Tasks

Get all of the tasks for a file.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/tasks

Path Params

file_id
string
required

Query Params

fields
string

Comma-separated list of fields to include in the response

Returns

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

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

public class BoxFile

public List<BoxTask.Info> getTasks()
Not Supported
Not Supported
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "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
        }
    ]
}
Suggest Edits

Representations

 

Representations are digital assets created for files stored in Box.

These representations are exposed through the Get File Info endpoint using fields=representations. When this field is requested, the X-Rep-Hints header should be provided. Omitting the header is primarily intended for development and testing with the expectation that production use cases provide X-Rep-Hints specifically.

The representations object returned by the endpoint contains an "entries" field which is an array of objects. Each object in the entries array has the following fields (fields marked always are always returned, fields marked X-Rep-Hints are only returned if X-Rep-Hints is provided):

representation (always)

string

Usually the extension of the format, but occasionally a name of a standard (potentially de facto) format or a proprietary format that Box supports.

properties (always)

object

A set of static properties to distinguish between subtypes of a given representation, for example, different sizes of jpg's. Each representation has its own set of properties.

info.url (always)

string

An opaque URL which will return status information about the file. It may change over time and should not be hard-coded or cached. The response is the entries object from the array with all fields available.

NOTE: Polling the URL returned under the info.url field also triggers the generation of representations that aren't generated automatically.

status.state (X-Rep-Hints)

string

A string with one of the following values: 'none', 'pending', 'viewable', 'error' and 'success'.
none - the unknown or initial state.
pending - content is being generated but is not ready yet.
viewable - like pending, though indicates that enough content is available to be useful.
error - an error happened and this content is not available.
success - all of the content is available and complete.

content.url_template (X-Rep-Hints)

string

An opaque URL template to the content, which follows RFC 6570. There is an asset_path variable that should be replaced with a valid path. Valid paths are different for each representation subtype. It may change over time and should not be hard-coded or cached.

metadata (X-Rep-Hints)

object

A set of dynamic properties about this specific representation of this specific file. Metadata is different for each representation subtype.

Each representation may have one or more properties which distinguish different subtypes of that representation. Each subtype may be uniquely identified by its name and a name/value pair for each supported property. The documentation for each representation will specify the list of properties and all supported property values for each property. The documentation uses the word representation to refer to a representation or a subtype of a representation.

E.g. The 'jpg' representation has multiple properties, 'dimension' being one of them. This allows having multiples subtypes which differ only in terms of size, but have the same format.

X-Rep-Hints Header

The X-Rep-Hints header allows developers to explicitly express interest in a subset of representations. This is done by providing a pattern which is matched against the representations which are supported by the specified file. Only representations that are referenced in the X-Rep-Hints will be returned as part of the API response, so a client which supports only a single representation may explicitly request only that representation and never have others returned.

Another benefit of including X-Rep-Hints is that it returns more information about the specified representations, as described in the overview.

The X-Rep-Hints header is logically separated into one or more groups. Each group contains one or more representation specifications with optional properties. These representations are ordered and only the first matching representation which is supported for the current file within a given group is returned. Each group is independent and therefore if this file supports representations from multiple groups, all of those representations will be returned. Multiple values may be specified for a property, which will match all representations which have that value for that property. If a property is not specified, a default value is used for that property.

Note: X-Rep-Hints is only applicable to the Get File Info endpoint.

The format of X-Rep-Hints is described through the following extended BNF. If you need to understand how to read BNF, please see this.

group-list ::= group { group }
group ::= '[' rep { ',' rep } ']'
rep ::= rep-name [ '?' property-list ]
property-list ::= property { '&' property }
property ::= property-name '=' property-value-alternation
property-value-alternation ::= property-value { '|' property-value }
Suggest Edits

Get Representations

Use this API to retrieve links to all representations supported for a specific file in Box.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id?fields=representations

Path Params

file_id
string
required

Headers

x-rep-hints
string

Allows you to limit the result set to the specific thumbnail formats/sizes you want. If not defined, the API will return references to all representations that are supported for the file. Thumbnails, PDF, Per-page images and Extracted Text are all types of representations. X-Rep-Hints also allows you to get the readiness status of the specific representation type. Read the "X-Rep-Hints Header" in the previous section for more details.

Note status.state for the above request should be "success" or "viewable" (for videos only) if the representation is generated and ready to be used. If the value is "pending", the specific representation is either still being generated. If the status is "none", generating the representation needs to be manually triggered. To trigger its generation, call the URL under the info.url field for that representation.

curl https://api.box.com/2.0/files/{file_id}?fields=representations
-H "Authorization: Bearer ACCESS_TOKEN”
-H "x-rep-hints: [jpg?dimensions=32x32]"

//this will return a 32x32 JPG thumbnail if supported for the source file type
curl -L https://api.box.com/2.0/files/{file_id}?fields=representations
-H "Authorization: Bearer ACCESS_TOKEN"
-H "x-rep-hints: [png?dimensions=32x32]" 

//this will return a 32x32 PNG thumbnail if supported for the source file type
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "type": "file",
    "id": "96793280071",
    "etag": "1",
    "representations": {
        "entries": [
            {
                "content": {
                    "url_template": ".../{+asset_path}" 
                },
                "info": {
                    "url": "..."
                },
                "properties": {
                    "dimensions": "32x32",
                    "paged": "false",
                    "thumb": "true"
                },
                "representation": "jpg",
                "status": {
                    "state": "success"
                }
            }
        ]
    }
}
Suggest Edits

Fetching a PDF Representation

 

At this time, you can retrieve a PDF representation for all Document File Types supported by Box. This does not include code, image and text file types.

If the file is watermarked in Box, you can also use the Representation APIs to retrieve the watermarked version of the file (scroll down to learn how).

PDF representation is generated upon uploading the source file to Box. A watermarked PDF is generated upon fetching the watermarked file the first time.

To fetch a PDF representation, follow the opaque url denoted by "..." of the content_url property contained in the response of the Get Representations API call. For PDF representations, asset_path is an empty string since PDF representations are single asset representations.

curl -X GET ".../" -H "authorization: Bearer ACCESS_TOKEN" -o file.pdf

file.pdf is the downloaded PDF.

Optional query parameters on the url_template endpoint

Header
Options
Description

set_content_disposition_type

"inline" or "attachment"

Sets the Content-Disposition header in the API response with the specified disposition type, of either "inline" or "attachment". See RFC 2616 for an explanation of Content-Disposition. For example, a disposition type of "attachment" causes most web browsers to prompt the user to save the response locally.

If not supplied, the Content-Disposition header is not included in the response, and the user-agent of the client is allowed to interpret that however it wants. To ensure consistency, we recommend supplying this parameter and setting it to the intended value.

set_content_disposition_filename

Defined by the application as "<filename>.<file_extension>"

Default: Filename in Box, with the extension substituted to match the representation's file type.

Allows the application to define the downloaded representation's file name.

If not defined, the downloaded rep derives its name from the source file name in Box and the extension is replaced to match the representation's file type.

x-rep-hints value for retrieving the PDF representation for a file
x-rep-hints: [pdf]

Retrieving a watermarked PDF

To retrieve a watermarked PDF of a document, firstly, the file itself needs to be watermarked in Box. You can watermark a file either via the Box web application, or using the Watermarking API. Once watermarked, a watermarked PDF version of the file is generated. Watermarked PDFs are currently generated for document (PDFs, Office files) and images (png, jpeg, etc.) file types.

Watermarked PDFs can be downloaded exactly the same way as a regular PDF.

Example: API response when getting PDF representation (x-rep-hints: [pdf]) of a watermarked document

{
    "type": "file",
    "id": "FILE_ID",
    "etag": "0",
    "representations": {
        "entries": [
            {
                "representation": "pdf",
                "properties": {},
                "info": {
                    "url": "https://api.box.com/2.0/internal_files/FILE_ID/versions/VERSION_ID/representations/pdf"
                },
                "status": {
                    "state": "success"
                },
                "content": {
                    "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/FILE_ID/versions/VERSION_ID/representations/pdf/content/{+asset_path}?watermark-cache=148721"
                }
            }
        ]
    }
}

To download the watermarked rep, follow the opaque URL denoted by "..." of the content_url as is without any changes.

curl -X GET "https://dl.boxcloud.com/api/2.0/internal_files/FILE_ID/versions/VERSION_ID/representations/pdf/content/..." -H "authorization: Bearer ACCESS_TOKEN" -o watermarked_file.pdf

watermarked_file.pdf is the downloaded Watermarked PDF.

Optional headers on the url_template endpoint
Same as those for a regular PDF defined above apply.

Suggest Edits

Fetching a Thumbnail Representation

 

At this time, you can retrieve thumbnails for all Document, Image and Video File Types supported by Box.

Thumbnail representations (all except 1024x1024 and 2048x2048 PNGs) are generated upon uploading the source file to Box.

To fetch a thumbnail, follow the opaque url denoted by "..." of the url_template property contained in the response of the Get Representations API call. For thumbnails, asset_path is an empty string since thumbnails are single asset representations.

curl -X GET ".../" -H "authorization: Bearer ACCESS_TOKEN" -o file.jpg

file.jpg should contain the thumbnail.

Optional query parameters on the url_template endpoint

We support the following two optional headers that developers can use while invoking the opaque url of the url_template property.

Header
Options
Description

set_content_disposition_type

"inline" or "attachment"

Sets the Content-Disposition header in the API response with the specified disposition type, of either "inline" or "attachment". See RFC 2616 for an explanation of Content-Disposition. For example, a disposition type of "attachment" causes most web browsers to prompt the user to save the response locally.

If not supplied, the Content-Disposition header is not included in the response, and the user-agent of the client is allowed to interpret that however it wants. To ensure consistency, we recommend supplying this parameter and setting it to the intended value.

set_content_disposition_filename

Defined by the application as "<filename>.<file_extension>"

Default: Filename in Box, with the extension substituted to match the representation's file type.

Allows the application to define the downloaded representation's file name.

If not defined, the downloaded rep derives its name from the source file name in Box and the extension is replaced to match the representation's file type.

Supported formats & sizes

The following formats and sizes of thumbnails are available in Box:

JPG
"32x32", "94x94", "160x160", "320x320", "1024x1024", "2048x2048"

PNG
"1024x1024", "2048x2048"

JPEG 2048 representation returned for JPEG file types only

The JPEG 2048 is returned for JPEG file types only. Unless you are okay introducing a separate check in your application code for JPEG files, we recommend requesting a PNG 2048 or JPEG 2048 and PNG 2048 both; but not just JPEG 2048.

JPEG 2048, PNG 1024 and PNG 2048 representations not available for video file types

We do not generate the aforementioned representations for video file types. All other image representations should be available.

The actual size of the thumbnail returned is capped based on the original image size

We do not upscale image sizes. So for example, if the original file size uploaded to Box is 360x480, requesting a 2048x2048 representation will still return a thumbnail that is 360x480.

Using x-rep-hints to request one or more specific thumbnail sizes
Below are sample x-rep-hints values that would allow you to request one or more specific thumbnails for a specific file in the same API call. These are meant as references for how you can structure x-rep-hints to request the thumbnail types that you are interested in.

Note: that you can only request thumbnail formats and sizes that are supported at this time.

Requesting a 32x32 JPEG Thumbnail:
x-rep-hints: [jpg?dimensions=32x32]

Requesting 32x32 and 1024x1024 JPEG Thumbnails
x-rep-hints: [jpg?dimensions=32x32][jpg?dimensions=1024x1024]

Requesting a 32x32 JPEG and 2048x2048 PNG Thumbnail
x-rep-hints: [jpg?dimensions=32x32][png?dimensions=2048x2048]

Requesting a 2048x2048 JPEG or 2048x2048 PNG Thumbnail
(returns the first representation only if available. If first is not available but second is, then returns the second. If neither exists, return nothing)
[jpg?dimensions=2048x2048,png?dimensions=2048x2048]

Suggest Edits

Fetching Single-page images Representation

 

Single-page images is a multi-asset representation currently generated for for all Document File Types and Multi-image File Types (such as TIFF) supported by Box. This does not include code and text file types.

Single-page images are especially useful for application clients that require a subset of pages of a document (you can think of them as full resolution thumbnails for each page of a document).

SIngle-page images representation is generated upon explicitly being requested via the Representation API

To request a single-page representation, the client needs to invoke the Get Representation API with x-rep-hints header set to [png?dimensions=1024x1024][dimensions=2048x2048], depending upon which size is expected.

Therefore, the first time you request a single-page representation, you will notice the status is set to none and the metadata->pages property is not returned, which indicates that the representation is not yet generated and that you must try again after some time.

Once the single-page representation is generated, the status will update the success and the metadata->pages property will update to the number of "per page images" that have been generated for the said document.

Since single-page images are a multi-asset representation, unlike Thumbnails and PDFs, it does require that the client specifies which asset it wants to request.

To fetch a specific page of a single-page image representation, follow the opaque url denoted by "..." of the content_url property contained in the response of the Get Representations API call and replace the {+asset_path} at the end of the url with the specific asset name.

Assets are named as <page_number>.<png>. So the assets of a 4-page long document will be 1.png, 2.png, 3.png and 4.png. Once again, the metadata->pages property represents the number of assets in a multi-page image representation.

curl -X GET ".../1.png" -H "authorization: Bearer ACCESS_TOKEN" -o file.png

file.png is the downloaded PNG of the first page of the document/mult-page image file.

Optional query parameters on the url_template endpoint

Header
Options
Description

set_content_disposition_type

"inline" or "attachment"

Sets the Content-Disposition header in the API response with the specified disposition type, of either "inline" or "attachment". See RFC 2616 for an explanation of Content-Disposition. For example, a disposition type of "attachment" causes most web browsers to prompt the user to save the response locally.

If not supplied, the Content-Disposition header is not included in the response, and the user-agent of the client is allowed to interpret that however it wants. To ensure consistency, we recommend supplying this parameter and setting it to the intended value.

set_content_disposition_filename

Defined by the application as "<filename>.<file_extension>"

Default: Filename in Box, with the extension substituted to match the representation's file type.

Allows the application to define the downloaded representation's file name.

If not defined, the downloaded rep derives its name from the source file name in Box and the extension is replaced to match the representation's file type.

Supported formats & sizes

The following formats and sizes of single-page image representations are available in Box:

PNG
"1024x1024", "2048x2048"

Using x-rep-hints to request one or more multi-page image representation sizes
Below are sample x-rep-hints values that would allow you to request one or more single-page image representation for a specific file in the same API call. These are meant as references for how you can structure x-rep-hints to request the sizes you want.

Note: that you can only request formats and sizes that are supported at this time.

Requesting a 1024x1024 PNG single-page image representation:
x-rep-hints: [png?dimensions=1024x1024]

Requesting a 1024x1024 or 2048x2048 PNG single-page image representation
x-rep-hints: [png?dimensions=1024x1024|2048x2048]

Requesting a 1024x1024 and 2048x2048 PNG single-page image representations
x-rep-hints: [png?dimensions=1024x1024][png?dimensions=2048x2048]

Suggest Edits

Fetching Text Representation

 

Text is a single asset representation currently generated for all Document File Types including Text/Code files supported by Box. This does not include image files (since there is no text layer).

The text representation provides you with the unformatted text contained in a document as a txt file.

Text representation is generated upon upload, just as PDF and Thumbnails are. Text representations are not generated for files larger than 500MB.

To fetch the text representation of a supported file type, follow the opaque url denoted by "..." of the content_url property contained in the response of the Get Representations API call. asset_path is an empty string since text is a single asset representation.

curl -X GET ".../" -H "authorization: Bearer ACCESS_TOKEN" -o file.txt

file.txt is the downloaded txt file that contains the text of the source document.

Optional query parameters on the url_template endpoint

Header
Options
Description

set_content_disposition_type

"inline" or "attachment"

Sets the Content-Disposition header in the API response with the specified disposition type, of either "inline" or "attachment". See RFC 2616 for an explanation of Content-Disposition. For example, a disposition type of "attachment" causes most web browsers to prompt the user to save the response locally.

If not supplied, the Content-Disposition header is not included in the response, and the user-agent of the client is allowed to interpret that however it wants. To ensure consistency, we recommend supplying this parameter and setting it to the intended value.

set_content_disposition_filename

Defined by the application as "<filename>.<file_extension>"

Default: Filename in Box, with the extension substituted to match the representation's file type.

Allows the application to define the downloaded representation's file name.

If not defined, the downloaded rep derives its name from the source file name in Box and the extension is replaced to match the representation's file type.

x-rep-hints value for retrieving the text representation for a supported file type
x-rep-hints: [extracted_text]

Suggest Edits

File Version Object

 

type

string

file_version

id

string

The ID of the file version object

sha1

string

The SHA-1 hash of the file version

name

string

The name of the file version

size

integer

Size of the file version in bytes

created_at

date-time

When the file version object was created

modified_at

date-time

When the file version object was last updated

content_modified_at

date-time

When the content of the file version was last modified (more info)

modified_by

mini user object

The user who last updated the file version

{
    "type": "file_version",
    "id": "26261748416",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "tigers.jpeg",
    "size": 629644,
    "created_at": "2012-12-12T10:55:30-08:00",
    "modified_at": "2012-12-12T11:04:26-08:00",
    "content_modified_at": "2013-02-04T16:57:52-08:00",
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
}
{
    "sequence_id": "0",
    "etag": "0",
    "type": "file",
    "id": "2631999573",
    "name":"IMG_1312.JPG"
}
Suggest Edits

Get Versions

Get information on prior versions of a file.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/versions

Path Params

file_id
string
required

Query Params

fields
string

Comma-separated list of fields to include in the response

offset
int32

The offset of the item at which to begin the response. See offset-based paging for details.

limit
int32

The maximum number of items to return. The default is 1,000 and the maximum is 1,000.

Returns

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

Alert:

Versions are only tracked for Box users with premium accounts.

Download Version

To download a specific file version, use the Download File Endpoint and specify the version needed.

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

public class BoxFile

public Collection<BoxFileVersion> getVersions()
Not Supported
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxCollection<BoxFileVersion>> ViewVersionsAsync(string id, List<string> fields = null)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
 "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"
     }
	 }
 ]
}
Suggest Edits

Get File Version Info

Get information about a prior file version.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/versions/file_version_id

Path Params

file_id
string
required
file_version_id
string
required

This endpoint can only be used on past file versions. It will return a 400 if called on the current file version.

curl https://api.box.com/2.0/files/FILE_ID/versions/FILE_VERSION_ID \
-H "Authorization: Bearer " \
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "created_at": "2017-05-02T11:28:41-07:00",
    "id": "176880312614",
    "modified_at": "2017-05-02T11:28:41-07:00",
    "modified_by": {
        "id": "193977422",
        "login": "bgrizzle@box.com",
        "name": "Bill Grizzle",
        "type": "user"
    },
    "name": "vacation.png",
    "purged_at": null,
    "sha1": "632eeeb98b4267752637d95bf6e2562e39708454",
    "size": 631,
    "trashed_at": null,
    "type": "file_version"
}
Suggest Edits

Promote Version

Copy a previous file version and make it the current version of the file. This create a copy of the old file version and puts it on the top of the versions stack. The file will have the exact same contents, the same SHA-1/etag, and the same name as the original. Other properties such as comments do not get updated to their former values.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/files/file_id/versions/current

Path Params

file_id
string
required

Query Params

fields
string

Comma-separated list of fields to include in the response

Body Params

type
string
required

file_version

id
string
required

The ID of the file version 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

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

public class BoxFileVersion

public void promote()
Not Supported
Not Supported
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "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"
    }
}
Suggest Edits

Delete Old Version

Discards a file version to the trash.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
deletehttps://api.box.com/2.0/files/file_id/versions/id

Path Params

file_id
string
required
id
string
required

Id of the file version

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.

curl https://api.box.com/2.0/files/FILE_ID/versions/VERSION_ID  \
-H "Authorization: Bearer " \
-X DELETE
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
Suggest Edits

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

folder

id

string

The ID of the folder object

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

The entity tag of this folder object. Used with If-Match headers. May be null for some folders such as root or trash.

name

string

The name of the folder

created_at

date-time

The time the folder was created. May be null for some folders such as root or trash.

modified_at

date-time

When this folder was last updated on the Box servers. This is a read-only field.

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

date-time

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

date-time

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

date-time

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

date-time

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 object for this file. Will be null if no shared link has been created.

folder_upload_email

object

The upload email address for this folder. null if not set.

parent

mini folder object

The folder that contains this folder.
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. Values include active, trashed if the item has been moved to the trash, and deleted if the item has been permanently deleted

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

An object containing 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 key has a boolean value.

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

array of strings

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

allowed_invitee_roles

array of strings

Folder collaboration roles allowed by the enterprise administrator

watermark_info

object

Information about the watermark status of this folder. See Watermarking for additional endpoints.

Fields:
is_watermarked (boolean): Whether the folder is watermarked or not.

metadata.<scope>.<templateKey>

object

Specific metadata on the folder, identified by scope and templateKey. The limit of metadata instances to be requested this way is 3.

Notes

When performing certain folder operations, parts of the file tree are locked to prevent errors. These operations include moving, copying, or deleting folders, as well as restoring folders from the trash.

During these operations, we lock:

  • the source folder and all of its descendants
  • the destination folder (the parent of the resulting moved, copied, or restored folder)

For the duration of the operation, no other move, copy, delete, or restore operation can operate on any of the locked folders. This means, for example, that you cannot copy the same folder to two different parts of the tree at the same time.

If an API call to move, copy, delete, or restore a folder can't proceed due to a locked folder, the API returns 409 - operation_blocked_temporary. The caller can retry the API call after a delay until it succeeds.

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

Get Folder Info

Get information about a folder.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/folders/folder_id

Path Params

folder_id
string
required

Query Params

fields
string

Comma-separated list of fields to include in the response

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

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.

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

public class BoxFolder

public BoxFolder.Info getInfo()
Folders.prototype.get = function(folderID, qs, callback)
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxFolder> GetInformationAsync(string id, List<string> fields = null)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "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
    }
}
Suggest Edits

Get Folder Items

Gets all of the files, folders, or web links contained within a folder.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/folders/folder_id/items

Path Params

folder_id
string
required

Query Params

fields
string

Comma-separated list of fields to include in the response

usemarker
boolean

This specifies whether you would like to use marker-based or offset-based paging. You can only use one or the other. Marker-based paging is the preferred method and is most performant. If not specified, this endpoint defaults to using offset-based paging. This parameter is unique to Get Folder Items to retain backwards compatibility for this endpoint. This parameter is required for both the first and subsequent calls to use marked-based paging.

marker
string

The position marker at which to begin the response. See marker-based paging for details. This parameter cannot be used simultaneously with the 'offset' parameter.

offset
int32

The offset of the item at which to begin the response. See offset-based paging for details. This parameter cannot be used simultaneously with the 'marker' parameter.

sort
string

This can be id,name, or date. This parameter is not yet supported for marker-based paging on folder 0.

direction
string

This can be ASC or DESC.

limit
int32

The maximum number of items to return. The default is 100 and the maximum is 1,000.

Any attribute in the full files or folders objects can be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default. Multiple attributes can be passed in separated by commas e.g. fields=name,created_at.

Returns

Returns all of the items contained in the folder. An error is returned if the folder does not exist, or if any of the parameters are invalid.

This endpoint can use either offset-based paging or marker-based paging. We recommend marker-based paging because it is more performant.

With offset-based paging, the total_count returned may not match the number of entries when using the enterprise scope, because external folders are excluded from the list of entries.

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

public class BoxFolder

public Iterable<BoxItem.Info> getChildren(final String... fields)

public PartialCollection<BoxItem.Info> getChildrenRange(long offset, long limit, String... fields)

public Iterator<BoxItem.Info> iterator()
Folders.prototype.getItems = function(folderID, qs, callback)
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxCollection<BoxItem>> GetFolderItemsAsync(string id, int limit, int offset = 0, List<string> fields = null)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "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"
        }
    ]
}
Suggest Edits

Create Folder

Create a new folder.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/folders

Query Params

fields
string

Comma-separated list of fields to include in the response

Body Params

name
string
required

The desired name for the folder

parent
object
 
parent.id
string
required

The ID of the parent folder

Returns

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

Supported Folder Names:

Box supports folder names of 255 characters or less. Names contain non-printable ASCII characters, "/" or "\", names with trailing spaces, and the special names “.” and “..” are also not allowed.

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

public class BoxFolder
  
public BoxFolder.Info createFolder(String name)
Folders.prototype.create = function(parentFolderID, name, callback)
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxFolder> CreateAsync(BoxFolderRequest folderRequest, List<string> fields = null)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "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
    }
}
Suggest Edits

Update Folder

Update a folder.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
puthttps://api.box.com/2.0/folders/folder_id

Path Params

folder_id
string
required

Query Params

fields
string

Comma-separated list of fields to include in the response

Body Params

name
string

The name of the folder

description
string

The description of the folder

parent
object
 
parent.id
string

The ID of the parent folder

shared_link
object
 
shared_link.access
string

The level of access. Can be open ("People with the link"), company ("People in your company"), or collaborators ("People in this folder"). If you omit this field then the access level will be set to the default access level specified by the enterprise admin.

shared_link.password
string

The password required to access the shared link. Set to null to remove the password.

shared_link.unshared_at
date-time

The date-time that this link will become disabled. This field can only be set by users with paid accounts.

shared_link.permissions
object
 
shared_link.permissions.can_download
boolean

Whether the shared link allows downloads. For shared links on folders, this also applies to any items in the folder. Can only be set with access levels open and company (not collaborators).

folder_upload_email
object
 
folder_upload_email.access
string

Can be open or collaborators

owned_by
object
 
owned_by.id
string

The ID of the user (should be your own user ID)

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 of strings

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.

can_non_owners_invite
boolean

If this parameter is set to false, only folder owners and co-owners can send collaborator invites

Headers

If-Match
string

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

To move a folder, update the ID of its parent. To enable an email address that can be used to upload files to the folder, update the folder_upload_email field. An optional If-Match header can be included to ensure that client only updates the folder if it knows about the latest version.

This call will return synchronously. This holds true even for folder moves when the folder contains (in all its descendants) a large number of items. For very large folders, this means the call could take minutes or hours to return.

The Folder Object docs have some more information about parts of the tree that are locked during moves.

Returns

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

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

public class BoxFolder
  
public void updateInfo(BoxFolder.Info info)
Folders.prototype.update = function(folderID, options, callback)
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxFolder> UpdateInformationAsync(BoxFolderRequest folderRequest, List<string> fields = null)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
   "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
 }
}
Suggest Edits

Delete Folder

Move a folder to the trash. The recursive parameter must be included in order to delete folders that aren't empty.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
deletehttps://api.box.com/2.0/folders/folder_id

Path Params

folder_id
string
required

Query Params

recursive
boolean

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

Headers

If-Match
string

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

An optional If-Match header can be included to ensure that client only deletes the folder if it knows about the latest version.

Trash:

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

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.

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

public class BoxFolder

public void delete(boolean recursive)
Folders.prototype.delete = function(folderID, qs, callback)
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<bool> DeleteAsync(string id, bool recursive = false)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
Try the API to see results
Suggest Edits

Copy Folder

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

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/folders/folder_id/copy

Path Params

folder_id
string
required

Query Params

fields
string

Comma-separated list of fields to include in the response

Body Params

parent
object
 
parent.id
string
required

The ID of the destination folder

name
string

An optional new name for the folder

If the folder being copied contains (in all of its descendants) less than or equal to 500 items, the copy will happen synchronously with the API call. The call will not return until the copy operation is complete, and when the copy is complete the call returns with a 201 Created.

If the folder contains more than 500 items, the copy operation will be kicked off asynchronously. The API call will return right away with the same 201 Created response code, but before the copy operation is complete. There is currently no way to check for when this operation is finished.

The Folder Object docs have some more information about parts of the tree that are locked during copies.

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

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

public class BoxFolder

public BoxFolder.Info copy(BoxFolder destination, String newName)
Folders.prototype.copy = function(folderID, newParentID, callback)
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxFolder> CopyAsync(BoxFolderRequest folderRequest, List<string> fields = null)
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "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
    }
}
Suggest Edits

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.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/folders/folder_id/collaborations

Path Params

folder_id
string
required

Query Params

fields
string

Comma-separated list of fields to include in the response

Returns

Returns all of the folder's collaborations. This API does not support paging -- it always returns all of the collaborations.

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

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

public class BoxFolder

public Collection<BoxCollaboration.Info> getCollaborations()
Folders.prototype.getCollaborations = function(folderID, qs, callback)
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxCollection<BoxCollaboration>> GetCollaborationsAsync(string id, List<string> fields = null)
A binary file was returned

Your OAuth2 token has expired

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

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.

Suggest Edits

Metadata Templates

 

Metadata that belongs to a file or 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. Metadata associated with folders is not displayed 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". The supported scopes are enterprise_{id} and global. Enterprise scopes are defined on a per enterprises basis, whereas the global scope is Box application-wide. Attribute order within template instances is not defined.

Templates support four attributes types: string, enum, float, and date (RFC 3339). There is a limit of 500 templates per enterprise.

For more information on how to structure a metadata template, please refer to this [Box Community page] (https://community.box.com/t5/How-to-Guides-for-Admins/How-to-Create-the-Right-Metadata-Structure-for-your-Enterprise/ta-p/43960).

Metadata templates can be set up in the Admin Console.

Template Object

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. 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 supported. The Global scope contains the properties template, 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: enterprise_{id}

displayName

string

The display name of the template.

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. Templates support four attribute types: 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. All characters are allowed.

description

string

A description of the field. The recommended 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

options[key]

string

For type enum, one of the potential values.

Global Properties Template

In addition to enterprise scoped templates, every file on Box has access to the properties template in the global scope. 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.

To access properties metadata use /files/{file_id}/metadata/global/properties.

Suggest Edits

Get Metadata Template by Name

Get information about a metadata template by its name.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/metadata_templates/scope/template/schema

Path Params

scope
string
required
template
string
required

RETURNS

The schema representing the metadata template queried

curl https://api.box.com/2.0/metadata_templates/enterprise/productInfo/schema \
-H "Authorization: Bearer "
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "id": "f7a9891f",
    "templateKey": "productInfo",
    "scope": "enterprise_12345",
    "displayName": "Product Info",
    "hidden": false,
    "fields": [
        {
            "id": "f7a9892f",
            "type": "float",
            "key": "skuNumber",
            "displayName": "SKU Number",
            "hidden": false
        },
        {
            "id": "f7a9893f",
            "type": "string",
            "key": "description",
            "displayName": "Description",
            "hidden": false
        },
        {
            "id": "f7a9894f",
            "type": "enum",
            "key": "department",
            "displayName": "Department",
            "hidden": false,
            "options": [
                {
                     "id": "f7a9895f",
                    "key": "Beauty"
                },
                {
                     "id": "f7a9896f",
                    "key": "Shoes"
                }
            ]
        },
        {
            "id": "f7a9897f",
            "type": "date",
            "key": "displayDate",
            "displayName": "Display Date",
            "hidden": false
        }
    ]
}
Suggest Edits

Get Metadata Template by ID

Get information about a metadata template by its id.

 
gethttps://api.box.com/2.0/metadata_templates/id

Path Params

id
string
required

Id for metadata template

curl https://api.box.com/2.0/metadata_templates/f7a9891f-0a84-4c80-bba3-a81b3123751d \
-H "Authorization: Bearer ACCESS_TOKEN"
A binary file was returned

You couldn't be authenticated

{
    "id": "f7a9891f",
    "templateKey": "productInfo",
    "scope": "enterprise_12345",
    "displayName": "Product Info",
    "hidden": false,
    "fields": [
        {
            "id": "f7a9892f",
            "type": "float",
            "key": "skuNumber",
            "displayName": "SKU Number",
            "hidden": false
        },
        {
            "id": "f7a9893f",
            "type": "string",
            "key": "description",
            "displayName": "Description",
            "hidden": false
        },
        {
            "id": "f7a9894f",
            "type": "enum",
            "key": "department",
            "displayName": "Department",
            "hidden": false,
            "options": [
                {
                     "id": "f7a9895f",
                    "key": "Beauty"
                },
                {
                     "id": "f7a9896f",
                    "key": "Shoes"
                }
            ]
        },
        {
            "id": "f7a9897f",
            "type": "date",
            "key": "displayDate",
            "displayName": "Display Date",
            "hidden": false
        }
    ]
}
Id is invalid or template does not exist for the given id or the user is not allowed to view it
Suggest Edits

Create Metadata Template

Create a new metadata template with the specified schema.

 
posthttps://api.box.com/2.0/metadata_templates/schema

Form Data

scope
string
required

The scope of the object. Only the enterprise scope is 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

The display name of the template.

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.

field.type
string
required

The data type of the field's value. Templates support four attributes types: string, enum, float, and date (RFC 3339).

field.key
string

A unique identifier for the field. The identifier must be unique within the template to which it belongs. Defaults to a string derived from the displayName if no value is provided.

fields.displayName
string
required

The display name of the field

fields.options
array

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

options.key
string
required

For type "enum", one of the potential 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.

Returns

A 201 will be received on successful creation. 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.

curl https://api.box.com/2.0/metadata_templates/schema \
-H "Authorization: Bearer " \
-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
A binary file was returned

You couldn't be authenticated

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

Update Metadata Template

Update a metadata template.

 
puthttps://api.box.com/2.0/metadata_templates/scope/template/schema

Path Params

scope
string
required
template
string
required

Form Data

op
string
required

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

data
object

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 of strings

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

enumOptionKeys
array of strings

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

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. data represents an enum option object. See Create Metadata Template for a list of supported attributes for an enum option.

  • 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. data represents a field object. See Create Metadata Template for a list of supported attributes for a field.

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

Alert:

The following changes can affect existing instances of this template.

  • editField: Edits any number of the base properties of a field: displayName, hidden, description, key
    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.
    Warning: If the key is changed, existing values of the specified field are migrated to the new key. Search indices are updated, which can take time depending on how many files are affected by the change.

Alert:

The following changes will affect existing instances of this template. These changes will be logged at the template change level, but not at the file-change level.

  • editEnumOption: Edits the enumOption
    Params:
    data: JSON object with the new key of the enumOption
    enumOptionKey: The key of the enum option to be edited
    fieldKey: The key of the field the specified enum option belongs to. Must refer to an enum field
    Example: [{"op":"editEnumOption","fieldKey":"fy","enumOptionKey":"FY11","data":{"key":"FY16"}}]. This will rename the enumOption FY11 to FY16. Existing instances of the template with the value set will be migrated to the new option. Search indices are updated, which can take time depending on how many files are affected by the change.
    Warning: This will affect existing instances of this template.

  • removeEnumOption: Removes the specified enum option from the specified enum field
    Params:
    enumOptionKey: The key of the enum option to be removed
    fieldKey: The key of the field from which the enum option should be removed. Must refer to an enum field
    Example: [{"op":"removeEnumOption","fieldKey":"fy","enumOptionKey":"FY11"}]. This will remove the enumOption FY11 from the field fy. It will also remove the enumOption from all instances of the template and if the field was set to the removed value, it will be unset. Search indices are updated, which can take time depending on how many files are affected by the change.
    Warning: This will affect existing instances of this template.

  • removeField: Removes the specified field from the template
    Params:
    fieldKey: The key of the field to be removed
    Example: [{"op":"removeField","fieldKey":"brand"}]. This will remove the field brand from the template as well as all instances of the template. Search indices are updated, which can take time depending on how many files are affected by the change.
    Warning: This will affect existing instances of this template.

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.

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

You couldn't be authenticated

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

Get Enterprise Templates

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

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/metadata_templates/scope

Path Params

scope
string
required

Query Params

marker
string

The position marker at which to begin the response. See marker-based paging for details.

limit
int32

The maximum number of items to return. The default is 100 and the maximum is 1,000.

Returns

Returns all of the metadata templates within an enterprise and their corresponding schema using marker-based paging.

curl https://api.box.com/2.0/metadata_templates/enterprise \
-H "Authorization: Bearer "
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "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
}
Suggest Edits

Metadata 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 supported. The global scope contains the properties template, while the enterprise scope pertains to custom templates within the enterprise. The ID of the enterprise will be appended to the enterprise scope in this format: enterprise_{id}

$parent

string

The ID of the object the metadata object belongs to. 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 or folder.

$version

integer

The version of the metadata 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 size of a template instance can not exceed 16384 characters. Since the "$" character is reserved for metadata service keys, custom values can not be prefixed with the "$" character.

Suggest Edits

Get All Metadata on File

Used to retrieve all metadata associated with a given file

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/metadata

Path Params

file_id
string
required

Returns

Returns all of the metadata instances associated with the file. This API does not support paging -- it always returns all of the metadata instances.

curl https://api.box.com/2.0/files/5010739061/metadata \
-H "Authorization: Bearer "
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "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
}
Suggest Edits

Get Metadata on File

Get the metadata instance for a file.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/metadata/scope/template

Path Params

file_id
string
required
scope
string
required

The scope of the metadata object (global or enterprise_{enterprise_id})

template
string
required

The key of the template. For example, the global scope has the properties 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.

curl https://api.box.com/2.0/files/5010739061/metadata/enterprise/marketingCollateral \
-H "Authorization: Bearer "
A binary file was returned

Your OAuth2 token has expired

Reauthenticate via OAuth2
{
    "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"
}
Suggest Edits

Create Metadata on File

Create a metadata instance for a file.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/files/file_id/metadata/scope/template

Path Params

file_id
string
required
scope
string
required

The scope of the metadata object (global or enterprise_{enterprise_id})

template
string
required

The key of the template. For example, the global scope has the properties template.

Body Params

key_1
string

Sample key:value pair

key_2
string

Sample key:value pair

Headers

Content-Type
string

Must be application/json

When creating metadata, only values that adhere to the metadata template schema will be accepted.

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.

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

Your OAuth2 token has expired

Reauthenticate via OAuth2