Uploads

Four endpoints. All require uploads:write.

Entrypoints

`POST /v1/uploads` — multipart (files up to ~32 MiB)

curl -X POST https://api.moda.app/v1/uploads \
  -H "Authorization: Bearer moda_live_..." \
  -H "Moda-Version: 2026-05-01" \
  -F "file=@/path/to/brief.pdf"

Response:

{
  "id": "file_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "url": "https://api.moda.app/api/v2/images/ref/550e8400-...?h=abc123",
  "filename": "brief.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 245760,
  "was_duplicate": false
}

Use when you have the bytes locally and the file is under ~32 MiB. Above that, use the signed-URL flow below — the gateway rejects the request before it reaches this handler.

`POST /v1/uploads/url` + `POST /v1/uploads/register` — signed URL (large files)

The bytes go straight from your client to object storage, bypassing our gateway entirely.

# 1. Mint a short-lived signed PUT URL
curl -X POST https://api.moda.app/v1/uploads/url \
  -H "Authorization: Bearer moda_live_..." \
  -H "Moda-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{"filename": "deck.pptx", "mime_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation"}'
# → {"upload_url": "https://storage.googleapis.com/...", "storage_key": "...", "mime_type": "...", "expires_in_seconds": 600}

# 2. PUT the raw bytes to upload_url with the SAME Content-Type.
#    No Authorization header — the signed URL itself is the capability.
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/vnd.openxmlformats-officedocument.presentationml.presentation" \
  --data-binary @deck.pptx

# 3. Register it to get a FileUploadResponse
curl -X POST https://api.moda.app/v1/uploads/register \
  -H "Authorization: Bearer moda_live_..." \
  -H "Moda-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{"storage_key": "...", "filename": "deck.pptx", "mime_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation"}'

register returns the same FileUploadResponse shape as multipart, including content-hash dedupe. Pass mime_type on step 3. It’s optional, but when omitted register re-derives the type from the basename embedded in storage_key — so a filename with no recognizable extension (perfectly legal at step 1, which takes an explicit mime_type) fails with 415 "Missing or unrecognizable content type" after you’ve already paid for the whole PUT. Send the same mime_type you declared at step 1 and that can’t happen. filename is optional too and defaults to the same basename. Signed URLs expire after expires_in_seconds (60–3600, default 600). The TTL bounds the PUT only — register doesn’t check it. Because register hashes the whole blob, a 100+ MB file can take several seconds; set your client timeout accordingly.

`POST /v1/uploads/from-url`

curl -X POST https://api.moda.app/v1/uploads/from-url \
  -H "Authorization: Bearer moda_live_..." \
  -H "Moda-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{"source_url": "https://example.com/mockup.png"}'

Server fetches the URL, validates MIME, stores. Returns the same FileUploadResponse shape. Use when the file is already hosted publicly and you don’t want to proxy it through your own machine. The fetch has a 30s budget; a slow source returns 400. SSRF-validated server-side — internal / localhost / metadata URLs are rejected with 422.

Supported types

