---
title: "Get an upload URL for a document"
method: POST
path: "/api/documents/generate-upload-url"
tags: ["Documents"]
---

# Get an upload URL for a document

`POST /api/documents/generate-upload-url`

Returns a one-time upload URL plus the form fields you need to attach. Send a `multipart/form-data` POST to the URL with each `uploadUrlFormFields` entry as a form field, then the file field last. The URL is valid for 60 minutes. Maximum file size is 10 MB.

## Headers

- `on-behalf-of` string
- `idempotency-key` string, uuid, required

## Request body

- GenerateUploadUrlRequest
  - `contentType` 'image/jpeg' | 'image/jpg' | 'image/png' | 'application/pdf', required — The MIME type of the document
  - `filename` string, required — Human-readable filename for the document

## Response `201`

Upload URL generated.

- GenerateUploadUrlResponse
  - `documentId` string, uuid, required — Unique identifier for the document. Use this ID to reference the document in subsequent API calls.
  - `expiresAt` string, date-time, required — Timestamp when the presigned upload URL expires.
  - `uploadUrl` string, required — The URL to send the multipart/form-data POST request to.
  - `uploadUrlFormFields` object, required — Key-value pairs that must be included as form fields in the multipart POST request. The file field must be the last field in the request. These fields carry the upload signature and policy.

## Other responses

- `401` — Unauthorized
- `403` — SignedAgreementRequiredException
- `409` — IdempotencyConflictError
- `422` — IdempotencyKeyExpiredError

---

[API](https://skmtc.net/muralpay/apis/mural-api.md) · [All operations](https://skmtc.net/muralpay/apis/mural-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/muralpay/mural-api/versions/437d277f5948/schema)