Uploads (Chunked) resources

The chunked upload endpoints support files from 20MB in size and allow an application to upload the file in parts, allowing for more control to catch any errors and retry parts individually.

Upload part

The representation of an upload session chunk.

Attributes and example

Property	Type	Required	Description
`part_id`	`string`	No	The unique ID of the chunk.
`offset`	`integer`	No	The offset of the chunk within the file in bytes. The lower bound of the position of the chunk within the file.
`size`	`integer`	No	The size of the chunk in bytes.
`sha1`	`string`	No	The SHA1 hash of the chunk.

Example

{
  "part_id": "6F2D3486",
  "offset": 16777216,
  "size": 3222784,
  "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
}

Upload part (Mini)

The basic representation of an upload session chunk.

Attributes and example

Property	Type	Required	Description
`part_id`	`string`	No	The unique ID of the chunk.
`offset`	`integer`	No	The offset of the chunk within the file in bytes. The lower bound of the position of the chunk within the file.
`size`	`integer`	No	The size of the chunk in bytes.

Example

{
  "part_id": "6F2D3486",
  "offset": 16777216,
  "size": 3222784
}

Upload part plan

Represents a planned upload part with SHA-512 hash for upload session planning.

Attributes and example

Property	Type	Required	Description
`offset`	`integer`	Yes	The offset of the chunk within the file in bytes. The lower bound of the position of the chunk within the file.
`size`	`integer`	Yes	The size of the chunk in bytes.
`sha512`	`string`	Yes	The `SHA-512` hash of the chunk.

Example

{
  "offset": 0,
  "size": 8388608,
  "sha512": "1f40fc92da241694750979ee6cf582f2d5d7c8b5d9c7f3b8a6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1"
}

Upload part plan hit

Represents a planned upload part that already exists on the server (cache hit).

Attributes and example

Property	Type	Required	Description
`offset`	`integer`	Yes	The offset of the chunk within the file in bytes. The lower bound of the position of the chunk within the file.
`size`	`integer`	Yes	The size of the chunk in bytes.
`sha512`	`string`	Yes	The `SHA-512` hash of the chunk.
`part_id`	`string`	Yes	The unique ID of the chunk.

Example

{
  "offset": 0,
  "size": 8388608,
  "sha512": "1f40fc92da241694750979ee6cf582f2d5d7c8b5d9c7f3b8a6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1",
  "part_id": "BFDF5379"
}

Upload parts

A list of uploaded chunks for an upload session.

Attributes and example

Property	Type	Required	Description
`total_count`	`integer`	No	One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
`limit`	`integer`	No	The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
`offset`	`integer`	No	The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
`order`	array of `object`	No	The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.
`entries`	array of Upload part	No	A list of uploaded chunks for an upload session.

Example

{
  "total_count": 5000,
  "limit": 1000,
  "offset": 2000,
  "order": [
    {
      "by": "type",
      "direction": "ASC"
    }
  ],
  "entries": [
    {
      "part_id": "6F2D3486",
      "offset": 16777216,
      "size": 3222784,
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    }
  ]
}

Upload session

An upload session for chunk uploading a file.

Attributes and example

Property	Type	Required	Description
`id`	`string`	No	The unique identifier for this session.
`type`	`enum<string>`	No	The value will always be `upload_session`. Available options: `upload_session`.
`session_expires_at`	`string`	No	The date and time when this session expires.
`part_size`	`integer`	No	The size in bytes that must be used for all parts of the upload. Only the last part is allowed to be of a smaller size.
`total_parts`	`integer`	No	The total number of parts expected in this upload session, as determined by the file size and part size.
`num_parts_processed`	`integer`	No	The number of parts that have been uploaded and processed by the server. This starts at `0`. When committing a file, inspecting this property can provide insight if all parts have been uploaded correctly.
`session_endpoints`	`object`	No	A list of endpoints for a chunked upload session.

Example

{
  "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": {
    "plan": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/plan",
    "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"
  }
}

Upload session plan request

Request body for planning an upload session. This allows checking which parts already exist on the server before uploading.

Attributes and example

Property	Type	Required	Description
`parts`	array of Upload part plan	Yes	The list of parts to check for existence.

Example

{
  "parts": [
    {
      "offset": 0,
      "size": 8388608,
      "sha512": "1f40fc92da241694750979ee6cf582f2..."
    },
    {
      "offset": 8388608,
      "size": 8388608,
      "sha512": "b109f3bbbc244eb82441917ed06d618b..."
    }
  ]
}

Upload session plan response

Response from planning an upload session. Contains information about which parts already exist (hits) and which need to be uploaded (misses).

Attributes and example

Property	Type	Required	Description
`upload_session_id`	`string`	Yes	The unique identifier for this upload session.
`hits`	array of Upload part plan hit	Yes	Parts that already exist on the server and do not need to be uploaded again.
`misses`	array of Upload part plan	Yes	Parts that do not exist on the server and need to be uploaded.

Example

{
  "upload_session_id": "F971964745A5CD0C001BBE4E58196BFD",
  "hits": [
    {
      "offset": 0,
      "size": 8388608,
      "sha512": "1f40fc92da241694750979ee6cf582f2...",
      "part_id": "BFDF5379"
    }
  ],
  "misses": [
    {
      "offset": 8388608,
      "size": 8388608,
      "sha512": "b109f3bbbc244eb82441917ed06d618b..."
    }
  ]
}

Uploaded part

A chunk of a file uploaded as part of an upload session, as returned by some endpoints.

Attributes and example

Property	Type	Required	Description
`part`	Upload part	No

Example

{
  "part": {
    "part_id": "6F2D3486",
    "offset": 16777216,
    "size": 3222784,
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
  }
}

v2025.0

v2026.0

Uploads (Chunked) resources

Upload part

Upload part (Mini)

Upload part plan

Upload part plan hit

Upload parts

Upload session

Upload session plan request

Upload session plan response

Uploaded part

​Upload part

​Upload part (Mini)

​Upload part plan

​Upload part plan hit

​Upload parts

​Upload session

​Upload session plan request

​Upload session plan response

​Uploaded part

Upload part

Upload part (Mini)

Upload part plan

Upload part plan hit

Upload parts

Upload session

Upload session plan request

Upload session plan response

Uploaded part