Quick Start - Box Dev Docs

Box is a cloud-based, intelligent content management and file sharing platform for storing, accessing, and collaborating on content from anywhere. Confirm your email address to activate your developer account.

Upload a file to Box and list all files in the root folder

The Upload file endpoint allows you to upload a single file to Box through the upload domain https://upload.box.com/api/2.0/files/content.

The maximum file size is 50MB. For larger files, use the .

A pre-built application is created for you to get started. Create a developer token to authenticate your requests. Go to the Developer Console > your pre-built application and find the App Details section. Locate the Developer Token field, select Generate Developer Token, and copy it.

Developer tokens expire one hour after you generate them.

We prepared an example invoice document for you to upload. Create a root folder for your project, download the file , and save it in the folder.

Python
Node.js
Swift
Java
.NET

Create and activate a Python virtual environment.

python3 -m venv .venv
source .venv/bin/activate

Install the Box Python SDK by running the following command using .

pip install "boxsdk>=10"

Make sure you use the most up-to-date version number of the Python SDK. Refer to the .

Obtain a client with your developer token:

from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth, UploadFileAttributes, UploadFileAttributesParentField
import json

auth = BoxDeveloperTokenAuth(token="YOUR_DEVELOPER_TOKEN")
client = BoxClient(auth=auth)

For production codebase, always store your credentials in a .env file and add .env to your .gitignore.

Then call the upload API as follows.

with open("demo-invoice-20tax-2.pdf", "rb") as file_content_stream:
    uploaded_file = client.uploads.upload_file(
        UploadFileAttributes(
            name="demo-invoice-20tax-2.pdf",
            parent=UploadFileAttributesParentField(id="0"),
        ),
        file_content_stream,
    )

items = client.folders.get_folder_items("0")
print(json.dumps(items.to_dict(), indent=2))

The get_folder_items command lists all files in the root folder. Execute the script to upload the file and list all files.

Install the Box Node.js SDK by running the following command using . The box package installs the Box Node SDK and the Box CLI as direct dependencies. Node.js 22 or later is required.

npm install box

Existing projects can keep using npm install box-node-sdk — that package is still supported.

Import the SDK:

import BoxSDK from 'box/sdk';  // ESM
const BoxSDK = require('box/sdk');  // CommonJS

const { BoxClient, BoxDeveloperTokenAuth } = require('box/sdk');
const auth = new BoxDeveloperTokenAuth({ token: 'YOUR_DEVELOPER_TOKEN' });
const client = new BoxClient({ auth });

Developer tokens expire one hour after you generate them.

const fs = require('fs');

const attrs = { name: 'demo-invoice-20tax-2.pdf', parent: { id: '0' } };
const body = {
  attributes: attrs,
  file: fs.createReadStream('demo-invoice-20tax-2.pdf'),
};
const files = await client.uploads.uploadFile(body);
const file = files.entries[0];
console.log(`File uploaded with id ${file.id}, name ${file.name}`);

const items = await client.folders.getFolderItems('0');
console.log(JSON.stringify(items, null, 2));

The getFolderItems command lists all files in the root folder. Execute the script to upload the file and list all files.

Install the Box Swift SDK by running the following command using .

swift package update

Developer tokens expire one hour after you generate them.

Obtain a client with your developer token:

import BoxSdkGen

let auth = BoxDeveloperTokenAuth(token: "YOUR_DEVELOPER_TOKEN")
let client = BoxClient(auth: auth)

Create a request body with the required parameters: attributes (name and parent id) and a file stream.

guard let fileStream = InputStream(url: URL(fileURLWithPath: "demo-invoice-20tax-2.pdf")) else {
    fatalError("Could not read a file")
}

let requestBody = UploadFileRequestBody(
    attributes: UploadFileRequestBodyAttributesField(
        name: "demo-invoice-20tax-2.pdf",
        parent: UploadFileRequestBodyAttributesParentField(id: "0")
    ),
    file: fileStream
)

let files = try await client.uploads.uploadFile(requestBody: requestBody)

if let file = files.entries?[0] {
    print("File uploaded with id \(file.id), name \(file.name!)")
}

let items = try await client.folders.getFolderItems(folderId: "0")
if let entries = items.entries {
    for entry in entries {
        switch entry {
        case let .fileMini(file):
            print("file \(file.name!) [\(file.id)]")
        case let .folderMini(folder):
            print("folder \(folder.name!) [\(folder.id)]")
        case let .webLinkMini(webLink):
            print("webLink \(webLink.name!) [\(webLink.id)]")
        }
    }
}

