---
title: "Upload File"
method: POST
path: "/uploads"
tags: ["uploads"]
---

# Upload File

`POST /uploads`

Upload a file and return a stable proxy URL.

The returned URL can be used as an attachment in start_design_task.
Supports images, PDFs, Office documents (PowerPoint, Word, and Excel
spreadsheets), CSV, plain-text/Markdown, and web-playable video
(MP4, WebM, MOV).

**Size limit:** the API gateway caps inbound HTTP request bodies at
~32 MiB. Files above that size must use the two-step signed-URL flow
(``POST /v1/uploads/url`` + ``POST /v1/uploads/register``) instead —
the bytes go directly to storage and never traverse the gateway.

## Headers

- `Moda-Version` '2026-04-12' | '2026-05-01'

## Response `200`

Successful Response

- FileUploadResponse
  - `id` string, required — Unique file identifier (prefixed ``file_...``).
  - `url` string, required — Stable proxy URL for the uploaded file. Use this in attachment URLs.
  - `filename` string, required — Filename of the uploaded file.
  - `mime_type` string, required — MIME type of the file.
  - `size_bytes` integer, nullable — File size in bytes.
  - `was_duplicate` boolean — True if an identical file already existed (deduplicated).

## Other responses

- `401` — Authentication required.
- `403` — Permission denied for this scope.
- `404` — Resource not found.
- `409` — Conflict (idempotency / resource state).
- `422` — Request validation failed.
- `429` — Rate limit exceeded.
- `500` — Internal error.

---

[API](https://skmtc.dev/moda/apis/moda-public-api.md) · [All operations](https://skmtc.dev/moda/apis/moda-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/moda/moda-public-api/revisions/b34cb4cca59e/schema)