---
title: "Initiate a large (multipart) file upload"
method: POST
path: "/v2/files/large-upload"
tags: ["FilesV2"]
---

# Initiate a large (multipart) file upload

`POST /v2/files/large-upload`

Initiate a multipart upload for files **up to 10 GB**. The response includes an opaque `upload_id` and a fully populated `urls` array containing one pre-signed `PUT` URL per part the client should upload. After uploading every part, call **Complete large upload** at `POST /v2/files/{file_id}/large-upload/complete` with the resulting part `etag` values.

The client may optionally specify the desired number of `parts` (1 to 10000). If omitted, the server picks a value based on the declared `size` and the recommended part size — for most uploads this is the right default.

Every URL in `urls` expires roughly **3 hours** after issue. If a part `PUT` fails after that window, abandon the upload and initiate a fresh session.

Once finalized, inspect the file with `GET /v1/files/{file_id}` and download it with `GET /v1/files/{file_id}/download` — no v2 read surface exists yet.

Returns `201` with the upload session details. Orphaned uploads that are not completed are eventually cleaned up.

## Request body

- object
  - `name` string, required — The file's original name, including extension. 1-1024 characters.
  - `type` string, required — The file's MIME type (e.g. `image/png`, `video/mp4`). Up to 255 characters.
  - `size` integer, required — Total size of the file in bytes. Must be between 1 and 10000000000 (10 GB).
  - `parts` integer — Number of parts the client will split the upload into. Optional — if omitted, the server picks a value based on the declared `size` and the recommended part size. Must be between 1 and 10000.

## Response `201`

201

- object
  - `data` object, required
    - `file_id` string, required — Base62-encoded UUID identifying the newly created file record.
    - `upload_id` string, required — Opaque identifier for the multipart upload. Pass this back to the large-upload complete endpoint.
    - `urls` object[], required — Signed `PUT` URLs for every part of the upload, ordered by `part_number` ascending. The array length equals the number of parts the server allocated for this session.
      - `part_number` integer, required — 1-indexed part number this URL corresponds to.
      - `url` string, uri, required — Pre-signed URL the client should `PUT` the part body to.
      - `expires_at` string, required — ISO 8601 timestamp at which this part URL expires.
    - `part_size_recommendation` object, required — Server-recommended part-size bounds for the multipart upload.
      - `min` 5242880, required — Minimum part size (bytes). All parts except the last must be at least this size.
      - `recommended` 26214400, required — Recommended part size (bytes). Balances throughput and request overhead.
      - `max` 5368709120, required — Maximum part size (bytes). No single part may exceed this value.
    - `max_parts` 10000, required — Maximum number of parts a large upload may use.
    - `max_file_size_bytes` 10000000000, required — Maximum size (bytes) accepted by this endpoint.

## Other responses

- `400` — 400
- `401` — 401
- `403` — 403
- `404` — 404
- `422` — 422
- `429` — 429
- `500` — 500

---

[API](https://skmtc.net/dovetail/apis/dovetail-public-api.md) · [All operations](https://skmtc.net/dovetail/apis/dovetail-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dovetail/dovetail-public-api/revisions/4107f5fdf8b2/schema)