Upload Session Start
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 or upload_session/append_batch to add
more data, then upload_session/finish or upload_session/finish_batch:2 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 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, upload_session/append:2, and 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 requests, with a few caveats. After all of the requests are complete,
finish the session with upload_session/finish as normal. You can not send data in a
upload_session/start or upload_session/finish call, only with upload_session/append:2 or
upload_session/append_batch. Also, the length of the uploaded data in a call to
upload_session/append:2 or 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
Authentication: User, Dropbox-API-Select-Admin (Team Admin)
Authentication
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.
Headers
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.
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.
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.
JSON-encoded arguments. Non-ASCII characters and 0x7F must use JSON \uXXXX escape sequences to be HTTP-header-safe.
Request
Response headers
Response
A unique identifier for the upload session. Pass this to upload_session/append:2 and upload_session/finish.