Files

Get a file variant

Fetches a resized or re-encoded copy of a file — a thumbnail, a preview, a smaller video or audio rendition. Like the raw download, the response is a 302 redirect to a signed storage URL rather than the bytes themselves.

GET

https://files.magicdoor.com/files/{fileId}/v/{variant}/{filename}

Authorization

Authorizationstringrequired

Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Path parameters

fileIdstringrequired

The source file, as a Snowflake id in decimal-string form. Must be a positive whole number.

example: 1831208734196891649

variantstringrequired

Which rendition you want. From the company portal this has to be one of the presets listed below. 3 to 100 characters, made of letters, digits, and the characters ; , _ -.

example: thumbthumbprevieworiginal320p720p1080p64k128k192k320k

filenamestring

An optional trailing segment that renames this one download. Leave the whole segment off and the variant's own generated name is used, such as kitchen-leak-thumb.webp. When you do send it, it must be 3 to 200 characters, and it must be URL-escaped.

example: kitchen-leak.webp

Query parameters

waitboolean

Whether to hold the request open until the variant has been generated. Leaving it at true always gives you the variant. Setting it to false only changes anything for files a browser could already display, and then only while the variant is still being made — see below.

default: trueexample: true

downloadboolean

true makes the storage URL send Content-Disposition: attachment, so a browser saves the file instead of displaying it.

default: falseexample: false

Response

302 · Redirect to the signed storage URL that holds the content

Locationstring

The signed storage URL for the variant — or, when wait=false and the variant is not ready, for the original file. Valid for seven days and needs no MagicDoor access token of its own, so treat it as a secret. There is no response body.

401 · The access token is missing, expired, or invalid

404 · No such file, the file has been deleted, it belongs to another company — or the variant could not be produced

The presets

Variant	Works on	What you get
`thumb`	Images	WebP, longest side at most 192 pixels
`preview`	Images	WebP, longest side at most 1280 pixels
`original`	Images	WebP at the original pixel size, quality 90 — the one to use to make a format a browser cannot show, such as HEIC, displayable
`320p`	Video	H.264 video with AAC audio, scaled to 320 lines
`720p`	Video	H.264 video with AAC audio, scaled to 720 lines
`1080p`	Video	H.264 video with AAC audio, scaled to 1080 lines
`64k`	Audio	MP3 at 64 kbit/s
`128k`	Audio	MP3 at 128 kbit/s
`192k`	Audio	MP3 at 192 kbit/s
`320k`	Audio	MP3 at 320 kbit/s

Presets only, and a silent 404 when it cannot be done

Company portal callers can only bring a preset into existence. Ask for anything else, ask for a preset that does not suit the source — a 720p of a PDF, a thumb of an audio file — and the answer is 404, with none of the detail the other failures carry. There is no way to tell a wrong variant name from a source file that cannot be converted.

Generation, and what `wait` really does

The first request for a given file and variant is what creates it; later requests reuse it.

wait=true, the default. The request stays open until the variant has been made, then redirects to it. Slower on that first call, but you always get what you asked for.
wait=false. Only takes effect when the source file is already something a browser can display — a JPEG, PNG, WebP, MP4, WebM, MP3, PDF, and so on. If the variant is not ready yet, you are redirected to the original file instead and generation carries on in the background, so a later request gets the variant. For anything a browser cannot display, wait=false is ignored and the request behaves as if it were true, because redirecting to the original would be no use.

The signed URL behaves exactly as it does on Download a file: follow the redirect, and do not forward your MagicDoor Authorization header to storage.