---
title: "Mint signed URLs for uploading a file to a VM"
method: POST
path: "/v1/vms/{id}/files/presign"
tags: ["files"]
---

# Mint signed URLs for uploading a file to a VM

`POST /v1/vms/{id}/files/presign`

Returns a pair of short-lived signed URLs targeting a per-VM staging
location. Upload to `uploadUrl` with PUT (`Content-Type:
application/octet-stream`), then pass `downloadUrl` to
`POST /v1/vms/{id}/files/fetch` to have the server pull it into the
guest filesystem.

## Request body

- FilePresignRequest
  - `path` string, required — Absolute destination path inside the guest filesystem (where the file will land after `fetchFileToVm`). Used only to scope the staging object key; any value server-side is accepted here.

## Response `200`

Signed URLs + upload size ceiling

- FilePresignResponse — Pair of signed URLs scoped to the same per-VM staging object. Usable in either direction: either side (client or VM) PUTs bytes to `uploadUrl`, and either side GETs them back via `downloadUrl`. URLs expire after `expiresInSec` seconds and the staging object is auto-deleted after about a day.
  - `uploadUrl` string, uri, required — Presigned PUT URL for the staging object. Accepts `Content-Type: application/octet-stream`. Used by the client on upload, or by the VM (via an exec'd `curl -T -`) on download.
  - `downloadUrl` string, uri, required — Presigned GET URL for the same staging object. Used by the VM (via `POST /v1/vms/{id}/files/fetch`) on upload, or by the client (via `httpx.stream` / `curl`) on download.
  - `expiresInSec` integer, required — Lifetime of both URLs in seconds.
  - `maxUploadBytes` integer, required — Upper bound on upload size (equals the VM's disk size in bytes).

## Other responses

- `400` — Invalid request
- `401` — Missing or invalid credentials
- `404` — Resource not found
- `409` — VM is not running
- `500` — Internal server error
- `501` — File transfer not configured on this deployment

## Changes

- **2026-04-22** `fdb53b5a79b3` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/fastvm-org/apis/fastvm-api/changes/v1/vms/:id/files/presign/post.md)

---

[API](https://skmtc.dev/fastvm-org/apis/fastvm-api.md) · [All operations](https://skmtc.dev/fastvm-org/apis/fastvm-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fastvm-org/fastvm-api/revisions/480d9714a7a5/schema)