BlueGit

timfa filemanager

Files

filemanager / docs / api.md

api.md

api.md 9.9 KiB Download Raw

Filemanager sync API (v1)

This API is for apps that sync files with the file manager: phone apps, desktop sync clients, or background services. It covers login with user consent, listing, a change feed (delta), upload (including resumable uploads for large files), download with Range, folders, move, delete and conflict detection.

server also serves it at /api/v1/openapi.json.

  • OAuth metadata: /.well-known/oauth-authorization-server.
  • Users manage access on /apps.html ("Connected apps", also in the

user menu of the web UI). There they can see every authorised app, device and token, see when each was last used, revoke them, and create personal tokens.

A token can never see more than its user can. Every request goes through the same permission checks as the web UI: per-root read/write rights, the user's own folder, and admin rights.

1. Register your app (once)

An admin registers the app on /apps.html under "OAuth clients". You provide a name and one or more redirect URIs and get back a client_id (fmc_...). Clients are public: there is no client secret, and PKCE is mandatory.

These redirect URIs are allowed:

KindExampleNotes
HTTPShttps://sync.example.com/callbackWeb services
Loopbackhttp://127.0.0.1/callbackDesktop apps. Any port is accepted at runtime (RFC 8252)
Private schemecom.example.sync:/callbackMobile apps

2. Authorisation (authorization code + PKCE)

1. Generate a code_verifier: 43–128 characters from A-Z a-z 0-9 - . _ ~. Then compute code_challenge = BASE64URL(SHA256(code_verifier)). 2. Open the following URL in the system browser:

   GET /oauth/authorize?response_type=code
       &client_id=fmc_...
       &redirect_uri=com.example.sync:/callback
       &scope=files:read%20files:write
       &state=<random>
       &code_challenge=<challenge>&code_challenge_method=S256
       &device_name=Tim's%20Pixel

The user sees which app, which device and which permissions are requested. They sign in and click Allow or Deny. 3. The browser is redirected to redirect_uri?code=...&state=...&iss=.... Check that state matches the value you sent. The code is valid for 10 minutes and works only once. If the user denied access, you get error=access_denied instead. 4. Exchange the code for tokens:

   POST /oauth/token   (application/x-www-form-urlencoded or JSON)
   grant_type=authorization_code&client_id=fmc_...&code=...
   &redirect_uri=com.example.sync:/callback&code_verifier=...
   {"access_token":"fma_...","token_type":"Bearer","expires_in":3600,
    "refresh_token":"fmr_...","scope":"files:read files:write","grant_id":"g_..."}

5. Send Authorization: Bearer <access_token> on every API call. An access token is valid for 1 hour. Renew it with grant_type=refresh_token&client_id=...&refresh_token=.... Refresh tokens rotate: always store the new one. If an old refresh token is used again, the whole grant is revoked, because that points to a stolen token. A refresh token expires after 90 days without use. 6. Logout: POST /oauth/revoke with token=<refresh or access token>.

Each authorisation is a separate grant, so each device has its own tokens, and the user can revoke one device without affecting the others.

Scopes: files:read lets an app list, read, download and use the delta feed. files:write lets it upload, create folders, move and delete, and always includes files:read.

Personal tokens (fmp_...) for your own scripts are created on /apps.html. They are used the same way (Authorization: Bearer), can optionally expire, and can be revoked there.

3. Paths and roots

GET /api/v1/roots returns the roots the user can see. ~ is always the user's own folder. Other roots are the shared folders the user has rights to. All paths are virtual and have the form /<root-id>/<relative path>, for example /~/Photos/2024/a.jpg or /team/report.pdf. The segments .. and ., backslashes and symlinks that leave the root are refused, and symlinks are not listed.

Every file or folder (Entry) has the following fields:

FieldMeaning
idStable identity. It stays the same across renames and moves on the same disk
path, name, typetype is file or folder
size, mtime, mtime_msSize and modification time
versionOpaque. It changes on every change and is also the ETag
sha256Present when known. Use GET /files/metadata?path=..&hash=1 to have it computed

