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=default
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 "discoveryMethods": 8,
479 "goroutines": 49,
480 "lastDialStatus": {
481 "tcp://10.20.30.40": {
482 "when": "2019-05-16T07:41:23Z",
483 "error": "dial tcp 10.20.30.40:22000: i/o timeout"
484 },
485 "tcp://172.16.33.3:22000": {
486 "when": "2019-05-16T07:40:43Z",
487 "ok": true
488 },
489 "tcp://83.233.120.221:22000": {
490 "when": "2019-05-16T07:41:13Z",
491 "error": "dial tcp 83.233.120.221:22000: connect: connection refused"
492 }
493 },
494 "myID": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2",
495 "pathSeparator": "/",
496 "startTime": "2016-06-06T19:41:43.039284753+02:00",
497 "sys": 42092792,
498 "themes": [
499 "default",
500 "dark"
501 ],
502 "tilde": "/Users/jb",
503 "uptime": 2635
504 }
505 New in version 1.2.0: The lastDialStatus dictionary contains the last
507 error (or null for success) for each peer address that Syncthing has
508 attempted to contact. The connectionServiceStatus entries gained "er‐
509 ror": null attributes where previously there would be no error attri‐
510 bute at all in the success case.
511 GET /rest/system/upgrade
514 Checks for a possible upgrade and returns an object describing the new‐
515 est version and upgrade possibility.
516 {
518 "latest": "v0.14.47",
519 "majorNewer": false,
520 "newer": true,
521 "running": "v0.14.46"
522 }
523 POST /rest/system/upgrade
525 Perform an upgrade to the newest released version and restart. Does
526 nothing if there is no newer version than currently running.
527 GET /rest/system/version
529 Returns the current Syncthing version information.
530 {
532 "arch": "amd64",
533 "longVersion": "syncthing v0.10.27+3-gea8c3de (go1.4 darwin-amd64 default) jb@syno 2015-03-16 11:01:29 UTC",
534 "os": "darwin",
535 "version": "v0.10.27+3-gea8c3de"
536 }
537
539 Config Endpoints
540 New in version 1.12.0.
541 These endpoints facilitate access and modification of the configuration
544 in a granular way. Config sent to the endpoints must be in the same
545 format as returned by the corresponding GET request. When posting the
546 configuration succeeds, the posted configuration is immediately ap‐
547 plied, except for changes that require a restart. Query
548 /rest/system/config/insync to check if a restart is required.
549 For all endpoints supporting PATCH, it takes the existing config and
551 unmarshals the given JSON object on top of it. This means all child ob‐
552 jects will replace the existing objects, not extend them. For example
553 for RawListenAddresses in options, which is an array of strings, send‐
554 ing {RawListenAddresses: ["tcp://10.0.0.2"]} will replace all existing
555 listen addresses.
556 /rest/config
558 GET returns the entire config and PUT replaces it.
559 /rest/system/config/insync
561 GET returns whether the config is in sync, i.e. whether the running
562 configuration is the same as that on disk or if a restart is required.
563 /rest/config/folders, /rest/config/devices
565 GET returns all folders respectively devices as an array. PUT takes an
566 array and POST a single object. In both cases if a given folder/device
567 already exists, it’s replaced, otherwise a new one is added.
568 /rest/config/folders/*id*, /rest/config/devices/*id*
570 Put the desired folder- respectively device-ID in place of *id*. GET
571 returns the folder/device for the given ID, PUT replaces the entire
572 config and PATCH replaces only the given child objects.
573 /rest/config/options, /rest/config/ldap, /rest/config/gui
575 GET returns the respective object, PUT replaces the entire object and
576 PATCH replaces only the given child objects.
577
579 Concerns the mesh network structure.
580 GET /rest/cluster/pending/devices
582 New in version 1.13.0.
583 Lists remote devices which have tried to connect, but are not yet con‐
586 figured in our instance.
587 {
589 "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
590 "time": "2020-03-18T11:43:07Z",
591 "name": "Friend Joe",
592 "address": "192.168.1.2:22000"
593 }
594 }
595 GET /rest/cluster/pending/folders
597 New in version 1.13.0.
598 Lists folders which remote devices have offered to us, but are not yet
601 shared from our instance to them. Takes the optional device parameter
602 to only return folders offered by a specific remote device. Other of‐
603 fering devices are also omitted from the result.
604 {
606 "cpkn4-57ysy": {
607 "offeredBy": {
608 "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
609 "time": "2020-03-18T11:43:07Z",
610 "label": "Joe's folder"
611 },
612 "DOVII4U-SQEEESM-VZ2CVTC-CJM4YN5-QNV7DCU-5U3ASRL-YVFG6TH-W5DV5AA": {
613 "time": "2020-03-01T10:12:13Z",
614 "label": "Jane's and Joe's folder"
615 }
616 }
617 },
618 "abcde-fghij": {
619 "offeredBy": {
620 "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
621 "time": "2020-03-18T11:43:07Z",
622 "label": "MyPics"
623 }
624 }
625 }
626 }
627
629 GET /rest/db/browse
630 Returns the directory tree of the global model. Directories are always
631 JSON objects (map/dictionary), and files are always arrays of modifica‐
632 tion time and size. The first integer is the files modification time,
633 and the second integer is the file size.
634 The call takes one mandatory folder parameter and two optional parame‐
636 ters. Optional parameter levels defines how deep within the tree we
637 want to dwell down (0 based, defaults to unlimited depth) Optional pa‐
638 rameter prefix defines a prefix within the tree where to start building
639 the structure.
640 $ curl -s http://localhost:8384/rest/db/browse?folder=j663y-3ct3e&prefix=DCIM&levels=2
642 [
643 {
644 "modTime" : "2020-10-02T23:48:52.076996974+02:00",
645 "name" : "100ANDRO",
646 "size" : 128,
647 "type" : "FILE_INFO_TYPE_DIRECTORY"
648 },
649 {
650 "children" : [
651 {
652 "modTime" : "2020-12-16T23:31:34.5009668+01:00",
653 "name" : "IMG_20201114_124821.jpg",
654 "size" : 10682189,
655 "type" : "FILE_INFO_TYPE_FILE"
656 },
657 {
658 "modTime" : "2020-12-16T23:31:35.0106367+01:00",
659 "name" : "IMG_20201213_122451.jpg",
660 "size" : 7936351,
661 "type" : "FILE_INFO_TYPE_FILE"
662 },
663 {
664 "modTime" : "2020-12-13T12:25:05.017097469+01:00",
665 "name" : "IMG_20201213_122504.jpg",
666 "size" : 8406507,
667 "type" : "FILE_INFO_TYPE_FILE"
668 },
669 {
670 "modTime" : "2020-12-13T12:25:06.127097469+01:00",
671 "name" : "IMG_20201213_122505.jpg",
672 "size" : 8381931,
673 "type" : "FILE_INFO_TYPE_FILE"
674 },
675 {
676 "modTime" : "2020-12-13T12:53:29.707298401+01:00",
677 "name" : "IMG_20201213_125329.jpg",
678 "size" : 4388331,
679 "type" : "FILE_INFO_TYPE_FILE"
680 },
681 ],
682 "modTime" : "2020-10-09T13:04:42.4410738+02:00",
683 "name" : "Camera",
684 "size" : 128,
685 "type" : "FILE_INFO_TYPE_DIRECTORY"
686 },
687 ]
688 NOTE:
690 This is an expensive call, increasing CPU and RAM usage on the de‐
691 vice. Use sparingly.
692 GET /rest/db/completion
694 Returns the completion percentage (0 to 100) and byte / item counts.
695 Takes optional device and folder parameters:
696 • folder specifies the folder ID to calculate completion for. An empty
698 or absent folder parameter means all folders as an aggregate.
699 • device specifies the device ID to calculate completion for. An empty
701 or absent device parameter means the local device.
702 If a device is specified but no folder, completion is calculated for
704 all folders shared with that device.
705 Example Queries
707 Completion status for folder abcd-1234 on device I6KAH76-...-3PSROAU:
708 /rest/db/completion?folder=abcd-1234&device=I6KAH76-...-3PSROAU
710 Aggregated completion status for device I6KAH76-...-3PSROAU (all fold‐
712 ers shared with them):
713 /rest/db/completion?device=I6KAH76-...-3PSROAU
715 Completion status for folder abcd-1234 on the local device:
717 /rest/db/completion?folder=abcd-1234
719 Aggregated completion status for all folders on the local device:
721 /rest/db/completion
723 Example Response
725 {
726 "completion": 99.9937565835,
727 "globalBytes": 156793013575,
728 "needBytes": 9789241,
729 "globalItems": 7823,
730 "needItems": 412,
731 "needDeletes": 0
732 }
733 New in version 1.8.0: The ability to aggregate multiple folders by
735 leaving out the folder ID. Querying data for the local device by leav‐
736 ing out the device ID. Returning the globalItems counter in the re‐
737 sponse.
738 GET /rest/db/file
741 Returns most data available about a given file, including version and
742 availability. Takes folder and file parameters.
743 {
745 "availability": [
746 {
747 "id": "ITZRNXE-YNROGBZ-HXTH5P7-VK5NYE5-QHRQGE2-7JQ6VNJ-KZUEDIU-5PPR5AM",
748 "fromTemporary": false
749 }
750 ],
751 "global": {
752 "deleted": false,
753 "ignored": false,
754 "invalid": false,
755 "localFlags": 0,
756 "modified": "2018-08-18T12:21:13.836784059+02:00",
757 "modifiedBy": "SYNO4VL",
758 "mustRescan": false,
759 "name": "testfile",
760 "noPermissions": false,
761 "numBlocks": 1,
762 "permissions": "0755",
763 "sequence": 107499,
764 "size": 1234,
765 "type": 0,
766 "version": [
767 "SYNO4VL:1"
768 ]
769 },
770 "local": {
771 "deleted": false,
772 "ignored": false,
773 "invalid": false,
774 "localFlags": 0,
775 "modified": "2018-08-18T12:21:13.836784059+02:00",
776 "modifiedBy": "SYNO4VL",
777 "mustRescan": false,
778 "name": "testfile",
779 "noPermissions": false,
780 "numBlocks": 1,
781 "permissions": "0755",
782 "sequence": 111038,
783 "size": 1234,
784 "type": 0,
785 "version": [
786 "SYNO4VL:1"
787 ]
788 }
789 }
790 GET /rest/db/ignores
792 Takes one parameter, folder, and returns the content of the .stignore
793 as the ignore field. A second field, expanded, provides a list of
794 strings which represent globbing patterns described by gobwas/glob
795 (based on standard wildcards) that match the patterns in .stignore and
796 all the includes. If appropriate these globs are prepended by the fol‐
797 lowing modifiers: ! to negate the glob, (?i) to do case insensitive
798 matching and (?d) to enable removing of ignored files in an otherwise
799 empty directory.
800 {
802 "ignore": [
803 "(?i)/Backups"
804 ],
805 "expanded": [
806 "(?i)Backups",
807 "(?i)Backups/**"
808 ]
809 }
810 POST /rest/db/ignores
812 Expects a format similar to the output of GET call, but only containing
813 the ignore field (expanded field should be omitted). It takes one pa‐
814 rameter, folder, and either updates the content of the .stignore echo‐
815 ing it back as a response, or returns an error.
816 GET /rest/db/need
818 Takes one mandatory parameter, folder, and returns lists of files which
819 are needed by this device in order for it to become in sync.
820 Furthermore takes an optional page and perpage arguments for pagina‐
822 tion. Pagination happens, across the union of all needed files, that
823 is - across all 3 sections of the response. For example, given the
824 current need state is as follows:
825 1. progress has 15 items
827 2. queued has 3 items
829 3. rest has 12 items
831 If you issue a query with page=1 and perpage=10, only the progress sec‐
833 tion in the response will have 10 items. If you issue a request query
834 with page=2 and perpage=10, progress section will have the last 5
835 items, queued section will have all 3 items, and rest section will have
836 first 2 items. If you issue a query for page=3 and perpage=10, you will
837 only have the last 10 items of the rest section.
838 In all these calls, total will be 30 to indicate the total number of
840 available items.
841 {
843 # Files currently being downloaded
844 "progress": [
845 {
846 "flags": "0755",
847 "sequence": 6,
848 "modified": "2015-04-20T23:06:12+09:00",
849 "name": "ls",
850 "size": 34640,
851 "version": [
852 "5157751870738175669:1"
853 ]
854 }
855 ],
856 # Files queued to be downloaded next (as per array order)
857 "queued": [
858 ...
859 ],
860 # Files to be downloaded after all queued files will be downloaded.
861 # This happens when we start downloading files, and new files get added while we are downloading.
862 "rest": [
863 ...
864 ],
865 "page": 1,
866 "perpage": 100,
867 "total": 2000
868 }
869 NOTE:
871 This is an expensive call, increasing CPU and RAM usage on the de‐
872 vice. Use sparingly.
873 POST /rest/db/override
875 Request override of a send only folder. Override means to make the lo‐
876 cal version latest, overriding changes made on other devices. This API
877 call does nothing if the folder is not a send only folder.
878 Takes the mandatory parameter folder (folder ID).
880 curl -X POST -H X-API-key:... http://127.0.0.1:8384/rest/db/override?folder=default
882 POST /rest/db/prio
884 Moves the file to the top of the download queue.
885 curl -X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
887 Response contains the same output as GET /rest/db/need
889 POST /rest/db/revert
891 New in version 0.14.50.
892 Request revert of a receive only folder. Reverting a folder means to
895 undo all local changes. This API call does nothing if the folder is not
896 a receive only folder.
897 Takes the mandatory parameter folder (folder ID).
899 curl -X POST -H X-API-Key:... http://127.0.0.1:8384/rest/db/revert?folder=default
901 POST /rest/db/scan
903 Request immediate scan. Takes the optional parameters folder (folder
904 ID), sub (path relative to the folder root) and next (time in seconds).
905 If folder is omitted or empty all folders are scanned. If sub is given,
906 only this path (and children, in case it’s a directory) is scanned. The
907 next argument delays Syncthing’s automated rescan interval for a given
908 amount of seconds.
909 Requesting scan of a path that no longer exists, but previously did, is
911 valid and will result in Syncthing noticing the deletion of the path in
912 question.
913 Returns status 200 and no content upon success, or status 500 and a
915 plain text error if an error occurred during scanning.
916 curl -X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar
918 GET /rest/db/status
920 Returns information about the current status of a folder.
921 Parameters: folder, the ID of a folder.
923 {
925 "globalBytes": 0,
926 "globalDeleted": 0,
927 "globalDirectories": 0,
928 "globalFiles": 0,
929 "globalSymlinks": 0,
930 "globalTotalItems": 0,
931 "ignorePatterns": false,
932 "inSyncBytes": 0,
933 "inSyncFiles": 0,
934 "invalid": "",
935 "localBytes": 0,
936 "localDeleted": 0,
937 "localDirectories": 0,
938 "localFiles": 0,
939 "localSymlinks": 0,
940 "localTotalItems": 0,
941 "needBytes": 0,
942 "needDeletes": 0,
943 "needDirectories": 0,
944 "needFiles": 0,
945 "needSymlinks": 0,
946 "needTotalItems": 0,
947 "pullErrors": 0,
948 "receiveOnlyChangedBytes": 0,
949 "receiveOnlyChangedDeletes": 0,
950 "receiveOnlyChangedDirectories": 0,
951 "receiveOnlyChangedFiles": 0,
952 "receiveOnlyChangedSymlinks": 0,
953 "receiveOnlyTotalItems": 0,
954 "sequence": 0,
955 "state": "idle",
956 "stateChanged": "2018-08-08T07:04:57.301064781+02:00",
957 "version": 0
958 }
959 The various fields have the following meaning:
961 global*:
963 Data in the cluster latest version.
964 inSync*:
966 Data that is locally the same as the cluster latest version.
967 local*:
969 Data that is locally present, regardless of whether it’s the
970 same or different version as the cluster latest version.
971 need*: Data that is needed to become up to date with the cluster latest
973 version (i.e., data that is out of sync).
974 receiveOnlyChanged*:
976 Data that has changed locally in a receive only folder, and thus
977 not been sent to the cluster.
978 invalid:
980 Deprecated, always empty.
981 pullErrors:
983 The number of files that failed to sync during the last sync op‐
984 erations.
985 sequence:
987 The current folder sequence number.
988 state: The current folder state.
990 stateChanged:
992 When the folder state last changed.
993 version:
995 Deprecated, equivalent to the sequence number.
996 NOTE:
998 This is an expensive call, increasing CPU and RAM usage on the de‐
999 vice. Use sparingly.
1000
1002 GET /rest/events
1003 To receive events, perform a HTTP GET of /rest/events.
1004 To filter the event list, in effect creating a specific subscription
1006 for only the desired event types, add a parameter events=EventTy‐
1007 peA,EventTypeB,... where the event types are any of the event-types.
1008 The optional parameter since=<lastSeenID> sets the ID of the last event
1010 you’ve already seen. Syncthing returns a JSON encoded array of event
1011 objects, starting at the event just after the one with this last seen
1012 ID. The default value is 0, which returns all events. There is a limit
1013 to the number of events buffered, so if the rate of events is high or
1014 the time between polling calls is long some events might be missed.
1015 This can be detected by noting a discontinuity in the event IDs.
1016 If no new events are produced since <lastSeenID>, the HTTP call blocks
1018 and waits for new events to happen before returning. By default it
1019 times out after 60 seconds returning an empty array. The time out dura‐
1020 tion can be customized with the optional parameter timeout=<seconds>.
1021 To receive only a limited number of events, add the limit=<n> parameter
1023 with a suitable value for n and only the last n events will be re‐
1024 turned. This can be used to catch up with the latest event ID after a
1025 disconnection for example: /rest/events?since=0&limit=1.
1026
1028 GET /rest/stats/device
1029 Returns general statistics about devices. Currently, only contains the
1030 time the device was last seen.
1031 $ curl -s http://localhost:8384/rest/stats/device | json
1033 {
1034 "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
1035 "lastSeen" : "2015-04-18T11:21:31.3256277+01:00"
1036 }
1037 }
1038 GET /rest/stats/folder
1040 Returns general statistics about folders. Currently contains the last
1041 scan time and the last synced file.
1042 $ curl -s http://localhost:8384/rest/stats/folder | json
1044 {
1045 "folderid" : {
1046 "lastScan": "2016-06-02T13:28:01.288181412-04:00",
1047 "lastFile" : {
1048 "filename" : "file/name",
1049 "at" : "2015-04-16T22:04:18.3066971+01:00"
1050 }
1051 }
1052 }
1053
1055 GET /rest/svc/deviceid
1056 Verifies and formats a device ID. Accepts all currently valid formats
1057 (52 or 56 characters with or without separators, upper or lower case,
1058 with trivial substitutions). Takes one parameter, id, and returns ei‐
1059 ther a valid device ID in modern format, or an error.
1060 $ curl -s http://localhost:8384/rest/svc/deviceid?id=1234 | json
1062 {
1063 "error": "device ID invalid: incorrect length"
1064 }
1065 $ curl -s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m--zjnu2iq-gdr-eydm-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json
1067 {
1068 "id": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2"
1069 }
1070 GET /rest/svc/lang
1072 Returns a list of canonicalized localization codes, as picked up from
1073 the Accept-Language header sent by the browser.
1074 ["sv_sv","sv","en_us","en"]
1076 GET /rest/svc/random/string
1078 Returns a strong random generated string (alphanumeric) of the speci‐
1079 fied length. Takes the length parameter.
1080 {
1082 "random": "FdPaEaZQ56sXEKYNxpgF"
1083 }
1084 GET /rest/svc/report
1086 Returns the data sent in the anonymous usage report.
1087 {
1089 "folderMaxMiB" : 0,
1090 "platform" : "linux-amd64",
1091 "totMiB" : 0,
1092 "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",
1093 "upgradeAllowedManual" : true,
1094 "totFiles" : 3,
1095 "folderUses" : {
1096 "ignorePerms" : 0,
1097 "autoNormalize" : 0,
1098 "sendonly" : 0,
1099 "ignoreDelete" : 0
1100 },
1101 "memoryUsageMiB" : 13,
1102 "version" : "v0.12.2",
1103 "sha256Perf" : 27.28,
1104 "numFolders" : 2,
1105 "memorySize" : 1992,
1106 "announce" : {
1107 "defaultServersIP" : 0,
1108 "otherServers" : 0,
1109 "globalEnabled" : false,
1110 "defaultServersDNS" : 1,
1111 "localEnabled" : false
1112 },
1113 "usesRateLimit" : false,
1114 "numCPU" : 2,
1115 "uniqueID" : "",
1116 "urVersion" : 2,
1117 "rescanIntvs" : [
1118 60,
1119 60
1120 ],
1121 "numDevices" : 2,
1122 "folderMaxFiles" : 3,
1123 "relays" : {
1124 "defaultServers" : 1,
1125 "enabled" : true,
1126 "otherServers" : 0
1127 },
1128 "deviceUses" : {
1129 "compressMetadata" : 1,
1130 "customCertName" : 0,
1131 "staticAddr" : 1,
1132 "compressAlways" : 0,
1133 "compressNever" : 1,
1134 "introducer" : 0,
1135 "dynamicAddr" : 1
1136 },
1137 "upgradeAllowedAuto" : false
1138 }
1139
1141 The Syncthing Authors
1142
1144 2014-2019, The Syncthing Authors
1145v1 Apr 15, 2021 SYNCTHING-REST-API(7)