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.
- Machine-readable spec:
docs/openapi.json. A running
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:
| Kind | Example | Notes |
|---|---|---|
| HTTPS | https://sync.example.com/callback | Web services |
| Loopback | http://127.0.0.1/callback | Desktop apps. Any port is accepted at runtime (RFC 8252) |
| Private scheme | com.example.sync:/callback | Mobile 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:
| Field | Meaning |
|---|---|
id | Stable identity. It stays the same across renames and moves on the same disk |
path, name, type | type is file or folder |
size, mtime, mtime_ms | Size and modification time |
version | Opaque. It changes on every change and is also the ETag |
sha256 | Present 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 matchesIf-Match, or
the target already exists while you sent If-None-Match: *.
409 conflict: the target exists and you sent noIf-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": "..."}.
| Status | Codes |
|---|---|
| 400 | invalid_path, invalid_request, invalid_cursor, not_a_folder, not_a_file |
| 401 | invalid_token |
| 403 | insufficient_scope, forbidden |
| 404 | not_found. Also returned for paths you are not allowed to see |
| 409 | conflict, parent_missing, folder_not_empty, offset_mismatch, incomplete |
| 410 | cursor_expired |
| 412 | precondition_failed |
| 413 | too_large |
| 422 | checksum_mismatch |
| 429 | too_many_uploads |
| 507 | quota_exceeded, too_many_entries |
The limits are in GET /api/v1/me and can be set in config.json under "api":
| Key | Default |
|---|---|
maxUploadBytes | 10 GB |
maxChunkBytes | 64 MB |
maxOpenUploadsPerUser | 20 |
uploadTtlHours | 24 |
maxHashBytes | 4 GB |
scanIntervalSeconds | 15 |
maxSyncEntries | 500000 |
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"
}
publicUrlis 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.
trustProxyis used whenpublicUrlis 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 | |
| 3 | This API is for apps that sync files with the file manager: phone apps, |
| 4 | desktop sync clients, or background services. It covers login with user |
| 5 | consent, listing, a change feed (delta), upload (including resumable |
| 6 | uploads for large files), download with Range, folders, move, delete and |
| 7 | conflict 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 | |
| 17 | A token can never see more than its user can. Every request goes through |
| 18 | the same permission checks as the web UI: per-root read/write rights, |
| 19 | the user's own folder, and admin rights. |
| 20 | |
| 21 | ## 1. Register your app (once) |
| 22 | |
| 23 | An admin registers the app on `/apps.html` under "OAuth clients". You |
| 24 | provide 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 |
| 26 | is mandatory. |
| 27 | |
| 28 | These 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 | |
| 38 | 1. Generate a `code_verifier`: 43–128 characters from `A-Z a-z 0-9 - . _ ~`. |
| 39 | Then compute `code_challenge = BASE64URL(SHA256(code_verifier))`. |
| 40 | 2. 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**. |
| 54 | 3. 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. |
| 58 | 4. 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 | |
| 71 | 5. 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. |
| 77 | 6. Logout: `POST /oauth/revoke` with `token=<refresh or access token>`. |
| 78 | |
| 79 | Each authorisation is a separate grant, so each device has its own |
| 80 | tokens, 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 |
| 83 | delta feed. `files:write` lets it upload, create folders, move and delete, |
| 84 | and 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 |
| 88 | optionally 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 |
| 93 | user's own folder. Other roots are the shared folders the user has rights |
| 94 | to. All paths are virtual and have the form `/<root-id>/<relative path>`, |
| 95 | for example `/~/Photos/2024/a.jpg` or `/team/report.pdf`. The segments |
| 96 | `..` and `.`, backslashes and symlinks that leave the root are refused, |
| 97 | and symlinks are not listed. |
| 98 | |
| 99 | Every 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 |
| 113 | GET /api/v1/delta?root=~ -> reset=true, entries(change=exists), cursor, has_more |
| 114 | GET /api/v1/delta?root=~&cursor=<c> -> repeat while has_more |
| 115 | store cursor |
| 116 | |
| 117 | # Every time after that (poll, e.g. every 30-60 s or when the app comes to the foreground) |
| 118 | GET /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 |
| 124 | 410 cursor_expired -> start over without a cursor and reconcile with local state |
| 125 | ``` |
| 126 | |
| 127 | The feed sees all changes: those made through the API, through the web |
| 128 | UI, and directly on disk. Changes from outside the API become visible |
| 129 | within about 15 seconds (`api.scanIntervalSeconds`). Changes made through |
| 130 | the API show up right away. |
| 131 | |
| 132 | Pushing local changes: |
| 133 | |
| 134 | ```text |
| 135 | new file : PUT /files/content?path=/~/a.txt&mtime=<ms> + If-None-Match: * |
| 136 | changed : PUT /files/content?path=/~/a.txt + If-Match: "<version you last saw>" |
| 137 | large 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 |
| 141 | rename/move: POST /files/move {from,to,if_match} |
| 142 | delete : DELETE /files?path=..&recursive=true + If-Match |
| 143 | folder : 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 | |
| 152 | Both responses include `current`, the server's state. The usual approach |
| 153 | is 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 | |
| 157 | Uploads first go to a temporary file. They only become visible after |
| 158 | the size and SHA-256 are verified, with an atomic rename. That way other |
| 159 | clients never see a half-written file. |
| 160 | |
| 161 | **Download:** `GET /files/content?path=..` supports `Range`/`If-Range`, |
| 162 | which lets an app resume a download, and `If-None-Match`, which returns |
| 163 | 304. The `ETag` is the `version`. |
| 164 | |
| 165 | **Delete is permanent.** The file manager has no trash, so ask the user |
| 166 | for confirmation before you delete. |
| 167 | |
| 168 | ## 5. Errors and limits |
| 169 | |
| 170 | Errors 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 | |
| 186 | The 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 | |
| 200 | The personal-folder quota (`userFolderSizeLimit`) also applies to the |
| 201 | API. The change history is kept for 30 days. |
| 202 | |
| 203 | ## 6. Server behind a reverse proxy (for the server admin) |
| 204 | |
| 205 | The URLs in the OAuth metadata, the `iss` parameter, the consent page and |
| 206 | the OpenAPI spec (`servers`, `authorizationUrl`, `tokenUrl`) use the |
| 207 | server'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 | |
| 231 | The proxy has to pass on `X-Forwarded-Proto: https` and, if the host |
| 232 | differs, `X-Forwarded-Host`. In nginx: |
| 233 | |
| 234 | ```nginx |
| 235 | proxy_set_header Host $host; |
| 236 | proxy_set_header X-Forwarded-Proto $scheme; |
| 237 | proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; |
| 238 | ``` |
| 239 | |
| 240 | `trustProxy` is read at startup, while `publicUrl` takes effect |
| 241 | immediately. |
| 242 | |
| 243 | ## 7. Example (curl, personal token) |
| 244 | |
| 245 | ```bash |
| 246 | T=fmp_...; H="Authorization: Bearer $T"; S=https://files.example.com/api/v1 |
| 247 | curl -H "$H" $S/roots |
| 248 | curl -H "$H" -T notes.txt -H 'If-None-Match: *' "$S/files/content?path=/~/notes.txt" |
| 249 | curl -H "$H" "$S/files/content?path=/~/notes.txt" -o notes.txt |
| 250 | curl -H "$H" "$S/delta?root=~" |
| 251 | ``` |