# List files with public URLs

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

Same filter and same result as listing files, with one addition: each file also gets a signed link that works without an access token, for putting in an email or handing to a third party. At least one filter has to be given.

`GET https://files.magicdoor.com/files/public-urls`

**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`.
- `expiry` (string) — How long the public links stay valid, written as `hh:mm:ss`, or `d.hh:mm:ss` for more than a day. Must be longer than one minute. Applies to every link in the response. Default: `01:00:00`. Example: `06:00:00`.

## Example request

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

## Responses

### 200 — The matching files, each with a public link. Not paged — every match comes back at once

- `id` (string) — The file's id, a Snowflake sent as a decimal string.
- `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.
- `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 with an access token. Both paths answer with a redirect to storage.
  - `base` (string) — The origin the two paths hang off.
  - `raw` (string) — Path to the file as it was uploaded.
  - `variantTemplate` (string) — Path to a resized or re-encoded copy, with `{variant}` still in it.
- `publicUrl` (object) — The same file behind a signed token, reachable without an access token. This is the one to put in an email or give to someone outside MagicDoor.
  - `base` (string) — The origin the two paths hang off.
  - `raw` (string) — Path to the file as it was uploaded. The signed token is part of the path, so treat the whole URL as a secret.
  - `variantTemplate` (string) — Path to a resized or re-encoded copy, with `{variant}` still in it. The same token covers it.
  - `expires` (string, date-time) — When the signed link stops working. This one timestamp carries a timezone offset, unlike the others in this response, which are offset-free and already in the company's timezone.

```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"
    },
    "publicUrl": {
      "base": "https://files.example",
      "raw": "/public/AQAAAAAAAAABeRhfqzsrus57jK9-mmLibDljjkGsihwnf0y5ZA/lease-agreement.pdf",
      "variantTemplate": "/public/AQAAAAAAAAABeRhfqzsrus57jK9-mmLibDljjkGsihwnf0y5ZA/v/{variant}/lease-agreement.pdf",
      "expires": "2026-08-18T03:04:11+00:00"
    }
  }
]
```

### 400 — No filter was given, one was outside its allowed range, or `expiry` was one minute or shorter

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

> **Danger: A public URL is a bearer credential**
>
> Anyone holding the link can read the file until it expires — there is no second check. Keep `expiry` as short as the recipient needs, and do not log these URLs or put them somewhere they can be crawled.

The same filtering rules apply as on [List files](https://api-docs.magicdoor.com/api-reference/files/list-files.md): at least one filter is required, deleted files are excluded, and files your company cannot read are dropped from the result rather than causing an error.