Overview

 

Content API Basics

The Box Content API gives you access to secure content management and content experience features for use in your own app. It strives to be RESTful and is organized around the main resources you’re familiar with from the Box web interface.

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

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

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

Example Requests

Sample API calls are provided next to each method using cURL, a standard command line tool. All you need to do is drop in your specific parameters, and you can test the calls from the command line. If the command line isn’t your preference, a great alternative is POSTMAN, an easy-to-use Chrome extension for making HTTP requests. Or you can always use one of our SDKs instead of making direct API calls.

Input/Output Format

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

Date Format

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

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

gzip

If you would like responses from Box to be compressed for faster response times, simply include an Accept-Encoding header with a value of gzip, deflate, and responses will be gzipped.

CORS

CORS, or cross-origin resource sharing, is a mechanism that allows a web page to make XMLHttpRequests to another domain (i.e. a domain different from the one it was loaded from). CORS is supported in a specific set of modern browsers. The Box API supports CORS on an app-by-app basis. If you’re building an application that needs CORS, please review this tutorial and contact us with a description of your use case.

Suppressing Notifications

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

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

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

Pagination

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

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

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

Getting Help

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

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

Errors

 

The Box API communicates errors through standard HTTP status codes paired with error objects. Generally the following pattern will apply:

2xx

The request was successfully received, understood, and accepted

3xx

Further action needs to be taken by the user agent in order to fulfill the request

4xx

An error in the request. Usually a bad parameter.

5xx

The request is fine, but something is wrong on Box’s end

HTTP STATUS CODES

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

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

type

string

for errors is ‘error’

status

int

the HTTP status of the error response

code

string

the HTTP code of the error response

context_info

object

additional context for the error

errors

array

child of context_info. An array of error objects give context for the error. includes reason, name, and message properties.

help_url

string

a URL linking to more information about why this error occurred

message

string

a human readable message about the error

request_id

string

a unique ID for this request helpful for troubleshooting

EXAMPLE ERROR

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

Fields

 

By default, each object has a standard and a mini format.

  • The standard format is returned when you request a specific object (e.g. GET /files/{id}).
  • The mini is returned when the object is part of a collection of items (e.g. GET /files/{id}/comments).

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

Some fields are not included in the standard format, and can only be retrieved if you request them using the fields URL parameter. These fields are listed as italicized in the object definitions.

Fields Support:

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

EXAMPLE REQUEST

curl https://api.box.com/2.0/files/FILE_ID?fields=modified_at,path_collection,name
-H "Authorization: Bearer ACCESS_TOKEN"

EXAMPLE RESPONSE

{
    "type": "file",
    "id": "3447956798",
    "etag": "1",
    "modified_at": "2012-10-04T12:34:05-07:00",
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
               	"sequence_id": null,
              	"etag": null,
                "name": "All Files"
           },
           {
               "type": "folder",
               "id": "423404344",
               "sequence_id": "15",
               "etag": "15",
               "name": "General Info"
           }
       ]
   },
   "name": "Org Chart.PDF"
}

If-Match

 

The Box API supports the HTTP If-Match and If-None-Match headers for certain methods in the files and folders endpoints (Supported methods listed on the right). If-Match headers let you ensure that your app only alters files/folders on Box if you have the current version; similarly, If-None-Match headers ensure that you don’t retrieve unnecessary data if you already have the most current version on-hand.

Etags

Every files and folders object has an etag attribute that is unique across every version of that file or folder. Etags are unique across versions of items, but not across different items. For example, the first version of File XYZ can have an etag value of “1”, and the first version of File ABC “1”, but any other version of File XYZ must have an etag value that is not “1”.

Etag:

You should make no assumptions about the value of etags outside of the fact that they are unique for each version of particular file or folder relative to other versions of that file or folder.

Using If-(None-)Match

The methods that can be used with If-Match are listed on the right. The following tables summarize the behavior you can expect when using If-Match:

If-Match Header Has Most Current Etag

RESOURCE EXISTS

HTTP Status of Response: 200

RESOURCE DOES NOT EXIST

HTTP Status of Response: 412

If-Match Header Does Not Have Most Current Etag

RESOURCE EXISTS

HTTP Status of Response: 412

RESOURCE DOES NOT EXIST

HTTP Status of Response: 404

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

If-None-Match Header Has Most Current Etag

RESOURCE EXISTS

HTTP Status of Response: 304

RESOURCE DOES NOT EXIST

HTTP Status of Response: 404

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

RESOURCE EXISTS

HTTP Status of Response: 200

RESOURCE DOES NOT EXIST

HTTP Status of Response: 404

IF-MATCH SUPPORTED METHODS

POST /files/{id}/content
PUT /files/{id}
DELETE /files/{id}
PUT /folders/{id}
DELETE /folder/{id}

IF-NONE-MATCH SUPPORTED METHODS

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

As-User

 

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

Note:

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

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

EXAMPLE REQUEST

curl https://api.box.com/2.0/folders/0?fields=item_collection,name \
-H "Authorization: Bearer ACCESS_TOKEN_OF_THE_ADMIN" \
-H "As-User: 10543463" 

EXAMPLE RESPONSE

{
 "type": "folder",
    "id": "0",
    "etag": null,
    "name": "All Files",
    "item_collection": {
        "total_count": 4,
        "entries": [
            {
                "type": "folder",
                "id": "494447198",
                "etag": "0",
                "name": "Archive"
            },
            {
                "type": "folder",
                "id": "611745226",
                "etag": "1",
                "name": "Customer Info"
            },
            {
                "type": "folder",
                "id": "329767175",
                "etag": "0",
                "name": "Vendors"
            },
            {
                "type": "folder",
                "id": "632559865",
                "etag": "0",
                "name": "Human Resources"
            }
        ],
        "offset": 0,
        "limit": 100,
        "order": [
            {
                "by": "type",
                "direction": "ASC"
            },
            {
                "by": "name",
                "direction": "ASC"
            }
        ]
    }
}

Rate Limiting

 

In certain cases, Box needs to enforce rate-limiting in order to prevent abuse by third-party services and/or users. In the event that an excessive level of usage is reached, a standard 429 Too Many Requests error will be returned, with an indication of when to retry the request. In the event that back-to-back 429s are received, an exponential backoff algorithm is recommended.

RETRY HEADER

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

OAuth 2

 

The Box API uses OAuth 2 for authentication. OAuth2 can be a little tricky to get started with, but we try to make it easier if you use our SDKs. Once you have authenticated a user, include an authorization header containing a valid access_token in every request.

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

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

OAUTH 2 URL

https://api.box.com/oauth2

BOX AUTHORIZATION HEADER

Authorization: Bearer YOUR_ACCESS_TOKEN

Authorize

 

The URL of Box’s authorization page. This is the URL that your application should forward the user to in first leg of OAuth 2. Note that for this authorize call, you want the user to go to https://account.box.com/api, not api.box.com.

response_type

required

Whether the endpoint returns an authorization code. For web applications, a value of code should be used.

Type: string

client_id

required

The client_id of your application

Type: string

redirect_uri

required

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

Type: uri

state

required

An arbitrary string of your choosing that will be included in the response to your application. It is recommended that you create and include an anti-forgery token.

Type: string

scope

What scope the eventual auth token will have. This field is not required. If not specified the application will get the default scope configured. If your application has different kinds of users that may need different types of scope, then you can provide a comma separated list of scopes, to give some users a lower scope if they sign in from different locations.

Type: string

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

EXAMPLE URL

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

EXAMPLE CALLBACK

