MOmoda
uploads

Create Upload Url

Changed on

Mint a short-lived signed PUT URL for direct-to-storage upload.

Two-step flow for files above the gateway's ~32 MiB inbound cap:

  1. POST /v1/uploads/url with {filename, mime_type} → {upload_url, storage_key, ...}.
  2. PUT raw bytes to upload_url with Content-Type: <mime_type>.
  3. POST /v1/uploads/register with {storage_key} to receive a standard FileUploadResponse whose url is reusable as an attachment in start_design_task.

Files are still capped, with a typed upload_too_large 413 at register time when the actual size is known. The ceiling is per-workspace: read it from GET /v1/uploads/limits as max_file_bytes rather than assuming the 250 MB deployment maximum, because a free workspace is capped lower (ENG-6169). Signed URLs expire after expires_in_seconds (default 600s, max 3600s).

post/uploads/url

Request

  • Base URL
    https://api.moda.app/v1
  • URL
    https://api.moda.app/v1/uploads/url
  • Auth
    HTTP bearer

Headers

Moda-Version'2026-04-12' | '2026-05-01'
Example:2026-05-01

Calendar-dated API version pin. New integrations should pin 2026-05-01 to opt into the newest response shapes. For back-compat the server also accepts requests with no header and resolves them to the current default (today: 2026-04-12); that default advances on each sunset date. Any unsupported value returns 400 unsupported_version.

Request body

filenamestring required

Original filename. Only the basename is used; path components are stripped.

mime_typestring required

MIME type of the file (e.g. application/vnd.openxmlformats-officedocument.presentationml.presentation for PPTX, application/pdf, image/png). Must be on the allow-list.

expires_in_secondsinteger

How long the signed URL is valid (60–3600 seconds, default 600).

Response

Successful Response

upload_urlstring required

Pre-signed URL. PUT the raw file bytes here with Content-Type: <mime_type> within expires_in_seconds. No auth header on the PUT — the URL itself is the capability.

storage_keystring required

Opaque key identifying the pending upload. Pass back to POST /v1/uploads/register after the PUT completes to finalize the file.

mime_typestring required

Resolved MIME type the signed URL is bound to.

expires_in_secondsinteger required

How long the upload URL remains valid (seconds).

instructionsstring required

Human-readable usage hint describing the PUT + register contract.

Changes

  • 9ac6a3abc0f8Revision changes
    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status