Upload a file
POST/files
Adds an image or a PDF to the workspace library and returns its CDN URL. A template reaches it
with asset('logo.png'), and relative image paths resolve against the same library.
The name is the address: uploading the same name replaces that file in place and answers 200
instead of 201, and templates that reference the name need no change. Renders may still use
the old picture for up to seven days, because each render machine caches images by their URL;
to change a picture at once, upload it under a new name and reference that.
Names are up to 200 characters of letters, digits, dot, dash, underscore and / for folders,
each segment starting with a letter or digit. Accepted types are PNG, JPEG, WebP, GIF, SVG,
AVIF and PDF, up to 10 MB (413 file_too_large above); another type, or a file whose bytes
do not match its type, answers 400 invalid_request. A workspace holds at most 1,000 files.
Organisation fonts are managed in the app, not here.
The library is served without a signature, to anyone who knows the URL, with
Cache-Control: public, max-age=3600: a browser or proxy may show a replaced file's old
version, or a deleted file, for up to an hour. Library files do not expire. Do not put
confidential documents in it. Needs file:write, which new keys do not have by default.
Request
Responses
- 200
- 201
- 400
- 413
- default
A file with this name was replaced.
Uploaded.
Not a multipart request or no file part, an invalid name, an empty file, a type outside the list, bytes that do not match their type (with name and content_type), or a library that already holds 1,000 files (feature: "files").
File too large.
Error (RFC 9457 problem details).