Skip to main content
POST
/
files
/
{file_id}
/
upload_sessions
Create upload session for existing file
curl -i -X POST "https://upload.box.com/api/2.0/files/12345/upload_sessions" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "file_size": 104857600
     }'
{
  "id": "F971964745A5CD0C001BBE4E58196BFD",
  "type": "upload_session",
  "session_expires_at": "2012-12-12T10:53:43-08:00",
  "part_size": 1024,
  "total_parts": 1000,
  "num_parts_processed": 455,
  "session_endpoints": {
    "upload_part": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "commit": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit",
    "abort": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "list_parts": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts",
    "status": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "log_event": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log"
  }
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

​
file_id
string
required

The unique identifier that represents a file.

The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL https://*.app.box.com/files/123 the file_id is 123.

Body

application/json
​
file_size
integer<int64>
required

The total number of bytes of the file to be uploaded.

Example:

104857600

​
file_name
string

The optional new name of new file.

Example:

"Project.mov"

Response

Returns a new upload session.

An upload session for chunk uploading a file.

​
id
string

The unique identifier for this session.

Example:

"F971964745A5CD0C001BBE4E58196BFD"

​
type
enum<string>

The value will always be upload_session.

Available options:
upload_session
Example:

"upload_session"

​
session_expires_at
string<date-time>

The date and time when this session expires.

Example:

"2012-12-12T10:53:43-08:00"

​
part_size
integer<int64>

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.

Example:

1024

​
total_parts
integer<int32>

The total number of parts expected in this upload session, as determined by the file size and part size.

Example:

1000

​
num_parts_processed
integer<int32>

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.

Example:

455

​
session_endpoints
Session endpoints · object

A list of endpoints for this session.