4. Sync walkthrough

# First sync of a root
GET /api/v1/delta?root=~                     -> reset=true, entries(change=exists), cursor, has_more
GET /api/v1/delta?root=~&cursor=<c>          -> repeat while has_more
store cursor

# Every time after that (poll, e.g. every 30-60 s or when the app comes to the foreground)
GET /api/v1/delta?root=~&cursor=<c>
  created  -> download (GET /files/content)
  modified -> download if version differs from your local copy
  moved    -> rename locally old_path -> path (children are implied)
  deleted  -> delete locally (folders: including contents)
  repeat while has_more, then store the new cursor
410 cursor_expired -> start over without a cursor and reconcile with local state

The feed sees all changes: those made through the API, through the web UI, and directly on disk. Changes from outside the API become visible within about 15 seconds (api.scanIntervalSeconds). Changes made through the API show up right away.

Pushing local changes:

new file   : PUT /files/content?path=/~/a.txt&mtime=<ms>   + If-None-Match: *
changed    : PUT /files/content?path=/~/a.txt               + If-Match: "<version you last saw>"
large file : POST /uploads {path,size,sha256,mtime,if_match|if_none_match}
             PATCH /uploads/<id> (Upload-Offset: n, body = chunk <= max_chunk_bytes) ...
             on interruption: GET /uploads/<id> -> offset, resume from there
             POST /uploads/<id>/complete
rename/move: POST /files/move {from,to,if_match}
delete     : DELETE /files?path=..&recursive=true  + If-Match
folder     : POST /folders {path, parents:true, exist_ok:true}

Conflicts: a write never overwrites anything silently.

  • 412 precondition_failed: the version no longer matches If-Match, or

the target already exists while you sent If-None-Match: *.

  • 409 conflict: the target exists and you sent no If-Match.

Both responses include current, the server's state. The usual approach is to save your local copy under a new name, such as a (conflict from Pixel).txt, and then download the server version. overwrite=true replaces the target on purpose.

Uploads first go to a temporary file. They only become visible after the size and SHA-256 are verified, with an atomic rename. That way other clients never see a half-written file.

Download: GET /files/content?path=.. supports Range/If-Range, which lets an app resume a download, and If-None-Match, which returns 304. The ETag is the version.

Delete is permanent. The file manager has no trash, so ask the user for confirmation before you delete.

5. Errors and limits

Errors are always JSON: {"error": "<code>", "message": "..."}.

StatusCodes
400invalid_path, invalid_request, invalid_cursor, not_a_folder, not_a_file
401invalid_token
403insufficient_scope, forbidden
404not_found. Also returned for paths you are not allowed to see
409conflict, parent_missing, folder_not_empty, offset_mismatch, incomplete
410cursor_expired
412precondition_failed
413too_large
422checksum_mismatch
429too_many_uploads
507quota_exceeded, too_many_entries

The limits are in GET /api/v1/me and can be set in config.json under "api":

KeyDefault
maxUploadBytes10 GB
maxChunkBytes64 MB
maxOpenUploadsPerUser20
uploadTtlHours24
maxHashBytes4 GB
scanIntervalSeconds15
maxSyncEntries500000
uploadDir<app>/api-uploads

The personal-folder quota (userFolderSizeLimit) also applies to the API. The change history is kept for 30 days.

6. Server behind a reverse proxy (for the server admin)

The URLs in the OAuth metadata, the iss parameter, the consent page and the OpenAPI spec (servers, authorizationUrl, tokenUrl) use the server's public address. You set it in config.json:

{
  "publicUrl": "https://files.example.com",
  "trustProxy": "loopback"
}
  • publicUrl is optional. When set, it always wins. A path prefix is

allowed, for example https://example.com/files. Query strings, fragments and credentials are refused, and an invalid value is ignored.

  • trustProxy is used when publicUrl is not set. It is the Express

