---
title: "Finalize a single-PUT file upload"
method: POST
path: "/v2/files/{file_id}/upload/complete"
tags: ["FilesV2"]
---

# Finalize a single-PUT file upload

`POST /v2/files/{file_id}/upload/complete`

Finalize an upload session created by **Initiate single-PUT upload** (`POST /v2/files/upload`). The server `HEAD`s the S3 object to confirm bytes are present and that the size matches the declared value, then flips the file row to `DONE`.

On success the file is marked as uploaded and returned in the response. The file's processing `status` may still be `pending` while downstream processing runs.

Idempotent for already-DONE files: a retry of a previously-successful complete call (or a complete call arriving after the auto-finalize backstop has already finalised the row) returns `200` with the file metadata instead of `409`. `FAILED` / `CANCELLED` still return `409`.

To cancel an in-progress upload, simply stop calling the API: abandoned file records are garbage-collected after 24 hours.

## Path parameters

- `file_id` string, required

## Request body

- object — Finalize a single-PUT upload. The endpoint takes no body parameters.

## Response `200`

200

- object
  - `data` object, required
    - `id` string, required — Unique identifier of the file.
    - `name` string, required — The file's original name.
    - `type` string, nullable, required — The file's MIME type (e.g. 'image/png', 'video/mp4'). Null if unknown.
    - `size` number, nullable, required — Size of the file in bytes. Null if unknown.
    - `status` 'completed' | 'pending' | 'failed', required — Processing status of the file. 'pending' while being processed, 'completed' when ready, or 'failed' if processing encountered an error.
    - `author` union, required — The user who uploaded the file, or null if the author is unknown.
      - object
        - `id` string, required
        - `name` string
      - string, null, nullable
    - `created_at` union, required — ISO 8601 timestamp when the file was created.
      - string
      - string, null, nullable
    - `url` string, nullable, required — Permanent URL pointing at the **Download a file** endpoint. Safe to cache and store — the URL itself never expires, but calling it requires the same authentication as other API endpoints and returns a short-lived presigned URL each time. The endpoint performs its own readiness and access checks.

## Other responses

- `400` — 400
- `401` — 401
- `403` — 403
- `404` — 404
- `409` — 409
- `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)