The quickstart guide below will take you through all the steps necessary to start accessing your own Box account through the API.
Please see the walkthrough on OAuth 2.0 to get an access token for making API calls.
Once you’ve successfully authenticated your user, you’ll want to be able to see what’s in their Box account. You can do this by simply getting the information about their root folder, which for every user is identified by ’0′. Using cURL, we would do this like so:
curl https://api.box.com/2.0/folders/FOLDER_ID \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
The response to this call in my account looks like this (yours will look similar):
{ "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": "https://www.box.com/shared/static/vspke7y05sb214wjokpk", "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 } }
Now that we’re able to see what’s in the user’s account, let’s try to add some new files through the API. We need to do this as a multipart form upload, which looks like this in cURL:
curl https://api.box.com/2.0/files/content \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -F filename=@FILE_NAME \ -F folder_id=FOLDER_ID
Upon success, you’ll receive a response that should look like this:
{ "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", "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" } ] }
Since we now have a file_id available, let’s try downloading that same file just to see how the process works. This is accomplished through a simple GET request to a /files resource like so:
curl https://api.box.com/2.0/files/FILE_ID/content?version=10849 \ -H "Authorization: Bearer ACCESS_TOKEN"
The response to this request will simply be the complete data of the file itself.
That’s just the beginning of what you can do with the Box API. Check out the full documentation to find out all of the other features of the API.