trust proxy setting and decides from which addresses X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-For are believed. The default is "loopback", which only trusts a proxy on the same machine. Other values:

  • false: never trust them.
  • A number of hops.
  • An IP address or subnet list, for example "10.0.0.0/8, loopback".

This setting also determines the client IP that sessions and the login rate limit see.

The proxy has to pass on X-Forwarded-Proto: https and, if the host differs, X-Forwarded-Host. In nginx:

proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

trustProxy is read at startup, while publicUrl takes effect immediately.

7. Example (curl, personal token)

T=fmp_...; H="Authorization: Bearer $T"; S=https://files.example.com/api/v1
curl -H "$H" $S/roots
curl -H "$H" -T notes.txt -H 'If-None-Match: *' "$S/files/content?path=/~/notes.txt"
curl -H "$H" "$S/files/content?path=/~/notes.txt" -o notes.txt
curl -H "$H" "$S/delta?root=~"
Source
1# Filemanager sync API (v1)
2
3This API is for apps that sync files with the file manager: phone apps,
4desktop sync clients, or background services. It covers login with user
5consent, listing, a change feed (delta), upload (including resumable
6uploads for large files), download with Range, folders, move, delete and
7conflict detection.
8
9- Machine-readable spec: [`docs/openapi.json`](openapi.json). A running
10 server also serves it at `/api/v1/openapi.json`.
11- OAuth metadata: `/.well-known/oauth-authorization-server`.
12- Users manage access on **`/apps.html`** ("Connected apps", also in the
13 user menu of the web UI). There they
14 can see every authorised app, device and token, see when each was last
15 used, revoke them, and create personal tokens.
16
17A token can never see more than its user can. Every request goes through
18the same permission checks as the web UI: per-root read/write rights,
19the user's own folder, and admin rights.
20
21## 1. Register your app (once)
22
23An admin registers the app on `/apps.html` under "OAuth clients". You
24provide a name and one or more redirect URIs and get back a `client_id`
25(`fmc_...`). Clients are **public**: there is no client secret, and PKCE
26is mandatory.
27
28These redirect URIs are allowed:
29
30| Kind | Example | Notes |
31|---|---|---|
32| HTTPS | `https://sync.example.com/callback` | Web services |
33| Loopback | `http://127.0.0.1/callback` | Desktop apps. Any port is accepted at runtime (RFC 8252) |
34| Private scheme | `com.example.sync:/callback` | Mobile apps |
35
36## 2. Authorisation (authorization code + PKCE)
37
381. Generate a `code_verifier`: 43–128 characters from `A-Z a-z 0-9 - . _ ~`.
39 Then compute `code_challenge = BASE64URL(SHA256(code_verifier))`.
402. Open the following URL in the system browser:
41
42 ```
43 GET /oauth/authorize?response_type=code
44 &client_id=fmc_...
45 &redirect_uri=com.example.sync:/callback
46 &scope=files:read%20files:write
47 &state=<random>
48 &code_challenge=<challenge>&code_challenge_method=S256
49 &device_name=Tim's%20Pixel
50 ```
51
52 The user sees which app, which device and which permissions are
53 requested. They sign in and click **Allow** or **Deny**.
543. The browser is redirected to `redirect_uri?code=...&state=...&iss=...`.
55 Check that `state` matches the value you sent. The code is valid for
56 10 minutes and works only once. If the user denied access, you get
57 `error=access_denied` instead.
584. Exchange the code for tokens:
59
60 ```
61 POST /oauth/token (application/x-www-form-urlencoded or JSON)
62 grant_type=authorization_code&client_id=fmc_...&code=...
63 &redirect_uri=com.example.sync:/callback&code_verifier=...
64 ```
65
66 ```json
67 {"access_token":"fma_...","token_type":"Bearer","expires_in":3600,
68 "refresh_token":"fmr_...","scope":"files:read files:write","grant_id":"g_..."}
69 ```
70
715. Send `Authorization: Bearer <access_token>` on every API call. An
72 access token is valid for 1 hour. Renew it with
73 `grant_type=refresh_token&client_id=...&refresh_token=...`.
74 **Refresh tokens rotate**: always store the new one. If an old refresh
75 token is used again, the whole grant is revoked, because that points to
76 a stolen token. A refresh token expires after 90 days without use.
776. Logout: `POST /oauth/revoke` with `token=<refresh or access token>`.
78
79Each authorisation is a separate grant, so each device has its own
80tokens, and the user can revoke one device without affecting the others.
81
82**Scopes:** `files:read` lets an app list, read, download and use the
83delta feed. `files:write` lets it upload, create folders, move and delete,
84and always includes `files:read`.
85
86**Personal tokens** (`fmp_...`) for your own scripts are created on
87`/apps.html`. They are used the same way (`Authorization: Bearer`), can
88optionally expire, and can be revoked there.
89
90## 3. Paths and roots
91
92`GET /api/v1/roots` returns the roots the user can see. `~` is always the
93user's own folder. Other roots are the shared folders the user has rights
94to. All paths are virtual and have the form `/<root-id>/<relative path>`,
95for example `/~/Photos/2024/a.jpg` or `/team/report.pdf`. The segments
96`..` and `.`, backslashes and symlinks that leave the root are refused,
97and symlinks are not listed.
98
99Every file or folder (`Entry`) has the following fields:
100
101| Field | Meaning |
102|---|---|
103| `id` | Stable identity. It stays the same across renames and moves on the same disk |
104| `path`, `name`, `type` | `type` is `file` or `folder` |
105| `size`, `mtime`, `mtime_ms` | Size and modification time |
106| `version` | Opaque. It changes on every change and is also the `ETag` |
107| `sha256` | Present when known. Use `GET /files/metadata?path=..&hash=1` to have it computed |
108
109## 4. Sync walkthrough
110
111```text
112# First sync of a root
113GET /api/v1/delta?root=~ -> reset=true, entries(change=exists), cursor, has_more
114GET /api/v1/delta?root=~&cursor=<c> -> repeat while has_more
115store cursor
116
117# Every time after that (poll, e.g. every 30-60 s or when the app comes to the foreground)
118GET /api/v1/delta?root=~&cursor=<c>
119 created -> download (GET /files/content)
120 modified -> download if version differs from your local copy
121 moved -> rename locally old_path -> path (children are implied)
122 deleted -> delete locally (folders: including contents)
123 repeat while has_more, then store the new cursor
124410 cursor_expired -> start over without a cursor and reconcile with local state
125```
126
127The feed sees all changes: those made through the API, through the web
128UI, and directly on disk. Changes from outside the API become visible
129within about 15 seconds (`api.scanIntervalSeconds`). Changes made through
130the API show up right away.
131
132Pushing local changes:
133
134```text
135new file : PUT /files/content?path=/~/a.txt&mtime=<ms> + If-None-Match: *
136changed : PUT /files/content?path=/~/a.txt + If-Match: "<version you last saw>"
137large file : POST /uploads {path,size,sha256,mtime,if_match|if_none_match}
138 PATCH /uploads/<id> (Upload-Offset: n, body = chunk <= max_chunk_bytes) ...
139 on interruption: GET /uploads/<id> -> offset, resume from there
140 POST /uploads/<id>/complete
141rename/move: POST /files/move {from,to,if_match}
142delete : DELETE /files?path=..&recursive=true + If-Match
143folder : POST /folders {path, parents:true, exist_ok:true}
144```
145
146**Conflicts:** a write never overwrites anything silently.
147
148- `412 precondition_failed`: the version no longer matches `If-Match`, or
149 the target already exists while you sent `If-None-Match: *`.
150- `409 conflict`: the target exists and you sent no `If-Match`.
151
152Both responses include `current`, the server's state. The usual approach
153is to save your local copy under a new name, such as
154`a (conflict from Pixel).txt`, and then download the server version.
155`overwrite=true` replaces the target on purpose.
156
157Uploads first go to a temporary file. They only become visible after
158the size and SHA-256 are verified, with an atomic rename. That way other
159clients never see a half-written file.
160
161**Download:** `GET /files/content?path=..` supports `Range`/`If-Range`,
162which lets an app resume a download, and `If-None-Match`, which returns
163304. The `ETag` is the `version`.
164
165**Delete is permanent.** The file manager has no trash, so ask the user
166for confirmation before you delete.
167
168## 5. Errors and limits
169
170Errors are always JSON: `{"error": "<code>", "message": "..."}`.
171
172| Status | Codes |
173|---|---|
174| 400 | `invalid_path`, `invalid_request`, `invalid_cursor`, `not_a_folder`, `not_a_file` |
175| 401 | `invalid_token` |
176| 403 | `insufficient_scope`, `forbidden` |
177| 404 | `not_found`. Also returned for paths you are not allowed to see |
178| 409 | `conflict`, `parent_missing`, `folder_not_empty`, `offset_mismatch`, `incomplete` |
179| 410 | `cursor_expired` |
180| 412 | `precondition_failed` |
181| 413 | `too_large` |
182| 422 | `checksum_mismatch` |
183| 429 | `too_many_uploads` |
184| 507 | `quota_exceeded`, `too_many_entries` |
185
186The limits are in `GET /api/v1/me` and can be set in `config.json` under
187`"api"`:
188
189| Key | Default |
190|---|---|
191| `maxUploadBytes` | 10 GB |
192| `maxChunkBytes` | 64 MB |
193| `maxOpenUploadsPerUser` | 20 |
194| `uploadTtlHours` | 24 |
195| `maxHashBytes` | 4 GB |
196| `scanIntervalSeconds` | 15 |
197| `maxSyncEntries` | 500000 |
198| `uploadDir` | `<app>/api-uploads` |
199
200The personal-folder quota (`userFolderSizeLimit`) also applies to the
201API. The change history is kept for 30 days.
202
203## 6. Server behind a reverse proxy (for the server admin)
204
205The URLs in the OAuth metadata, the `iss` parameter, the consent page and
206the OpenAPI spec (`servers`, `authorizationUrl`, `tokenUrl`) use the
207server's public address. You set it in `config.json`:
208
209```json
210{
211 "publicUrl": "https://files.example.com",
212 "trustProxy": "loopback"
213}
214```
215
216- **`publicUrl`** is optional. When set, it always wins. A path prefix is
217 allowed, for example `https://example.com/files`. Query strings,
218 fragments and credentials are refused, and an invalid value is ignored.
219- **`trustProxy`** is used when `publicUrl` is not set. It is the Express
220 `trust proxy` setting and decides from which addresses
221 `X-Forwarded-Proto`, `X-Forwarded-Host` and `X-Forwarded-For` are
222 believed. The default is `"loopback"`, which only trusts a proxy on the
223 same machine. Other values:
224 - `false`: never trust them.
225 - A number of hops.
226 - An IP address or subnet list, for example `"10.0.0.0/8, loopback"`.
227
228 This setting also determines the client IP that sessions and the login
229 rate limit see.
230
231The proxy has to pass on `X-Forwarded-Proto: https` and, if the host
232differs, `X-Forwarded-Host`. In nginx:
233
234```nginx
235proxy_set_header Host $host;
236proxy_set_header X-Forwarded-Proto $scheme;
237proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
238```
239
240`trustProxy` is read at startup, while `publicUrl` takes effect
241immediately.
242
243## 7. Example (curl, personal token)
244
245```bash
246T=fmp_...; H="Authorization: Bearer $T"; S=https://files.example.com/api/v1
247curl -H "$H" $S/roots
248curl -H "$H" -T notes.txt -H 'If-None-Match: *' "$S/files/content?path=/~/notes.txt"
249curl -H "$H" "$S/files/content?path=/~/notes.txt" -o notes.txt
250curl -H "$H" "$S/delta?root=~"
251```