Create upload session


Creates an upload session for a new file.



Request Body

stringin bodyrequired

The name of new file

integer / int64in bodyrequired

The total number of bytes of the file to be uploaded

stringin bodyrequired

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


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.

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

Request Example

curl -i -X POST "" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "folder_id": "0",
       "file_size": 104857600,
       "file_name": "Contract.pdf"
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);
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 {} with chunk size of {upload_session.part_size} bytes')
// 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": "",
    "commit": "",
    "list_parts": "",
    "log_event": "",
    "status": "",
    "upload_part": ""
  "session_expires_at": "2012-12-12T10:53:43-08:00",
  "total_parts": 1000