The getFolderItems command lists all files in the root folder. Execute the script to upload the file and list all files.

Developer tokens expire one hour after you generate them.

GradleInstall the Box Java SDK by adding the following dependency to the build.gradle file.

implementation 'com.box:box-java-sdk:10.9.0'

Make sure you use the most up-to-date version number of the Java SDK. Refer to the .

MavenThen add the following to Maven dependency.

<dependency>
    <groupId>com.box</groupId>
    <artifactId>box-java-sdk</artifactId>
    <version>10.9.0</version>
</dependency>

Obtain a client with your developer token:

BoxDeveloperTokenAuth auth = new BoxDeveloperTokenAuth("YOUR_DEVELOPER_TOKEN");
BoxClient client = new BoxClient(auth);

Pass new UploadFileRequestBody to client.getUploads().uploadFile: attributes (UploadFileRequestBodyAttributesField with name and UploadFileRequestBodyAttributesParentField for folder id) and an InputStream for the file bytes.

FileInputStream fileContentStream = new FileInputStream("demo-invoice-20tax-2.pdf");
client.getUploads().uploadFile(
    new UploadFileRequestBody(
        new UploadFileRequestBodyAttributesField(
            "demo-invoice-20tax-2.pdf",
            new UploadFileRequestBodyAttributesParentField("0")
        ),
        fileContentStream
    )
);

client.getFolders().getFolderItems("0").getEntries().forEach(item -> {
    System.out.println(item);
});

The getFolderItems command lists all files in the root folder. Execute the script to upload the file and list all files.

.NET FrameworkTo install the .NET SDK in the .NET framework, run the following command using the package manager.

PM> Install-Package Box.V2.Core

Developer tokens expire one hour after you generate them.

.NET CoreTo install the .NET SDK in the .NET Core framework, run the following command using the package manager.

PM> Install-Package Box.V2.Core

Obtain a client with your developer token:

using Box.Sdk.Gen;

var auth = new BoxDeveloperTokenAuth(token: "YOUR_DEVELOPER_TOKEN");
var client = new BoxClient(auth: auth);

Await client.Uploads.UploadFileAsync with new UploadFileRequestBody: UploadFileRequestBodyAttributesField (name and parent id) and a Stream (for example from File.OpenRead).

using var fileContentStream = File.OpenRead("demo-invoice-20tax-2.pdf");
var files = await client.Uploads.UploadFileAsync(
    requestBody: new UploadFileRequestBody(
        attributes: new UploadFileRequestBodyAttributesField(
            name: "demo-invoice-20tax-2.pdf",
            parent: new UploadFileRequestBodyAttributesParentField(id: "0")),
        file: fileContentStream));
var file = files.Entries[0];
Console.WriteLine($"File uploaded with id {file.Id}, name {file.Name}");

var items = await client.Folders.GetFolderItemsAsync(folderId: "0");
if (items.Entries != null)
{
    foreach (var item in items.Entries)
    {
        if (item.FileFull != null)
        {
            Console.WriteLine(item.FileFull.Name);
        }
        else if (item.FolderMini != null)
        {
            Console.WriteLine(item.FolderMini.Name);
        }
        else if (item.WebLink != null)
        {
            Console.WriteLine(item.WebLink.Name);
        }
    }
}

The getFolderItems command lists all files in the root folder. Execute the script to upload the file and list all files.

Congratulations! You’ve uploaded your first file to Box and listed all files in the root folder.

Use cases

Unsure if your use case is a good fit for Box Platform? You’re in the right place if:

Content is in the center of your use case
Your process involves moving content from one place to another
Your workflow can abide by waterfall permissions
Your process involves administrative tasks that can be automated

Some common customer solutions include:

Marketing asset management
Secure document vaults
Wealth management portals
Automatic folder creation based on user provisioning
Adding relevant metadata using machine learning
Claim reviews with built-in approval/rejection flows
Event monitoring for security and auditing

What’s next

Explore the following resources:

What a free developer plan offers
Authentication methods to understand the different authentication methods available.
Box CLI to help you build your application.
Box glossary to understand the key concepts of Box Platform.
Changelog to stay up to date with the latest changes.

​Sign up for a free account

​Upload a file to Box and list all files in the root folder

​Use cases

​What’s next

Sign up for a free account

Upload a file to Box and list all files in the root folder

Use cases

What’s next