Images: any image/* (PNG, JPEG, WebP, GIF, SVG, …)
Documents: PDF, PPTX / PPT, DOCX / DOC, XLSX / XLS
Text: CSV, plain text, Markdown, JSON
Video (upload + in-app viewing, no transcoding): MP4, WebM, MOV
Audio (upload + in-app playback, no transcoding): MP3, M4A, AAC, WAV, FLAC, OGG / OGA
Figma local-copy exports: .fig, .deck (brand-kit import)

Anything else is rejected with 415 unsupported media type.

Size limits

The gateway cap is fixed; the application cap varies by workspace plan:

Path	Effective max	Why
`POST /v1/uploads` (multipart)	~32 MiB	Our API gateway caps inbound HTTP/1 request bodies. Larger requests are rejected before reaching the handler.
`POST /v1/uploads/url` + `POST /v1/uploads/register`	`max_file_bytes`	Bytes go client → storage directly, so the gateway cap doesn’t apply.
`POST /v1/uploads/from-url`	`max_file_bytes`	The server does the fetch; nothing traverses our ingress.

max_file_bytes is the application cap and it applies to every path. It is per-workspace, not per-deployment — 250 MB is the maximum, and a free workspace is capped lower — so read it from GET /v1/uploads/limits and cache it per API key rather than hard-coding a number. The same response carries max_file_bytes_is_plan_limit: when it is true, the ceiling is the workspace’s plan rather than the platform, so the remedy to report is an upgrade and not only a smaller file. Oversize uploads return 413 payload too large — on POST /v1/uploads/register, the staged blob is deleted automatically.

Deduplication

Content-hash dedupe. Uploading the same bytes twice returns:

{ "id": "file_01HT9...", "was_duplicate": true, ... }

id / url / filename / mime_type / size_bytes point at the existing record. Safe to call repeatedly — no duplicate storage, no duplicate billing.

Using in a task

curl -X POST https://api.moda.app/v1/tasks \
  -H "Authorization: Bearer moda_live_..." \
  -H "Moda-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Build a pitch deck from the attached brief",
    "format": { "category": "slides", "width": 1920, "height": 1080 },
    "attachments": [
      { "file_id": "file_01HT9WK8...", "role": "source", "label": "Q2 strategy brief" }
    ]
  }'

Roles

Role	Meaning
`source`	Extract content from this file (brief, notes, CSV)
`reference`	Emulate this file’s style (mood board, screenshot)
`asset`	Use verbatim (logo, hero image)
`import`	Convert a PPTX deck into editable slides on the canvas, then design against it (PPTX-only; any other file type is rejected)

Pick the right role — it determines what the agent does with the file. See the Attachments section of moda-mcp/references/gotchas.md for details; the attachment shape is identical between MCP and REST.

URL-form attachment (legacy, less preferred)

{
  "attachments": [
    { "url": "https://example.com/mockup.png", "type": "image" }
  ]
}

No role metadata. Still works for hosted public URLs when you want to avoid the upload roundtrip. Mix with file-id-form in the same list freely.

Worked example

import httpx, os

HEADERS = {"Authorization": f"Bearer {os.environ['MODA_API_KEY']}",
           "Moda-Version": "2026-05-01"}

with httpx.Client(base_url="https://api.moda.app/v1", headers=HEADERS, timeout=60) as c:
    with open("brief.pdf", "rb") as f:
        upload = c.post("/uploads", files={"file": ("brief.pdf", f, "application/pdf")}).json()

    task = c.post("/tasks", json={
        "prompt": "Build a 10-slide pitch deck from the brief",
        "format": {"category": "slides", "width": 1920, "height": 1080},
        "number_of_slides": 10,
        "attachments": [
            {"file_id": upload["id"], "role": "source", "label": "Q2 strategy"},
        ],
        "idempotency_key": "q2-strategy-deck-v1",
    }).json()

Common wrong guesses

Posting files as JSON-encoded base64 into POST /v1/uploads. Use multipart (multipart/form-data).
Pushing a >32 MiB file at POST /v1/uploads and reading the 413 as “the file is over Moda’s limit”. The app cap is max_file_bytes from GET /v1/uploads/limits, at most 250 MB; that 413 is the gateway. Switch to the signed-URL flow.
PUT-ing to upload_url with a different Content-Type than you declared on /uploads/url. The signature is bound to the content type — a mismatch fails the PUT at storage.
Calling POST /v1/uploads/register before the PUT finished, or after a signed URL expired without the bytes ever landing. Both return 422 with “No blob found at storage_key”. Note the TTL bounds the PUT only — POST /v1/uploads/register does not check it, so once the blob is staged you can register whenever. A late register is never a reason to re-upload.
Using the proxy URL (/api/v2/images/ref/…) as if it were stable public content. It includes an auth hash; it’s a stable reference for use in Moda-side operations, not a CDN URL.
Re-uploading on every run when content hasn’t changed. Dedupe handles it server-side, but you still pay a roundtrip. Cache file_id in your app.
Skipping role in the attachment. It drops back to a generic “reference” semantic, which is usually not what you want. Always set role.
Mixing file_id and url in one attachment item. Pick one per item. Mix items within the array is fine.

Upstream

docs.moda.app/api/uploads/uploadFile
docs.moda.app/api/uploads/uploadFromUrl
docs.moda.app/api-reference/large-file-uploads — the signed-URL flow in full

Welcome

Getting started

Brand kit

The AI agent

The canvas

Animation

Workspace

Export & sharing

Websites

Credits & billing

Integrations

Trust & security

FAQ

Uploads

Uploads

Entrypoints

`POST /v1/uploads` — multipart (files up to ~32 MiB)

`POST /v1/uploads/url` + `POST /v1/uploads/register` — signed URL (large files)

`POST /v1/uploads/from-url`

Supported types

Size limits

Deduplication

Using in a task

Roles

URL-form attachment (legacy, less preferred)

Worked example

Common wrong guesses

Upstream

​Uploads

​Entrypoints

​POST /v1/uploads — multipart (files up to ~32 MiB)

​POST /v1/uploads/url + POST /v1/uploads/register — signed URL (large files)

​POST /v1/uploads/from-url

​Supported types

​Size limits

​Deduplication

​Using in a task

​Roles

​URL-form attachment (legacy, less preferred)

​Worked example

​Common wrong guesses

​Upstream

Uploads

Entrypoints

`POST /v1/uploads` — multipart (files up to ~32 MiB)

`POST /v1/uploads/url` + `POST /v1/uploads/register` — signed URL (large files)

`POST /v1/uploads/from-url`

Supported types

Size limits

Deduplication

Using in a task

Roles

URL-form attachment (legacy, less preferred)

Worked example

Common wrong guesses

Upstream