# Upload API

Reference for Munition's upload routes: buy a slot, PUT the bytes, return a temporary public URL. Routes, input schema, output, price and limits.

Munition hosts one file per upload, up to 10 MiB, at a public URL that lasts 7 days and can be renewed up to 30 days after the upload. Over HTTP, an upload takes two requests: a paid request that buys a slot and returns a presigned upload URL, then a `PUT` of the file's bytes to that URL. The `@munition/mcp` package does both for a local file in one tool call.

## Routes and prices

### Buy an upload slot

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/uploads` | `upload` | 0.005 |
| MPP | `POST /v1/mpp/uploads` | `upload_mpp` | 0.005 |
| Account balance | MCP tool `upload` (`@munition/mcp` only) | `upload` | 0.005 |

`POST /v1/uploads` has no tool id of its own in the price list: it charges the `upload` price.

### Renew an upload

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/uploads/{id}/renew` | `renew_upload_direct` | 0.005 |
| MPP | `POST /v1/mpp/uploads/{id}/renew` | `renew_upload_mpp` | 0.005 |
| Account balance | MCP tool `renew_upload` (`@munition/mcp` only) | `renew` | 0.005 |

### Delete an upload

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `DELETE /v1/uploads/{id}` | `delete_upload_direct` | 0.001 |
| MPP | `DELETE /v1/mpp/uploads/{id}` | `delete_upload_mpp` | 0.001 |
| Free | MCP tool `delete_upload` (`@munition/mcp` only) | — | Free |
| Free | MCP tool `recent_uploads` (`@munition/mcp` only) | — | Free |

`recent_uploads` lists the account's uploads that are not deleted, most recent first. The remote MCP connector has no upload tools, because uploading reads a file on the user's machine.

## Upload a file

1. **Describe the file.** Compute its size in bytes and the SHA-256 of its bytes, as lowercase hex and as base64:

   ```bash
   wc -c < agent-report.pdf                                    # size
   shasum -a 256 agent-report.pdf                              # sha256 (hex)
   openssl dgst -sha256 -binary agent-report.pdf | base64      # sha256Base64
   ```

2. **Buy a slot** with a paid `POST /v1/uploads` (or `POST /v1/mpp/uploads`), described below. The answer has the `uploadUrl`, the `uploadHeaders` and the future `publicUrl`.
3. **Upload the bytes** with a `PUT` to `uploadUrl`, sending every entry of `uploadHeaders`, before `uploadUrlExpiresAt`, 10 minutes after the slot was bought. The storage service refuses bytes whose size or SHA-256 differs from what you declared.
4. **Check the `PUT` succeeded**, then share `publicUrl`.

The slot is paid when it is created: bytes not uploaded in time are not refunded. Retrying the slot request with the same `Idempotency-Key` returns the same slot, without a second charge, also after a `503 upload_effect_pending` answer: the slot then comes back with a new `uploadUrl`, and `uploadUrlExpiresAt` gives that URL's expiry.

## Input

Body of `POST /v1/uploads` and `POST /v1/mpp/uploads`:

| Field | Type | Required | Default | Limits and notes |
| --- | --- | --- | --- | --- |
| `filename` | string | no | — | 1 to 180 characters, used for the URL. Characters other than letters, digits, `.`, `_` and `-` become `_`, and the URL keeps the first 80. |
| `mime` | string | yes | — | The file's media type, 1 to 120 characters, such as `application/pdf` or `image/png`. |
| `size` | integer | yes | — | The size in bytes, 1 to 10,485,760 (10 MiB). |
| `sha256` | string | yes | — | The SHA-256 of the bytes, as 64 lowercase hex characters. |
| `sha256Base64` | string | yes | — | The same digest in base64: 44 characters ending with `=`. |
| `tier` | string | no | short-10mb | The only tier, `short-10mb`: one file up to 10 MiB, kept 7 days. |
| `tags` | array of strings | no | [] | Up to 20 tags of 1 to 64 characters, returned with the upload. |

On the x402 route the payment is verified before the body is checked; on the MPP route the body is checked first. Either way, a `400` comes before settlement and costs nothing.

## Response

