---
title: "Mint signed URLs for uploading a build context tarball"
method: POST
path: "/v1/build-contexts/presign"
tags: ["builds"]
---

# Mint signed URLs for uploading a build context tarball

`POST /v1/build-contexts/presign`

Returns a pair of short-lived signed URLs targeting a per-org
staging location. Tar+gzip your build-context directory, PUT it
to `uploadUrl` with `Content-Type: application/gzip`, then pass
`downloadUrl` as `contextDownloadUrl` on `POST /v1/builds`.

Unlike `/v1/vms/{id}/files/presign`, this endpoint isn't keyed
to a specific VM — context uploads happen *before* the build VM
exists.

## 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

- `401` — Missing or invalid credentials
- `500` — Internal server error
- `501` — File staging is not configured on this deployment

## Changes

- **2026-05-09** `480d9714a7a5` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/fastvm-org/apis/fastvm-api/changes/v1/build-contexts/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)