# Media: upload, serving, variants, resize

URL: https://kywi-docs-production.up.railway.app/integrating/media-upload-serving-variants-resize
Type: docPage

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.

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

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

## 201 Created

## 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 two gates never check each other

The extension is tested against one list and the declared type against another, separately — and an empty type, or `application/octet-stream`, is treated as "unknown" and defers to the extension entirely. So `photo.jpg` announced as `image/png` passes both gates and is stored with the wrong type on its record, which is then what every serve route echoes back. Derive the `Content-Type` from the file rather than from whatever your caller believed it was. The same trap on the tool side is [Media through an agent](/agent/media-through-an-agent/).

## 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

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

## A second site’s media 404s without ?siteId=

Every read route resolves the site before it looks the row up, and with no `?siteId=` that resolution lands on the first site in your config. So on a multi-site deployment the second site's own upload returns 404 — including from the layout modules, which emit the bare `/api/v1/media/<id>/file`. Append `?siteId=` on every media URL you construct yourself; see [Site scoping and the `siteId` contract](/integrating/site-scoping-and-the-siteid-contract/).

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.

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

## GET /api/v1/media/<id>/file — an SVG

## 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.

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 never enlarges — it still caches under the key you asked for

The resize passes `withoutEnlargement: true` to sharp, so a `w` larger than the source's own width returns the source unscaled. A 1600px original asked for at `?w=2400` comes back 1600px wide — and that 1600px response is what gets cached under the `2400` key, so every later request for that geometry keeps serving the smaller image.

## 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`.
