Munition
Docs menu

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:

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

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.