Skip to content

Media: upload, serving, variants, resize

Uploads are raw bytes with an `x-filename` header, never multipart; variants come from configured `imageSizes`, and `/resize` generates then caches on demand.

The upload route parses no form. The bytes are the request body, the file name travels in an x-filename header, and the type is the request's own Content-Type. Any HTTP client that can PUT a file can upload one.

bash
curl -X POST "$KYWI/api/v1/media?siteId=default" \
  -H "Authorization: Bearer $KYWI_TOKEN" \
  -H "Content-Type: image/png" \
  -H "x-filename: hero.png" \
  --data-binary @hero.png
POST/api/v1/mediaBearer token

The request body is the file, and header values must be printable ASCII — which is why the SDK has a separate postBinary.

201 Created
{
  "data": {
    "id": "0d4c…",
    "siteId": "9b1f…",
    "filename": "hero.png",
    "originalFilename": "hero.png",
    "mimeType": "image/png",
    "fileSize": 148203,
    "width": 1600,
    "height": 900,
    "storageKey": "9b1f…/0d4c…/hero.png"
  }
}

Two gates, in that order

The allowlist runs before the body is read, so a rejected type costs one round trip rather than an upload: UNSUPPORTED_MEDIA_TYPE at HTTP 400, with the reason spelled out — File extension ".exe" is not allowed, File type "application/x-msdownload" is not allowed. A file with no extension at all is refused the same way. Only then are the bytes read and measured against media.maxUploadSizeMb, which is 10 unless your config says otherwise.

The stored name is not the name you sent

x-filename reaches a filesystem path, so it is reduced to a basename first: everything before the last / or \ is dropped and every character outside [A-Za-z0-9._-] — spaces, quotes, accents, CJK — becomes an underscore. A name that survives as nothing, . or .. is a 400. Only that cleaned basename is used from there on: the allowlist tests it, the record stores it as both filename and originalFilename, and the storage key is <siteId>/<mediaId>/<filename>. If your integration needs the name the user typed, keep it yourself.

Serving

GET/api/v1/media/:id/fileNo auth

The original bytes; /api/v1/media/:id/original is the same response under another URL. Neither sends Cache-Control — the cacheable routes are below.

SVG is on the default allowlist and an SVG is a document, so the serve routes refuse to render it as one: an inline-risky item — SVG, HTML, XML and their relatives, by extension or by declared type — comes back as a download under a permit-nothing CSP. Everything else stays inline with nosniff added.

GET /api/v1/media/<id>/file — an SVGtext
Content-Type: image/svg+xml
X-Content-Type-Options: nosniff
Content-Disposition: attachment; filename="logo.svg"; filename*=UTF-8''logo.svg
Content-Security-Policy: default-src 'none'; sandbox

Variants and resize

Named variants are generated once, at upload, from the media.imageSizes in force at that moment, and stored beside the original as <storageKey>__<name>. GET /api/v1/media/:id/variant/:name reads exactly that key and 404s when it is absent — which is what a size added to the config after the upload looks like. Bytes that cannot be decoded as the image type they claim fail the whole upload with Unsupported or corrupt image file, and the original is deleted rather than left half-processed.

GET/api/v1/media/:id/resize?w=&h=&fit=No auth

Generate-on-demand and self-caching: the result is written back under <storageKey>__w<W>h<H> — with h omitted the key ends in a bare h, e.g. …__w800h — so the first request for a given geometry pays for the resize and every one after it is a read. Non-images are a 400, not a passthrough.

Resize parameters

The geometry is part of the cache key, so every distinct w/h pair a page asks for becomes a stored derivative — worth knowing before you wire a resize URL to a breakpoint variable. Both /variant/:name and /resize answer with Cache-Control: public, max-age=31536000.

NameTypeDefaultDescription
wrequiredinteger—

Target width. Missing, non-numeric or ≤ 0 is a 400. Never enlarges past the source width.

hinteger—

Target height. Omit it and the height is left to the fit.

fit'cover' | 'contain' | 'fill'cover

How the source is fitted to the box.