YOUR_REDIRECT_URI?code=THE_AUTHORIZATION_CODE

Token

 

The endpoint that returns access tokens.

grant_type

required

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

Type: string

code

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

Type: string

refresh_token

A refresh token retrieved in the final leg of OAuth 2. In most cases these are valid for 60 days, or until used

Type: string

client_id

required

Your application’s client_id

Type: string

client_secret

required

Your application’s client_secret

Type: string

redirect_uri

required

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

Type: uri

box_device_id

Optional unique ID of this device. Used for applications that want to support device-pinning

Type: string

box_device_name

Optional human readable name for this device

Type: string

box_access_token_expires_at

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

Type: unix timestamp

box_refresh_token_expires_at

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

Type: unix timestamp

EXAMPLE REQUEST

curl https://api.box.com/oauth2/token \
-d 'grant_type=authorization_code&code=YOUR_AUTH_CODE&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET' \
-X POST

EXAMPLE RESPONSE

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

Revoke

 

Use this endpoint to revoke active tokens i.e. to ‘log out’ a user.

client_id

required

Your application’s client_id

Type: string

client_secret

required

Your application’s client_secret

Type: string

token

required

One of an access_token or refresh_token (both will be revoked)

Type: string

EXAMPLE REQUEST

curl https://api.box.com/oauth2/revoke \
-d 'client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&token=YOUR_TOKEN' \
-X POST

Folder Object

 

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

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

type

string

For folders is ‘folder’

id

string

The folder’s ID.

sequence_id

string

A unique ID for use with the /events endpoint.

May be null for some folders such as root or trash.

etag

string

A unique string identifying the version of this folder.

May be null for some folders such as root or trash.

name

string

The name of the folder.

created_at

timestamp

The time the folder was created.

May be null for some folders such as root or trash.

description

string

The description of the folder.

size

integer

The folder size in bytes. Be careful parsing this integer, it can easily go into EE notation: see IEEE754 format.

path_collection

collection

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

created_by

mini user object

The user who created this folder.

modified_by

mini user object

The user who last modified this folder.

trashed_at

timestamp

The time the folder or its contents were put in the trash.

May be null for some folders such as root or trash.

purged_at

timestamp

The time the folder or its contents were purged from the trash.

May be null for some folders such as root or trash.

content_created_at

timestamp

The time the folder or its contents were originally created (according to the uploader).
May be null for some folders such as root or trash.

content_modified_at

timestamp

The time the folder or its contents were last modified (according to the uploader).

May be null for some folders such as root or trash.

owned_by

mini user object

The user who owns this folder.

shared_link

object

The shared link for this folder. Null if not set.

folder_upload_email

object

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

parent

mini folder object

The folder that contains this one.
May be null for folders such as root, trash and child folders whose parent is inaccessible.

item_status

string

Whether this item is deleted or not.

item_collection

collection

A collection of mini file and folder objects contained in this folder.

sync_state

string

Whether this folder will be synced by the Box sync clients or not. Can be synced, not_synced, or partially_synced.

has_collaborations

boolean

Whether this folder has any collaborators.

permissions

object

The permissions that the current user has on this folder. The keys are can_download, can_upload, can_rename, can_delete, can_share, can_invite_collaborator, and can_set_share_access. Each value is a boolean.

tags

array of strings

All tags applied to this folder.

can_non_owners_invite

boolean

Whether non-owners can invite collaborators to this folder.

is_externally_owned

boolean

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

allowed_shared_link_access_levels

string

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

allowed_invitee_roles

string

Folder collaboration collaboration settings allowed by the enterprise administrator.

{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": null,
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "file",
                "id": "5000948880",
                "sequence_id": "3",
                "etag": "3",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
                "name": "tigers.jpeg"
            }
        ],
        "offset": 0,
        "limit": 100
    },
    "tags": [
        "approved",
        "ready to publish"
    ]
}
{
    "type":"folder",
    "id":"301415432",
    "sequence_id":"0",
    "etag":"0",
    "name":"my first sub-folder"
}

Get Folder's Info

Retrieves the full metadata about a folder, including information about when it was last updated as well as the files and folders contained in it. The root folder of a Box account is always represented by the id “0”.

 
gethttp://f/folders/FOLDER_ID
curl --request GET \
  --url http://f/folders/FOLDER_ID
var request = require("request");

var options = { method: 'GET', url: 'http://f/folders/FOLDER_ID' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders/FOLDER_ID")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/folders/FOLDER_ID");

xhr.send(data);
import requests

url = "http://f/folders/FOLDER_ID"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 

Returns

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

Request

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

Results

{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": null,
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "file",
                "id": "5000948880",
                "sequence_id": "3",
                "etag": "3",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
                "name": "tigers.jpeg"
            }
        ],
        "offset": 0,
        "limit": 100
    }
}

Get Folder’s Items

Retrieves the files and/or folders contained within this folder without any other metadata about the folder. Any attribute in the full files or folders objects can be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default. Multiple attributes can be passed in separated by commas e.g. fields=name,created_at. Paginated results can be retrieved using the limit and offset parameters.

 
gethttp://f/folders/FOLDER_ID/items
curl --request GET \
  --url http://f/folders/FOLDER_ID/items
var request = require("request");

var options = { method: 'GET', url: 'http://f/folders/FOLDER_ID/items' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders/FOLDER_ID/items")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/folders/FOLDER_ID/items");

xhr.send(data);
import requests

url = "http://f/folders/FOLDER_ID/items"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Query Params

fields
string

Attribute(s) to include in the response

limit
int32

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

offset
string

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

 

Returns

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

Request

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

Results

{
    "total_count": 24,
    "entries": [
        {
            "type": "folder",
            "id": "192429928",
            "sequence_id": "1",
            "etag": "1",
            "name": "Stephen Curry Three Pointers"
        },
        {
            "type": "file",
            "id": "818853862",
            "sequence_id": "0",
            "etag": "0",
            "name": "Warriors.jpg"
        }
    ],
    "offset": 0,
    "limit": 2,
    "order": [
        {
            "by": "type",
            "direction": "ASC"
        },
        {
            "by": "name",
            "direction": "ASC"
        }
    ]
}

Create Folder

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

 
posthttp://f/folders
curl --request POST \
  --url http://f/folders
var request = require("request");

var options = { method: 'POST', url: 'http://f/folders' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://f/folders");

xhr.send(data);
import requests

url = "http://f/folders"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

name
string
required

The desired name for the folder

parent
object
required

The parent folder

id
string
required

Child of parent. The ID of the parent folder

 

Supported Folder Names:

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

Returns

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

Request

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

Results

{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": null,
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 0,
        "entries": [],
        "offset": 0,
        "limit": 100
    }
}

Update Folder

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

 
puthttp://f/folders/FOLDER_ID
curl --request PUT \
  --url http://f/folders/FOLDER_ID
var request = require("request");

