A beta version of the new Box developer documentation site is launching soon! Updated Developer Guides, modern API Reference, and AI-powered search are on the way to help you build with Box faster. Stay tuned for more updates.
Latest version
Create upload session
API version 2024.0
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
104857600The 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: Nofolder_idwas provided.invalid_folder_id:folder_idis not valid.item_name_invalid:file_nameis not valid.missing_file_size:file_sizewas not provided.invalid_file_size:file_sizewas not a valid number.file_size_too_small:file_sizeis below minimum file size for uploads via this API.missing_file_name:file_namewas 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: Thefolder_idvalue 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.
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"
}'Node/TypeScript v10
await client.chunkedUploads.createFileUploadSession({
fileName: fileName,
fileSize: fileSize,
folderId: parentFolderId,
} satisfies CreateFileUploadSessionRequestBody);Python v10
client.chunked_uploads.create_file_upload_session(
parent_folder_id, file_size, file_name
).NET v10
await client.ChunkedUploads.CreateFileUploadSessionAsync(requestBody: new CreateFileUploadSessionRequestBody(fileName: fileName, fileSize: fileSize, folderId: parentFolderId));Swift v10
try await client.chunkedUploads.createFileUploadSession(requestBody: CreateFileUploadSessionRequestBody(fileName: fileName, fileSize: Int64(fileSize), folderId: parentFolderId))Java v10
client.getChunkedUploads().createFileUploadSession(new CreateFileUploadSessionRequestBody(parentFolderId, fileSize, fileName)).NET v6
await client.ChunkedUploads.CreateFileUploadSessionAsync(requestBody: new CreateFileUploadSessionRequestBody(fileName: fileName, fileSize: fileSize, folderId: parentFolderId));Node v4
await client.chunkedUploads.createFileUploadSession({
fileName: fileName,
fileSize: fileSize,
folderId: parentFolderId,
} satisfies CreateFileUploadSessionRequestBody);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
}