---
title: "Upload a file"
method: POST
path: "/files"
tags: ["Files"]
---

# Upload a file

`POST /files`

## Request

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

Upload a file (max 200 MB) as a raw binary body or as
`multipart/form-data`. For a raw body, set `Content-Type` to the file's
media type; any non-JSON `Content-Type` is treated as the media type.
When it's missing or generic, varg sniffs the type from magic bytes.
Multipart uploads take the file in the `file` part (or the first file
part) and an optional `workspace_id` text field.

Send `X-Content-Hash: sha256:<hex>` to enable deduplication — if your
account already has a file with the same content, the existing file is
returned instantly (`deduplicated: true`) without re-uploading. Use
`GET /files/check?hash=` to pre-check before sending bytes.

## Headers

- `Content-Type` string
- `X-Content-Hash` string
- `X-Filename` string
- `X-Workspace-Id` string

## Response `200`

File stored (or deduplicated)

- FileUploadResponse
  - `file_id` string, required
  - `url` string, required: Stable varg-hosted URL
  - `hash` string, nullable
  - `size` integer, required
  - `media_type` string, required
  - `filename` string, nullable
  - `title` string, nullable
  - `subtitle` string, nullable
  - `metadata` object, nullable
  - `deduplicated` boolean, required: true when an existing file with the same content was returned
  - `origin` 'upload' | 'generated': Present on `/files/import` responses

## Other responses

- `400`: Multipart upload without a file part (`missing_file`), or empty body (`missing_body`)
- `401`: Missing or invalid API key / JWT
- `404`: Unknown folder (`workspace_not_found`)
- `413`: File too large (max 200 MB)
- `502`: Storage upload failed

## Changes

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

[Operation history](https://skmtc.dev/varg/apis/varg-api/changes/files/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)