API ReferenceUser EndpointsFiles

Upload Session Start

View as MarkdownOpen in Claude
Upload sessions allow you to upload a single file in one or more requests, for example where the size of the file is greater than 150 MiB. This call starts a new upload session with the given data. You can then use [upload_session/append:2](api:dropbox-api:POST/2/files/upload_session/append_v2) or [upload_session/append_batch](api:dropbox-api:POST/2/files/upload_session/append_batch) to add more data, then [upload_session/finish](api:dropbox-api:POST/2/files/upload_session/finish) or [upload_session/finish_batch:2](api:dropbox-api:POST/2/files/upload_session/finish_batch_v2) to save all the data to a file in Dropbox. A single request should not upload more than 150 MiB. The maximum size of a file one can upload to an upload session is 2^41 - 2^22 (2,199,019,061,248) bytes. An upload session can be used for a maximum of 7 days. Attempting to use a `UploadSessionStartResult.session_id` with [upload_session/append:2](api:dropbox-api:POST/2/files/upload_session/append_v2) or other upload session routes more than 7 days after its creation will return `UploadSessionLookupError.not_found`. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page https://www.dropbox.com/developers/reference/data-transport-limit. By default, upload sessions require you to send content of the file in sequential order via consecutive [upload_session/start](api:dropbox-api:POST/2/files/upload_session/start), [upload_session/append:2](api:dropbox-api:POST/2/files/upload_session/append_v2), and [upload_session/finish](api:dropbox-api:POST/2/files/upload_session/finish) calls (or their batch variants). For better performance, you can optionally set `UploadSessionStartArg.session_type` to `UploadSessionType.concurrent` to start a concurrent upload session. Concurrent upload sessions may upload file data in concurrent [upload_session/append:2](api:dropbox-api:POST/2/files/upload_session/append_v2) requests, with a few caveats. After all of the requests are complete, finish the session with [upload_session/finish](api:dropbox-api:POST/2/files/upload_session/finish) as normal. You can not send data in a [upload_session/start](api:dropbox-api:POST/2/files/upload_session/start) or [upload_session/finish](api:dropbox-api:POST/2/files/upload_session/finish) call, only with [upload_session/append:2](api:dropbox-api:POST/2/files/upload_session/append_v2) or [upload_session/append_batch](api:dropbox-api:POST/2/files/upload_session/append_batch). Also, the length of the uploaded data in a call to [upload_session/append:2](api:dropbox-api:POST/2/files/upload_session/append_v2) or [upload_session/append_batch](api:dropbox-api:POST/2/files/upload_session/append_batch) must be a multiple of 2^22 (4,194,304) bytes, except for the final append request with `UploadSessionAppendArg.close` or `UploadSessionAppendBatchArgEntry.close` set to true that may contain any remaining data. **Required scope:** `files.content.write` **Endpoint format:** [Content-upload](https://docs.dropboxapi.com/dropbox-api/docs/technical-reference/request-response-formats#content-upload-endpoints) **Authentication:** [User](https://docs.dropboxapi.com/dropbox-api/docs/auth-types#user-authentication), [Dropbox-API-Select-Admin (Team Admin)](https://docs.dropboxapi.com/dropbox-api/docs/auth-types#admin-authentication-via-dropbox-api-select-admin)

Authentication

AuthorizationBearer
OAuth 2.0 token issued to a specific user. Use `Authorization: Bearer <token>`. Public clients should use the authorization code flow with PKCE (S256). For background or offline access, send `token_access_type=offline` during authorization and use the returned refresh token to obtain new access tokens. You can generate a short-lived access token from the App Console; see [Testing with a generated token](https://docs.dropboxapi.com/dropbox-api/docs/oauth#testing-with-a-generated-token).

Headers

Dropbox-API-Select-UserstringOptional

Acts on behalf of a team member for supported user-auth operations. Pass a team member ID such as dbmid:.... When used with a team token, that token must also include the team_data.member scope.

Dropbox-API-Select-AdminstringOptional

Acts as the specified team admin for supported user-auth operations. Pass a team member ID for an admin account. When used with a team token, that token must also include the team_data.member scope.

Dropbox-API-Path-RootstringOptional
Scopes path-based operations to a namespace (root). The value is a JSON serialization of the `common.PathRoot` union: `{".tag": "home"}`, `{".tag": "root", "root": "<namespace_id>"}`, or `{".tag": "namespace_id", "namespace_id": "<namespace_id>"}`. On failure the request returns 422 with a `common.PathRootError`.
Dropbox-API-ArgobjectRequired

JSON-encoded arguments. Non-ASCII characters and 0x7F must use JSON \uXXXX escape sequences to be HTTP-header-safe.

Request

This endpoint expects binary data of type application/octet-stream.

Response headers

X-Dropbox-Request-IdstringOptional
A unique identifier for the request, useful for debugging and support.

Response

Successful response
session_idstring

A unique identifier for the upload session. Pass this to upload_session/append:2 and upload_session/finish.

Errors

401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error