---
title: "Prepare file uploads"
method: POST
path: "/api/v1/files/uploads"
tags: ["Files"]
---

# Prepare file uploads

`POST /api/v1/files/uploads`

## Request

- Base URL: `https://app.khotan.com`
- URL: `https://app.khotan.com/api/v1/files/uploads`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Validates up to 10 files (1GB each), persists pending records, and returns a presigned PUT URL, required headers, and an expiry per file. PUT each file's bytes to its uploadUrl with the returned headers, then call the complete endpoint with the file ids. Target a folder with folderId or folderPath (mutually exclusive); folderPath creates missing folders along the way. Pending uploads that are never completed expire and are cleaned up automatically.

## Request body

- object
  - `files` object[], required: Up to 10 files, 1GB each, per request.
    - `name` string, required
    - `size` integer, required
    - `type` string, nullable: MIME content type, if known.
  - `folderId` string, nullable
  - `folderPath` string, nullable: Target folder path; missing folders are created ("mkdir -p" semantics).

## Response `200`

Per-file presigned upload instructions.

- object
  - `uploads` object[], required
    - `fileId` string, required
    - `name` string, required
    - `contentType` string, required
    - `size` integer, required
    - `uploadUrl` string, required: Presigned PUT URL; send the file bytes directly here.
    - `headers` object, required: Headers that must be sent with the PUT request.
    - `expiresAt` string, required

## Other responses

- `400`: The request was malformed or failed validation.
- `401`: Authentication is missing or invalid.
- `403`: The caller is not permitted to perform this action.
- `404`: The resource was not found.
- `429`: Too many requests; retry after the indicated delay.

---

[API](https://skmtc.dev/khotan/apis/khotan-api.md) - [All operations](https://skmtc.dev/khotan/apis/khotan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/khotan/apis/khotan-api/revisions/90b512a53e42?raw)