Sample - Box Platform API
POST/files/{file_id}/upload_sessions

Create an upload session for an existing file

Creates an upload session for replacing or uploading content for an existing file. Supply file_size and optionally provide file_name when the existing file should receive a new name. Use the returned session details to upload the file in chunks.

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

1 parameter · 2 body fields
file_idstringrequired
The unique identifier of the existing file for which to create an upload session.

Details for creating an upload session for an existing file. file_size is required; file_name can optionally rename the file.

file_sizeintegerrequired
The total number of bytes of the file to be uploaded.
file_namestringoptional
The optional new name of new file.

3 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
409Returned when the file already exists in a conflicting state 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 409 is returned when the file already exists in a conflicting state or the account has run out of disk space. file_id must identify the existing file to update, and file_size must specify the total number of bytes to upload.