# Backend HTTP API Base URL: `${FILEX_PUBLIC_URL}` (default `http://localhost:5212`). All endpoints under `/api/*` return JSON. All write endpoints expect `Content-Type: application/json` unless explicitly noted. **OpenAPI.** The routes under `/api/files` and `/api/ai` are described in [`backend/internal/api/openapi.json`](../backend/internal/api/openapi.json) (OpenAPI 3.1): every operation, its parameters, the request bodies and the answers of the main ones, the token verb or scope each needs. A test holds it to the router in both directions - no operation the server does not serve, no `/api/files` or `/api/ai` route left out - so it is safe to generate a client from. The admin API is not in it; this page is its reference, and the routes of the areas under [Admin: routes described on their own page](#admin-routes-described-on-their-own-page) are described on that area's page. - [Auth & sessions](#auth--sessions) - [Capabilities](#capabilities) - [File browsing](#file-browsing) - [Encryption policy](#encryption-policy) - [Vault (encryption level 3)](#vault-encryption-level-3) - [Drafts](#drafts) - [Uploads](#uploads) - [Archives](#archives) - [Sharing](#sharing) - [The public surface](#the-public-surface) - [Interface preferences](#interface-preferences) - [Thumbnails](#thumbnails) - [Versions](#versions) - [Comments](#comments) - [Realtime (WebSocket)](#realtime-websocket) - [Operations (long-running)](#operations-long-running) - [Admin: storages](#admin-storages) - [Admin: plugins](#admin-plugins) - [Admin: plugin requests](#admin-plugin-requests) - [Admin: encryption policy](#admin-encryption-policy) - [App plugins](#app-plugins) - [Admin: users](#admin-users) - [Admin: roles and permissions](#admin-roles-and-permissions) - [Admin: groups](#admin-groups) - [Admin: tenants](#admin-tenants) - [Admin: routes described on their own page](#admin-routes-described-on-their-own-page) - [Admin: quota](#admin-quota) - [Admin: external services](#admin-external-services) - [Admin: protection & antivirus](#admin-protection--antivirus) - [Admin: sign-in security](#admin-sign-in-security) - [Admin: webhooks](#admin-webhooks) - [Admin: sync runs](#admin-sync-runs) - [Admin: audit log](#admin-audit-log) ### Auth markers | Symbol | Meaning | |--------|---------| | ![public](https://img.shields.io/badge/-public-lightgrey) | No auth | | ![user](https://img.shields.io/badge/-user-blue) | Any authenticated user | | ![admin](https://img.shields.io/badge/-admin-red) | Admin role required - or, where the section says so, the delegated administration permission it names (`admin.users`, `admin.monitor`, `admin.audit`, …; [PERMISSIONS.md](PERMISSIONS.md#delegated-administration)). When an API token calls, the token must also carry the `admin` scope and no `root:` confinement (since v0.41.0): an administrator's token without it gets `403 token missing scope: admin` | | ![signed](https://img.shields.io/badge/-signed-yellow) | A session/token **or** a signed URL - see the route | | ![session](https://img.shields.io/badge/-admin%20session-darkred) | An administrator **signed in to the panel**: an API key is refused `403 session_required`, whatever its scopes ([Admin: plugin requests](#admin-plugin-requests), [Admin: encryption policy](#admin-encryption-policy)) | | ![watch key](https://img.shields.io/badge/-filex--watch%20key-orange) | A filex-watch key for the storage the path names, and no other credential ([FILEX-WATCH.md](FILEX-WATCH.md)) | Auth is provided either by a session cookie (`filex_session`) or a Bearer token (`Authorization: Bearer `). Both are accepted on the same routes. An API token (`X-Filex-Token: ` or `Authorization: Bearer `) is accepted there too, limited by its verbs - `read`, `write`, `delete` - on every route: see [RBAC.md → API tokens](RBAC.md#api-tokens-verbs-on-every-surface). Every caller is also held to the account's permissions ([PERMISSIONS.md](PERMISSIONS.md)); a refusal from that layer is `403 {"error": "permission_denied", "permission", "source", "message"}`. A refusal answers `{"error": "

", "message": "", "params"?}`:
`error` is a stable code to branch on, `message` the sentence to show, written
by the server in the reader's language, and a failed queue operation carries
`error_code` + `error_text` the same way. The codes, the language rules and
what changed in 0.54: [API-ERRORS.md](API-ERRORS.md).

