Box Developer Documentation

Join BoxWorks 2024 to discover what's possible with content and AI!

Register now!

Create upload session

post
https://upload.box.com/api/2.0
/files/upload_sessions

Creates an upload session for a new file.

Request

bearer [ACCESS_TOKEN]
application/json

Request Body

stringin bodyrequired
"Project.mov"

The name of new file

integer (int64)in bodyrequired
104857600

The total number of bytes of the file to be uploaded

stringin bodyrequired
"0"

The ID of the folder to upload the new file to.

Response

application/jsonUpload session

Returns a new upload session.

application/jsonClient error

Returns an error if some of the parameters are missing or not valid.

  • missing_destination: No folder_id was provided
  • invalid_folder_id: folder_id is not valid
  • item_name_invalid: file_name is not valid
  • missing_file_size: file_size was not provided
  • invalid_file_size: file_size was not a valid number
  • file_size_too_small: file_size is below minimum file size for uploads via this API
  • missing_file_name: file_name was not provided
application/jsonClient error

Returns an error if the operation is not allowed for some reason.

  • storage_limit_exceeded: Account storage limit reached
application/jsonClient error

Returns an error if the parent folder could not be found, or the authenticated user does not have access to it.

  • invalid_parameter: The folder_id value represents a folder that the user does not have access to, or does not exist.
application/jsonClient error

Returns an error if the file already exists, or the account has run out of disk space.

application/jsonClient error

An unexpected client error.

post
Create upload session
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -i -X POST "https://upload.box.com/api/2.0/files/upload_sessions" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "folder_id": "0",
       "file_size": 104857600,
       "file_name": "Contract.pdf"
     }'
TypeScript Gen
await client.chunkedUploads.createFileUploadSession({
  fileName: fileName,
  fileSize: fileSize,
  folderId: parentFolderId,
} satisfies CreateFileUploadSessionRequestBody);
Python Gen
client.chunked_uploads.create_file_upload_session(
    parent_folder_id, file_size, file_name
)
.NET Gen
await client.ChunkedUploads.CreateFileUploadSessionAsync(requestBody: new CreateFileUploadSessionRequestBody(fileName: fileName, fileSize: fileSize, folderId: parentFolderId));
Swift Gen (Beta)
try await client.chunkedUploads.createFileUploadSession(requestBody: CreateFileUploadSessionRequestBody(fileName: fileName, fileSize: Int64(fileSize), folderId: parentFolderId))
Java
BoxFileUploadSession.Info sessionInfo;
if (/* uploading a new file */) {
    // Create the upload session for a new file
    BoxFolder rootFolder = BoxFolder.getRootFolder(api);
    sessionInfo = rootFolder.createUploadSession("New Large File.pdf", fileSize);
} else if (/* uploading a new version of an exiting file */) {
    // Create the uplaod session for a new version of an existing file
    String fileID = "93465";
    BoxFile file = new BoxFile(api, fileID);
    sessionInfo = file.createUploadSession(fileSize);
}

//Get the session resource from the session info
BoxFileUploadSession session = sessionInfo.getResource();

//Create the Message Digest for the whole file
MessageDigest digest = null;
try {
    digest = MessageDigest.getInstance("SHA1");
} catch (NoSuchAlgorithmException ae) {
    throw new BoxAPIException("Digest algorithm not found", ae);
}
Python
file_size = 26000000
file_name = 'test_file.pdf'
upload_session = client.folder('22222').create_upload_session(file_size, file_name)
print(f'Created upload session {upload_session.id} with chunk size of {upload_session.part_size} bytes')
Node
// Create a session to upload a 2GB file "huge.pdf" into folder 12345
client.files.createUploadSession('12345', 2147483648, 'huge.pdf', callback);

Response Example

{
  "id": "F971964745A5CD0C001BBE4E58196BFD",
  "type": "upload_session",
  "num_parts_processed": 455,
  "part_size": 1024,
  "session_endpoints": {
    "abort": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "commit": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit",
    "list_parts": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts",
    "log_event": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log",
    "status": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "upload_part": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD"
  },
  "session_expires_at": "2012-12-12T10:53:43-08:00",
  "total_parts": 1000
}