---
title: "Create upload session"
method: POST
path: "/files/upload_sessions"
tags: ["Uploads (Chunked)"]
---

# Create upload session

`POST /files/upload_sessions`

Creates an upload session for a new file.

## Request body

- object
  - `folder_id` string, required — The ID of the folder to upload the new file to.
  - `file_size` integer, required — The total number of bytes of the file to be uploaded.
  - `file_name` string, required — The name of new file.

## Response `201`

Returns a new upload session.

- UploadSession — An upload session for chunk uploading a file.
  - `id` string — The unique identifier for this session.
  - `type` 'upload_session' — The value will always be `upload_session`.
  - `session_expires_at` string, date-time — The date and time when this session expires.
  - `part_size` integer — 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_parts` integer — The total number of parts expected in this upload session, as determined by the file size and part size.
  - `num_parts_processed` integer — 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_endpoints` object — A list of endpoints for this session.
    - `upload_part` string — The URL to upload parts to.
    - `commit` string — The URL used to commit the file.
    - `abort` string — The URL for used to abort the session.
    - `list_parts` string — The URL users to list all parts.
    - `status` string — The URL used to get the status of the upload.
    - `log_event` string — The URL used to get the upload log from.

## Other responses

- `400` — Returns an error if some of the parameters are missing or not valid. * `missing_destination`: No `folder_id` was provided. * `invalid_folder_id`: `folder_id` is not valid. * `item_name_invalid`: `file_name` is not valid. * `missing_file_size`: `file_size` was not provided. * `invalid_file_size`: `file_size` was not a valid number. * `file_size_too_small`: `file_size` is below minimum file size for uploads via this API. * `missing_file_name`: `file_name` was not provided.
- `403` — Returns an error if the operation is not allowed for some reason. * `storage_limit_exceeded`: Account storage limit reached.
- `404` — Returns an error if the parent folder could not be found, or the authenticated user does not have access to it. * `invalid_parameter`: The `folder_id` value represents a folder that the user does not have access to, or does not exist.
- `409` — Returns an error if the file already exists, or the account has run out of disk space.
- `default` — An unexpected client error.

---

[API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/versions/ba8f087e1a4d/schema)