MOmoda
uploads

Upload From Url

Changed on

Download a file from a URL and store it.

The returned URL can be used as an attachment in start_design_task.

A URL that cannot become a file is refused with a typed code: source_url_unreachable (the fetch failed — honour retryable: a timeout or 429 is transient, a 404 is not), unusable_source_url (it redirected somewhere unfetchable) or source_url_not_a_file (the content's type is unresolvable — pass filename with the real extension — or not accepted). An upstream 5xx is a 502 upstream_error — the remote's fault, worth a retry.

post/uploads/from-url

Request

  • Base URL
    https://api.moda.app/v1
  • URL
    https://api.moda.app/v1/uploads/from-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

source_urlstring required

Public URL of the file to download and store.

filenamestring nullable

Filename to use. Inferred from URL if omitted.

folder_idstring nullable

Prefixed fld_ wire ID (Crockford base32 body) — the canonical, recommended form. For back-compat, a bare UUID string is also accepted in both path parameters and JSON request bodies (older integrations that stored raw UUIDs keep working), as is the prefix over a UUID body (fld_00000000-0000-4000-8000-000000000000). All three are permanent, supported inputs; only the canonical form is ever emitted.

Example request

{
  "folder_id": "fld_01HT9WK8N3M2J4A5Z6P7Q8R9TV"
}

Response

Successful Response

idstring required

Unique file identifier (prefixed file_...).

urlstring required

Stable proxy URL for the uploaded file. Use this in attachment URLs.

filenamestring required

Filename of the uploaded file.

mime_typestring required

MIME type of the file.

size_bytesinteger nullable

File size in bytes.

was_duplicateboolean

True if an identical file already existed (deduplicated).

folder_idstring nullable

Prefixed fld_ wire ID (Crockford base32 body) — the canonical, recommended form. For back-compat, a bare UUID string is also accepted in both path parameters and JSON request bodies (older integrations that stored raw UUIDs keep working), as is the prefix over a UUID body (fld_00000000-0000-4000-8000-000000000000). All three are permanent, supported inputs; only the canonical form is ever emitted.

expires_atstring nullable

ISO 8601 UTC time after which Moda deletes this transient upload (purpose voice_source), or null for a file that never expires.

Example response

{
  "id": "file_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "folder_id": "fld_01HT9WK8N3M2J4A5Z6P7Q8R9TV"
}

Changes

  • 9ac6a3abc0f8Revision changes
    • info

      added the new optional request property

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • 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

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status