BlueGit

timfa filemanager

Files

filemanager / docs / api.md

api.md

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