A change (any method but `GET`, `HEAD`, `OPTIONS`, and a WebSocket upgrade) that
a browser sends from another origin with only the session cookie is refused
before any route runs: `403 {"error": "cross_origin_refused", "message"}`. A
Bearer or `X-Filex-Token` header, and a client that is not a browser, are not
affected; another origin is trusted only when it is in
`FILEX_CORS_ALLOWED_ORIGINS` ([CONFIGURATION.md → Requests from other origins](CONFIGURATION.md#requests-from-other-origins)).

---

## Auth & sessions

### `POST /api/auth/login` ![public](https://img.shields.io/badge/-public-lightgrey)
Password login. Every running password provider is asked in turn: the local
accounts, and LDAP, Windows and Linux (PAM) when they are switched on (Admin →
Identity providers). `email` is what the person typed - an e-mail address or a
username, and with a Windows provider also `.\alex` or `CORP\alex`.

**Request**
```json
{ "email": "admin@local", "password": "" }
```
**Response 200**
```json
{
  "user": { "id": 1, "email": "admin@local", "username": "admin", "role": "admin" },
  "token": "eyJhbGc..."
}
```
The session cookie is set by the same response. The Bearer token is for SPA
embeds that prefer header auth.

**The bot check.** While [bot protection](BOT-PROTECTION.md) is on for `login`
(or `demo_login`, a demo's documented account), the body carries the widget's
answer, `captcha_token` - or, during an outage, the local solution
`captcha_local` - and it is judged before the password is compared:
**422** `captcha_required` / `captcha_failed` / `captcha_expired` /
`captcha_fallback_inactive` (`captcha` names the reason; the attempt is not
counted against the account), **409** `captcha_fallback` with a `challenge`.
A token is spent by the attempt, whatever the password turns out to be.

**The account's language.** An account that holds no language yet is given
the one its sign-in arrived in: the request's `Accept-Language` (the web panel
sends the language on its screen; a browser back from an identity provider
sends its own list), when filex offers it - a shipped language or one a
running language pack adds. The answer's `user.locale` already carries it. An
account that has a language keeps it, and a language filex does not offer
leaves the account without one (it reads the instance's,
`FILEX_DEFAULT_LOCALE`, until somebody picks). The same happens at the realm
handoff (`POST /api/auth/handoff`) and at the end of an OIDC sign-in; no
client writes a language after a sign-in.

**Status codes:** `200` ok · `401` invalid creds · `403` the account is
disabled (`"disabled": true`), or its tenant may not sign in now - suspended,
or maintenance mode (`"maintenance": true`) · `403 cross_origin_refused`
the form was posted from another origin (sign-in forgery; a script that sends
no `Origin`, `Sec-Fetch-Site` or `Referer` is not affected) · `429` too
many failed attempts (see below) · `503` busy (see below).

**Response 401** - the machine-readable `error` is unchanged; what a person needs
is added beside it, worded in their language (`Accept-Language`):
```json
{
  "error": "invalid credentials",
  "message": "Wrong credentials. 3 attempts left; the account is locked at failed attempt 5.",
  "remaining": 3, "limit": 5, "scope": "account"
}
```
`scope` is `account` or `ip` - whichever counter has fewer tries left. The body
is the same for an account that exists and one that does not (the counter is keyed
by the identifier typed). On a public demo the shared account has no account
counter, so its replies are always `scope: "ip"` - the address's tries - and never
promise an account lock ([CONFIGURATION.md → Demo mode](CONFIGURATION.md#demo-mode)). A wrong second-factor code answers the same way with
`"error": "invalid two-factor code", "totp_required": true`; a *missing* code does
not count. See [Sign-in attempt limits](CONFIGURATION.md#sign-in-attempt-limits).

**Response 429** - the attempt that trips the limit, and every attempt while the
lock lasts (even with the right password), with a `Retry-After` header:
```json
{ "error": "too many attempts", "message": "Too many failed attempts: this account is locked. Try again in 1 minute.",
  "countdown": "Too many failed attempts: this account is locked. Try again in {wait}.",
  "locked": true, "scope": "account", "retry_after": 60 }
```

`countdown` (since 0.54) is the same sentence with `{wait}` left open: a
sign-in form that counts the lock down replaces `{wait}` with its own clock
(`4:05`) instead of keeping a copy of the words.

**Response 503** `{"error": "busy", "message": "…"}` with `Retry-After: 3` -
the sign-in provider is at its limit of simultaneous sign-ins (a Linux PAM
provider's `max_concurrent`). It is not a judgement of the password and is not
counted as a wrong attempt.

**`realm`** (multi-tenant installs only; a single-tenant install ignores it) -
the tenant realm the person typed in the form's Realm field
([MULTI-TENANCY.md → Realms](MULTI-TENANCY.md#realms-which-tenant-a-sign-in-is-for)):
```json
{ "email": "alex", "password": "…", "realm": "acme" }
```
Empty (or absent) is the tenant the request's host names, else the platform's
own. The account lookup never leaves the tenant, and the account signed in to is
checked against it once more. A realm nobody has, and a realm that is not the
host's tenant, answer exactly like a wrong password (`401`, the same body,
counted). The attempt limit counts `/`.

**Response 200, handed to the tenant's address** - when the realm names a tenant
that has a `host` of its own and the request came in on another host, no
session is opened here (no cookie, no token):
```json
{ "handoff": { "origin": "https://files.acme.example", "code": "Zk…" } }
```
The client continues on the tenant's address, on the same sign-in page it
started from (`/drive/login` or `/admin/login`, with the same query), with the
code in the URL fragment (`/drive/login#handoff=`); that page
redeems it with
[`POST /api/auth/handoff`](#post-apiauthhandoff-). The code is bound to the one
account that just signed in, lives 60 seconds, is spent by its first use and is
honoured on the tenant's host only.

### `POST /api/auth/handoff` ![public](https://img.shields.io/badge/-public-lightgrey)
The tenant's-address half of a sign-in typed on the platform's address
(multi-tenant). **Body** `{"code": "…"}` - the code a `POST /api/auth/login`
answered with.

**Response 200** - as for a sign-in: `{"user", "token"}` and the session cookie,
set on this host. **Response 401** `{"error": "invalid or expired handoff"}` -
the code is unknown, spent, expired, issued for another purpose, presented on
another host than the tenant's (it is spent all the same), or its account may
no longer sign in or is no longer this host's tenant's. The same answer for
every reason; the reason is in the audit row `auth.handoff_refused`
(`reason`: `expired`, `wrong_host`, `wrong_purpose`, `wrong_tenant`,
`actor_gone`, `subject_gone`, `actor_is_not_subject`), beside
`auth.handoff_issued` and `auth.handoff_used` (`purpose`, `actor_id`,
`subject_id`, `host`). The code is never logged or audited; an unknown or spent
one is not audited at all. `404` on an install where the handoff does not exist
(single-tenant).

### `POST /api/auth/logout` ![public](https://img.shields.io/badge/-public-lightgrey)
Deletes the session and clears the cookie (with no session it only clears the
cookie).

**Body** (optional): `{"return_to": "/admin/login" | "/drive/login"}` - the
sign-in page of the front door the person was using. Anything else means
`/admin/login`; the address is never taken from the request.

**Response 200**: `{"ok": true}`, plus `"logout_url"` for an SSO session whose
identity provider can end sessions - its end-session URL with `id_token_hint`,
`client_id` and `post_logout_redirect_uri` (`?signed_out=1`). The
web app sends the browser there so the provider's session ends too
(RP-initiated logout, [SSO.md](SSO.md#signing-out)). Never present with
`FILEX_OIDC_LOGOUT=local`, for a password session, or for a session signed in
through a provider that has since been replaced.

### `GET /api/auth/oidc/start` ![public](https://img.shields.io/badge/-public-lightgrey)
Redirects (302) the browser to the configured OIDC issuer authorise URL.

**Query**: `?next=/path/to/return/to` (optional)

### `GET /api/auth/oidc/callback` ![public](https://img.shields.io/badge/-public-lightgrey)
OIDC redirect target. Validates `code`, exchanges for tokens, creates/updates
the user, sets the session cookie, redirects to `next`.

### `GET /api/auth/me` ![user](https://img.shields.io/badge/-user-blue)
**Response 200**
```json
{
  "user": {
    "id": 5, "email": "ayse@example.com", "username": "ayse",
    "role": "user",
    "avatar_url": "data:image/jpeg;base64,…"
  },
  "permissions": ["files.download", "files.create", "files.modify", "share.links", "…"],
  "permissions_in_folders": ["files.delete"],
  "permissions_by_folder": ["files.delete"],
  "permission_settings": { "share_link_max_days": 7 },
  "two_factor_required": false,
  "realm": "acme"
}
```
What the account may do ([PERMISSIONS.md](PERMISSIONS.md)), so a client can
hide what would only answer `403`: `permissions` holds account-wide,
`permissions_in_folders` only in some folders, and `permissions_by_folder`
lists every permission whose answer differs from folder to folder - a client
asks `POST /api/files/manager?action=allowed` about the selected paths before
offering those. The explorer reads this itself when its host passes no
`permissions` ([INTEGRATION.md](INTEGRATION.md)). The effective answer with the
source of each permission is `GET /api/auth/me/permissions`.

`realm` (multi-tenant installs, a tenant's account only) is the account's tenant
realm - what it writes in front of its name where no address names its tenant
(`acme/alex` over SFTP). Absent on a single-tenant install and for the
platform's own accounts. `GET /api/auth/ssh-keys` answers the SFTP/FTPS `login`
already written that way.

### `PATCH /api/auth/profile` ![user](https://img.shields.io/badge/-user-blue)
Patches the caller's own `email`, `display_name`, `locale`, `timezone` and
`avatar_url`. Absent fields are left alone.

Needs the `account.edit` permission; an API token needs `write` too - as do
`POST /api/auth/password` and `POST /api/auth/totp/enroll`, `…/verify` and
`…/disable`: a token that may only read cannot change the account it belongs
to (`403 token missing scope: write`).

`POST /api/auth/password` (`{current_password, new_password}`) takes a new
password of at least **8 characters** (counted as characters, not bytes). The
same rule, in the same words, holds wherever an administrator sets one
(`POST` and `PATCH /api/admin/users`): a shorter password is `400
{"error":"password_too_short","field":"password","message":…}`, the sentence in
the reader's language naming the number. The rule lives in one place on the
server (`internal/auth/drivers/local/password_rule.go`); until 0.54.0 only the
person's own change asked it.

`avatar_url` is the **profile picture**: a `data:image/…` URI (≤ 48 KB) or an
`http(s)` / site-relative URL; an explicit `""` removes it. Anything else is a
`400` rather than a silent drop - the person is looking at an upload they
believe worked. The SPA's user-settings dialog downscales what you pick to 160px
before encoding, so the cap is not something a user meets.

The picture belongs to the **account**, which is what makes it appear
everywhere: the explorer's collaboration strip draws it instead of initials for
that user on every client of the account - browser session, desktop app, and any
API key minted under it. Two deliberate exceptions, because the alternative is
drawing the wrong face on somebody's row:

- A token with a **username allow-list** is a shared proxy, not a person (its
  presence entry reads "work"), so no picture is attached.
- When a trusted host proxy re-identifies a connection as a different end user
  via `X-Filex-Presence-Name`, only *that* person's picture may be drawn -
  supplied by the proxy as `X-Filex-Presence-Avatar` (same accepted shapes, same
  cap). Without it the row falls back to initials. "A trusted host proxy" is
  a token with a username allow-list: the `X-Filex-Presence-*` headers
  (`-Name`, `-Avatar`, `-Key`) are read from such a token only. A personal
  token (the desktop app, a CLI, a script) is its owner, and its headers are
  not read (since 0.54).

The cap is small on purpose: the avatar rides inside every presence frame the
collaboration socket broadcasts, so it is paid for again on each join, leave and
focus change - unlike the branding logo, which is fetched once per page.

### `POST /api/auth/account/check` ![user](https://img.shields.io/badge/-user-blue)
Would this e-mail address or username be accepted? Asked while a form is typed
(the profile, an administrator adding a user) and answered by the same rules
and in the same words a save refuses with. It writes nothing; an API token
with `read` may ask. Since 0.54.

```json
{ "email": "a,b@x", "username": "9lives", "for": "self" }
```

Only the fields sent are checked. `for` is whose account the values are for:
`self` (the default; the address and the name the account already holds are no
change) or `new` (an account an administrator is about to create).

**Response 200** - a field is present only when it would be refused, with the
save's code and the sentence in the reader's language:

```json
{ "email": { "error": "email_invalid", "message": "“a,b@x” is not an email address. Write it as name@example.com." },
  "username": { "error": "username_invalid", "message": "A username cannot start with a digit." } }
```

Whether an address or a name is **taken** (`email_taken`, `username_taken`) is
said only where the save would say it: about your own account when you may edit
it (`account.edit`), and to a full administrator about a new one. Anybody else
is told about the format only.

---

## Capabilities

### `GET /api/capabilities` ![public](https://img.shields.io/badge/-public-lightgrey)
Tells the frontend what features are available - used to hide buttons for
disabled features.

**Response 200** (abridged - the real body also carries the per-storage probe,
build metadata and a set of flat aliases kept for older embeds)
```json
{
  "version": "0.34.0",
  "upload": true, "move": true, "copy": true, "delete": true, "mkdir": true,
  "search": true, "versions": true, "ocr": false,
  "thumbs": {
    "enabled": true,
    "image": true, "video": true, "pdf": true, "office": false
  },
  "antivirus": true,
  "antivirus_mode": "daemon",
  "external": {
    "onlyoffice": { "enabled": true, "url": "https://docs.example.com", "state": "ok" },
    "drawio":     { "enabled": false, "url": "", "state": "" }
  },
  "onlyoffice_url": "https://docs.example.com",
  "drawio_url": "",
  "max_upload_size": 5368709120,
  "chunk_size": 8388608,
  "auth_drivers": ["local", "oidc"],
  "storage_drivers": ["ftp", "local", "s3", "sftp", "smb", "webdav"],
  "db_driver": "sqlite",
  "share_max_ttl_days": 7,
  "share_link_max_days": 3
}
```
Cached client-side for 1h. `share_max_ttl_days` is the longest life a new share
link may be given on this install (0 = no ceiling; [PROTECTION.md](PROTECTION.md)).
`share_link_max_days` is the CALLER's: that ceiling or the **Maximum share-link
lifetime** of the permission rules binding them, whichever is shorter (0 = no
ceiling) - what the share dialog derives its expiry choices from
([SHARING.md](SHARING.md)).

#### Rules the server publishes

Since 0.54, some answers are rules the clients used to keep copies of; the
server publishes them and every client (the explorer, the admin panel, the
desktop app, an embed) reads them instead (#211):

- `release`, `commit`, `built` - the release (`v0.54.0`), the commit and the
  build time, apart. `version` keeps the one-line form
  (`v0.54.0 (, )`); nothing needs to parse it. `commit` and
  `built` are absent when the build did not stamp them.
- `edit_kinds` - how each kind of file is edited, from `internal/editkind`:
  `office` (extensions the document server opens and edits), `text`
  (extensions the built-in editor opens and `POST /api/files/save-text`
  saves), `text_names` (whole names that are text, lower case: `makefile`,
  `.gitignore`), and `text_mime_prefixes` / `text_mimes` (a file whose name
  says nothing is text when its catalogued mime is). The two rules never
  claim one file: `.txt`, `.csv`, `.html` and `.xml` are text, and `.pdf`,
  `.xps` and `.epub`, which the document server only displays, are neither.
- `limits` - the numbers an input is held to before it is sent, each
  enforced by the server again: `tag_max_runes` (64), `comment_max_runes`
  (5000), `e2e_request_reason_max_runes` (2000, the rest is cut),
  `app_state_max_bytes` (16384 - what one app's interface keeps for a
  person; `PUT /api/me/prefs` answers `413 APP_STATE_TOO_LARGE` above it)
  and `app_ui_save_chunk_bytes` (8 MiB). Characters are Unicode code points,
  not UTF-16 units.
- `event_off` - for a signed-in caller, the notification events that cannot
  happen on this instance: `{ "": { "reason", "fixable", "text" } }`.
  `reason` is what it waits for (`antivirus`, `escrow`, `app_plugins`,
  `e2e_approval`), `fixable` whether THIS caller could switch that on (the
  instance's administrator for a service, the tenant's own administrator
  for the encryption policy) and `text` the sentence, in the reader's
  language. An event absent from the map can happen. The settings dialog
  greys a `fixable` one with the sentence and leaves the rest out; Admin →
  Webhooks prints the sentence beside the box.

A rule a client applies while a person types or picks (a theme's key, the
accent colour, a ZIP password, which app action a selection may run, which
form field shows) cannot travel as a value: its cases are kept in
`backend/internal/api/handlers/testdata/rule-mirrors.json`, which the Go tests
and the client tests both check their side against.

`realm` is present on a **multi-tenant** install only - the sign-in form's Realm
field ([MULTI-TENANCY.md → Realms](MULTI-TENANCY.md#realms-which-tenant-a-sign-in-is-for)):
`{"enabled": true, "locked_realm": null}` on the platform's address (the field
is empty and free), `{"enabled": true, "locked_realm": "acme"}` on a tenant's
own address (filled in and read-only). A single-tenant answer carries no
`realm` key at all.

⚠⚠ **An anonymous caller is told _whether_ a capability is on, never _where_ it
lives.** The endpoint is deliberately public - an embedder probes it before
anybody logs in ([INTEGRATION.md](INTEGRATION.md)) - so for a request carrying
no usable credential the `url` is dropped from every `external.` entry
and the flat `onlyoffice_url` / `drawio_url` aliases come back
empty. `enabled` and `state` are unchanged, which is what a feature probe
actually asks.

Signed-in callers see the payload above in full, because one consumer needs a
real host in the browser: the draw.io iframe. OnlyOffice
does not - the browser gets its document-server URL from the authenticated
`POST /api/files/onlyoffice/config` (`documentServerUrl`, and `frame` - the
page on `FILEX_ONLYOFFICE_FRAME_ORIGIN`, else on `FILEX_APP_UI_ORIGIN`, the
editor runs in, when there is one) - so that
host now travels only with a credential as well.

Measured before this changed (2026-09-07, demo.filex.sh): an unauthenticated
`GET /api/files/capabilities` answered 200 with
`"url": "https://docs.example.com"` - the operator's internal document server,
published by every install that configured one.

`newdoc_types` is the other field worth naming, because it decides what a
"New document" menu may offer: the document types **this build can create**,
from a template registry compiled into the binary (`internal/newdoc`). Each row
is `{ ext, group, mime, requires, ext_required }`, where `requires` names the
external service the *editor* needs (`"onlyoffice"`, `"drawio"`, or absent for
the built-in code and markdown editors), and `ext_required` says whether the
file must carry the extension - `true` for office documents and diagrams, whose
editors find them by it, `false` for text types, which a person may name
anything (`LICENSE`, `test.conf`; #56). It is published as `false`, never
omitted: its absence is how a client recognises a server from before #56.

```json
"newdoc_types": [
  { "ext": "docx", "group": "document", "mime": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "requires": "onlyoffice", "ext_required": true },
  { "ext": "md",   "group": "text",     "mime": "text/markdown; charset=utf-8", "ext_required": false }
]
```

⚠ It answers "can the SERVER make these bytes", not "can this deployment open
them". A client crosses `requires` against the `external` block above and
offers only what is satisfied, which is what stops an install with no document
server from offering a `.docx` nobody there can then open - and what keeps the
client from carrying a hardcoded extension list that rots the moment the
registry grows a type. Published to anonymous callers too: it is a static
property of the build, identical on every install of this version, and names no
host.

A signed-in person also gets the rows **running apps** add to the menu
(`new_documents`, [APP-PLUGINS-API.md](APP-PLUGINS-API.md#new-documents)):
`group` and `requires` are `"app"`, `key` is what the create call sends
(`app::`), and `app` names the app, the view that opens the new
file and the app's own label. They are not a property of the build, so an
anonymous caller or an app token is never told them.

A signed-in caller also gets `e2e_policy: { "available": true, "policy": "permitted" }` -
the caller's own tenant's row of [who may encrypt](E2E-ENCRYPTION.md#who-may-encrypt):
`available` is the platform operator's switch for the tenant, `policy` the
tenant's choice (`off` · `admins` · `permitted` · `approval`). Not an anonymous
caller's (a tenant's policy is not a property of the build), and absent on a
server from before the policy, which the explorer reads as "offer encryption as
before". The explorer's menus are not read off this row - the platform operator,
looking at another tenant's storage, is answered by that tenant's policy - but
asked per path (`POST /api/files/e2e/allowed`, [Encryption
policy](#encryption-policy)); the row tells the notification settings and the
Webhooks screen when the two request events can happen. The server decides
every write.

`e2e_vault` is always present: `true` only on a server that serves the
[vault API](#vault-encryption-level-3) (`FILEX_E2E_VAULT`). A client offers the
third encryption level only there.

⚠ `antivirus` means **configured**, not answering: the setting is on and either
a scanner binary resolved or a clamd address is set. Reachability costs a
network round trip and is probed on `GET /api/admin/protection`, where an
operator is waiting for the answer. `antivirus_mode` is `binary` or `daemon`
and is absent when `antivirus` is false - the two deployments produce the same
green light and behave very differently when one of them breaks.

---

## File browsing

### `GET /api/files/manager` ![user](https://img.shields.io/badge/-user-blue)
List the contents of a directory (`action=index`, the default). The same
route reads a file (`action=preview`, `action=download`, both honour `Range`),
lists only the subfolders (`action=subfolders`) and asks what changed
(`action=changes`, below).

**Query**
| Param  | Notes |
|--------|-------|
| `action` | `index` (default) \| `subfolders` \| `changes` \| `search` \| `preview` \| `download` |
| `path` | `://`, e.g. `docs://reports/2026`; empty = the first storage's root |
| `sort` | `index` / `subfolders`: `name` (default), `modified`, `size` or `type`; a leading `-` reverses it. Folders always come first. An unknown key answers `400 bad_sort`. |
| `filter` | `search`: the query. `search` also takes the [narrowing parameters](SEARCH.md#narrowing-a-search) (`type`, `min_size`, `modified_after`, `under`, `owner`, `hidden`…). |

**Response 200**
```json
{
  "adapter": "docs",
  "storages": ["docs", "archive"],
  "dirname": "docs://reports",
  "read_only": false,
  "perm": "editor",
  "files": [
    {
      "id": 4711, "path": "docs://reports/report.pdf", "basename": "report.pdf",
      "type": "file", "extension": "pdf", "size": 102400,
      "mime_type": "application/pdf", "last_modified": 1776852000000,
      "storage": "docs", "perm": "editor", "etag": "abc123",
      "thumb_url": "/api/files/thumb/4711?exp=…&sig=…"
    },
    { "id": 4712, "path": "docs://reports/photos", "basename": "photos", "type": "dir", "size": 0, "storage": "docs" }
  ]
}
```

`last_modified` is Unix milliseconds. `id` is the catalogue id (versions, tags
and comments are addressed by it); a folder listed straight from the storage
before a scan catalogued it carries rows without one.

**One order.** The rows come back folders first, then by name (case and the
four Latin i's folded, numbers as numbers: `Disk 2` before `Disk 10`), whichever
path built the answer - the catalogue, the storage itself, or both merged - and
`file_list` (MCP) answers in the same order (`internal/listorder`). Before 0.54
the catalogue path answered files first and the others folders first.

**`starred`** is `true` on the rows the caller has starred (absent otherwise),
and **`kind`** says what a row is (`folder`, `document`, `spreadsheet`,
`presentation`, `pdf`, `image`, `video`, `audio`, `archive`, `code`, `text`,
`other`) - the server's one rule, which the explorer's Type chip and a search's
`type=` both use. Inside an end-to-end
encrypted folder the answer also carries `e2e` and `e2e_root`, and an
encrypted folder's own row `e2e: true`. A vault (encryption level 3,
[E2E-VAULT-FORMAT.md](E2E-VAULT-FORMAT.md)) is marked as one: its row
carries `e2e_vault: true`, and a listing of the vault folder or of anything
in it carries `e2e_vault_root` (the vault folder's wire path) - what is
listed there is the vault's layout on the storage (`v/`, packs, index
files), which clients never show as folders. Every **file** row inside an
encrypted folder says how it is encrypted - `encrypted: "folder"`, or
`"vault"` inside a vault; a single encrypted file (`.fxe`) elsewhere says
`"file"` - and so does each file row of the search answer, Recent, Starred,
a tag view, Shared with me and `/api/files/stat`; a folder row and a plain
file never carry it (one rule, `encryptedKind` in
`internal/api/handlers/e2e_rows.go`). An app's interface is handed it as
`FileInfo.encrypted`, and an app is refused such a file's bytes
([APP-PLUGINS-API.md](APP-PLUGINS-API.md#which-rows-say-encrypted)).

**Status codes:** `200` ok · `403` forbidden · `404` path missing.

### `GET /api/files/pdf/{name}` ![user](https://img.shields.io/badge/-user-blue)
A PDF's preview, on a path of its own (0.57.4, GitHub #124). It answers what
`GET /api/files/manager?action=preview` answers for a PDF: the same storages,
the token's root, the drafts and traversal guards, and `Range`.

It exists for the built-in viewer. filex's own pages name the frames they may
show of filex by path (`frame-src`, [CONFIGURATION.md](CONFIGURATION.md#security-headers-and-framing)),
and Chrome checks a PDF in an `