var options = { method: 'PUT', url: 'http://f/folders/FOLDER_ID' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders/FOLDER_ID")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "http://f/folders/FOLDER_ID");

xhr.send(data);
import requests

url = "http://f/folders/FOLDER_ID"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

If-Match
string

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

name
string

The name of the folder.

description
string

The description of the folder.

parent
object

The parent folder of this file.

id
string

Child of parent. The ID of the parent folder.

shared_link
object

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

access
string

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

unshared_at
date-time

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

permissions
object

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

can_download
boolean

Child of permissions. Whether this link allows downloads.

can_preview
boolean

Child of permissions. Whether this link allows previews.

folder_upload_email
object

The email-to-upload address for this folder. Set to “null” to disable.

access
string

Child of folder_upload_email. Can be open or collaborators.

owned_by
object

The user who owns the folder. Only used when moving a collaborated folder that you are not the owner of to a folder you are the owner of. Not a substitute for changing folder owners, please reference collaborations to accomplish folder ownership changes.

id
string

Child of owned_by. 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.

 

Request

Returns

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

Request

Results

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

Results

{
 "type": "folder",
 "id": "11446498",
 "sequence_id": "1",
 "etag": "1",
 "name": "New Folder Name!",
 "created_at": "2012-12-12T10:53:43-08:00",
 "modified_at": "2012-12-12T11:15:04-08:00",
 "description": "Some pictures I took",
 "size": 629644,
 "path_collection": {
 "total_count": 1,
 "entries": [
 {
 "type": "folder",
 "id": "0",
 "sequence_id": null,
 "etag": null,
 "name": "All Files"
 }
 ]
 },
 "created_by": {
 "type": "user",
 "id": "17738362",
 "name": "sean rose",
 "login": "sean@box.com"
 },
 "modified_by": {
 "type": "user",
 "id": "17738362",
 "name": "sean rose",
 "login": "sean@box.com"
 },
 "owned_by": {
 "type": "user",
 "id": "17738362",
 "name": "sean rose",
 "login": "sean@box.com"
 },
 "shared_link": {
 "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
 "download_url": null,
 "vanity_url": null,
 "is_password_enabled": false,
 "unshared_at": null,
 "download_count": 0,
 "preview_count": 0,
 "access": "open",
 "permissions": {
 "can_download": true,
 "can_preview": true
 }
 },
 "folder_upload_email": {
 "access": "open",
 "email": "upload.Picture.k13sdz1@u.box.com"
 },
 "parent": {
 "type": "folder",
 "id": "0",
 "sequence_id": null,
 "etag": null,
 "name": "All Files"
 },
 "item_status": "active",
 "item_collection": {
 "total_count": 1,
 "entries": [
 {
 "type": "file",
 "id": "5000948880",
 "sequence_id": "3",
 "etag": "3",
 "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
 "name": "tigers.jpeg"
 }
 ],
 "offset": 0,
 "limit": 100
 }
}

Delete Folder

Used to delete a folder. A recursive parameter must be included in order to delete folders that have items inside of them. An optional If-Match header can be included to ensure that client only deletes the folder if it knows about the latest version.

 
deletehttp://f/folders/FOLDER_ID
curl --request DELETE \
  --url http://f/folders/FOLDER_ID
var request = require("request");

var options = { method: 'DELETE', url: 'http://f/folders/FOLDER_ID' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders/FOLDER_ID")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "http://f/folders/FOLDER_ID");

xhr.send(data);
import requests

url = "http://f/folders/FOLDER_ID"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

If-Match
string

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

fields
string

Attribute(s) to include in the response.

recursive
boolean

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

 

Trash:

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

Returns

An empty 204 response will be returned upon successful deletion. An error is thrown if the folder is not empty and the ‘recursive’ parameter is not included.

Request

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

Results

Copy Folder

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

 
posthttp://f/folders/FOLDER_ID/copy
curl --request POST \
  --url http://f/folders/FOLDER_ID/copy
var request = require("request");

var options = { method: 'POST', url: 'http://f/folders/FOLDER_ID/copy' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders/FOLDER_ID/copy")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://f/folders/FOLDER_ID/copy");

xhr.send(data);
import requests

url = "http://f/folders/FOLDER_ID/copy"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

parent
object
required

Object representing the new location of the folder.

id
string
required

Child of parent. The ID of the destination folder.

name
string

An optional new name for the folder.

 

Returns

A full folder object is returned if the ID is valid and if the update is successful. Errors can be thrown if the destination folder is invalid or if a file-name collision occurs. A 409 will be returned if the intended destination folder is the same, as this will cause a name collision.

Request

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

Results

{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": null,
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "file",
                "id": "5000948880",
                "sequence_id": "3",
                "etag": "3",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
                "name": "tigers.jpeg"
            }
        ],
        "offset": 0,
        "limit": 100
    }
}

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.

 
gethttp://f/folders/FOLDER_ID/collaborations
curl --request GET \
  --url http://f/folders/FOLDER_ID/collaborations
var request = require("request");

var options = { method: 'GET',
  url: 'http://f/folders/FOLDER_ID/collaborations' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders/FOLDER_ID/collaborations")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/folders/FOLDER_ID/collaborations");

xhr.send(data);
import requests

url = "http://f/folders/FOLDER_ID/collaborations"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Query Params

fields
string

Attribute(s) to include in the response

 

Returns

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

Request

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

Results

{
    "total_count": 1,
    "entries": [
        {
            "type": "collaboration",
            "id": "14176246",
            "created_by": {
                "type": "user",
                "id": "4276790",
                "name": "David Lee",
                "login": "david@box.com"
            },
            "created_at": "2011-11-29T12:56:35-08:00",
            "modified_at": "2012-09-11T15:12:32-07:00",
            "expires_at": null,
            "status": "accepted",
            "accessible_by": {
                "type": "user",
                "id": "755492",
                "name": "Simon Tan",
                "login": "simon@box.net"
            },
            "role": "editor",
            "acknowledged_at": "2011-11-29T12:59:40-08:00",
            "item": null
        }
    ]
}

Get Trashed Items

Retrieves the files and/or folders that have been moved to the trash. Any attribute in the full files or folders objects can be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default. Multiple attributes can be passed in separated by commas e.g. fields=name,created_at. Paginated results can be retrieved using the limit and offset parameters.

 
gethttp://f/folders/trash/items
curl --request GET \
  --url http://f/folders/trash/items
var request = require("request");

var options = { method: 'GET', url: 'http://f/folders/trash/items' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders/trash/items")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/folders/trash/items");

xhr.send(data);
import requests

url = "http://f/folders/trash/items"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Query Params

fields
string

Attribute(s) to include in the response

limit
int32

The maximum number of items to return

offset
int32

The item at which to begin the response

 

fields:

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

Returns

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

Request

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

Results

{
    "total_count": 49542,
    "entries": [
        {
            "type": "file",
            "id": "2701979016",
            "sequence_id": "1",
            "etag": "1",
            "sha1": "9d976863fc849f6061ecf9736710bd9c2bce488c",
            "name": "file Tue Jul 24 145436 2012KWPX5S.csv"
        },
        {
            "type": "file",
            "id": "2698211586",
            "sequence_id": "1",
            "etag": "1",
            "sha1": "09b0e2e9760caf7448c702db34ea001f356f1197",
            "name": "file Tue Jul 24 010055 20129Z6GS3.csv"
        }
    ],
    "offset": 0,
    "limit": 2
}

Get Trashed Folder

Retrieves an item that has been moved to the trash.

 
gethttp://f/folders/FOLDER_ID/trash
curl --request GET \
  --url http://f/folders/FOLDER_ID/trash
var request = require("request");

var options = { method: 'GET', url: 'http://f/folders/FOLDER_ID/trash' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders/FOLDER_ID/trash")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/folders/FOLDER_ID/trash");

xhr.send(data);
import requests

url = "http://f/folders/FOLDER_ID/trash"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Query Params

fields
string

Attribute(s) to include in the response

 

Returns

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

Errors

404

The item is not in the trash

Request

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

Results

