---
title: "Upload a file and get a public download link via x402"
method: POST
path: "/v1/uploads"
tags: ["Upload"]
---

# Upload a file and get a public download link via x402

`POST /v1/uploads`

## Request

- Base URL: `https://api.munition.io`
- URL: `https://api.munition.io/v1/uploads`
- Auth: none required

Munition Upload: temporary file hosting to share a PDF report, spreadsheet, image or other agent-created file through a public download link. Pay 0.005 USDC via x402 to reserve a slot for one file up to 10 MiB with seven-day retention. Send the exact file bytes to the returned presigned uploadUrl using PUT and uploadHeaders; only then is publicUrl ready to share. URLs are non-guessable but public. Supports browser downloads, webhook sharing and agent-to-human handoff. Call without payment for the canonical 402 challenge, then retry with the required x402 payment signature.

## Request body

- DirectUploadInput
  - `filename` string: Optional original filename used for a readable public URL slug, for example report.pdf or screenshot.png.
  - `mime` string, required: MIME type of the file to upload, for example application/pdf, image/png, text/plain, or application/json.
  - `size` integer, required: File size in bytes. The short-10mb tier accepts one file up to 10 MB.
  - `sha256` string, required: Lowercase hex-encoded SHA-256 digest of the exact file bytes, used to bind the upload slot to the final file.
  - `sha256Base64` string, required: Base64-encoded 32-byte SHA-256 digest of the same file bytes, sent as x-amz-checksum-sha256 during the S3 PUT.
  - `tags` string[]: Stable upload tags for categorization.
  - `tier` 'short-10mb': Upload tier. short-10mb costs 0.005 USDC, accepts one file up to 10 MB, and retains the public link for 7 days.

## Response `200`

Paid upload slot

- DirectUploadOutput
  - `id` string, required: Munition upload slot id.
  - `uploadUrl` string, uri, required: Presigned S3 URL where the client uploads file bytes after payment.
  - `uploadMethod` 'PUT', required: HTTP method to use when uploading bytes to uploadUrl.
  - `uploadHeaders` object, required: Required headers for the uploadUrl PUT, including content-type, content-length, checksum, and sha256 metadata.
  - `publicUrl` string, uri, required: Public non-guessable files.munition.io URL for sharing the uploaded file.
  - `expiresAt` string, date-time, required: When the public file link expires and the file is deleted.
  - `uploadUrlExpiresAt` string, date-time, required: When the presigned upload URL expires.
  - `maxSize` integer, required: Maximum allowed file size in bytes for this upload slot.
  - `tags` string[], required: Stable upload tags for categorization.

## Other responses

- `402`: x402 payment required or settlement failed
- `413`: File too large

---

[API](https://skmtc.dev/munition/apis/munition-api.md) · [All operations](https://skmtc.dev/munition/apis/munition-api/llms.txt) · [OpenAPI document](https://skmtc.dev/munition/apis/munition-api/revisions/3b11109809d1?raw)