# List files

Source: https://api-docs.magicdoor.com/api-reference/files/list-files

Returns the files matching your filter, each with the paths for fetching its content. At least one filter has to be given. Files your company cannot read are quietly dropped from the result rather than causing an error.

`GET https://files.magicdoor.com/files`

**Authentication:** bearer token in the `Authorization` header, as `Bearer <token>`.

## Query parameters

- `ids` (string[]) — Fetch these specific files. Snowflake ids in decimal-string form, repeated once per id: `?ids=1831208734196891648&ids=1831208734196891649`. Send at least one id when you use this filter. Example: `1831208734196891648`.
- `name` (string) — Match the stored file name exactly — not a prefix and not a substring. 1 to 250 characters. Example: `lease-agreement.pdf`.
- `sizeRange` (object) — Match files whose size in bytes falls in this range. Sent as separate query parameters, `sizeRange.start=1024&sizeRange.end=1048576`. Give either end on its own for an open-ended range.
  - `start` (integer) — Smallest size in bytes to include.
  - `end` (integer) — Largest size in bytes to include.
  - `startInclusive` (boolean) — Whether a file exactly at `start` counts as a match. Default: `true`.
  - `endInclusive` (boolean) — Whether a file exactly at `end` counts as a match. Default: `true`.

## Example request

```bash
curl --request GET \
  --url 'https://files.magicdoor.com/files?ids=1831208734196891648&name=lease-agreement.pdf' \
  --header 'Authorization: Bearer <token>'
```

## Responses

### 200 — The matching files. Not paged — every match comes back at once

- `id` (string) — The file's id, a Snowflake sent as a decimal string. This is what other endpoints take when they ask for a file.
- `created` (string, date-time) — When the file was stored, in the company's timezone and with no offset.
- `name` (string) — The original file name, with no path. Display only — content is looked up by id, not by name.
- `size` (integer) — How large the file is, in bytes.
- `contentType` (string) — The MIME type of the stored content, for example `application/pdf`.
- `secureUrl` (object) — Where to fetch the file. Both paths need an access token, and both answer with a redirect to storage.
  - `base` (string) — The origin the two paths hang off. Join it to `raw`, or to a filled-in `variantTemplate`, for a complete URL.
  - `raw` (string) — Path to the file as it was uploaded. Add `?download=true` to make the browser save it instead of displaying it.
  - `variantTemplate` (string) — Path to a resized or re-encoded copy, with `{variant}` still in it. Replace that placeholder with a preset name such as `thumb` to get a usable path.

```json
[
  {
    "id": "1831208734196891648",
    "created": "2026-08-17T21:04:11",
    "name": "lease-agreement.pdf",
    "size": 284197,
    "contentType": "application/pdf",
    "secureUrl": {
      "base": "https://files.example",
      "raw": "/files/1831208734196891648/lease-agreement.pdf",
      "variantTemplate": "/files/1831208734196891648/v/{variant}/lease-agreement.pdf"
    }
  },
  {
    "id": "1831208734196891649",
    "created": "2026-08-17T21:06:48",
    "name": "kitchen-leak.jpg",
    "size": 1904226,
    "contentType": "image/jpeg",
    "secureUrl": {
      "base": "https://files.example",
      "raw": "/files/1831208734196891649/kitchen-leak.jpg",
      "variantTemplate": "/files/1831208734196891649/v/{variant}/kitchen-leak.jpg"
    }
  }
]
```

### 400 — No filter was given, or one was outside its allowed range. The empty-filter message is *At least one filter criteria must be provided.*

### 401 — The access token is missing, expired, or invalid

> **Warning: One filter, minimum**
>
> Calling this with no query parameters at all returns `400` rather than every file in the company. Deleted files are excluded whatever you ask for.

`base` in the example is a placeholder. Read the real origin out of the response rather than assembling one yourself, because it is not always the host you sent this request to.