{
    "type": "folder",
    "id": "588970022",
    "sequence_id": "1",
    "etag": "1",
    "name": "heloo world",
    "created_at": "2013-01-15T16:15:27-08:00",
    "modified_at": "2013-01-17T13:48:23-08:00",
    "description": "",
    "size": 0,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "1",
                "sequence_id": null,
                "etag": null,
                "name": "Trash"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "trashed_at": "2013-02-07T12:53:32-08:00",
    "purged_at": "2013-03-09T12:53:32-08:00",
    "content_created_at": "2013-01-15T16:15:27-08:00",
    "content_modified_at": "2013-01-17T13:48:23-08:00",
    "owned_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "shared_link": null,
    "folder_upload_email": null,
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "trashed"
}

Permanently Delete

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

 
deletehttp://f/folders/FOLDER_ID/trash
curl --request DELETE \
  --url http://f/folders/FOLDER_ID/trash
var request = require("request");

var options = { method: 'DELETE', url: 'http://f/folders/FOLDER_ID/trash' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders/FOLDER_ID/trash")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "http://f/folders/FOLDER_ID/trash");

xhr.send(data);
import requests

url = "http://f/folders/FOLDER_ID/trash"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 

Returns

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

Request

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

Results

Restore Folder

Restores an item that has been moved to the trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. If that parent folder no longer exists or if there is now an item with the same name in that parent folder, the new parent folder and/or new name will need to be included in the request.

 
posthttp://f/folders/FOLDER_ID
curl --request POST \
  --url http://f/folders/FOLDER_ID
var request = require("request");

var options = { method: 'POST', url: 'http://f/folders/FOLDER_ID' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders/FOLDER_ID")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://f/folders/FOLDER_ID");

xhr.send(data);
import requests

url = "http://f/folders/FOLDER_ID"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

name
string

The new name for this item

parent
object

The new parent folder for this item

id
string

Child of parent. The id of the new parent folder

 

Returns

The full item will be returned with a 201 Created status. By default it is restored to the parent folder it was in before it was trashed.

Errors

403

The user doesn’t have access to the folder the item is being restored to or the user doesn’t have permission to restore items from the trash

405

The item is not in the trash

409

There is an item with the same name in the folder the item is being restored to

Request

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

Results

{
    "type": "folder",
    "id": "588970022",
    "sequence_id": "2",
    "etag": "2",
    "name": "heloo world",
    "created_at": "2013-01-15T16:15:27-08:00",
    "modified_at": "2013-02-07T13:26:00-08:00",
    "description": "",
    "size": 0,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "trashed_at": null,
    "purged_at": null,
    "content_created_at": "2013-01-15T16:15:27-08:00",
    "content_modified_at": "2013-02-07T13:26:00-08:00",
    "owned_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "shared_link": null,
    "folder_upload_email": null,
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active"
}

File Object

 

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

Supported Filenames:

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

type

string

For files is ‘file’.

id

string

Box’s unique string identifying this file.

file_version

object

The version information of the file.

sequence_id

string

A unique ID for use with the /events endpoint.

etag

string

A unique string identifying the version of this file.

sha1

string

The sha1 hash of this file.

name

string

The name of this file.

description

string

The description of this file.

size

integer

Size of this file in bytes.

path_collection

collection

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

created_at

timestamp

When this file was created on Box’s servers.

modified_at

timestamp

When this file was last updated on the Box servers.

trashed_at

timestamp

When this file was last moved to the trash.

purged_at

timestamp

When this file will be permanently deleted.

content_created_at

timestamp

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

content_modified_at

timestamp

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

created_by

mini user object

The user who first created file.

modified_by

mini user object

The user who last updated this file.

owned_by

mini user object

The user who owns this file.

shared_link

object

The shared link object for this file.

parent

mini folder object

The folder containing this file.

item_status

string

Whether this item is deleted or not.

version_number

string

The version number of the file.

comment_count

integer

The number of comments on a file.

permissions

object

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

tags

array of strings

All tags applied to this file.

lock

object

The lock held on the file.

extension

string

Indicates the suffix, when available, on the file. By default, set to an empty string. The suffix usually indicates the encoding (file format) of the file contents or usage.

is_package

boolean

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

expiring_embed_link

string

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

{
    "type": "file",
    "id": "5000948880",
    "file_version": {
        "type": "file_version",
        "id": "26261748416",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc "
    },
    "sequence_id": "3",
    "etag": "3",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "tigers.jpeg",
    "description": "a picture of tigers",
    "size": 629644,
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            }
        ]
    },
    "created_at": "2012-12-12T10:55:30-08:00",
    "modified_at": "2012-12-12T11:04:26-08:00",
    "trashed_at": null,
    "purged_at": null,
    "content_created_at": "2013-02-04T16:57:52-08:00",
    "content_modified_at": "2013-02-04T16:57:52-08:00",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
    },
    "item_status": "active",
    "tags": [
        "cropped",
        "color corrected"
    ],
    "lock": {
        "type": "lock",
        "id": "112429",
        "created_by": {
            "type": "user",
            "id": "18212074",
            "name": "Obi Wan",
            "login": "obiwan@box.com"
        },
        "created_at": "2013-12-04T10:28:36-08:00",
        "expires_at": "2012-12-12T10:55:30-08:00",
        "is_download_prevented": false
    }
}
 
{
    "sequence_id": "0",
    "etag": "d9efb63902768a30c9e6225ebff46d15cde82476",
    "type": "file",
    "id": "2631999573",
    "name":"IMG_1312.JPG"
}

Get File's Info

Used to retrieve the metadata about a file.

 
gethttp://f/files/FILE_ID
curl --request GET \
  --url http://f/files/FILE_ID
var request = require("request");

var options = { method: 'GET', url: 'http://f/files/FILE_ID' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/files/FILE_ID");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Query Params

fields
string

Attribute(s) to include in the response

 

Returns

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

Request

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

Results

{
    "type": "file",
    "id": "5000948880",
    "file_version": {
        "type": "file_version",
        "id": "26261748416",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "sequence_id": "3",
    "etag": "3",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "tigers.jpeg",
    "description": "a picture of tigers",
    "size": 629644,
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            }
        ]
    },
    "created_at": "2012-12-12T10:55:30-08:00",
    "modified_at": "2012-12-12T11:04:26-08:00",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
    },
    "item_status": "active"
}

Update File Info

Used to update individual or multiple fields in the file object, including renaming the file, changing its description, and creating a shared link for the file. To move a file, change the ID of its parent folder. An optional If-Match header can be included to ensure that Box only accepts the upload if the sha1 checksum matches what is sent in the header.

 
puthttp://f/files/FILE_ID
curl --request PUT \
  --url http://f/files/FILE_ID
var request = require("request");

var options = { method: 'PUT', url: 'http://f/files/FILE_ID' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "http://f/files/FILE_ID");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

If-Match
string

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

name
string

The new name for the file.

description
string

The new description for the file.

parent
string

The parent folder of this file.

id
string

Child of parent. The ID of the parent folder.

shared_link
object

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

access
string

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

unshared_at
date-time

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

permissions
object

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

download
boolean

Child of permissions. Whether this link allows downloads.

preview
boolean

Child of permissions. Whether this link allows previews.

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

 

Note:

Editing of passwords is currently not supported for shared links.

Returns

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

Request

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

Results

{
    "type": "file",
    "id": "5000948880",
    "sequence_id": "3",
    "etag": "3",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "new name.jpg",
    "description": "a picture of tigers",
    "size": 629644,
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            }
        ]
    },
    "created_at": "2012-12-12T10:55:30-08:00",
    "modified_at": "2012-12-12T11:04:26-08:00",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
    },
    "item_status": "active"
}

