---
title: "Start a resumable upload — for a file of any size up to 50 GiB [write]"
method: POST
path: "/files/uploads"
tags: ["files"]
---

# Start a resumable upload — for a file of any size up to 50 GiB \[write\]

`POST /files/uploads`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/files/uploads`
- Auth: HTTP bearer

JSON `{filename, size_bytes, mime_type?, expires_in_seconds?}` (expires_in_seconds 3600–7776000; omitted, the file never expires). Send the bytes to `upload_url` as `PUT` requests carrying `Content-Range: bytes <first>-<last>/<size_bytes>`, `chunk_size` bytes at a time: each answers 308 with `Range: bytes=0-<last received>` until the final chunk answers 200. After a dropped connection, `PUT` with no body and `Content-Range: bytes */<size_bytes>` answers the same 308 or 200, and the upload continues from the byte after the `Range`. The session lasts a week. 413 file_too_large past 50 GiB.

## Request body

- object
  - `filename` string, required
  - `size_bytes` integer, required
  - `mime_type` string
  - `expires_in_seconds` integer

## Response `200`

OK

- FileUpload
  - `type` 'file_upload', required
  - `id` string, required: fupl_…; pass to /files/uploads/{upload_id}/complete
  - `upload_url` string, required: Where the bytes go, in Content-Range chunks. Needs no credentials: the URL is the capability, so keep it private.
  - `chunk_size` integer, required: The chunk size to send; every chunk but the last must be exactly this long
  - `size_bytes` integer, required
  - `filename` string, required
  - `mime_type` string, required
  - `expires_at` string, date-time, required: When the upload session lapses; start a new one after

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/files/uploads/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/0d435187cd55?raw)