Files

Upload a file

Uploads one file as multipart form data and returns its id and paths. The file is stored on its own, not yet attached to any record — pass the returned id to whatever you want to attach it to.

This endpoint is deprecated and may be removed in a future release.

POST

https://files.magicdoor.com/files

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.

Body

multipart/form-data

Send this as multipart/form-data, not JSON. The nested allowedSize values are separate form fields named allowedSize.start and allowedSize.end.

filefilerequired

The file itself. Must not be empty, and must not exceed 100 MB — that ceiling is fixed and allowedSize can only lower it, never raise it.

allowedTypesstring[]

Refuse the upload unless its detected MIME type matches one of these. Each entry is an exact type such as application/pdf, a subtype wildcard such as image/*, or * for anything. Repeat the field once per pattern, and send at least one when you use it. Leave it out to accept any type.

example: application/pdf

allowedSizeobject

Refuse the upload unless its size in bytes falls in this range. Sent as the form fields allowedSize.start and allowedSize.end.

Response

200 · The stored file

idstring

The new file's id, a Snowflake sent as a decimal string. This is what you hand to whatever should own the file.

namestring

The file name taken from the upload, with any path stripped off.

sizeinteger

How large the stored file is, in bytes.

contentTypestring

The MIME type MagicDoor worked out by inspecting the content, not the one your form claimed. It can differ from what you sent.

secureUrlobject

Where to fetch the file back. Both paths need an access token.

400 · No file, an empty file, a file over the size ceiling, a size outside `allowedSize`, or a detected type not in `allowedTypes`

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

This endpoint is on its way out

It still works and is still supported, but it is marked obsolete in MagicDoor's source and will be removed. Nothing replaces it in this reference yet — if you are building on it, tell support so the change can be planned around you.

The file starts out unattached

An upload here is stored with no category and no owning record, and is not claimed by anything. It is a staging step: upload first, get an id back, then send that id to whichever endpoint creates or updates the record the file belongs to.

Both allowedTypes and allowedSize are guardrails you set for yourself. They are optional, and if you leave them out the only limit is the fixed 100 MB ceiling.

The type is detected, not declared

MagicDoor reads the content to decide the MIME type and ignores the one in your multipart part. allowedTypes is checked against the detected type, so a .pdf that is really a JPEG is rejected by allowedTypes=application/pdf, and the contentType in the response can differ from what you sent.