Lock and Unlock

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

 
puthttp://f/files/FILE_ID
curl --request PUT \
  --url http://f/files/FILE_ID
var request = require("request");

var options = { method: 'PUT', url: 'http://f/files/FILE_ID' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "http://f/files/FILE_ID");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

lock
object
required

The lock object

type
string
required

Child of lock. Can be lock or unlock.

expires_at
date-time

Child of lock. The time the lock expires.

is_download_prevented
boolean

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

 

Request

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

Results

Download File

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

 
gethttp://f/files/FILE_ID/content
curl --request GET \
  --url http://f/files/FILE_ID/content
var request = require("request");

var options = { method: 'GET', url: 'http://f/files/FILE_ID/content' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID/content")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/files/FILE_ID/content");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID/content"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Query Params

Range
string

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

version
string

The ID specific version of this file to download.

BoxApi
string

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

 

Returns

If the file is available to be downloaded, the response will be a 302 Found to a URL at dl.boxcloud.com. The dl.boxcloud.com URL is not persistent. Clients will need to follow the redirect in order to actually download the file. The raw data of the file is returned unless the file ID is invalid or the user does not have access to it.

If the file is not ready to be downloaded (i.e. in the case where the file was uploaded immediately before the download request), a response with an HTTP status of 202 Accepted will be returned with a Retry-After header indicating the time in seconds after which the file will be available for the client to download.

Sample Call:

For convenience, the sample cURL request includes a -L flag that will automatically follow the redirect to boxcloud.com. To change this behavior, simply remove the -L from the sample call.

Request

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

Results

Redirected to secured download at dl.boxcloud.com

Preflight Check

 
optionshttp://fhttps://api.box.com/2.0/files/content
curl --request OPTIONS \
  --url http://fhttps//api.box.com/2.0/files/content
var request = require("request");

var options = { method: 'OPTIONS',
  url: 'http://fhttps//api.box.com/2.0/files/content' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://fhttps//api.box.com/2.0/files/content")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Options.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("OPTIONS", "http://fhttps//api.box.com/2.0/files/content");

xhr.send(data);
import requests

url = "http://fhttps//api.box.com/2.0/files/content"

response = requests.request("OPTIONS", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

name
string
required

The name of the file to be uploaded

parent
object

The parent folder of this file.

id
string

Child of parent. The ID of the parent folder.

size
string
required

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

 

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

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

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

Supported File Names:

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

Returns

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

Request

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

Upload File

Use the Uploads API to allow users to add a new file. The user can then upload a file by specifying the destination folder for the file. If the user provides a file name that already exists in the destination folder, the user will receive an error.

A different Box URL, https://upload.box.com/api/2.0/files/content, handles uploads. This API uses the multipart post method to complete all upload tasks. You can optionally specify a Content-MD5 header with the SHA1 hash of the file to ensure that the file is not corrupted in transit.

 
posthttp://fhttps://upload.box.com/api/2.0/files/content
curl --request POST \
  --url http://fhttps//upload.box.com/api/2.0/files/content
var request = require("request");

var options = { method: 'POST',
  url: 'http://fhttps//upload.box.com/api/2.0/files/content' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://fhttps//upload.box.com/api/2.0/files/content")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://fhttps//upload.box.com/api/2.0/files/content");

xhr.send(data);
import requests

url = "http://fhttps//upload.box.com/api/2.0/files/content"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

Content-MD5
string

The SHA1 hash of the file

attributes
object
required

File attributes

name
string
required

Name of the file

parent
object
required

Folder object being uploaded into

id
string
required

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

content_created_at
date-time

See content times for formatting

content_modified_at
date-time

See content times for formatting

 

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 full file object is returned inside of a collection if the ID is valid and if the update is successful. An error is thrown when a name collision occurs.

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

Request

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

Results

{
    "total_count": 1,
    "entries": [
        {
            "type": "file",
            "id": "5000948880",
            "sequence_id": "3",
            "etag": "3",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
            "name": "tigers.jpeg",
            "description": "a picture of tigers",
            "size": 629644,
            "path_collection": {
                "total_count": 2,
                "entries": [
                    {
                        "type": "folder",
                        "id": "0",
                        "sequence_id": null,
                        "etag": null,
                        "name": "All Files"
                    },
                    {
                        "type": "folder",
                        "id": "11446498",
                        "sequence_id": "1",
                        "etag": "1",
                        "name": "Pictures"
                    }
                ]
            },
            "created_at": "2012-12-12T10:55:30-08:00",
            "modified_at": "2012-12-12T11:04:26-08:00",
            "trashed_at": null,
            "purged_at": null,
            "content_created_at": "2013-02-04T16:57:52-08:00",
            "content_modified_at": "2013-02-04T16:57:52-08:00",
            "created_by": {
                "type": "user",
                "id": "17738362",
                "name": "sean rose",
                "login": "sean@box.com"
            },
            "modified_by": {
                "type": "user",
                "id": "17738362",
                "name": "sean rose",
                "login": "sean@box.com"
            },
            "owned_by": {
                "type": "user",
                "id": "17738362",
                "name": "sean rose",
                "login": "sean@box.com"
            },
            "shared_link": null,
            "parent": {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            },
            "item_status": "active"
        }
    ]
}

Delete File

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

 
deletehttp://f/files/FILE_ID
curl --request DELETE \
  --url http://f/files/FILE_ID
var request = require("request");

var options = { method: 'DELETE', url: 'http://f/files/FILE_ID' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "http://f/files/FILE_ID");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

If-Match
string

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

 

Trash:

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

Returns

An empty 204 response is sent to confirm deletion of the file. If the If-Match header is sent and fails, a 412 Precondition Failed error is returned.

Request

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

Update File

Uploading a new file version is performed in the same way as uploading a file. This method is used to upload a new version of an existing file in a user’s account. Similar to regular file uploads, these are performed as multipart form uploads. An optional If-Match header can be included to ensure that client only overwrites the file if it knows about the latest version. The filename on Box will remain the same as the previous version. To update the file’s name, use PUT /files/{id}.

 
posthttp://fhttps://upload.box.com/api/2.0/files/FILE_ID/content
curl --request POST \
  --url http://fhttps//upload.box.com/api/2.0/files/FILE_ID/content
var request = require("request");

var options = { method: 'POST',
  url: 'http://fhttps//upload.box.com/api/2.0/files/FILE_ID/content' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://fhttps//upload.box.com/api/2.0/files/FILE_ID/content")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://fhttps//upload.box.com/api/2.0/files/FILE_ID/content");

xhr.send(data);
import requests

url = "http://fhttps//upload.box.com/api/2.0/files/FILE_ID/content"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

If-Match
string

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

 

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

Request

curl https://upload.box.com/api/2.0/files/FILE_ID/content \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "If-Match: ETAG_OF_ORIGINAL" \
-F filename=@FILE_NAME

Results

{
  "total_count": 1,
  "entries": [
    {
      "type": "file",
      "id": "5000948880",
      "sequence_id": "3",
      "etag": "3",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
      "name": "tigers.jpeg",
      "description": "a picture of tigers",
      "size": 629644,
      "path_collection": {
        "total_count": 2,
        "entries": [
          {
            "type": "folder",
            "id": "0",
            "sequence_id": null,
            "etag": null,
            "name": "All Files"
          },
          {
            "type": "folder",
            "id": "11446498",
            "sequence_id": "1",
            "etag": "1",
            "name": "Pictures"
          }
        ]
      },
      "created_at": "2012-12-12T10:55:30-08:00",
      "modified_at": "2012-12-12T11:04:26-08:00",
      "trashed_at": null,
      "purged_at": null,
      "content_created_at": "2013-02-04T16:57:52-08:00",
      "content_modified_at": "2013-02-04T16:57:52-08:00",
      "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
      },
      "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
      },
      "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
      },
      "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
          "can_download": true,
          "can_preview": true
        }
      },
      "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
      },
      "item_status": "active"
    }
  ]
}

