Documentation

Introduction

The XML Server Endpoint URL is http://box.net/api/1.0/xml
You should post your queries there.

Getting Started Guide

Getting Started with the Box.net API

You can use the Box.net API to create applications and Web sites that integrate with Box.net. The Box.net API is a collection of Web services, which means that you can create Box Enabled applications using any modern programming language and operating system on any computer connected to the internet.

Box Enabled applications can perform the following functions:

Store and retrieve files from Box.net
Organize files into folders
Move, rename and delete files
Share files

Before you do anything, you'll need to sign up and obtain a Box.net API key, since you'll need to pass in your API key with every API call you make.

Every session with a Box Enabled application begins with user authentication, so we'll start there. For simplicity, we'll use the Box.net REST API, although you can also use the SOAP or XML Post APIs in your applications if you prefer -- the basic concepts are the same.

Box.net API authentication provides a secure way for users to authenticate with Box.net without having to share their Box.net user name or password with you. This provides a consistent, safe experience for users and makes things easier on you (since you don't have to store user credentials).

To obtain an authentication ticket, your application performs these steps:

Obtain an authentication ticket by calling the get_ticket API method
Redirect the user to the Box.net API authentication page, passing the ticket you obtained from the get_ticket call as a query string parameter
The user then authenticates by entering their user name and password on the authentication page

After the user has authenticated, the next step depends on whether you're writing a web application or a client application.

If you're writing a web application, Box.net redirects the user to a page called the callback page. This is a page that resides on your site (you should have designated this page when you set up your application). The authentication appends a ticket variable to the end of this URL, passing you a request that looks like this:

http://mysite.com/callback.php?ticket=ncnpjxt8bz7qkbn83c0qaf3ps0tr30tq &auth_token=98j243g9ijapwedfgjap8wj34gajw38w

After the user has been redirected to your callback page, you should store the auth_token value securely, since every API call your application makes from this point forward will require the application key and the authentication token to be passed in along with the call. (The ticket parameter is deprecated and only provided for backwards compatibility.)

For client applications, the user is shown a message instructing them to return to the application after they've authenticated. The application then calls get_auth_token with the ticket parameter to retrieve the authorization token.

At this point, you'll probably either want to show the user the files in their Box or enable them to upload a file to their Box.

To show a complete list of the user's files and folders, use the get_account_tree call. This call retrieves an XML document describing the entire contents of the user's box, including files and folders. You can also pass the ID of a folder as a parameter to this call, enabling your application to retrieve a subset of the tree structure.

To upload a file, your application performs an HTTP POST using a URL of the form:

http://upload.box.net/api/upload/<auth_token>/<folder_id>

At the time you upload a file using HTTP POST, you can also specify whether you want the file to be publicly sharable (as described in the Upload and Download reference documentation). You can also share a file after it's been uploaded using the public_share API if you prefer.

Authentication

Box.net authentication

To authenticate users you should follow these steps:

Get a ticket calling get_ticket method.
Redirect the user to www.box.net/api/1.0/auth/<ticket>.
User authenticates on box.net.
1. For desktop software, users will see a message that they can now proceed into the application.
  The user can then press a button in the application to continue authentication, at which point the application can get the auth_token by calling the get_auth_token method, which will authenticate further requests.
2. For web-based applications, the user will be redirected to a url provided in your application settings at enabled.box.net.
  At the end of the url auth_token=<ticket> will be appended after '&' or '?' mark depending on your redirect url.

get_ticket

input parameters:
    api_key: string
output parameters:
    status: string,
    ticket: string

This method is used in the authorization process.

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>get_ticket</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
</request>

Response

<?xml version='1.0' encoding='UTF-8'?>
<response>
    <status>get_ticket_ok</status>
    <ticket>bxquuv025arztljze2n438md9zef95e8</ticket>
</response>

get_auth_token

input parameters:
    api_key: string,
    ticket: string,
output parameters:
    status: string,
    auth_token: string,
    user: SOAPUser

This method is used in the authorization process. You should call this method after the user has authorized themself on box.net site. Pass ticket that you get when called get_ticket method. On a successful result, method will return 'get_auth_token_ok' as status, auth_token to use in other method calls, and user struct which describes logged user.

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>get_auth_token</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
    <ticket>udd863k39gn9mioc6ym2c6erbqm8qfsh</ticket>
</request>

Response

<?xml version='1.0' encoding='UTF-8'?>
<response>
    <status>get_auth_token_ok</status>
    <auth_token>9byo5bg8d2o3otp0voji0ej0v49bqcmo</auth_token>
    <user>
        <login>stas@itscript.com</login>
        <email>stas@itscript.com</email>
        <access_id>453</access_id>
        <user_id>453</user_id>
        <space_amount>2147483648</space_amount>
        <space_used>1024</space_used>
    </user>
</response>

authorization

input parameters:
    api_key: string,
    login: string,
    password: string,
    method: string
output parameters:
    status: string,
    auth_token: string,
    user: SOAPUser

This method is used to authorize a user. The 'method' param can be either empty or 'md5'. If method param is 'md5' you should provide password as md5 hash of login+pass, where pass is original user password.

On successful authorization method will return 'logged' as status, sid is session id to use in other method calls, and SOAPUser which describes logged user.

If authorization wasn't successful, then status filed can be:
'invalid_login' when login or password is incorrect
'application_restricted' if you use an incorrect or restricted API key.
Other fields will be empty.

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>authorization</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
    <login>email@example.com</login>
    <password>1</password>
    <method />
</request>

Response

<?xml version='1.0' encoding='UTF-8'?>
<response>
    <status>logged</status>
    <auth_token>7umg20uoqv8bya5qj86txv8v7dmbrue0</auth_token>
    <user>
        <login>email@example.com</login>
        <email>email@example.com</email>
        <access_id>453</access_id>
        <user_id>453</user_id>
        <space_amount>2147483648</space_amount>
        <space_used>42782559</space_used>
    </user>
</response>

logout

input parameters:
    api_key: string,
    sid: string
output parameters:
    status: string,

This method is used to logout a user.
On successful logout method will return 'logout_ok' as status.
If logout wasn't successful, then status filed can be:
'invalid_auth_token' when auth_token is invalid.

Request

<?xml version='1.0' encoding='UTF-8' ?>
 <request>
    <action>logout</action>
 </request>

Response

<?xml version='1.0' encoding='UTF-8' ?>
<response>
  <status>logout_ok</status>
</response>

register_new_user

input parameters:
    api_key: string,
    login: string,
    password: string
output parameters:
    status: string,
    sid: string,
    user: SOAPUser

This method is used to register a user. Upon a successful registration, the status param will be 'successful_register'.
If registration wasn't successful, status field can be:
'e_register',
'email_invalid',
'email_already_registered',
'application_restricted'.

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>register_new_user</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
    <login>email@example.com</login>
    <password>123</password>
</request>

Response

<?xml version='1.0' encoding='UTF-8' ?>
<response>
    <status>successful_register</status>
    <auth_token>29135479a888671e0dd6512df4f7a009</auth_token>
    <user>
        <login>email@example.com</login>
        <email>email@example.com</email>
        <access_id>398387</access_id>
        <user_id>398387</user_id>
        <space_amount>1073741824</space_amount>
        <space_used>0</space_used>
    </user>
</response>

register_paid_user

input parameters:
	api_key: string,
	login: string,
	password: string,
	name: string,
	plan: string,
	period: string,
	credit_card_first_name: string,
	credit_card_last_name: string,
	credit_card_street_address: string,
	credit_card_zip: string,
	credit_card_country: string,
	credit_card_number: string,
	credit_card_cvv: string,
	credit_card_exp_date: string
output parameters:
	status: string,
	sid: string,
	user: SOAPUser

This method is used to register paid user. The 'plan' param can be either 'Individual' or 'Business'. The 'period' param can be either 'Month' or 'Year'. Upon a successful registration, the status param will be 'successful_register'.
If registration wasn't successful, status field can be:
'e_register',
'email_invalid',
'email_already_registered',
'credit_card_fields_error',
'wrong_billing_plan',
'wrong_billing_period',
'billing_error',
'application_restricted'.

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
	<action>register_paid_user</action>
	<api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
	<login>email@example.com</login>
	<password>123</password>
	<name>John Doe</name>
	<plan>Business</plan>
	<period>Year</period>
	<credit_card_first_name>John</credit_card_first_name>
	<credit_card_last_name>Doe</credit_card_last_name>
	<credit_card_street_address>100 Main Street</credit_card_street_address>
	<credit_card_zip>12345</credit_card_zip>
	<credit_card_country>US</credit_card_country>
	<credit_card_number>0000000000000000</credit_card_number>
	<credit_card_cvv>111</credit_card_cvv>
	<credit_card_exp_date>1109</credit_card_exp_date>
</request>

Response

<?xml version='1.0' encoding='UTF-8' ?>
<response>
	<status>successful_register</status>
	<auth_token>29135479a888671e0dd6512df4f7a009</auth_token>
	<user>
		<login>email@example.com</login>
		<email>email@example.com</email>
		<access_id>398387</access_id>
		<user_id>398387</user_id>
		<space_amount>1073741824</space_amount>
		<space_used>0</space_used>
	</user>
</response>

verify_registration_email

input parameters:
    api_key: string,
    login: string
output parameters:
    status: string,

This method is used to verify user registration email . Upon a not used and right registration email, the status param will be 'email_ok'.
Else status field can be:
'email_invalid',
'email_already_registered',
'application_restricted'.

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>verify_registration_email</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
    <login>email@example.com</login>
</request>

Response

<?xml version='1.0' encoding='UTF-8' ?>
<response>
    <status>email_ok</status>
</response>

get_account_tree

input parameters:
    api_key: string,
    sid: string,
    folder_id: long,
    params: ArrayOfString
output parameters:
    status: string,
    tree: base64Binary

This method is used to get a user's files and folders tree.

'folder_id' param defines root folder from which the tree begins.
'params' is array of string where you can set additional parameters, which are:
onelevel - make a tree of one level depth, so you will get only files and folders stored in folder which folder_id you have provided.
nofiles - include folders only in result tree, no files.
nozip - do not zip tree xml.

On successful result you will receive 'listing_ok' as status and base64 encoded zipped tree xml.
So you have to decode the received tree, then unzip it (if you haven't set 'nozip' param) and you will get xml like this:
(note that

updated

and

created

are UNIX timestamps in PST)

<?xml version="1.0" ?>
<folder id="0" name="" shared="0">
  <tags></tags>
  <files></files>
  <folders>
     <folder id="4384" name="Incoming" shared="0">
        <tags>
           <tag id="34" />
         </tags>
         <files>
            <file id="68736" file_name="cows.w3g" keyword="" shared="0" size="232386"
            created="1129537520" updated="1129537520">
               <tags>
               </tags>
            </file>
            <file id="68737" file_name="silver.html" keyword="" shared="0" size="15805"
            created="1129537520" updated="1129537520">
               <tags>
                  <tag id="35" />
               </tags>
            </file>
         </files>
      </folder>
   <folders>
</folder>

If result wasn't successful status can be:
'not_logged_id',
'application_restricted',
'e_folder_id'

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>get_account_tree</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
    <auth_token>263gtmxiy8k8o2ebzs41pilbubvpn91g</auth_token>
    <folder_id>0</folder_id>
    <params />
</request>

Response

<?xml version='1.0' encoding='UTF-8'?>
<response>
 <status>listing_ok</status>
 <tree>
  <folder id="0" name="" shared="0">
   <tags></tags>
   <files></files>
   <folders>
    <folder id="4384" name="Incoming" shared="0">
     <tags>
      <tag id="34" />
     </tags>
   <files>
    <file id="68736" file_name="cows.w3g" keyword="" shared="0" size="232386"
    created="1129537520" updated="1129537520">
     <tags> </tags>
    </file>
    <file id="68737" file_name="silver.html" keyword="" shared="0" size="15805"
    created="1129537520" pdated="1129537520">
     <tags>
      <tag id="35" />
     </tags>
    </file>
   </files>
  </folder>
   <folders>
  </folder>
 </tree>
</response>

export_tags

input parameters:
    api_key: string,
    sid: string
output parameters:
    status: string,
    tag_xml: base64Binary,

This method returns all the user's tags.

On successful a result, you will receive 'export_tags_ok' and tag_xml will be base64 encoded tags xml.
After decoding tag_xml you will get xml like this:

<?xml version="1.0"?>
<tags>
    <tag id="37">
        music
    </tag>
    <tag id="38">
        mp3
    </tag>
</tags>

If the result wasn't successful, status field can be:
not_logged_id,
application_restricted

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>export_tags</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
    <auth_token>z35bqm6o87ry4k02eug3r3yhrfsc5del</auth_token>
</request>

Response

<?xml version='1.0' encoding='UTF-8'?>
<response>
    <status>export_tags_ok</status>
    <tags>
        <tag id="37">tag1</tag>
        <tag id="38">tag2</tag>
    </tags>
</response>

create_folder

input parameters:
    api_key: string,
    sid: string,
    parent_id: long,
    name: string,
    share: long
output parameters:
    status: string,
    folder: SOAPFolder

This method creates a new folder.

'parent_id' param is the id of a folder in which a new folder will be created, 'name' param is the name of a new folder.
Set 'share' to 1 if you want to share a folder publicly.

On a successful result, the status will be 'create_ok'.

If the result wasn't successful, status field can be:
'e_no_parent_folder',
'not_logged_in',
'application_r'stricted'

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>create_folder</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
    <auth_token>5oahsklt4x0emkj1rdzm3nug1aq81t9k</auth_token>
    <parent_id>0</parent_id>
    <name>New Folder</name>
    <share>1</share>
</request>

Response

<?xml version='1.0' encoding='UTF-8'?>
<response>
    <status>create_ok</status>
    <folder>
        <folder_id>738</folder_id>
        <folder_name>New Folder</folder_name>
        <folder_type_id>0</folder_type_id>
        <user_id>453</user_id>
        <path></path>
        <shared>1</shared>
        <public_name>gh23ghjj</public_name>
        <show_comments></show_comments>
        <parent_folder_id>0</parent_folder_id>
        <password></password>
    </folder>
</response>

move

input parameters:
    api_key: string,
    sid: string,
    target: string,
    target_id: long,
    destination_id: long
output_parameters:
    status: string

This method moves a file or folder to another folder.

'target' param can be either 'file' or 'folder' depending on what do you want to move, 'target_id' is the id of a file or folder to be moved, 'destination_id' is the destination folder id.

On a successful result, status will be 's_move_node'.
If the result wasn't successful, status field can be:
'e_move_node',
'not_logged_in',
'application_restricted'

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>move</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
    <auth_token>19x43ykyo3bnefz75yyuepxgm6o4rf7a</auth_token>
    <target>folder</target>
    <target_id>739</target_id>
    <destination_id>738</destination_id>
</request>

Response

<?xml version='1.0' encoding='UTF-8'?>
<response>
    <status>s_move_node</status>
</response>

rename

input parameters:
    api_key: string,
    sid: string,
    target: string,
    target_id: long,
    new_name: string
output parameters:
    status: string

This method renames a file or folder.

'target' param can be either 'file' or 'folder' depending on what you want to rename, 'target_id' is the id of a file or folder to be renamed, 'new_name' is the new name for a file or folder.

On a successful result, status will be 's_rename_node'.
If result wasn't successful, stat's field can be:
'e_rename_node',
'not_logged_in',
'application_restricted'

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>rename</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
    <auth_token>bhpcsgorohv70rrkcf5so19vrapuznla</auth_token>
    <target>folder</target>
    <target_id>739</target_id>
    <new_name>New Name</new_name>
</request>

Response

<?xml version='1.0' encoding='UTF-8'?>
<response>
    <status>s_rename_node</status>
</response>

delete

input parameters:
    api_key: string,
    sid: string,
    target: string,
    target_id: long
output parameters:
    status: string

This method deletes a file or folder.

'target' param can be either 'file' or 'folder' depending on what you want to delete, 'target_id' is id of a file or folder to be deleted.

On a successful result, the status will be 's_delete_node'.
If the result wasn't successful, status field can be:
'e_delete_node',
'not_logged_in',
'application_restricted'

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>delete</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
    <auth_token>tkm1l2ojyhgrf86zzvdqvoa6zcqss6pf</auth_token>
    <target>folder</target>
    <target_id>738</target_id>
</request>

Response

<?xml version='1.0' encoding='UTF-8'?>
<response>
    <status>s_delete_node</status>
</response>

public_share

input parameters:
    api_key: string,
    sid: string,
    target: string,
    target_id: long,
    password: string,
    message: string,
    emails: ArrayOfString,
output parameters:
    status: string,
    public_name: string

This method publicly shares a file or folder. 'target' param should be either 'file' or 'folder', 'target_id' is id of the file or folder to be shared. 'password' param is to protect sharing with a password, 'emails' params is array of emails to notify about a new share, 'message' param is some message to be included in a notification email.

On a successful result, the status will be 'share_ok' and 'public_name' param will be a unique identifier of a publicly shared file or folder.
If the result wasn't successful, the status field can be:
'share_error',
'wrong_node',
'not_logged_in',
'application_restricted'

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>public_share</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
    <auth_token>rpuis3lincpbyz60gyym8s3xhnc6gbcl</auth_token>
    <target>folder</target>
    <target_id>709</target_id>
    <password></password>
    <message>hey</message>
    <emails>
        <item>email@example.com</item>
        <item>email2@example.com</item>
    </emails>
</request>

Response

<?xml version='1.0' encoding='UTF-8'?>
<response>
    <status>share_ok</status>
    <public_name>ojf3i2n100</public_name>
</response>

public_unshare

input parameters:
    api_key: string,
    sid: string,
    target: string,
    target_id: long
output parameters:
    status: string

This method unshares a shared file or folder. 'target' param shoud be either 'file' or 'folder', 'target_id' is id of a file or folder to be unshared.

On a successful result, the status will be 'unshare_ok'.
If the result wasn't successful, the status field can be:
'unshare_error',
'wrong_node',
'not_logged_in',
'application_restricted'

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>public_unshare</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
    <auth_token>j8eu39sn43pmso00au856izbndae5oom</auth_token>
    <target>folder</target>
    <target_id>709</target_id>
</request>

Response

<?xml version='1.0' encoding='UTF-8'?>
<response>
    <status>unshare_ok</status>
</response>

private_share

input parameters:
    api_key: string,
    sid: string,
    target: string,
    target_id: long,
    emails: ArrayOfString,
    message: string,
    notify: boolean
output parameters:
    status: string

This method privately shares a file or folder with another user(s). 'target' param should be either 'file' or 'folder', 'target_id' is the id of the file or folder to be shared. 'emails' params is an array of emails of users' to share files with. if 'notify' param is true, then a notification email will be sent to users, 'message' param is a message to be included in the notification email.

Note: currently only files can be shared privately.

On a successful result, the status will be 'private_share_ok'.
If the result wasn't successful, the status field can be:
'private_share_error',
'wrong_node',
'not_logged_in',
'application_restricted'

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>private_share</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
    <auth_token>7pdreq6aqtq7udn986mxnp8lpq1ol0ec</auth_token>
    <target>file</target>
    <target_id>4935</target_id>
    <emails>
        <item>email@example.com</item>
    </emails>
    <message>hey</message>
    <notify>true</notify>
</request>

Response

<?xml version='1.0' encoding='UTF-8'?>
<response>
    <status>private_share_ok</status>
</response>

add_to_mybox

input parameters:
    api_key: string,
    sid: string,
    file_id: long,
    public_name: string,
    folder_id: long,
    tags: string
output parameters:
    status: string

This method copies a file publicly shared by someone to a user's mybox. 'file_id' and 'public_name' params identify a publicly shared file, you should provide either file_id or public name (like '31nhke0ahp') as a parameter. 'folder_id' is the id of a user's folder, where files are to be copied.

On a successful result, the status will be 'addtomybox_ok'.
If the result wasn't successful, the status field can be:
'addtomybox_error',
'not_logged_id',
'application_restricted',
's_link_exists'

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>add_to_mybox</action>
    <api_key>rrc1d3ntb53tt6b2vhail6rdtrsxov3v</api_key>
    <auth_token>a3ysjive1k2x1q82bme6pxhngqh9ryrn</auth_token>
    <file_id>4940</file_id>
    <public_name></public_name>
    <folder_id>0</folder_id>
    <tags />
</request>

Response

<?xml version='1.0' encoding='UTF-8'?>
<response>
    <status>addtomybox_ok</status>
</response>

add_to_tag

input parameters:
    api_key: string,
    sid: string,
    tags: ArrayOfString,
    target: string,
    target_id: long
output parameters:
    status: string

This method adds file or folder to tags list. 'target' param can be either 'file' or 'folder' depending on what do you want to add, 'target_id' is the id of a file or folder to be added, 'tags' array of tags where target will be added.

On successful a result, you will receive 'addtotag_ok'.
If the result wasn't successful, status field can be:
addtotag_error

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>add_to_tag</action>
    <api_key>p6eu1n2tblaeebnfkyby4gfkg6mrz0xp</api_key>
    <auth_token>8bp4l5h28pkyfrdz40v5mdru8k59d6d9</auth_token>
    <tags><item>test_tag</item><item>test_tag1</item></tags>
    <target>file</target>
    <target_id>6334</target_id>
</request>

Response

<?xml version='1.0' encoding='UTF-8' ?>
<response>
	<status>addtotag_ok</status>
</response>

get_file_info

input parameters:
    api_key: string,
    sid: string,
    file_id: long
output parameters:
    status: string,
    info: SOAPFileInfo

This method gets file info. 'file_id' param should contain valid if of user file.

On successful a result, you will receive status 's_get_file_info' and file info in 'info'.
If the result wasn't successful, status field can be:
e_access_denied

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>get_file_info</action>
    <api_key>rrc1d3n4b53tt6b2vh1il6tdtrsxov3v</api_key>
    <auth_token>d1bpbz3r1nc5z5jk00tkkldsrhxy6u8q</auth_token>
    <file_id>224</file_id>
</request>

Response

<?xml version='1.0' encoding='UTF-8' ?>
<response><status>s_get_file_info</status>
<info>
	<file_id>224</file_id>
	<file_name>Box Press Release.doc</file_name>
	<folder_id>0</folder_id>
	<shared>0</shared>
	<shared_name></shared_name>
	<size>22528</size>
	<description></description>
	<sha1>9a0bc49038c167151c544ac0b5fc9042335a41a3</sha1>
	<created>1182159570</created>
	<updated>1182159571</updated>
</info>
</response>

set_description

input parameters:
    api_key: string,
    sid: string,
    target: string,
    target_id: login,
    description: string
output parameters:
    status: string

This method sets a description to a file or folder. 'target' can be a 'file' or 'folder', 'target_id' - id of file or folder, description - string that should be set as description.

On successful a result, you will receive status 's_set_description'.
If the result wasn't successful, status field can be:
e_set_description

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>set_description</action>
    <api_key>rrc1d3n4b53tt6b2vh1il6tdtrsxov3v</api_key>
    <auth_token>79r205ihgupsbucfani0iu483oa1iupn</auth_token>
    <target>file</target>
    <target_id>224</target_id>
    <description>123</description>
</request>

Response

<?xml version='1.0' encoding='UTF-8' ?>
<response>
<status>s_set_description</status>
</response>

get_friends

input parameters:
    api_key: string,
    sid: string,
    params: ArrayOfString
output parameters:
    status: string,
    friends: base64Binary

This method is used to retrieve a list of freinds.

'params' is an array of the string where you can set additional parameters, which are:
nozip - do not zip tree xml.

On a successful result you will receive 's_get_friends' as the status and base64 encoded (and zipped) friends xml.
Friends xml looks like this:

<friends>
  <friend>
    <name>email2@example.com</name>
    <email>email2@example.com</email>
    <accepted>1</accepted>
    <avatar_url>
      http://box.net/index.php?rm=box_user_avatar&amp;user_id=398396
      &amp;width=40&amp;height=40&amp;type=large
    </avatar_url>
    <boxes>
      <box>
        <id>15</id>
        <url>http://box.net/p/email2</url>
        <status>0</status>
      </box>
    </boxes>
    <subscriptions>
      <subscription>
        <box_id>14</box_id>
        <user_name>email3@example.com</user_name>
        <url>http://box.net/p/email3</url>
        <status>subscribed</status>
      </subscription>
    </subscriptions>
  </friend>
</friends>

If the result wasn't successful, status field can be:
e_get_friends

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>get_friends</action>
    <api_key>rrc1d3n4b53tt6b2vh1il6tdtrsxov3v</api_key>
    <auth_token>79r205ihgupsbucfani0iu483oa1iupn</auth_token>
    <params>
        <item>nozip</item>
    </params>
</request>

Response

<?xml version='1.0' encoding='UTF-8' ?>
<response>
<status>s_get_friends</status>
<friends>
<friends>
  <friend>
    <name>email2@example.com</name>
    <email>email2@example.com</email>
    <accepted>1</accepted>
    <avatar_url>
      http://box.net/index.php?rm=box_user_avatar&amp;user_id=398396
      &amp;width=40&amp;height=40&amp;type=large
    </avatar_url>
    <boxes>
      <box>
        <id>15</id>
        <url>http://box.net/p/email2</url>
        <status>0</status>
      </box>
    </boxes>
    <subscriptions>
      <subscription>
        <box_id>14</box_id>
        <user_name>email3@example.com</user_name>
        <url>http://box.net/p/email3</url>
        <status>subscribed</status>
      </subscription>
    </subscriptions>
  </friend>
</friends>
</response>

request_friends

input parameters:
    api_key: string,
    sid: string,
    emails: ArrayOfString,
    message: string,
    params: ArrayOfString
output parameters:
    status: string

This method requests new friends to be added to your network.
'emails' - array of emails.
'message' - text message that you want to send to freinds.
'params' is an array of string where you can set additional parameters, which are:
box_auto_subscribe - subscribe to public boxes of inveted users.
no_email - don't send emails to invited users.

On a successful result, you will receive status 's_request_friends'.
If the result wasn't successful, status field can be:
e_request_friends

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>request_friends</action>
    <api_key>rrc1d3n4b53tt6b2vh1il6tdtrsxov3v</api_key>
    <auth_token>l9zk4uob1pvlaj4h75z272nq1kgds19c</auth_token>
	<emails>
	  <item>email1@example.com</item>
	  <item>email2@example.com</item>
	</emails>
    <message>123</message>
    <params>
      <item>auto_subscribe</item>
    </params>
</request>

Response

<?xml version='1.0' encoding='UTF-8' ?>
<response>
	<status>s_request_friends</status>
</response>

get_updates

input parameters:
    api_key: string,
    sid: string,
    begin_timestamp: long,
    params: ArrayOfString
output parameters:
    status: string,
    updates: base64Binary

This method is used to get a list of last updates.
'begin_timestamp' - the start date in unix timestamp of the range of updates you wish to retrieve.
'params' is array of string where you can set additional parameters, which are:
nozip - do not zip tree xml.

On successful result you will receive 's_get_updates' as status and base64 encoded(and zipped) updates xml.
Updates xml looks like this:

<updates>
  <update>
    <name></name>
      <message></message>
      <updated>1180341648</updated>
      <user_name>email1@example.xom</user_name>
      <public_url>http://box.net/p/email1</public_url>
      <files>
        <file>
          <name></name>
          <size>293.5 KB</size>
          <date>May 28, 2007</date>
          <thumbnail>
            http://dav1.box.net/large_thumb/2007-05-28/b711d51b95bd
            888ada7a46999b3d2b70.jpg
          </thumbnail>
        </file>
     </files>
  </update>
</updates>

If the result wasn't successful, status field can be:
e_get_updates

Request

<?xml version='1.0' encoding='UTF-8' ?>
<request>
    <action>get_updates</action>
    <api_key>rrc1d3n4b53tt6b2vh1il6tdtrsxov3v</api_key>
    <auth_token>y27omu660h6raey99j2ey8hqfo2tv9oe</auth_token>
    <begin_timestamp>0</begin_timestamp>
    <params>
      <item>nozip</item>
    </params>
</request>

Response

<?xml version='1.0' encoding='UTF-8' ?>
<response>
<status>s_get_updates</status>
<updates>
  <updates>
  <update>
    <name></name>
      <message></message>
      <updated>1180341648</updated>
      <user_name>email1@example.xom</user_name>
      <public_url>http://box.net/p/email1</public_url>
      <files>
        <file>
          <name></name>
          <size>293.5 KB</size>
          <date>May 28, 2007</date>
          <thumbnail>
            http://dav1.box.net/large_thumb/2007-05-28/b711d51b95bd
            888ada7a46999b3d2b70.jpg
          </thumbnail>
        </file>
     </files>
  </update>
</updates>
</updates>
</response>

Upload & Download

Download

To download a file, use a link like http://box.net/api/1.0/download/<auth_token>/<file_id>
for example:

http://box.net/api/1.0/download/0ef4e2b1be630554ffa4044c054b1954/542666

Upload

To upload a file, send HTTP POST request to http://upload.box.net/api/1.0/upload/<auth_token>/<folder_id>

It is important that you upload to upload.box.net otherwise your upload will be rejected.

folder_id is the id of a folder in which the file will be uploaded.
For public sharing of file set share, message and emails fields.
HTML to perform an upload might look like the following:

<form action="http://upload.box.net/api/1.0/upload/0ef4e2b1be630554ffa4044c054b1954/756"
 enctype="multipart/form-data" method="POST">
<input type="file" name="new_file1" />
<input type="file" name="new_file2" />
<input type="text" name="share" value="1" />
<input type="text" name="message" value="Hello" />
<input type="text" name="emails[]" value="test@domain.com" />
<input type="text" name="emails[]" value="test1@domain.com" />
<input type="submit" name="upload_files" value="Upload File" />
</form>

Response will be:

<?xml version='1.0' encoding='UTF-8' ?>
<response>
<status>upload_ok</status>
<files>
  <file file_name="read_me.txt" id="5996" folder_id="756" shared="0" public_name="" />
  <file file_name="Rally.avi" error="filesize_limit_exceeded" />
</files>
</response>

If the result wasn't successful, the status field can be:
'upload_some_files_failed',
'not_logged_id',
'application_restricted'

For files that wasn't upload error field can be:
not_enough_free_space,
filesize_limit_exceeded,
access_denied

Need help? Contact us

Sections

Introduction Getting Started Guide Authentication get_ticket get_auth_token logout register_new_user verify_registration_email get_account_tree export_tags create_folder move rename delete public_share public_unshare private_share add_to_mybox add_to_tag get_file_info set_description get_friends request_friends Upload & Download