Sign in

v1

latestOpenAPI 3.1.02026-07-223261135.0 KB
uploads

Create Upload Url

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 at settings.MAX_FILE_SIZE_BYTES (enforced at register time when the actual size is known). Signed URLs expire after expires_in_seconds (default 600s, max 3600s).

post/uploads/url

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.