View Versions

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

 
gethttp://f/files/FILE_ID/versions
curl --request GET \
  --url http://f/files/FILE_ID/versions
var request = require("request");

var options = { method: 'GET', url: 'http://f/files/FILE_ID/versions' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID/versions")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/files/FILE_ID/versions");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID/versions"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Query Params

fields
string

Attribute(s) to include in the response

 

Alert:

Versions are only tracked for Box users with premium accounts.

Returns

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

Request

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

Results

{
 "total_count": 1,
 "entries": [
 {
 "type": "file_version",
 "id": "672259576",
 "sha1": "359c6c1ed98081b9a69eb3513b9deced59c957f9",
 "name": "Dragons.js",
 "size": 92556,
 "created_at": "2012-08-20T10:20:30-07:00",
 "modified_at": "2012-11-28T13:14:58-08:00",
 "modified_by": {
 "type": "user",
 "id": "183732129",
 "name": "sean rose",
 "login": "sean+apitest@box.com"
 }
 }
 ]
}

Download Version

 
gethttp://f
curl --request GET \
  --url http://f/
var request = require("request");

var options = { method: 'GET', url: 'http://f/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/");

xhr.send(data);
import requests

url = "http://f/"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 

Use version url parameter referenced in Download a File section

Promote Version

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

 
posthttp://f/files/FILE_ID/versions/current
curl --request POST \
  --url http://f/files/FILE_ID/versions/current
var request = require("request");

var options = { method: 'POST',
  url: 'http://f/files/FILE_ID/versions/current' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID/versions/current")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://f/files/FILE_ID/versions/current");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID/versions/current"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

type
string
required

Must be ‘file_version’ for this request

id
string
required

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

 

Alert:

Versions are only tracked for Box users with premium accounts.

Returns

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

Request

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

Results

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

Delete Old Version

Discards a specific file version to the trash.

 
deletehttp://f/files/file id/versions/VERSION_ID
curl --request DELETE \
  --url http://f/files/%7Bfile%20id%7D/versions/VERSION_ID
var request = require("request");

var options = { method: 'DELETE',
  url: 'http://f/files/%7Bfile%20id%7D/versions/VERSION_ID' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/%7Bfile%20id%7D/versions/VERSION_ID")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "http://f/files/%7Bfile%20id%7D/versions/VERSION_ID");

xhr.send(data);
import requests

url = "http://f/files/%7Bfile%20id%7D/versions/VERSION_ID"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

If-Match
string

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

 

Trash:

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

Returns

An empty 204 response is sent to confirm deletion of the file. If the If-Match header is sent and fails, a ‘412 Precondition Failed’ error is returned.

Request

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

Copy File

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

 
posthttp://f/files/FILE_ID/copy
curl --request POST \
  --url http://f/files/FILE_ID/copy
var request = require("request");

var options = { method: 'POST', url: 'http://f/files/FILE_ID/copy' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID/copy")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://f/files/FILE_ID/copy");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID/copy"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

parent
object
required

Folder object representing the new location of the file

id
string
required

Child of parent. The ID of the destination folder

name
string

An optional new name for the file

 

Returns

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

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

Request

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

Results

{
    "type": "file",
    "id": "5000948880",
    "sequence_id": "3",
    "etag": "3",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "tigers.jpeg",
    "description": "a picture of tigers",
    "size": 629644,
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            }
        ]
    },
    "created_at": "2012-12-12T10:55:30-08:00",
    "modified_at": "2012-12-12T11:04:26-08:00",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
    },
    "item_status": "active"
}

Get Thumbnail

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

 
gethttp://f/files/FILE_ID/thumbnail.extension
curl --request GET \
  --url http://f/files/FILE_ID/thumbnail.extension
var request = require("request");

var options = { method: 'GET',
  url: 'http://f/files/FILE_ID/thumbnail.extension' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID/thumbnail.extension")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/files/FILE_ID/thumbnail.extension");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID/thumbnail.extension"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

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

 

Returns

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

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

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

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

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

Request

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

Results

Contents of thumbnail

Get Trashed File

Retrieves an item that has been moved to the trash.

 
gethttp://f/files/FILE_ID/trash
curl --request GET \
  --url http://f/files/FILE_ID/trash
var request = require("request");

var options = { method: 'GET', url: 'http://f/files/FILE_ID/trash' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID/trash")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/files/FILE_ID/trash");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID/trash"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 

Returns

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

Request

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

Results

{
    "type": "file",
    "id": "5859258256",
    "sequence_id": "2",
    "etag": "2",
    "sha1": "4bd9e98652799fc57cf9423e13629c151152ce6c",
    "name": "Screenshot_1_30_13_6_37_PM.png",
    "description": "",
    "size": 163265,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "1",
                "sequence_id": null,
                "etag": null,
                "name": "Trash"
            }
        ]
    },
    "created_at": "2013-01-30T18:43:56-08:00",
    "modified_at": "2013-01-30T18:44:00-08:00",
    "trashed_at": "2013-02-07T10:49:34-08:00",
    "purged_at": "2013-03-09T10:49:34-08:00",
    "content_created_at": "2013-01-30T18:43:56-08:00",
    "content_modified_at": "2013-01-30T18:44:00-08:00",
    "created_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "shared_link": {
        "url": null,
        "download_url": null,
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "trashed"
}

Permanently Delete

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

 
deletehttp://f/files/FILE_ID/trash
curl --request DELETE \
  --url http://f/files/FILE_ID/trash
var request = require("request");

