---
title: "Start session"
method: POST
path: "/3/drive/{drive_id}/upload/session/start"
tags: ["Drive > Files > File/Directory > Upload > Session"]
---

# Start session

`POST /3/drive/{drive_id}/upload/session/start`

This call creates a new upload session. <br/>
Upload session allows you to upload a single file in one or more requests (chunks). It is the only way to upload a file larger than 1GB.
<br/><note>
  The maximum size per chunk request is 1GB.
</note>
<br/><note>
When a session is started, it can be used for a maximum of 4 hours.
</note>
<br/><note>
To upload a chunk, you must use the ‘upload_url’ returned from this session opening call : <a href="#">upload/session/start</a>.
</note><br/><note>
Finally, when all the data have been sent, you should call <a href="./{session_token}/finish">upload/session/finish</a> to close the session and save the file in kDrive.
</note>
<br/><note>
If your file is small (<100MB) we recommend you to use the <a href="../../upload">direct upload route</a> to avoid multiple requests.</note>

## Path parameters

- `drive_id` integer, required

## Query parameters

- `with` string

## Headers

- `If-Match` string, nullable — Specify a ETag (Entity tag) who is the identifier for a specific version of file.

## Request body

- object
  - `conflict` 'error' | 'rename' | 'version' — Select what to do when a file with the same name already exists. The default conflict mode is error.<li><small><ul><strong>error</strong> : An error is returned without creating the file/session.</ul><ul><strong>rename</strong> : Rename the new file with an available name (ex. `file.txt` to `file(3).txt`).</ul><ul><strong>version</strong> : Replace the content of the existing file (create a new version of the file).</ul></small></li>
  - `created_at` integer — Override the creation date metadata of the new file.<note>The value of this field will be capped at 24h from the current time.</note>
  - `directory_id` integer — The directory destination root of the new file. Must be a directory. <note>If the identifier is unknown you can use only <strong>directory_path</strong>.</note> <note>You can get your root private folder ID from <a href='/docs/api/get/3/drive/{drive_id}/files/{file_id}/files'>3/drive/{drive_id}/files/{file_id}/files</a>. <note>Required without <strong>directory_path</strong></note>
  - `directory_path` string, nullable — The destination path of the new file. If the <strong> directory_id</strong> is provided the directory path is used as a relative path, otherwise it will be used as an absolute path. The destination should be a directory. <note>If the directory path does not exist, folders are created automatically.</note> <note>The path is a destination path, the file name should not be provided at the end.</note> <note>Required without <strong>directory_id</strong>.</note>
  - `file_id` integer — File identifier of uploaded file. <note>This is an alternative to replace a file by its identifier, if this mode is used <strong>file_name</strong>, <strong>directory_id</strong>, <strong>conflict</strong> and <strong>directory_path</strong> params are automatically computed and cannot be provided.</note> <note>If you don't know the identifier, or you want to upload a new file, you should provide a filename and a directory destination.</note>
  - `file_name` string — The name of the file to create. <note>Slashes will be replaced by colons.</note> <note>Maximum bytes size is 255</note>
  - `last_modified_at` integer — Override the update date metadata of the new file.<note>The value of this field will be capped at 24h from the current time.</note>
  - `total_chunks` integer, required — The total number of chunks attached to the session.
  - `total_size` integer, required — Expected total size of the file to upload. If the uploaded content does not match this size, an error will be returned.<note>the unit of size is defined in Bytes.</note>

## Response `200`

OK

- object
  - `result` 'success' | 'error' | 'asynchronous', required — Result of the HTTP request
  - `data` 91ac10ffUploadSessionFeedback — unresolved $ref

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `409` — Conflict
- `503` — Service Unavailable

---

[API](https://skmtc.dev/infomaniak/apis/api-reference-developer-tools.md) · [All operations](https://skmtc.dev/infomaniak/apis/api-reference-developer-tools/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/infomaniak/api-reference-developer-tools/revisions/158a854b0c7d/schema)