Sample - Box Platform API
POST/files/upload_sessions

Create an upload session

Creates an upload session for a new file in a specified folder. Supply folder_id, file_size, and file_name so the service can determine the required part size and number of upload parts. Use the returned session details to upload the file in chunks.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

3 body fields

Details for creating an upload session for a new file. folder_id, file_size, and file_name are required.

folder_idstringrequired
The ID of the folder to upload the new file to.
file_sizeintegerrequired
The total number of bytes of the file to be uploaded.
file_namestringrequired
The name of new file.

6 status codes
201Returns the created upload session, including its identifier, expiration time, required part size, total part count, processed part count, and session endpoints.
idstringoptional
The unique identifier for this session.
typestringoptional
The value will always be `upload_session`.
Allowed:upload_session
session_expires_atstringoptional
The date and time when this session expires.
part_sizeintegeroptional
The size in bytes that must be used for all parts of of the upload. Only the last part is allowed to be of a smaller size.
total_partsintegeroptional
The total number of parts expected in this upload session, as determined by the file size and part size.
num_parts_processedintegeroptional
The number of parts that have been uploaded and processed by the server. This starts at `0`. When committing a file files, inspecting this property can provide insight if all parts have been uploaded correctly.
session_endpointsobjectoptional
400Returned when a required parameter is missing or invalid, including an invalid `folder_id`, `file_name`, or `file_size`, or a file size below the minimum supported for this upload method.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
403Returned when the operation is not allowed because the account storage limit has been exceeded.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
404Returned when the parent folder identified by `folder_id` does not exist or the authenticated user cannot access it.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
409Returned when the file already exists or the account has run out of disk space.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultReturns a generic error object for an unexpected client error.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 400 is returned when folder_id, file_size, or file_name is missing or invalid, including when file_size is below the minimum supported size. A 403 is returned when the account storage limit is exceeded, and a 404 is returned when folder_id does not identify an accessible folder. A 409 is returned when the file already exists or the account has no remaining disk space.