var options = { method: 'DELETE', url: 'http://f/files/FILE_ID/trash' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID/trash")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "http://f/files/FILE_ID/trash");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID/trash"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 

Returns

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

Request

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

Restore Item

Restores an item that has been moved to the trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. If that parent folder no longer exists or if there is now an item with the same name in that parent folder, the new parent folder and/or new name will need to be included in the request.

 
posthttp://f/files/FILE_ID
curl --request POST \
  --url http://f/files/FILE_ID
var request = require("request");

var options = { method: 'POST', url: 'http://f/files/FILE_ID' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://f/files/FILE_ID");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

name
string

The new name for this item

parent
object

The new parent folder for this item

id
string

Child of parent. The id of the new parent folder

 

Returns

The full item will be returned with a 201 Created status. By default it is restored to the parent folder it was in before it was trashed.

Errors

403

The user doesn’t have access to the folder the item is being restored to or the user doesn’t have permission to restore items from the trash

404

The item is not in the trash

409

There is an item with the same name in the folder the item is being restored to

Request

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

Results

{
    "type": "file",
    "id": "5859258256",
    "sequence_id": "3",
    "etag": "3",
    "sha1": "4bd9e98652799fc57cf9423e13629c151152ce6c",
    "name": "Screenshot_1_30_13_6_37_PM.png",
    "description": "",
    "size": 163265,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_at": "2013-01-30T18:43:56-08:00",
    "modified_at": "2013-02-07T10:56:58-08:00",
    "trashed_at": null,
    "purged_at": null,
    "content_created_at": "2013-01-30T18:43:56-08:00",
    "content_modified_at": "2013-02-07T10:56:58-08:00",
    "created_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "shared_link": {
        "url": "https://seanrose.box.com/s/ebgti08mtmhbpb4vlp55",
        "download_url": "https://seanrose.box.com/shared/static/ebgti08mtmhbpb4vlp55.png",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 4,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active"
}

View Comments

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

 
gethttp://f/files/FILE_ID/comments
curl --request GET \
  --url http://f/files/FILE_ID/comments
var request = require("request");

var options = { method: 'GET', url: 'http://f/files/FILE_ID/comments' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID/comments")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/files/FILE_ID/comments");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID/comments"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Query Params

fields
string

Attribute(s) to include in the response

 

Returns

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

Request

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

Results

{
    "total_count": 1,
    "entries": [
        {
            "type": "comment",
            "id": "191969",
            "is_reply_comment": false,
            "message": "These tigers are cool!",
            "created_by": {
                "type": "user",
                "id": "17738362",
                "name": "sean rose",
                "login": "sean@box.com"
            },
            "created_at": "2012-12-12T11:25:01-08:00",
            "item": {
                "id": "5000948880",
                "type": "file"
            },
            "modified_at": "2012-12-12T11:25:01-08:00"
        }
    ]
}

Get File's Tasks

Retrieves all of the tasks for given file.

 
gethttp://f/files/FILE_ID/tasks
curl --request GET \
  --url http://f/files/FILE_ID/tasks
var request = require("request");

var options = { method: 'GET', url: 'http://f/files/FILE_ID/tasks' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID/tasks")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/files/FILE_ID/tasks");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID/tasks"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Query Params

fields
string

Attribute(s) to include in the response

 

Returns

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

Request

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

Results

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

Metadata Overview

 

Metadata allows users and applications to define and store custom data associated with their files and folders in Box. 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.

Metadata Templates

 

Templates

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

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

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

Metadata templates can be set up in the Admin Console.

Template Object

template

string

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

scope

string

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

displayName

string

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

hidden

boolean

Whether this template is hidden in the UI

fields

Collection
Template Field objects

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

Template Fields Object

type

string

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

key

string

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

displayName

string

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

description

string

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

hidden

boolean

Whether this template is hidden in the UI

options

array of strings

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

key

string

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

Global Properties Template

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

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

Get Enterprise Metadata

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

 
gethttp://f/metadata_templates/SCOPE
curl --request GET \
  --url http://f/metadata_templates/SCOPE
var request = require("request");

var options = { method: 'GET', url: 'http://f/metadata_templates/SCOPE' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/metadata_templates/SCOPE")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/metadata_templates/SCOPE");

xhr.send(data);
import requests

url = "http://f/metadata_templates/SCOPE"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 

Returns

All the templates within an enterprise and their corresponding schema

Request

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

Results

{
    "entries": [
        {
            "templateKey": "customer",
            "scope": "enterprise_490585",
            "displayName": "Customer",
            "hidden": false,
            "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",
                    "hidden": false,
                    "options": [
                        {
                            "key": "FY11"
                        },
                        {
                            "key": "FY12"
                        },
                        {
                            "key": "FY13"
                        },
                        {
                            "key": "FY14"
                        },
                        {
                            "key": "FY15"
                        }
                    ]
                },
                {
                    "type": "enum",
                    "key": "qtr",
                    "displayName": "Qtr",
                    "hidden": false,
                    "options": [
                        {
                            "key": "First"
                        },
                        {
                            "key": "Second"
                        },
                        {
                            "key": "Third"
                        },
                        {
                            "key": "Fourth"
                        }
                    ]
                }
            ]
        }
    ],
    "total_count": 1
}

Get Metadata Schema

Used to retrieve the schema for a given metadata template.

 
gethttp://f/metadata_templates/SCOPE/TEMPLATE/schema
curl --request GET \
  --url http://f/metadata_templates/SCOPE/TEMPLATE/schema
var request = require("request");

var options = { method: 'GET',
  url: 'http://f/metadata_templates/SCOPE/TEMPLATE/schema' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/metadata_templates/SCOPE/TEMPLATE/schema")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/metadata_templates/SCOPE/TEMPLATE/schema");

xhr.send(data);
import requests

url = "http://f/metadata_templates/SCOPE/TEMPLATE/schema"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 

RETURNS

The schema representing the metadata template queried

Request

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

Results

{
    "templateKey": "customer",
    "scope": "enterprise_490685",
    "displayName": "Customer",
    "hidden": false,
    "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",
            "hidden": false,
            "options": [
                {
                    "key": "FY11"
                },
                {
                    "key": "FY12"
                },
                {
                    "key": "FY13"
                },
                {
                    "key": "FY14"
                },
                {
                    "key": "FY15"
                }
            ]
        },
        {
            "type": "enum",
            "key": "qtr",
            "displayName": "Qtr",
            "hidden": false,
            "options": [
                {
                    "key": "First"
                },
                {
                    "key": "Second"
                },
                {
                    "key": "Third"
                },
                {
                    "key": "Fourth"
                }
            ]
        }
    ]
}
{}

Metadata on Files and Folders

 

Template Instance Object

$template

string

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

$scope

string

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

$parent

string

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

$version

integer

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

$id

string

36 character UUID to identify the metadata object.

$type

string

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

$typeVersion

integer

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

key(s)

string

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

Create Metadata on File

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

 
posthttp://f/files/FILE_ID/metadata/SCOPE/TEMPLATE
curl --request POST \
  --url http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE
var request = require("request");

