---
title: "Start a large file upload"
method: POST
path: "/files/upload-session"
tags: ["Files"]
---

# Start a large file upload

`POST /files/upload-session`

## Request

- Base URL: `https://api.varg.ai/v2`
- URL: `https://api.varg.ai/v2/files/upload-session`
- Auth: HTTP bearer

Upload flow for files too large or awkward for `POST /files` (up to
200 MB):

1. Call this endpoint with the file's `media_type` and, ideally, its
   `size` and sha256 `hash`.
2. If the response has `deduplicated: true`, the file already exists in
   your account: use the returned `file_id` and `url` and skip the
   upload.
3. Otherwise send the raw bytes with `PUT {upload_url}` (direct to
   storage), or `PUT /files/upload/{session_id}` (`proxy_url`) when
   your environment can only reach `api.varg.ai`. Use the
   `Content-Type` in `headers`. The session is valid for 1 hour and
   accepts one upload.
4. The proxy PUT registers the file and returns `file_id`. If you
   uploaded to `upload_url` directly, register it afterwards with
   `POST /files/import` using `public_url`.

Send `X-Workspace-Id` (or `workspace_id` in the body) to file the
upload into a folder.

## Headers

- `X-Workspace-Id` string

## Request body

- UploadSessionRequest
  - `media_type` string: MIME type of the file. Defaults to `application/octet-stream` (the real type is then detected from the bytes on upload).
  - `filename` string
  - `size` integer: File size in bytes (max 200 MB)
  - `hash` string: sha256 of the file, with or without the `sha256:` prefix. Lets the API skip the upload when you already have the file.
  - `workspace_id` string: Folder (id or slug) to file the upload into. `X-Workspace-Id` takes precedence.

## Response `200`

A new upload session, or the existing file when the hash matches

- union
  - UploadSession
    - `deduplicated` false, required
    - `session_id` string, required: Id for `PUT /files/upload/{session_id}`. Also becomes the file id.
    - `upload_url` string, required: Presigned URL. `PUT` the bytes here directly, with the headers below.
    - `public_url` string, required: URL the file will have once uploaded
    - `proxy_url` string, required: Path of the proxy endpoint on this API, for clients that cannot reach `upload_url`
    - `headers` object, required: Headers to send with the PUT
    - `expires_in` integer, required: Seconds until the session expires
    - `hash` string, nullable
  - UploadSessionDeduplicated: The file already exists in your account; no upload is needed.
    - `deduplicated` true, required
    - `file_id` string, required
    - `url` string, required
    - `hash` string, nullable
    - `size` integer, nullable
    - `media_type` string, nullable
    - `filename` string, nullable

## Other responses

- `400`: Body is not JSON (`invalid_json`) or `size` is out of range (`invalid_size`)
- `401`: Missing or invalid API key / JWT
- `404`: Unknown folder (`workspace_not_found`)
- `500`: Could not create the upload URL (`presign_failed`)

## Changes

- **2026-10-20** `43bcf5ea398d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/varg/apis/varg-api/changes/files/upload-session/post.md)

---

[API](https://skmtc.dev/varg/apis/varg-api.md) · [All operations](https://skmtc.dev/varg/apis/varg-api/llms.txt) · [OpenAPI document](https://skmtc.dev/varg/apis/varg-api/revisions/09d49a6d852f?raw)