---
title: "Plan upload session"
method: POST
path: "/files/upload_sessions/{upload_session_id}/plan"
tags: ["Uploads (Chunked)"]
---

# Plan upload session

`POST /files/upload_sessions/{upload_session_id}/plan`

## Request

- Base URL: `https://upload.box.com/api/2.0`
- URL: `https://upload.box.com/api/2.0/files/upload_sessions/{upload_session_id}/plan`
- Auth: OAuth 2
  - Authorization code: `https://account.box.com/api/oauth2/authorize`
  - Token URL: `https://api.box.com/oauth2/token`

Plan an upload session by checking which parts already exist on the server. This endpoint allows clients to optimize uploads by skipping parts that have already been uploaded (cache hits) and only uploading missing parts.

The actual endpoint URL is returned by the [`Create upload session`](/reference/post-files-upload-sessions) and [`Get upload session`](/reference/get-files-upload-sessions-id) endpoints.

## Path parameters

- `upload_session_id` string, required

## Request body

- UploadSessionPlanRequest: Request body for planning an upload session. This allows checking which parts already exist on the server before uploading.
  - `parts` UploadPartPlan[], required: The list of parts to check for existence.
    - `offset` integer, required: The offset of the chunk within the file in bytes. The lower bound of the position of the chunk within the file.
    - `size` integer, required: The size of the chunk in bytes.
    - `sha512` string, required: The `SHA-512` hash of the chunk, as a hex string of 128 lower case characters.

## Response `200`

Returns information about which parts already exist (hits) and which parts need to be uploaded (misses).

- UploadSessionPlanResponse: Response from planning an upload session. Contains information about which parts already exist (hits) and which need to be uploaded (misses).
  - `upload_session_id` string, required: The unique identifier for this upload session.
  - `hits` UploadPartPlanHit[], required: Parts that already exist on the server and do not need to be uploaded again.
    - `offset` integer, required: The offset of the chunk within the file in bytes. The lower bound of the position of the chunk within the file.
    - `size` integer, required: The size of the chunk in bytes.
    - `sha512` string, required: The `SHA-512` hash of the chunk, as a hex string of 128 lower case characters.
    - `part_id` string, required: The unique ID of the chunk.
  - `misses` UploadPartPlan[], required: Parts that do not exist on the server and need to be uploaded.
    - `offset` integer, required: The offset of the chunk within the file in bytes. The lower bound of the position of the chunk within the file.
    - `size` integer, required: The size of the chunk in bytes.
    - `sha512` string, required: The `SHA-512` hash of the chunk, as a hex string of 128 lower case characters.

## Other responses

- `404`: Returns an error if the upload session cannot be found.
- `default`: An unexpected client error.

## Changes

- **2026-11-03** `c4d5303fa5c3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/box/apis/platform-api/changes/files/upload_sessions/:upload_session_id/plan/post.md)

---

[API](https://skmtc.dev/box/apis/platform-api.md) - [All operations](https://skmtc.dev/box/apis/platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/box/apis/platform-api/revisions/c4d5303fa5c3?raw)