var options = { method: 'POST',
  url: 'http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

Content-Type
string
required

Must be application/json

custom-defined-key(s)
string
required

Custom value(s) defined by a user or application

 

Returns

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

Request

curl https://api.box.com/2.0/files/6122548033/metadata/enterprise/marketingCollateral \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"audience":"external", "vertical": "healthcare", "documentType": "datasheet", "status": "active"}' \
-X POST

Results

{
  "audience": "external",
  "vertical": "healthcare",
  "documentType": "datasheet",
  "status": "active",
  "$type": "marketingCollateral-1199c73f-11aa-439a-a7d0-e981fc6cc22f",
  "$parent": "file_6122548033",
  "$id": "fab04c3b-bf72-4726-80d1-d87f8cb87592",
  "$template": "marketingCollateral",
  "$scope": "enterprise_42500",
  "$version": 0,
  "$typeVersion": 0
}

Get Metadata on File

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

 
gethttp://f/files/FILE_ID/metadata/SCOPE/TEMPLATE
curl --request GET \
  --url http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE
var request = require("request");

var options = { method: 'GET',
  url: 'http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 

Returns

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

Request

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

Results

{
  "audience": "external",
  "vertical": "healthcare",
  "documentType": "datasheet",
  "status": "active",
  "$type": "marketingCollateral-1199c73f-11aa-439a-a7d0-e981fc6cc22f",
  "$parent": "file_6122548033",
  "$id": "1e3ab159-3737-405e-9d9e-de3cebdd5e29",
  "$template": "marketingCollateral",
  "$scope": "enterprise_42500",
  "$version": 0,
  "$typeVersion": 0
}

Update Metadata on File

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

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

 
puthttp://f/files/FILE_ID/metadata/SCOPE/TEMPLATE
curl --request PUT \
  --url http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE
var request = require("request");

var options = { method: 'PUT',
  url: 'http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

Content-Type
string
required

Must be application/json-patch+json

op
string
required

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

path
string
required

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

value
string

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

from
string

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

 

Returns

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

Request

curl https://api.box.com/2.0/files/6122548033/metadata/enterprise/marketingCollateral \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json-patch+json" \
-d '[{"op": "test", "path":"/audience", "value":"external"},
	{ "op": "replace", "path":"/audience", "value": "internal"},
	{ "op": "test", "path":"/status", "value":"active"},
  { "op": "remove", "path":"/status"},
	{ "op": "add", "path":"/competitiveDocument", "value": "yes"},
  { "op": "test", "path":"/author", "value":"Ned Stark"},
  { "op": "copy", "from":"/author", "path":"/editor"},
  { "op": "test", "path":"/category", "value":"Cloud"},
  { "op": "move", "from":"/category", "path": "/oldCategory"}]' \
-X PUT

Results

{
  "$type": "marketingCollateral-1199c73f-11aa-439a-a7d0-e981fc6cc22f",
  "$parent": "file_6122548033",
  "$id": "d55c2a68-6032-447a-a5fd-2539c29db5fc",
  "$template": "marketingCollateral",
  "$scope": "enterprise_42500",
  "$version": 1,
  "$typeVersion": 0,
  "audience": "internal",
  "documentType": "presentation",
  "competitiveDocument": "yes",
  "status": "active"
}

Delete Metadata on File

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

 
deletehttp://f/files/FILE_ID/metadata/SCOPE/TEMPLATE
curl --request DELETE \
  --url http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE
var request = require("request");

var options = { method: 'DELETE',
  url: 'http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID/metadata/SCOPE/TEMPLATE"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 

Returns

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

Request

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

Get All Metadata on File

Used to retrieve all metadata associated with a given file

 
gethttp://f/files/FILE_ID/metadata/
curl --request GET \
  --url http://f/files/FILE_ID/metadata/
var request = require("request");

var options = { method: 'GET', url: 'http://f/files/FILE_ID/metadata/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/files/FILE_ID/metadata/")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/files/FILE_ID/metadata/");

xhr.send(data);
import requests

url = "http://f/files/FILE_ID/metadata/"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "entries": [
        {
            "$type": "marketingCollateral-1199c73f-11aa-439a-a7d0-e981fc6cc22f",
            "$parent": "file_10559150999",
            "$id": "2f76a16d-44af-44a8-b630-fc62e0f1d80c",
            "$template": "marketingCollateral",
            "$scope": "enterprise_42500",
            "$version": 0,
            "$typeVersion": 0,
            "contentApproved": "yes",
            "audience": "external"
        },
       {
            "$type": "legal-05014851-9823-4d7d-9784-a6626b855e2b",
            "$parent": "file_27243056898",
            "$id": "8c76e8e1-1525-4cb8-a863-e61408336e24",
            "$template": "legal",
            "$scope": "enterprise_42500",
            "$version": 0,
            "$typeVersion": 0,
            "clientNumber": "49281"
        },
        {
            "$type": "properties",
            "$parent": "file_10559150999",
            "$id": "81f320f4-bd07-4c93-b2fb-e4614f4e5d8d",
            "$template": "properties",
            "$scope": "global",
            "$version": 0,
            "$typeVersion": 0,
            "programmatic_key": "18282as3df9",
            "my_app_id": "389"
        }
    ],
    "limit": 20
}
 

Returns

An array of metadata template instances associated with the file.

Create Metadata on Folder

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

 
posthttp://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE
curl --request POST \
  --url http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE
var request = require("request");

var options = { method: 'POST',
  url: 'http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE");

xhr.send(data);
import requests

url = "http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

Content-Type
string
required

Must be application/json

JSON formatted metadata value(s)
string
required

JSON formatted value(s) for the specific metadata template

 

Available in Beta

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

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

Returns

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

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

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

Request

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

Results

{
    "currentDocumentStage": "initial vetting",
    "needsApprovalFrom": "vetting team",
    "nextDocumentStage": "prioritization",
    "maximumDaysAllowedInCurrentStage": 5,
    "$type": "documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f",
    "$parent": "folder_998951261",
    "$id": "8a4719fd-f3f9-41cc-b31e-11f6060093ef",
    "$version": 0,
    "$typeVersion": 0,
    "$template": "documentFlow",
    "$scope": "enterprise_12345"
}

Get Metadata on Folder

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

 
gethttp://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE
curl --request GET \
  --url http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE
var request = require("request");

var options = { method: 'GET',
  url: 'http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE");

xhr.send(data);
import requests

url = "http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 

Available in Beta

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

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

Returns

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

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

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

Request

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

Results

{
    "currentDocumentStage": "initial vetting",
    "needsApprovalFrom": "vetting team",
    "nextDocumentStage": "prioritization",
    "maximumDaysAllowedInCurrentStage": 5,
    "$type": "documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f",
    "$parent": "folder_998951261",
    "$id": "8a4719fd-f3f9-41cc-b31e-11f6060093ef",
    "$version": 0,
    "$typeVersion": 0,
    "$template": "documentFlow",
    "$scope": "enterprise_12345"
}

Update Metadata on Folder

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

 
puthttp://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE
curl --request PUT \
  --url http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE
var request = require("request");

var options = { method: 'PUT',
  url: 'http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE");

xhr.send(data);
import requests

url = "http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

Content-Type
string
required

Must be application/json-patch+json

op
string
required

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

path
string
required

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

value
string

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

 

Available in Beta

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

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

Returns

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

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

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

Request

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

Results

{
    "currentDocumentStage": "initial vetting",
    "needsApprovalFrom": "vetting team",
    "nextDocumentStage": "legal",
    "competitiveDocument": "yes",
    "$type": "documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f",
    "$parent": "folder_998951261",
    "$id": "54c7c38b-6afa-438a-abd4-c74eeef02a2c",
    "$version": 1,
    "$typeVersion": 0,
    "$template": "documentFlow",
    "$scope": "enterprise_12345"
}

Delete Metadata on Folder

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

 
deletehttp://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE
curl --request DELETE \
  --url http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE
var request = require("request");

var options = { method: 'DELETE',
  url: 'http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE");

xhr.send(data);
import requests

url = "http://f/folders/FOLDER_ID/metadata/SCOPE/TEMPLATE"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 

Available in Beta

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

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

Returns

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

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

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

Request

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

Collection Object

 

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

type

string

For collections is ‘collection’.

id

string

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

name

string

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

collection_type

string

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

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

Get Collections

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

 
gethttp://f/collections
curl --request GET \
  --url http://f/collections
var request = require("request");

var options = { method: 'GET', url: 'http://f/collections' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/collections")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/collections");

xhr.send(data);
import requests

url = "http://f/collections"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 

Request

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

Results

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

Get Collection Items

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

 
gethttp://f/collections/COLLECTION_ID/items
curl --request GET \
  --url http://f/collections/COLLECTION_ID/items
var request = require("request");

var options = { method: 'GET',
  url: 'http://f/collections/COLLECTION_ID/items' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://f/collections/COLLECTION_ID/items")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://f/collections/COLLECTION_ID/items");

xhr.send(data);
import requests

url = "http://f/collections/COLLECTION_ID/items"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Query Params

fields
string

Attribute(s) to include in the response

limit
int32

The maximum number of items to return in a page.

offset
string

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

 

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

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

Returns

An array of items contained in the collection is returned. An error is thrown if the collection does not exist, or if any of the parameters are invalid.

Order:

Each order object will list an attribute (e.g. name) and direction (e.g. ASC).

Request

curl https://api.box.com