Response of `POST /v1/uploads` and `POST /v1/mpp/uploads`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string | yes | The upload id, used to renew or delete it. |
| `uploadUrl` | string | yes | The presigned URL to `PUT` the bytes to. |
| `uploadMethod` | string | yes | Always `PUT`. |
| `uploadHeaders` | object | yes | The headers the `PUT` must send: `content-type`, `content-length`, `x-amz-checksum-sha256` and `x-amz-meta-sha256`. |
| `publicUrl` | string | yes | The file's public URL, on `files.munition.io`. |
| `expiresAt` | string | yes | When the file expires and is deleted, 7 days after the slot was bought. |
| `uploadUrlExpiresAt` | string | yes | When `uploadUrl` stops working, 10 minutes after the slot was bought (or after the retry that finished a paid slot). |
| `maxSize` | integer | yes | The tier's largest file size, in bytes. |
| `tags` | array of strings | yes | The tags you sent. |

## Renew and delete

`{id}` is the upload's `id`. Neither route has a body. Both work only on uploads made over x402 or MPP, and must be paid from the wallet address that paid for the upload. These are checked after the payment is verified and before it settles, so a refusal costs nothing:

- an unknown or deleted upload gets `404`;
- a payment from another wallet gets `403`;
- a renewal that would go past 30 days after the upload gets `409`;
- a PDF from [HTML to PDF](/docs/services/pdf) cannot be renewed (`400`).

A renewal adds 7 days to the current `expiresAt`. One payment renews once: sending the same renewal again with the same `Idempotency-Key` returns the same answer and never adds 7 more days.

Response of `POST /v1/uploads/{id}/renew` and `POST /v1/mpp/uploads/{id}/renew`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string | yes | The upload id. |
| `expiresAt` | string | yes | The new expiry. |
| `renewalCount` | integer | yes | How many renewals the upload has had. |
| `txHash` | string or null | yes | The settlement transaction, when known. |

A deletion removes the stored file and marks the upload deleted.

Response of `DELETE /v1/uploads/{id}` and `DELETE /v1/mpp/uploads/{id}`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string | yes | The upload id. |
| `status` | string | yes | Always `deleted`. |
| `deleted` | boolean | yes | Always `true`. |
| `deletedAt` | string | yes | When the upload was deleted. |
| `expiresAt` | string | yes | The expiry the upload had. |

## Limits

- One file per slot, 1 byte to 10 MiB.
- The upload URL works for 10 minutes.
- The public URL cannot be guessed, but anyone with it can open the file: do not upload confidential content.
- A file is kept 7 days. Each renewal adds 7 days, up to 30 days after the upload.

## Example

Buying a slot for a 42,000-byte PDF. Called without payment, the route answers `402` with the price in the `PAYMENT-REQUIRED` header; pay and send it again as in [Copy-paste examples](/docs/payments/examples).

```bash
curl -sS -i https://api.munition.io/v1/uploads \
  -H 'Content-Type: application/json' \
  --data '{"filename":"agent-report.pdf","mime":"application/pdf","size":42000,"sha256":"b43cd80a9e6155029135a38c0559aff6696566c431bfb8a9c9433882898247d1","sha256Base64":"tDzYCp5hVQKRNaOMBVmv9mllZsQxv7ipyUM4gomCR9E=","tags":["agent-output","report"]}'
```

Paid, it costs 0.005 USDC. A response of `POST /v1/uploads` looks like this:

```json
{
  "id": "upl_example",
  "uploadUrl": "https://s3.example.com/presigned-put",
  "uploadMethod": "PUT",
  "uploadHeaders": {
    "content-type": "application/pdf",
    "content-length": "42000",
    "x-amz-checksum-sha256": "tDzYCp5hVQKRNaOMBVmv9mllZsQxv7ipyUM4gomCR9E=",
    "x-amz-meta-sha256": "b43cd80a9e6155029135a38c0559aff6696566c431bfb8a9c9433882898247d1"
  },
  "publicUrl": "https://files.munition.io/direct/upl_example-agent-report.pdf",
  "expiresAt": "2026-11-10T12:00:00.000Z",
  "uploadUrlExpiresAt": "2026-11-03T12:10:00.000Z",
  "maxSize": 10485760,
  "tags": ["agent-output", "report"]
}
```

Then send the bytes to `uploadUrl` with every `uploadHeaders` entry:

```bash
curl -sS -X PUT "$UPLOAD_URL" \
  -H 'content-type: application/pdf' \
  -H 'content-length: 42000' \
  -H 'x-amz-checksum-sha256: tDzYCp5hVQKRNaOMBVmv9mllZsQxv7ipyUM4gomCR9E=' \
  -H 'x-amz-meta-sha256: b43cd80a9e6155029135a38c0559aff6696566c431bfb8a9c9433882898247d1' \
  --data-binary @agent-report.pdf
```

What happens when something fails after payment is on [Errors and refunds](/docs/payments/errors#when-payment-settles-but-the-service-fails).
