1SYNCTHING-REST-API(7) Syncthing SYNCTHING-REST-API(7)
2
6 syncthing-rest-api - REST API
7 Syncthing exposes a REST interface over HTTP on the GUI port. This is
9 used by the GUI (from Javascript) and can be used by other processes
10 wishing to control Syncthing. In most cases both the input and output
11 data is in JSON format. The interface is subject to change.
12
14 To use the REST API an API key must be set and used. The API key can be
15 generated in the GUI, or set in the configuration/gui/apikey element in
16 the configuration file. To use an API key, set the request header
17 X-API-Key to the API key value. For example, curl -X POST -H
18 "X-API-Key: abc123" http://localhost:8384/rest/... can be used to in‐
19 voke with curl (add -k flag when using HTTPS with a Syncthing generated
20 or self signed certificate).
21
23 GET /rest/system/browse
24 Returns a list of directories matching the path given by the optional
25 parameter current. The path can use patterns as described in Go’s
26 filepath package <https://golang.org/pkg/path/filepath/#Match>. A ‘*’
27 will always be appended to the given path (e.g. /tmp/ matches all its
28 subdirectories). If the option current is not given, filesystem root
29 paths are returned.
30 $ curl -H "X-API-Key: yourkey" localhost:8384/rest/system/browse | json_pp
32 [
33 "/"
34 ]
35 $ curl -H "X-API-Key: yourkey" localhost:8384/rest/system/browse?current=/var/ | json_pp
37 [
38 "/var/backups/",
39 "/var/cache/",
40 "/var/lib/",
41 "/var/local/",
42 "/var/lock/",
43 "/var/log/",
44 "/var/mail/",
45 "/var/opt/",
46 "/var/run/",
47 "/var/spool/",
48 "/var/tmp/"
49 ]
50 $ curl -H "X-API-Key: yourkey" localhost:8384/rest/system/browse?current=/var/*o | json_pp
52 [
53 "/var/local/",
54 "/var/lock/",
55 "/var/log/",
56 "/var/opt/",
57 "/var/spool/"
58 ]
59 GET /rest/system/config
61 Deprecated since version v1.12.0: This endpoint still works as before
62 but is deprecated. Use rest-config instead.
63 Returns the current configuration.
66 {
68 "version": 30,
69 "folders": [
70 {
71 "id": "GXWxf-3zgnU",
72 "label": "MyFolder",
73 "filesystemType": "basic",
74 "path": "...",
75 "type": "sendreceive",
76 "devices": [
77 {
78 "deviceID": "...",
79 "introducedBy": ""
80 }
81 ],
82 "rescanIntervalS": 60,
83 "fsWatcherEnabled": false,
84 "fsWatcherDelayS": 10,
85 "ignorePerms": false,
86 "autoNormalize": true,
87 "minDiskFree": {
88 "value": 1,
89 "unit": "%"
90 },
91 "versioning": {
92 "type": "simple",
93 "params": {
94 "keep": "5"
95 }
96 },
97 "copiers": 0,
98 "pullerMaxPendingKiB": 0,
99 "hashers": 0,
100 "order": "random",
101 "ignoreDelete": false,
102 "scanProgressIntervalS": 0,
103 "pullerPauseS": 0,
104 "maxConflicts": 10,
105 "disableSparseFiles": false,
106 "disableTempIndexes": false,
107 "paused": false,
108 "weakHashThresholdPct": 25,
109 "markerName": ".stfolder",
110 "copyOwnershipFromParent": false,
111 "modTimeWindowS": 0
112 }
113 ],
114 "devices": [
115 {
116 "deviceID": "...",
117 "name": "Laptop",
118 "addresses": [
119 "dynamic",
120 "tcp://192.168.1.2:22000"
121 ],
122 "compression": "metadata",
123 "certName": "",
124 "introducer": false,
125 "skipIntroductionRemovals": false,
126 "introducedBy": "",
127 "paused": false,
128 "allowedNetworks": [],
129 "autoAcceptFolders": false,
130 "maxSendKbps": 0,
131 "maxRecvKbps": 0,
132 "ignoredFolders": [],
133 "maxRequestKiB": 0
134 }
135 ],
136 "gui": {
137 "enabled": true,
138 "address": "127.0.0.1:8384",
139 "user": "Username",
140 "password": "$2a$10$ZFws69T4FlvWwsqeIwL.TOo5zOYqsa/.TxlUnsGYS.j3JvjFTmxo6",
141 "authMode": "static",
142 "useTLS": false,
143 "apiKey": "pGahcht56664QU5eoFQW6szbEG6Ec2Cr",
144 "insecureAdminAccess": false,
145 "theme": "default",
146 "debugging": false,
147 "insecureSkipHostcheck": false,
148 "insecureAllowFrameLoading": false
149 },
150 "ldap": {
151 "address": "",
152 "bindDN": "",
153 "transport": "plain",
154 "insecureSkipVerify": false
155 },
156 "options": {
157 "listenAddresses": [
158 "default"
159 ],
160 "globalAnnounceServers": [
161 "default"
162 ],
163 "globalAnnounceEnabled": true,
164 "localAnnounceEnabled": true,
165 "localAnnouncePort": 21027,
166 "localAnnounceMCAddr": "[ff12::8384]:21027",
167 "maxSendKbps": 0,
168 "maxRecvKbps": 0,
169 "reconnectionIntervalS": 60,
170 "relaysEnabled": true,
171 "relayReconnectIntervalM": 10,
172 "startBrowser": false,
173 "natEnabled": true,
174 "natLeaseMinutes": 60,
175 "natRenewalMinutes": 30,
176 "natTimeoutSeconds": 10,
177 "urAccepted": -1,
178 "urSeen": 2,
179 "urUniqueId": "",
180 "urURL": "https://data.syncthing.net/newdata",
181 "urPostInsecurely": false,
182 "urInitialDelayS": 1800,
183 "restartOnWakeup": true,
184 "autoUpgradeIntervalH": 12,
185 "upgradeToPreReleases": false,
186 "keepTemporariesH": 24,
187 "cacheIgnoredFiles": false,
188 "progressUpdateIntervalS": 5,
189 "limitBandwidthInLan": false,
190 "minHomeDiskFree": {
191 "value": 1,
192 "unit": "%"
193 },
194 "releasesURL": "https://upgrades.syncthing.net/meta.json",
195 "alwaysLocalNets": [],
196 "overwriteRemoteDeviceNamesOnConnect": false,
197 "tempIndexMinBlocks": 10,
198 "unackedNotificationIDs": [],
199 "trafficClass": 0,
200 "defaultFolderPath": "~",
201 "setLowPriority": true,
202 "maxFolderConcurrency": 0,
203 "crURL": "https://crash.syncthing.net/newcrash",
204 "crashReportingEnabled": true,
205 "stunKeepaliveStartS": 180,
206 "stunKeepaliveMinS": 20,
207 "stunServers": [
208 "default"
209 ],
210 "databaseTuning": "auto",
211 "maxConcurrentIncomingRequestKiB": 0
212 },
213 "remoteIgnoredDevices": []
214 }
215 GET /rest/system/config/insync
217 Deprecated since version v1.12.0: This endpoint still works as before
218 but is deprecated. Use rest-config-insync instead.
219 Returns whether the config is in sync, i.e. whether the running config‐
222 uration is the same as that on disk.
223 {
225 "configInSync": true
226 }
227 POST /rest/system/config
229 Deprecated since version v1.12.0: This endpoint still works as before
230 but is deprecated. Use rest-config instead.
231 Post the full contents of the configuration, in the same format as re‐
234 turned by the corresponding GET request. When posting the configuration
235 succeeds, the posted configuration is immediately applied, except for
236 changes that require a restart. Query rest-config-insync to check if a
237 restart is required.
238 This endpoint is the main point to control Syncthing, even if the
240 change only concerns a very small part of the config: The usual work‐
241 flow is to get the config, modify the needed parts and post it again.
242 GET /rest/system/connections
244 NOTE:
245 Return format changed in 0.13.0.
246 Returns the list of configured devices and some metadata associated
248 with them. The list also contains the local device itself as not con‐
249 nected.
250 The connection types are TCP (Client), TCP (Server), Relay (Client) and
252 Relay (Server).
253 {
255 "total" : {
256 "paused" : false,
257 "clientVersion" : "",
258 "at" : "2015-11-07T17:29:47.691637262+01:00",
259 "connected" : false,
260 "inBytesTotal" : 1479,
261 "type" : "",
262 "outBytesTotal" : 1318,
263 "address" : ""
264 },
265 "connections" : {
266 "YZJBJFX-RDBL7WY-6ZGKJ2D-4MJB4E7-ZATSDUY-LD6Y3L3-MLFUYWE-AEMXJAC" : {
267 "connected" : true,
268 "inBytesTotal" : 556,
269 "paused" : false,
270 "at" : "2015-11-07T17:29:47.691548971+01:00",
271 "clientVersion" : "v0.12.1",
272 "address" : "127.0.0.1:22002",
273 "type" : "TCP (Client)",
274 "outBytesTotal" : 550
275 },
276 "DOVII4U-SQEEESM-VZ2CVTC-CJM4YN5-QNV7DCU-5U3ASRL-YVFG6TH-W5DV5AA" : {
277 "outBytesTotal" : 0,
278 "type" : "",
279 "address" : "",
280 "at" : "0001-01-01T00:00:00Z",
281 "clientVersion" : "",
282 "paused" : false,
283 "inBytesTotal" : 0,
284 "connected" : false
285 },
286 "UYGDMA4-TPHOFO5-2VQYDCC-7CWX7XW-INZINQT-LE4B42N-4JUZTSM-IWCSXA4" : {
287 "address" : "",
288 "type" : "",
289 "outBytesTotal" : 0,
290 "connected" : false,
291 "inBytesTotal" : 0,
292 "paused" : false,
293 "at" : "0001-01-01T00:00:00Z",
294 "clientVersion" : ""
295 }
296 }
297 }
298 GET /rest/system/debug
300 New in version 0.12.0.
301 Returns the set of debug facilities and which of them are currently en‐
304 abled.
305 {
307 "enabled": [
308 "beacon"
309 ],
310 "facilities": {
311 "beacon": "Multicast and broadcast discovery",
312 "config": "Configuration loading and saving",
313 "connections": "Connection handling",
314 "db": "The database layer",
315 "dialer": "Dialing connections",
316 "discover": "Remote device discovery",
317 "events": "Event generation and logging",
318 "http": "REST API",
319 "main": "Main package",
320 "model": "The root hub",
321 "protocol": "The BEP protocol",
322 "relay": "Relay connection handling",
323 "scanner": "File change detection and hashing",
324 "stats": "Persistent device and folder statistics",
325 "sync": "Mutexes",
326 "upgrade": "Binary upgrades",
327 "upnp": "UPnP discovery and port mapping",
328 "versioner": "File versioning"
329 }
330 }
331 POST /rest/system/debug
333 New in version 0.12.0.
334 Enables or disables debugging for specified facilities. Give one or
337 both of enable and disable query parameters, with comma separated fa‐
338 cility names. To disable debugging of the beacon and discovery pack‐
339 ages, and enable it for config and db:
340 $ curl -H X-API-Key:abc123 -X POST 'http://localhost:8384/rest/system/debug?disable=beacon,discovery&enable=config,db'
342 GET /rest/system/discovery
344 Returns the contents of the local discovery cache.
345 {
347 "LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q": [
348 "192.162.129.11:22000"
349 ]
350 }
351 POST /rest/system/discovery
353 NOTE:
354 Removed in v0.12.0.
355 Post with the query parameters device and addr to add entries to the
357 discovery cache.
358 curl -X POST http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\&addr=192.162.129.11:22000
360 # Or with the X-API-Key header:
361 curl -X POST --header "X-API-Key: TcE28kVPdtJ8COws1JdM0b2nodj77WeQ" http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\&addr=192.162.129.11:22000
362 POST /rest/system/error/clear
364 Post with empty to body to remove all recent errors.
365 GET /rest/system/error
367 NOTE:
368 Return format changed in 0.12.0.
369 Returns the list of recent errors.
371 {
373 "errors": [
374 {
375 "when": "2014-09-18T12:59:26.549953186+02:00",
376 "message": "This is an error string"
377 }
378 ]
379 }
380 POST /rest/system/error
382 Post with an error message in the body (plain text) to register a new
383 error. The new error will be displayed on any active GUI clients.
384 GET /rest/system/log
386 New in version 0.12.0.
387 Returns the list of recent log entries.
390 {
392 "messages": [
393 {
394 "when": "2014-09-18T12:59:26.549953186+02:00",
395 "message": "This is a log entry"
396 }
397 ]
398 }
399 POST /rest/system/pause
401 Pause the given device or all devices.
402 Takes the optional parameter device (device ID). When omitted, pauses
404 all devices. Returns status 200 and no content upon success, or status
405 500 and a plain text error on failure.
406 GET /rest/system/ping
408 Returns a {"ping": "pong"} object.
409 {
411 "ping": "pong"
412 }
413 POST /rest/system/ping
415 Returns a {"ping": "pong"} object.
416 POST /rest/system/reset
418 Post with empty body to erase the current index database and restart
419 Syncthing. With no query parameters, the entire database is erased from
420 disk. By specifying the folder parameter with a valid folder ID, only
421 information for that folder will be erased:
422 $ curl -X POST -H "X-API-Key: abc123" http://localhost:8384/rest/system/reset?folder=ab1c2-def3g
424 Caution: See -reset-database for .stfolder creation side-effect and
426 caution regarding mountpoints.
427 POST /rest/system/restart
429 Post with empty body to immediately restart Syncthing.
430 POST /rest/system/resume
432 Resume the given device or all devices.
433 Takes the optional parameter device (device ID). When omitted, resumes
435 all devices. Returns status 200 and no content upon success, or status
436 500 and a plain text error on failure.
437 POST /rest/system/shutdown
439 Post with empty body to cause Syncthing to exit and not restart.
440 GET /rest/system/status
442 Returns information about current system status and resource usage. The
443 CPU percent value has been deprecated from the API and will always re‐
444 port 0.
445 {
447 "alloc": 30618136,
448 "connectionServiceStatus": {
449 "dynamic+https://relays.syncthing.net/endpoint": {
450 "error": null,
451 "lanAddresses": [
452 "relay://23.92.71.120:443/?id=53STGR7-YBM6FCX-PAZ2RHM-YPY6OEJ-WYHVZO7-PCKQRCK-PZLTP7T-434XCAD&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=canton7"
453 ],
454 "wanAddresses": [
455 "relay://23.92.71.120:443/?id=53STGR7-YBM6FCX-PAZ2RHM-YPY6OEJ-WYHVZO7-PCKQRCK-PZLTP7T-434XCAD&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=canton7"
456 ]
457 },
458 "tcp://0.0.0.0:22000": {
459 "error": null,
460 "lanAddresses": [
461 "tcp://0.0.0.0:22000"
462 ],
463 "wanAddresses": [
464 "tcp://0.0.0.0:22000"
465 ]
466 }
467 },
468 "cpuPercent": 0,
469 "discoveryEnabled": true,
470 "discoveryErrors": {
471 "global@https://discovery-v4-1.syncthing.net/v2/": "500 Internal Server Error",
472 "global@https://discovery-v4-2.syncthing.net/v2/": "Post https://discovery-v4-2.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)",
473 "global@https://discovery-v4-3.syncthing.net/v2/": "Post https://discovery-v4-3.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)",
474 "global@https://discovery-v6-1.syncthing.net/v2/": "Post https://discovery-v6-1.syncthing.net/v2/: dial tcp [2001:470:28:4d6::5]:443: connect: no route to host",
475 "global@https://discovery-v6-2.syncthing.net/v2/": "Post https://discovery-v6-2.syncthing.net/v2/: dial tcp [2604:a880:800:10::182:a001]:443: connect: no route to host",
476 "global@https://discovery-v6-3.syncthing.net/v2/": "Post https://discovery-v6-3.syncthing.net/v2/: dial tcp [2400:6180:0:d0::d9:d001]:443: connect: no route to host"
477 },
478 "discoveryStatus": {
479 "IPv4 local": {
480 "error": null
481 },
482 "IPv6 local": {
483 "error": null
484 },
485 "global@https://discovery-v4-1.syncthing.net/v2/": {
486 "error": "500 Internal Server Error"
487 },
488 "global@https://discovery-v4-2.syncthing.net/v2/": {
489 "error": "Post https://discovery-v4-2.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)"
490 },
491 "global@https://discovery-v4-3.syncthing.net/v2/": {
492 "error": "Post https://discovery-v4-3.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)"
493 },
494 "global@https://discovery-v6-1.syncthing.net/v2/": {
495 "error": "Post https://discovery-v6-1.syncthing.net/v2/: dial tcp [2001:470:28:4d6::5]:443: connect: no route to host"
496 },
497 "global@https://discovery-v6-2.syncthing.net/v2/": {
498 "error": "Post https://discovery-v6-2.syncthing.net/v2/: dial tcp [2604:a880:800:10::182:a001]:443: connect: no route to host"
499 },
500 "global@https://discovery-v6-3.syncthing.net/v2/": {
501 "error": "Post https://discovery-v6-3.syncthing.net/v2/: dial tcp [2400:6180:0:d0::d9:d001]:443: connect: no route to host"
502 }
503 },
504 "discoveryMethods": 8,
505 "goroutines": 49,
506 "lastDialStatus": {
507 "tcp://10.20.30.40": {
508 "when": "2019-05-16T07:41:23Z",
509 "error": "dial tcp 10.20.30.40:22000: i/o timeout"
510 },
511 "tcp://172.16.33.3:22000": {
512 "when": "2019-05-16T07:40:43Z",
513 "ok": true
514 },
515 "tcp://83.233.120.221:22000": {
516 "when": "2019-05-16T07:41:13Z",
517 "error": "dial tcp 83.233.120.221:22000: connect: connection refused"
518 }
519 },
520 "myID": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2",
521 "pathSeparator": "/",
522 "startTime": "2016-06-06T19:41:43.039284753+02:00",
523 "sys": 42092792,
524 "themes": [
525 "default",
526 "dark"
527 ],
528 "tilde": "/Users/jb",
529 "uptime": 2635
530 }
531 New in version 1.2.0: The lastDialStatus dictionary contains the last
533 error (or null for success) for each peer address that Syncthing has
534 attempted to contact. The connectionServiceStatus entries gained "er‐
535 ror": null attributes where previously there would be no error attri‐
536 bute at all in the success case.
537 New in version 1.18.0: The discoveryStatus dictionary lists all config‐
540 ured discovery methods, not only failed ones like the now deprecated
541 discoveryErrors. Each entry is an object itself (for consistency with
542 other fields), where a null value for the error attribute means the
543 method is running successfully. This effectively deprecates the dis‐
544 coveryMethods attribute as well, which now always matches the number of
545 entries in discoveryStatus.
546 GET /rest/system/upgrade
549 Checks for a possible upgrade and returns an object describing the new‐
550 est version and upgrade possibility.
551 {
553 "latest": "v0.14.47",
554 "majorNewer": false,
555 "newer": true,
556 "running": "v0.14.46"
557 }
558 POST /rest/system/upgrade
560 Perform an upgrade to the newest released version and restart. Does
561 nothing if there is no newer version than currently running.
562 GET /rest/system/version
564 Returns the current Syncthing version information.
565 {
567 "arch": "amd64",
568 "longVersion": "syncthing v0.10.27+3-gea8c3de (go1.4 darwin-amd64 default) jb@syno 2015-03-16 11:01:29 UTC",
569 "os": "darwin",
570 "version": "v0.10.27+3-gea8c3de"
571 }
572
574 Config Endpoints
575 New in version 1.12.0.
576 These endpoints facilitate access and modification of the configuration
579 in a granular way. Config sent to the endpoints must be in the same
580 format as returned by the corresponding GET request. When posting the
581 configuration succeeds, the posted configuration is immediately ap‐
582 plied, except for changes that require a restart. Query
583 /rest/config/restart-required to check if a restart is required.
584 For all endpoints supporting PATCH, it takes the existing config and
586 unmarshals the given JSON object on top of it. This means all child ob‐
587 jects will replace the existing objects, not extend them. For example
588 for RawListenAddresses in options, which is an array of strings, send‐
589 ing {RawListenAddresses: ["tcp://10.0.0.2"]} will replace all existing
590 listen addresses.
591 /rest/config
593 GET returns the entire config and PUT replaces it.
594 /rest/config/restart-required
596 GET returns whether a restart of Syncthing is required for the current
597 config to take effect.
598 /rest/config/folders, /rest/config/devices
600 GET returns all folders respectively devices as an array. PUT takes an
601 array and POST a single object. In both cases if a given folder/device
602 already exists, it’s replaced, otherwise a new one is added.
603 /rest/config/folders/*id*, /rest/config/devices/*id*
605 Put the desired folder- respectively device-ID in place of *id*. GET
606 returns the folder/device for the given ID, PUT replaces the entire
607 config, PATCH replaces only the given child objects and DELETE removes
608 the folder/device.
609 /rest/config/options, /rest/config/ldap, /rest/config/gui
611 GET returns the respective object, PUT replaces the entire object and
612 PATCH replaces only the given child objects.
613
615 Concerns the mesh network structure.
616 DELETE /rest/cluster/pending/devices
618 New in version 1.18.0.
619 Remove records about a pending remote device which tried to connect.
622 Valid values for the device parameter are those from the corresponding
623 /rest/cluster-pending-devices-get endpoint.
624 $ curl -X DELETE -H "X-API-Key: abc123" http://localhost:8384/rest/cluster/pending/devices?device=P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2
626 Returns status 200 and no content upon success, or status 500 and a
628 plain text error on failure. A /events/pendingdeviceschanged event
629 will be generated in response.
630 For a more permanent effect, also for future connections from the same
632 device ID, the device should be ignored in the configuration instead.
633 GET /rest/cluster/pending/devices
635 New in version 1.13.0.
636 Lists remote devices which have tried to connect, but are not yet con‐
639 figured in our instance.
640 {
642 "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
643 "time": "2020-03-18T11:43:07Z",
644 "name": "Friend Joe",
645 "address": "192.168.1.2:22000"
646 }
647 }
648 DELETE /rest/cluster/pending/folders
650 New in version 1.18.0.
651 Remove records about a pending folder announced from a remote device.
654 Valid values for the folder and device parameters are those from the
655 corresponding /rest/cluster-pending-folders-get endpoint. The device
656 parameter is optional and affects announcements of this folder from the
657 given device, or from any device if omitted.
658 $ curl -X DELETE -H "X-API-Key: abc123" http://localhost:8384/rest/cluster/pending/folders?folder=cpkn4-57ysy&device=P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2
660 Returns status 200 and no content upon success, or status 500 and a
662 plain text error on failure. A /events/pendingfolderschanged event
663 will be generated in response.
664 For a more permanent effect, also for future announcements of the same
666 folder ID, the folder should be ignored in the configuration instead.
667 GET /rest/cluster/pending/folders
669 New in version 1.13.0.
670 Lists folders which remote devices have offered to us, but are not yet
673 shared from our instance to them. Takes the optional device parameter
674 to only return folders offered by a specific remote device. Other of‐
675 fering devices are also omitted from the result.
676 {
678 "cpkn4-57ysy": {
679 "offeredBy": {
680 "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
681 "time": "2020-03-18T11:43:07Z",
682 "label": "Joe's folder",
683 "receiveEncrypted": true,
684 "remoteEncrypted": false
685 },
686 "DOVII4U-SQEEESM-VZ2CVTC-CJM4YN5-QNV7DCU-5U3ASRL-YVFG6TH-W5DV5AA": {
687 "time": "2020-03-01T10:12:13Z",
688 "label": "Jane's and Joe's folder",
689 "receiveEncrypted": false,
690 "remoteEncrypted": false
691 }
692 }
693 },
694 "abcde-fghij": {
695 "offeredBy": {
696 "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
697 "time": "2020-03-18T11:43:07Z",
698 "label": "MyPics",
699 "receiveEncrypted": false,
700 "remoteEncrypted": false
701 }
702 }
703 }
704 }
705
707 GET /rest/db/browse
708 Returns the directory tree of the global model. Directories are always
709 JSON objects (map/dictionary), and files are always arrays of modifica‐
710 tion time and size. The first integer is the files modification time,
711 and the second integer is the file size.
712 The call takes one mandatory folder parameter and two optional parame‐
714 ters. Optional parameter levels defines how deep within the tree we
715 want to dwell down (0 based, defaults to unlimited depth) Optional pa‐
716 rameter prefix defines a prefix within the tree where to start building
717 the structure.
718 $ curl -s http://localhost:8384/rest/db/browse?folder=j663y-3ct3e&prefix=DCIM&levels=2
720 [
721 {
722 "modTime" : "2020-10-02T23:48:52.076996974+02:00",
723 "name" : "100ANDRO",
724 "size" : 128,
725 "type" : "FILE_INFO_TYPE_DIRECTORY"
726 },
727 {
728 "children" : [
729 {
730 "modTime" : "2020-12-16T23:31:34.5009668+01:00",
731 "name" : "IMG_20201114_124821.jpg",
732 "size" : 10682189,
733 "type" : "FILE_INFO_TYPE_FILE"
734 },
735 {
736 "modTime" : "2020-12-16T23:31:35.0106367+01:00",
737 "name" : "IMG_20201213_122451.jpg",
738 "size" : 7936351,
739 "type" : "FILE_INFO_TYPE_FILE"
740 },
741 {
742 "modTime" : "2020-12-13T12:25:05.017097469+01:00",
743 "name" : "IMG_20201213_122504.jpg",
744 "size" : 8406507,
745 "type" : "FILE_INFO_TYPE_FILE"
746 },
747 {
748 "modTime" : "2020-12-13T12:25:06.127097469+01:00",
749 "name" : "IMG_20201213_122505.jpg",
750 "size" : 8381931,
751 "type" : "FILE_INFO_TYPE_FILE"
752 },
753 {
754 "modTime" : "2020-12-13T12:53:29.707298401+01:00",
755 "name" : "IMG_20201213_125329.jpg",
756 "size" : 4388331,
757 "type" : "FILE_INFO_TYPE_FILE"
758 },
759 ],
760 "modTime" : "2020-10-09T13:04:42.4410738+02:00",
761 "name" : "Camera",
762 "size" : 128,
763 "type" : "FILE_INFO_TYPE_DIRECTORY"
764 },
765 ]
766 NOTE:
768 This is an expensive call, increasing CPU and RAM usage on the de‐
769 vice. Use sparingly.
770 GET /rest/db/completion
772 Returns the completion percentage (0 to 100) and byte / item counts.
773 Takes optional device and folder parameters:
774 • folder specifies the folder ID to calculate completion for. An empty
776 or absent folder parameter means all folders as an aggregate.
777 • device specifies the device ID to calculate completion for. An empty
779 or absent device parameter means the local device.
780 If a device is specified but no folder, completion is calculated for
782 all folders shared with that device.
783 Example Queries
785 Completion status for folder abcd-1234 on device I6KAH76-...-3PSROAU:
786 /rest/db/completion?folder=abcd-1234&device=I6KAH76-...-3PSROAU
788 Aggregated completion status for device I6KAH76-...-3PSROAU (all fold‐
790 ers shared with them):
791 /rest/db/completion?device=I6KAH76-...-3PSROAU
793 Completion status for folder abcd-1234 on the local device:
795 /rest/db/completion?folder=abcd-1234
797 Aggregated completion status for all folders on the local device:
799 /rest/db/completion
801 Example Response
803 {
804 "completion": 99.9937565835,
805 "globalBytes": 156793013575,
806 "needBytes": 9789241,
807 "globalItems": 7823,
808 "needItems": 412,
809 "needDeletes": 0
810 }
811 New in version 1.8.0: The ability to aggregate multiple folders by
813 leaving out the folder ID. Querying data for the local device by leav‐
814 ing out the device ID. Returning the globalItems counter in the re‐
815 sponse.
816 GET /rest/db/file
819 Returns most data available about a given file, including version and
820 availability. Takes folder and file parameters.
821 {
823 "availability": [
824 {
825 "id": "ITZRNXE-YNROGBZ-HXTH5P7-VK5NYE5-QHRQGE2-7JQ6VNJ-KZUEDIU-5PPR5AM",
826 "fromTemporary": false
827 }
828 ],
829 "global": {
830 "deleted": false,
831 "ignored": false,
832 "invalid": false,
833 "localFlags": 0,
834 "modified": "2018-08-18T12:21:13.836784059+02:00",
835 "modifiedBy": "SYNO4VL",
836 "mustRescan": false,
837 "name": "testfile",
838 "noPermissions": false,
839 "numBlocks": 1,
840 "permissions": "0755",
841 "sequence": 107499,
842 "size": 1234,
843 "type": 0,
844 "version": [
845 "SYNO4VL:1"
846 ]
847 },
848 "local": {
849 "deleted": false,
850 "ignored": false,
851 "invalid": false,
852 "localFlags": 0,
853 "modified": "2018-08-18T12:21:13.836784059+02:00",
854 "modifiedBy": "SYNO4VL",
855 "mustRescan": false,
856 "name": "testfile",
857 "noPermissions": false,
858 "numBlocks": 1,
859 "permissions": "0755",
860 "sequence": 111038,
861 "size": 1234,
862 "type": 0,
863 "version": [
864 "SYNO4VL:1"
865 ]
866 }
867 }
868 GET /rest/db/ignores
870 Takes one parameter, folder, and returns the content of the .stignore
871 as the ignore field. A second field, expanded, provides a list of
872 strings which represent globbing patterns described by gobwas/glob
873 (based on standard wildcards) that match the patterns in .stignore and
874 all the includes. If appropriate these globs are prepended by the fol‐
875 lowing modifiers: ! to negate the glob, (?i) to do case insensitive
876 matching and (?d) to enable removing of ignored files in an otherwise
877 empty directory.
878 {
880 "ignore": [
881 "(?i)/Backups"
882 ],
883 "expanded": [
884 "(?i)Backups",
885 "(?i)Backups/**"
886 ]
887 }
888 POST /rest/db/ignores
890 Expects a format similar to the output of GET call, but only containing
891 the ignore field (expanded field should be omitted). It takes one pa‐
892 rameter, folder, and either updates the content of the .stignore echo‐
893 ing it back as a response, or returns an error.
894 GET /rest/db/need
896 Takes one mandatory parameter, folder, and returns lists of files which
897 are needed by this device in order for it to become in sync.
898 Furthermore takes an optional page and perpage arguments for pagina‐
900 tion. Pagination happens, across the union of all needed files, that
901 is - across all 3 sections of the response. For example, given the
902 current need state is as follows:
903 1. progress has 15 items
905 2. queued has 3 items
907 3. rest has 12 items
909 If you issue a query with page=1 and perpage=10, only the progress sec‐
911 tion in the response will have 10 items. If you issue a request query
912 with page=2 and perpage=10, progress section will have the last 5
913 items, queued section will have all 3 items, and rest section will have
914 first 2 items. If you issue a query for page=3 and perpage=10, you will
915 only have the last 10 items of the rest section.
916 In all these calls, total will be 30 to indicate the total number of
918 available items.
919 {
921 # Files currently being downloaded
922 "progress": [
923 {
924 "flags": "0755",
925 "sequence": 6,
926 "modified": "2015-04-20T23:06:12+09:00",
927 "name": "ls",
928 "size": 34640,
929 "version": [
930 "5157751870738175669:1"
931 ]
932 }
933 ],
934 # Files queued to be downloaded next (as per array order)
935 "queued": [
936 ...
937 ],
938 # Files to be downloaded after all queued files will be downloaded.
939 # This happens when we start downloading files, and new files get added while we are downloading.
940 "rest": [
941 ...
942 ],
943 "page": 1,
944 "perpage": 100,
945 "total": 2000
946 }
947 NOTE:
949 This is an expensive call, increasing CPU and RAM usage on the de‐
950 vice. Use sparingly.
951 POST /rest/db/override
953 Request override of a send only folder. Override means to make the lo‐
954 cal version latest, overriding changes made on other devices. This API
955 call does nothing if the folder is not a send only folder.
956 Takes the mandatory parameter folder (folder ID).
958 curl -X POST -H X-API-key:... http://127.0.0.1:8384/rest/db/override?folder=default
960 POST /rest/db/prio
962 Moves the file to the top of the download queue.
963 curl -X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
965 Response contains the same output as GET /rest/db/need
967 POST /rest/db/revert
969 New in version 0.14.50.
970 Request revert of a receive only folder. Reverting a folder means to
973 undo all local changes. This API call does nothing if the folder is not
974 a receive only folder.
975 Takes the mandatory parameter folder (folder ID).
977 curl -X POST -H X-API-Key:... http://127.0.0.1:8384/rest/db/revert?folder=default
979 POST /rest/db/scan
981 Request immediate scan. Takes the optional parameters folder (folder
982 ID), sub (path relative to the folder root) and next (time in seconds).
983 If folder is omitted or empty all folders are scanned. If sub is given,
984 only this path (and children, in case it’s a directory) is scanned. The
985 next argument delays Syncthing’s automated rescan interval for a given
986 amount of seconds.
987 Requesting scan of a path that no longer exists, but previously did, is
989 valid and will result in Syncthing noticing the deletion of the path in
990 question.
991 Returns status 200 and no content upon success, or status 500 and a
993 plain text error if an error occurred during scanning.
994 curl -X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar
996 GET /rest/db/status
998 Returns information about the current status of a folder.
999 Parameters: folder, the ID of a folder.
1001 {
1003 "globalBytes": 0,
1004 "globalDeleted": 0,
1005 "globalDirectories": 0,
1006 "globalFiles": 0,
1007 "globalSymlinks": 0,
1008 "globalTotalItems": 0,
1009 "ignorePatterns": false,
1010 "inSyncBytes": 0,
1011 "inSyncFiles": 0,
1012 "invalid": "",
1013 "localBytes": 0,
1014 "localDeleted": 0,
1015 "localDirectories": 0,
1016 "localFiles": 0,
1017 "localSymlinks": 0,
1018 "localTotalItems": 0,
1019 "needBytes": 0,
1020 "needDeletes": 0,
1021 "needDirectories": 0,
1022 "needFiles": 0,
1023 "needSymlinks": 0,
1024 "needTotalItems": 0,
1025 "pullErrors": 0,
1026 "receiveOnlyChangedBytes": 0,
1027 "receiveOnlyChangedDeletes": 0,
1028 "receiveOnlyChangedDirectories": 0,
1029 "receiveOnlyChangedFiles": 0,
1030 "receiveOnlyChangedSymlinks": 0,
1031 "receiveOnlyTotalItems": 0,
1032 "sequence": 0,
1033 "state": "idle",
1034 "stateChanged": "2018-08-08T07:04:57.301064781+02:00",
1035 "version": 0
1036 }
1037 The various fields have the following meaning:
1039 global*:
1041 Data in the cluster latest version.
1042 inSync*:
1044 Data that is locally the same as the cluster latest version.
1045 local*:
1047 Data that is locally present, regardless of whether it’s the
1048 same or different version as the cluster latest version.
1049 need*: Data that is needed to become up to date with the cluster latest
1051 version (i.e., data that is out of sync).
1052 receiveOnlyChanged*:
1054 Data that has changed locally in a receive only folder, and thus
1055 not been sent to the cluster.
1056 invalid:
1058 Deprecated, always empty.
1059 pullErrors:
1061 The number of files that failed to sync during the last sync op‐
1062 erations.
1063 sequence:
1065 The current folder sequence number.
1066 state: The current folder state.
1068 stateChanged:
1070 When the folder state last changed.
1071 version:
1073 Deprecated, equivalent to the sequence number.
1074 NOTE:
1076 This is an expensive call, increasing CPU and RAM usage on the de‐
1077 vice. Use sparingly.
1078
1080 GET /rest/events
1081 To receive events, perform a HTTP GET of /rest/events.
1082 To filter the event list, in effect creating a specific subscription
1084 for only the desired event types, add a parameter events=EventTy‐
1085 peA,EventTypeB,... where the event types are any of the event-types.
1086 The optional parameter since=<lastSeenID> sets the ID of the last event
1088 you’ve already seen. Syncthing returns a JSON encoded array of event
1089 objects, starting at the event just after the one with this last seen
1090 ID. The default value is 0, which returns all events. There is a limit
1091 to the number of events buffered, so if the rate of events is high or
1092 the time between polling calls is long some events might be missed.
1093 This can be detected by noting a discontinuity in the event IDs.
1094 If no new events are produced since <lastSeenID>, the HTTP call blocks
1096 and waits for new events to happen before returning. By default it
1097 times out after 60 seconds returning an empty array. The time out dura‐
1098 tion can be customized with the optional parameter timeout=<seconds>.
1099 To receive only a limited number of events, add the limit=<n> parameter
1101 with a suitable value for n and only the last n events will be re‐
1102 turned. This can be used to catch up with the latest event ID after a
1103 disconnection for example: /rest/events?since=0&limit=1.
1104
1106 GET /rest/stats/device
1107 Returns general statistics about devices. Currently, only contains the
1108 time the device was last seen.
1109 $ curl -s http://localhost:8384/rest/stats/device | json
1111 {
1112 "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
1113 "lastSeen" : "2015-04-18T11:21:31.3256277+01:00"
1114 }
1115 }
1116 GET /rest/stats/folder
1118 Returns general statistics about folders. Currently contains the last
1119 scan time and the last synced file.
1120 $ curl -s http://localhost:8384/rest/stats/folder | json
1122 {
1123 "folderid" : {
1124 "lastScan": "2016-06-02T13:28:01.288181412-04:00",
1125 "lastFile" : {
1126 "filename" : "file/name",
1127 "at" : "2015-04-16T22:04:18.3066971+01:00"
1128 }
1129 }
1130 }
1131
1133 GET /rest/svc/deviceid
1134 Verifies and formats a device ID. Accepts all currently valid formats
1135 (52 or 56 characters with or without separators, upper or lower case,
1136 with trivial substitutions). Takes one parameter, id, and returns ei‐
1137 ther a valid device ID in modern format, or an error.
1138 $ curl -s http://localhost:8384/rest/svc/deviceid?id=1234 | json
1140 {
1141 "error": "device ID invalid: incorrect length"
1142 }
1143 $ curl -s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m--zjnu2iq-gdr-eydm-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json
1145 {
1146 "id": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2"
1147 }
1148 GET /rest/svc/lang
1150 Returns a list of canonicalized localization codes, as picked up from
1151 the Accept-Language header sent by the browser.
1152 ["sv_sv","sv","en_us","en"]
1154 GET /rest/svc/random/string
1156 Returns a strong random generated string (alphanumeric) of the speci‐
1157 fied length. Takes the length parameter.
1158 {
1160 "random": "FdPaEaZQ56sXEKYNxpgF"
1161 }
1162 GET /rest/svc/report
1164 Returns the data sent in the anonymous usage report.
1165 {
1167 "folderMaxMiB" : 0,
1168 "platform" : "linux-amd64",
1169 "totMiB" : 0,
1170 "longVersion" : "syncthing v0.12.2 \"Beryllium Bedbug\" (go1.4.3 linux-amd64 default) unknown-user@build2.syncthing.net 2015-11-09 13:23:26 UTC",
1171 "upgradeAllowedManual" : true,
1172 "totFiles" : 3,
1173 "folderUses" : {
1174 "ignorePerms" : 0,
1175 "autoNormalize" : 0,
1176 "sendonly" : 0,
1177 "ignoreDelete" : 0
1178 },
1179 "memoryUsageMiB" : 13,
1180 "version" : "v0.12.2",
1181 "sha256Perf" : 27.28,
1182 "numFolders" : 2,
1183 "memorySize" : 1992,
1184 "announce" : {
1185 "defaultServersIP" : 0,
1186 "otherServers" : 0,
1187 "globalEnabled" : false,
1188 "defaultServersDNS" : 1,
1189 "localEnabled" : false
1190 },
1191 "usesRateLimit" : false,
1192 "numCPU" : 2,
1193 "uniqueID" : "",
1194 "urVersion" : 2,
1195 "rescanIntvs" : [
1196 60,
1197 60
1198 ],
1199 "numDevices" : 2,
1200 "folderMaxFiles" : 3,
1201 "relays" : {
1202 "defaultServers" : 1,
1203 "enabled" : true,
1204 "otherServers" : 0
1205 },
1206 "deviceUses" : {
1207 "compressMetadata" : 1,
1208 "customCertName" : 0,
1209 "staticAddr" : 1,
1210 "compressAlways" : 0,
1211 "compressNever" : 1,
1212 "introducer" : 0,
1213 "dynamicAddr" : 1
1214 },
1215 "upgradeAllowedAuto" : false
1216 }
1217
1219 The Syncthing Authors
1220
1222 2014-2019, The Syncthing Authors
1223v1 Oct 17, 2021 SYNCTHING-REST-API(7)