Upload File
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). Pass folder_id to file the upload into a drive
folder (see GET /v1/drive/tree).
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.
Authorizations
API key from Settings > Developer > REST API
Headers
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.
2026-04-12, 2026-05-01 "2026-05-01"
Body
Destination drive folder (fld_... or a bare folder UUID). The file adopts the folder's visibility, exactly like an in-app upload into that folder. An unknown or inaccessible folder is a 404 folder_not_found; a folder you can see but not edit, or a read-only namespace (Skills, Brand Kits), is a 403 folder_write_denied; brand-kit-managed folders are a 403 brand_kit_folder_protected. Omit to land unfiled (library root).
Response
Successful Response
Unique file identifier (prefixed file_...).
^file_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$"file_01HT9WK8N3M2J4A5Z6P7Q8R9TV"
Stable proxy URL for the uploaded file. Use this in attachment URLs.
Filename of the uploaded file.
MIME type of the file.
File size in bytes.
True if an identical file already existed (deduplicated).
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). Both are permanent, supported inputs.
^fld_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$"fld_01HT9WK8N3M2J4A5Z6P7Q8R9TV"