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 One exception to this requirement is /rest/noauth, you do not need an
23 API key to use those endpoints. This way third-party devices and ser‐
24 vices can do simple calls that don’t expose sensitive information with‐
25 out having to expose your API key.
26
28 Some GET endpoints take optional page and perpage arguments for pagina‐
29 tion. No more than perpage (defaults to 65536 if not given) result en‐
30 tries are returned in an array. To access further entries, passing the
31 page parameter will advance in the results by that many pages. The ac‐
32 tually used parameters are always returned as attributes in the re‐
33 sponse object.
34
36 GET /rest/system/browse
37 Returns a list of directories matching the path given by the optional
38 parameter current. The path can use patterns as described in Go’s
39 filepath package <https://pkg.go.dev/path/filepath#Match>. A ‘*’ will
40 always be appended to the given path (e.g. /tmp/ matches all its subdi‐
41 rectories). If the option current is not given, filesystem root paths
42 are returned.
43 $ curl -H "X-API-Key: yourkey" localhost:8384/rest/system/browse | json_pp
45 [
46 "/"
47 ]
48 $ curl -H "X-API-Key: yourkey" localhost:8384/rest/system/browse?current=/var/ | json_pp
50 [
51 "/var/backups/",
52 "/var/cache/",
53 "/var/lib/",
54 "/var/local/",
55 "/var/lock/",
56 "/var/log/",
57 "/var/mail/",
58 "/var/opt/",
59 "/var/run/",
60 "/var/spool/",
61 "/var/tmp/"
62 ]
63 $ curl -H "X-API-Key: yourkey" localhost:8384/rest/system/browse?current=/var/*o | json_pp
65 [
66 "/var/local/",
67 "/var/lock/",
68 "/var/log/",
69 "/var/opt/",
70 "/var/spool/"
71 ]
72 GET /rest/system/config (DEPRECATED)
74 Deprecated since version v1.12.0: This endpoint still works as before
75 but is deprecated. Use rest-config instead.
76 Returns the current configuration.
79 {
81 "version": 35,
82 "folders": [
83 {
84 "id": "default",
85 "label": "Default Folder",
86 "filesystemType": "basic",
87 "path": "...",
88 "type": "sendreceive",
89 "devices": [
90 {
91 "deviceID": "...",
92 "introducedBy": "",
93 "encryptionPassword": ""
94 }
95 ],
96 "rescanIntervalS": 3600,
97 "fsWatcherEnabled": true,
98 "fsWatcherDelayS": 10,
99 "ignorePerms": false,
100 "autoNormalize": true,
101 "minDiskFree": {
102 "value": 1,
103 "unit": "%"
104 },
105 "versioning": {
106 "type": "",
107 "params": {},
108 "cleanupIntervalS": 3600,
109 "fsPath": "",
110 "fsType": "basic"
111 },
112 "copiers": 0,
113 "pullerMaxPendingKiB": 0,
114 "hashers": 0,
115 "order": "random",
116 "ignoreDelete": false,
117 "scanProgressIntervalS": 0,
118 "pullerPauseS": 0,
119 "maxConflicts": -1,
120 "disableSparseFiles": false,
121 "disableTempIndexes": false,
122 "paused": false,
123 "weakHashThresholdPct": 25,
124 "markerName": ".stfolder",
125 "copyOwnershipFromParent": false,
126 "modTimeWindowS": 0,
127 "maxConcurrentWrites": 2,
128 "disableFsync": false,
129 "blockPullOrder": "standard",
130 "copyRangeMethod": "standard",
131 "caseSensitiveFS": false,
132 "junctionsAsDirs": true
133 }
134 ],
135 "devices": [
136 {
137 "deviceID": "...",
138 "name": "Laptop",
139 "addresses": [
140 "dynamic",
141 "tcp://192.168.1.2:22000"
142 ],
143 "compression": "metadata",
144 "certName": "",
145 "introducer": false,
146 "skipIntroductionRemovals": false,
147 "introducedBy": "",
148 "paused": false,
149 "allowedNetworks": [],
150 "autoAcceptFolders": false,
151 "maxSendKbps": 0,
152 "maxRecvKbps": 0,
153 "ignoredFolders": [
154 {
155 "time": "2022-01-09T19:09:52Z",
156 "id": "br63e-wyhb7",
157 "label": "Foo"
158 }
159 ],
160 "maxRequestKiB": 0,
161 "untrusted": false,
162 "remoteGUIPort": 0
163 }
164 ],
165 "gui": {
166 "enabled": true,
167 "address": "127.0.0.1:8384",
168 "unixSocketPermissions": "",
169 "user": "Username",
170 "password": "$2a$10$ZFws69T4FlvWwsqeIwL.TOo5zOYqsa/.TxlUnsGYS.j3JvjFTmxo6",
171 "authMode": "static",
172 "useTLS": false,
173 "apiKey": "k1dnz1Dd0rzTBjjFFh7CXPnrF12C49B1",
174 "insecureAdminAccess": false,
175 "theme": "default",
176 "debugging": false,
177 "insecureSkipHostcheck": false,
178 "insecureAllowFrameLoading": false
179 },
180 "ldap": {
181 "address": "",
182 "bindDN": "",
183 "transport": "plain",
184 "insecureSkipVerify": false,
185 "searchBaseDN": "",
186 "searchFilter": ""
187 },
188 "options": {
189 "listenAddresses": [
190 "default"
191 ],
192 "globalAnnounceServers": [
193 "default"
194 ],
195 "globalAnnounceEnabled": true,
196 "localAnnounceEnabled": true,
197 "localAnnouncePort": 21027,
198 "localAnnounceMCAddr": "[ff12::8384]:21027",
199 "maxSendKbps": 0,
200 "maxRecvKbps": 0,
201 "reconnectionIntervalS": 60,
202 "relaysEnabled": true,
203 "relayReconnectIntervalM": 10,
204 "startBrowser": true,
205 "natEnabled": true,
206 "natLeaseMinutes": 60,
207 "natRenewalMinutes": 30,
208 "natTimeoutSeconds": 10,
209 "urAccepted": 0,
210 "urSeen": 0,
211 "urUniqueId": "...",
212 "urURL": "https://data.syncthing.net/newdata",
213 "urPostInsecurely": false,
214 "urInitialDelayS": 1800,
215 "restartOnWakeup": true,
216 "autoUpgradeIntervalH": 12,
217 "upgradeToPreReleases": false,
218 "keepTemporariesH": 24,
219 "cacheIgnoredFiles": false,
220 "progressUpdateIntervalS": 5,
221 "limitBandwidthInLan": false,
222 "minHomeDiskFree": {
223 "value": 1,
224 "unit": "%"
225 },
226 "releasesURL": "https://upgrades.syncthing.net/meta.json",
227 "alwaysLocalNets": [],
228 "overwriteRemoteDeviceNamesOnConnect": false,
229 "tempIndexMinBlocks": 10,
230 "unackedNotificationIDs": [
231 "authenticationUserAndPassword"
232 ],
233 "trafficClass": 0,
234 "setLowPriority": true,
235 "maxFolderConcurrency": 0,
236 "crURL": "https://crash.syncthing.net/newcrash",
237 "crashReportingEnabled": true,
238 "stunKeepaliveStartS": 180,
239 "stunKeepaliveMinS": 20,
240 "stunServers": [
241 "default"
242 ],
243 "databaseTuning": "auto",
244 "maxConcurrentIncomingRequestKiB": 0,
245 "announceLANAddresses": true,
246 "sendFullIndexOnUpgrade": false,
247 "featureFlags": [],
248 "connectionLimitEnough": 0,
249 "connectionLimitMax": 0,
250 "insecureAllowOldTLSVersions": false
251 },
252 "remoteIgnoredDevices": [
253 {
254 "time": "2022-01-09T20:02:01Z",
255 "deviceID": "...",
256 "name": "...",
257 "address": "192.168.0.20:22000"
258 }
259 ],
260 "defaults": {
261 "folder": {
262 "id": "",
263 "label": "",
264 "filesystemType": "basic",
265 "path": "~",
266 "type": "sendreceive",
267 "devices": [
268 {
269 "deviceID": "...",
270 "introducedBy": "",
271 "encryptionPassword": ""
272 }
273 ],
274 "rescanIntervalS": 3600,
275 "fsWatcherEnabled": true,
276 "fsWatcherDelayS": 10,
277 "ignorePerms": false,
278 "autoNormalize": true,
279 "minDiskFree": {
280 "value": 1,
281 "unit": "%"
282 },
283 "versioning": {
284 "type": "",
285 "params": {},
286 "cleanupIntervalS": 3600,
287 "fsPath": "",
288 "fsType": "basic"
289 },
290 "copiers": 0,
291 "pullerMaxPendingKiB": 0,
292 "hashers": 0,
293 "order": "random",
294 "ignoreDelete": false,
295 "scanProgressIntervalS": 0,
296 "pullerPauseS": 0,
297 "maxConflicts": 10,
298 "disableSparseFiles": false,
299 "disableTempIndexes": false,
300 "paused": false,
301 "weakHashThresholdPct": 25,
302 "markerName": ".stfolder",
303 "copyOwnershipFromParent": false,
304 "modTimeWindowS": 0,
305 "maxConcurrentWrites": 2,
306 "disableFsync": false,
307 "blockPullOrder": "standard",
308 "copyRangeMethod": "standard",
309 "caseSensitiveFS": false,
310 "junctionsAsDirs": false
311 },
312 "device": {
313 "deviceID": "",
314 "name": "",
315 "addresses": [
316 "dynamic"
317 ],
318 "compression": "metadata",
319 "certName": "",
320 "introducer": false,
321 "skipIntroductionRemovals": false,
322 "introducedBy": "",
323 "paused": false,
324 "allowedNetworks": [],
325 "autoAcceptFolders": false,
326 "maxSendKbps": 0,
327 "maxRecvKbps": 0,
328 "ignoredFolders": [],
329 "maxRequestKiB": 0,
330 "untrusted": false,
331 "remoteGUIPort": 0
332 }
333 }
334 }
335 GET /rest/system/config/insync (DEPRECATED)
337 Deprecated since version v1.12.0: This endpoint still works as before
338 but is deprecated. Use rest-config-insync instead.
339 Returns whether the config is in sync, i.e. whether the running config‐
342 uration is the same as that on disk.
343 {
345 "configInSync": true
346 }
347 POST /rest/system/config (DEPRECATED)
349 Deprecated since version v1.12.0: This endpoint still works as before
350 but is deprecated. Use config instead.
351 Post the full contents of the configuration, in the same format as re‐
354 turned by the corresponding GET request. When posting the configuration
355 succeeds, the posted configuration is immediately applied, except for
356 changes that require a restart. Query rest-config-insync to check if a
357 restart is required.
358 This endpoint is the main point to control Syncthing, even if the
360 change only concerns a very small part of the config: The usual work‐
361 flow is to get the config, modify the needed parts and post it again.
362 GET /rest/system/connections
364 NOTE:
365 Return format changed in versions 0.13.0, 1.19.0 and 1.23.0.
366 Returns the list of configured devices and some metadata associated
368 with them. The list also contains the local device itself as not con‐
369 nected.
370 The connection types are TCP (Client), TCP (Server), Relay (Client) and
372 Relay (Server).
373 {
375 "connections": {
376 "DOVII4U-SQEEESM-VZ2CVTC-CJM4YN5-QNV7DCU-5U3ASRL-YVFG6TH-W5DV5AA": {
377 "address": "",
378 "at": "0001-01-01T00:00:00Z",
379 "clientVersion": "",
380 "connected": false,
381 "inBytesTotal": 0,
382 "isLocal": false,
383 "outBytesTotal": 0,
384 "paused": false,
385 "startedAt": "0001-01-01T00:00:00Z",
386 "type": ""
387 },
388 "UYGDMA4-TPHOFO5-2VQYDCC-7CWX7XW-INZINQT-LE4B42N-4JUZTSM-IWCSXA4": {
389 "address": "",
390 "at": "0001-01-01T00:00:00Z",
391 "clientVersion": "",
392 "connected": false,
393 "inBytesTotal": 0,
394 "isLocal": false,
395 "outBytesTotal": 0,
396 "paused": false,
397 "startedAt": "0001-01-01T00:00:00Z",
398 "type": ""
399 },
400 "YZJBJFX-RDBL7WY-6ZGKJ2D-4MJB4E7-ZATSDUY-LD6Y3L3-MLFUYWE-AEMXJAC": {
401 "address": "127.0.0.1:22002",
402 "at": "2015-11-07T17:29:47.691548971+01:00",
403 "clientVersion": "v0.12.1",
404 "connected": true,
405 "inBytesTotal": 556,
406 "isLocal": true,
407 "outBytesTotal": 550,
408 "paused": false,
409 "startedAt": "2015-11-07T00:09:47Z",
410 "type": "TCP (Client)"
411 }
412 },
413 "total": {
414 "at": "2015-11-07T17:29:47.691637262+01:00",
415 "inBytesTotal": 1479,
416 "outBytesTotal": 1318
417 }
418 }
419 GET /rest/system/debug
421 New in version 0.12.0.
422 Returns the set of debug facilities and which of them are currently en‐
425 abled.
426 {
428 "enabled": [
429 "beacon"
430 ],
431 "facilities": {
432 "beacon": "Multicast and broadcast discovery",
433 "config": "Configuration loading and saving",
434 "connections": "Connection handling",
435 "db": "The database layer",
436 "dialer": "Dialing connections",
437 "discover": "Remote device discovery",
438 "events": "Event generation and logging",
439 "http": "REST API",
440 "main": "Main package",
441 "model": "The root hub",
442 "protocol": "The BEP protocol",
443 "relay": "Relay connection handling",
444 "scanner": "File change detection and hashing",
445 "stats": "Persistent device and folder statistics",
446 "sync": "Mutexes",
447 "upgrade": "Binary upgrades",
448 "upnp": "UPnP discovery and port mapping",
449 "versioner": "File versioning"
450 }
451 }
452 POST /rest/system/debug
454 New in version 0.12.0.
455 Enables or disables debugging for specified facilities. Give one or
458 both of enable and disable query parameters, with comma separated fa‐
459 cility names. To disable debugging of the beacon and discovery pack‐
460 ages, and enable it for config and db:
461 $ curl -H X-API-Key:abc123 -X POST 'http://localhost:8384/rest/system/debug?disable=beacon,discovery&enable=config,db'
463 GET /rest/system/discovery
465 Returns the contents of the local discovery cache.
466 {
468 "LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q": [
469 "192.162.129.11:22000"
470 ]
471 }
472 POST /rest/system/discovery
474 NOTE:
475 Removed in v0.12.0.
476 Post with the query parameters device and addr to add entries to the
478 discovery cache.
479 curl -X POST http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\&addr=192.162.129.11:22000
481 # Or with the X-API-Key header:
482 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
483 POST /rest/system/error/clear
485 Post with empty to body to remove all recent errors.
486 GET /rest/system/error
488 NOTE:
489 Return format changed in 0.12.0.
490 Returns the list of recent errors.
492 {
494 "errors": [
495 {
496 "when": "2014-09-18T12:59:26.549953186+02:00",
497 "message": "This is an error string"
498 }
499 ]
500 }
501 POST /rest/system/error
503 Post with an error message in the body (plain text) to register a new
504 error. The new error will be displayed on any active GUI clients.
505 GET /rest/system/log
507 New in version 0.12.0.
508 Returns the list of recent log entries. The optional since parameter
511 limits the results to message newer than the given timestamp in RFC
512 3339 <https://datatracker.ietf.org/doc/html/rfc3339.html> format.
513 {
515 "messages": [
516 {
517 "when": "2014-09-18T12:59:26.549953186+02:00",
518 "message": "This is a log entry"
519 }
520 ]
521 }
522 GET /rest/system/log.txt
524 Returns the same information, formatted as a text log instead of a JSON
525 object.
526 GET /rest/system/paths
528 New in version 1.21.0.
529 Returns the path locations used internally for storing configuration,
532 database, and others.
533 {
535 "auditLog": "/home/user/.local/share/syncthing/audit-${timestamp}.log",
536 "baseDir-config": "/home/user/.config/syncthing",
537 "baseDir-data": "/home/user/.local/share/syncthing",
538 "baseDir-userHome": "/home/user",
539 "certFile": "/home/user/.config/syncthing/cert.pem",
540 "config": "/home/user/.config/syncthing/config.xml",
541 "csrfTokens": "/home/user/.config/syncthing/csrftokens.txt",
542 "database": "/home/user/.local/share/syncthing/index-v0.14.0.db",
543 "defFolder": "/home/user/Sync",
544 "guiAssets": "/home/user/src/syncthing/gui",
545 "httpsCertFile": "/home/user/.config/syncthing/https-cert.pem",
546 "httpsKeyFile": "/home/user/.config/syncthing/https-key.pem",
547 "keyFile": "/home/user/.config/syncthing/key.pem",
548 "logFile": "-",
549 "panicLog": "/home/user/.local/share/syncthing/panic-${timestamp}.log"
550 }
551 POST /rest/system/pause
553 Pause the given device or all devices.
554 Takes the optional parameter device (device ID). When omitted, pauses
556 all devices. Returns status 200 and no content upon success, or status
557 500 and a plain text error on failure.
558 GET /rest/system/ping
560 Returns a {"ping": "pong"} object.
561 {
563 "ping": "pong"
564 }
565 POST /rest/system/ping
567 Returns a {"ping": "pong"} object.
568 POST /rest/system/reset
570 Post with empty body to erase the current index database and restart
571 Syncthing. With no query parameters, the entire database is erased from
572 disk. By specifying the folder parameter with a valid folder ID, only
573 information for that folder will be erased:
574 curl -X POST -H "X-API-Key: abc123" http://localhost:8384/rest/system/reset?folder=ab1c2-def3g
576 Caution: See --reset-database for .stfolder creation side-effect and
578 caution regarding mountpoints.
579 POST /rest/system/restart
581 Post with empty body to immediately restart Syncthing.
582 POST /rest/system/resume
584 Resume the given device or all devices.
585 Takes the optional parameter device (device ID). When omitted, resumes
587 all devices. Returns status 200 and no content upon success, or status
588 500 and a plain text error on failure.
589 POST /rest/system/shutdown
591 Post with empty body to cause Syncthing to exit and not restart.
592 GET /rest/system/status
594 Returns information about current system status and resource usage. The
595 CPU percent value has been deprecated from the API and will always re‐
596 port 0.
597 {
599 "alloc": 30618136,
600 "connectionServiceStatus": {
601 "dynamic+https://relays.syncthing.net/endpoint": {
602 "error": null,
603 "lanAddresses": [
604 "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"
605 ],
606 "wanAddresses": [
607 "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"
608 ]
609 },
610 "tcp://0.0.0.0:22000": {
611 "error": null,
612 "lanAddresses": [
613 "tcp://0.0.0.0:22000"
614 ],
615 "wanAddresses": [
616 "tcp://0.0.0.0:22000"
617 ]
618 }
619 },
620 "cpuPercent": 0,
621 "discoveryEnabled": true,
622 "discoveryErrors": {
623 "global@https://discovery-v4-1.syncthing.net/v2/": "500 Internal Server Error",
624 "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)",
625 "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)",
626 "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",
627 "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",
628 "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"
629 },
630 "discoveryStatus": {
631 "IPv4 local": {
632 "error": null
633 },
634 "IPv6 local": {
635 "error": null
636 },
637 "global@https://discovery-v4-1.syncthing.net/v2/": {
638 "error": "500 Internal Server Error"
639 },
640 "global@https://discovery-v4-2.syncthing.net/v2/": {
641 "error": "Post https://discovery-v4-2.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)"
642 },
643 "global@https://discovery-v4-3.syncthing.net/v2/": {
644 "error": "Post https://discovery-v4-3.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)"
645 },
646 "global@https://discovery-v6-1.syncthing.net/v2/": {
647 "error": "Post https://discovery-v6-1.syncthing.net/v2/: dial tcp [2001:470:28:4d6::5]:443: connect: no route to host"
648 },
649 "global@https://discovery-v6-2.syncthing.net/v2/": {
650 "error": "Post https://discovery-v6-2.syncthing.net/v2/: dial tcp [2604:a880:800:10::182:a001]:443: connect: no route to host"
651 },
652 "global@https://discovery-v6-3.syncthing.net/v2/": {
653 "error": "Post https://discovery-v6-3.syncthing.net/v2/: dial tcp [2400:6180:0:d0::d9:d001]:443: connect: no route to host"
654 }
655 },
656 "discoveryMethods": 8,
657 "goroutines": 49,
658 "lastDialStatus": {
659 "tcp://10.20.30.40": {
660 "when": "2019-05-16T07:41:23Z",
661 "error": "dial tcp 10.20.30.40:22000: i/o timeout"
662 },
663 "tcp://172.16.33.3:22000": {
664 "when": "2019-05-16T07:40:43Z",
665 "ok": true
666 },
667 "tcp://83.233.120.221:22000": {
668 "when": "2019-05-16T07:41:13Z",
669 "error": "dial tcp 83.233.120.221:22000: connect: connection refused"
670 }
671 },
672 "myID": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2",
673 "pathSeparator": "/",
674 "startTime": "2016-06-06T19:41:43.039284753+02:00",
675 "sys": 42092792,
676 "themes": [
677 "default",
678 "dark"
679 ],
680 "tilde": "/Users/jb",
681 "uptime": 2635
682 }
683 New in version 1.2.0: The lastDialStatus dictionary contains the last
685 error (or null for success) for each peer address that Syncthing has
686 attempted to contact. The connectionServiceStatus entries gained "er‐
687 ror": null attributes where previously there would be no error attri‐
688 bute at all in the success case.
689 New in version 1.18.0: The discoveryStatus dictionary lists all config‐
692 ured discovery methods, not only failed ones like the now deprecated
693 discoveryErrors. Each entry is an object itself (for consistency with
694 other fields), where a null value for the error attribute means the
695 method is running successfully. This effectively deprecates the dis‐
696 coveryMethods attribute as well, which now always matches the number of
697 entries in discoveryStatus.
698 GET /rest/system/upgrade
701 Checks for a possible upgrade and returns an object describing the new‐
702 est version and upgrade possibility.
703 {
705 "latest": "v0.14.47",
706 "majorNewer": false,
707 "newer": true,
708 "running": "v0.14.46"
709 }
710 POST /rest/system/upgrade
712 Perform an upgrade to the newest released version and restart. Does
713 nothing if there is no newer version than currently running.
714 GET /rest/system/version
716 Returns the current Syncthing version information.
717 {
719 "arch": "amd64",
720 "longVersion": "syncthing v0.10.27+3-gea8c3de (go1.4 darwin-amd64 default) jb@syno 2015-03-16 11:01:29 UTC",
721 "os": "darwin",
722 "version": "v0.10.27+3-gea8c3de"
723 }
724
726 Config Endpoints
727 New in version 1.12.0.
728 These endpoints facilitate access and modification of the configuration
731 in a granular way. Config sent to the endpoints must be in the same
732 format as returned by the corresponding GET request. When posting the
733 configuration succeeds, the posted configuration is immediately ap‐
734 plied, except for changes that require a restart. Query
735 /rest/config/restart-required to check if a restart is required.
736 For all endpoints supporting PATCH, it takes the existing config and
738 unmarshals the given JSON object on top of it. This means all child ob‐
739 jects will replace the existing objects, not extend them. For example
740 for RawListenAddresses in options, which is an array of strings, send‐
741 ing {RawListenAddresses: ["tcp://10.0.0.2"]} will replace all existing
742 listen addresses.
743 /rest/config
745 GET returns the entire config and PUT replaces it.
746 /rest/config/restart-required
748 GET returns whether a restart of Syncthing is required for the current
749 config to take effect.
750 /rest/config/folders, /rest/config/devices
752 GET returns all folders respectively devices as an array. PUT takes an
753 array and POST a single object. In both cases if a given folder/device
754 already exists, it’s replaced, otherwise a new one is added.
755 /rest/config/folders/*id*, /rest/config/devices/*id*
757 Put the desired folder- respectively device-ID in place of *id*. GET
758 returns the folder/device for the given ID, PUT replaces the entire
759 config, PATCH replaces only the given child objects and DELETE removes
760 the folder/device.
761 /rest/config/defaults/folder, /rest/config/defaults/device
763 GET returns a template folder / device configuration object with all
764 default values, which only needs a unique ID to be applied. PUT re‐
765 places the default config (omitted values are reset to the hard-coded
766 defaults), PATCH replaces only the given child objects.
767 /rest/config/defaults/ignores
769 New in version 1.19.0.
770 GET returns an object with a single lines attribute listing ignore pat‐
773 terns to be used by default on folders, as an array of single-line
774 strings. PUT replaces the default ignore patterns from an object of
775 the same format.
776 /rest/config/options, /rest/config/ldap, /rest/config/gui
778 GET returns the respective object, PUT replaces the entire object and
779 PATCH replaces only the given child objects.
780
782 Concerns the mesh network structure.
783 DELETE /rest/cluster/pending/devices
785 New in version 1.18.0.
786 Remove records about a pending remote device which tried to connect.
789 Valid values for the device parameter are those from the corresponding
790 cluster-pending-devices-get endpoint.
791 $ curl -X DELETE -H "X-API-Key: abc123" http://localhost:8384/rest/cluster/pending/devices?device=P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2
793 Returns status 200 and no content upon success, or status 500 and a
795 plain text error on failure. A /events/pendingdeviceschanged event
796 will be generated in response.
797 For a more permanent effect, also for future connections from the same
799 device ID, the device should be ignored in the configuration instead.
800 GET /rest/cluster/pending/devices
802 New in version 1.13.0.
803 Lists remote devices which have tried to connect, but are not yet con‐
806 figured in our instance.
807 {
809 "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
810 "time": "2020-03-18T11:43:07Z",
811 "name": "Friend Joe",
812 "address": "192.168.1.2:22000"
813 }
814 }
815 DELETE /rest/cluster/pending/folders
817 New in version 1.18.0.
818 Remove records about a pending folder announced from a remote device.
821 Valid values for the folder and device parameters are those from the
822 corresponding cluster-pending-folders-get endpoint. The device parame‐
823 ter is optional and affects announcements of this folder from the given
824 device, or from any device if omitted.
825 $ 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
827 Returns status 200 and no content upon success, or status 500 and a
829 plain text error on failure. A /events/pendingfolderschanged event
830 will be generated in response.
831 For a more permanent effect, also for future announcements of the same
833 folder ID, the folder should be ignored in the configuration instead.
834 GET /rest/cluster/pending/folders
836 New in version 1.13.0.
837 Lists folders which remote devices have offered to us, but are not yet
840 shared from our instance to them. Takes the optional device parameter
841 to only return folders offered by a specific remote device. Other of‐
842 fering devices are also omitted from the result.
843 {
845 "cpkn4-57ysy": {
846 "offeredBy": {
847 "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
848 "time": "2020-03-18T11:43:07Z",
849 "label": "Joe's folder",
850 "receiveEncrypted": true,
851 "remoteEncrypted": false
852 },
853 "DOVII4U-SQEEESM-VZ2CVTC-CJM4YN5-QNV7DCU-5U3ASRL-YVFG6TH-W5DV5AA": {
854 "time": "2020-03-01T10:12:13Z",
855 "label": "Jane's and Joe's folder",
856 "receiveEncrypted": false,
857 "remoteEncrypted": false
858 }
859 }
860 },
861 "abcde-fghij": {
862 "offeredBy": {
863 "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
864 "time": "2020-03-18T11:43:07Z",
865 "label": "MyPics",
866 "receiveEncrypted": false,
867 "remoteEncrypted": false
868 }
869 }
870 }
871 }
872
874 Runtime state of the individual shared folders.
875 GET /rest/folder/errors
877 New in version 0.14.53.
878 Takes one mandatory parameter, folder, and returns the list of errors
881 encountered during scanning or pulling.
882 The results can be paginated using the common pagination parameters.
884 {
886 "folder": "nnhic-sxuae",
887 "errors": [
888 {
889 "path": "noperm.txt",
890 "error": "hashing: open /path/to/folder/noperm.txt: permission denied"
891 }
892 ],
893 "page": 1,
894 "perpage": 100
895 }
896 GET /rest/folder/pullerrors (DEPRECATED)
898 Deprecated since version v0.14.53: This endpoint still works as before
899 but is deprecated. Use folder-errors-get instead, which returns the
900 same information.
901 See d510e3cca3d5caae42121fa206b3decc981ae59e <https://github.com/sync‐
903 thing/syncthing/commit/d510e3cca3d5caae42121fa206b3decc981ae59e>
904 GET /rest/folder/versions
907 New in version 0.14.44.
908 Takes one mandatory parameter, folder, and returns the list of archived
911 files that could be recovered. How many versions are available depends
912 on the /users/versioning configuration. Each entry specifies when the
913 file version was archived as the versionTime, the modTime when it was
914 last modified before being archived, and the size in bytes.
915 {
917 "dir1/dir2/bar": [
918 {
919 "versionTime": "2022-02-06T20:44:12+01:00",
920 "modTime": "2021-01-14T13:21:22+01:00",
921 "size": 4
922 }
923 ],
924 "baz": [
925 {
926 "versionTime": "2022-02-06T20:44:20+01:00",
927 "modTime": "2021-01-14T13:23:49+01:00",
928 "size": 4
929 }
930 ],
931 "foo": [
932 {
933 "versionTime": "2022-02-06T20:55:31+01:00",
934 "modTime": "2022-02-06T20:44:13+01:00",
935 "size": 4
936 },
937 {
938 "versionTime": "2022-02-06T20:44:20+01:00",
939 "modTime": "2021-01-14T13:21:16+01:00",
940 "size": 4
941 }
942 ]
943 }
944 POST /rest/folder/versions
946 Restore archived versions of a given set of files. Expects an object
947 with attributes named after the relative file paths, with timestamps as
948 values matching valid versionTime entries in the corresponding
949 folder-versions-get response object.
950 Takes the mandatory parameter folder (folder ID). Returns an object
952 containing any error messages that occurred during restoration of the
953 file, with the file path as attribute name.
954 curl -X POST -H X-API-key:... http://127.0.0.1:8384/rest/folder/versions?folder=default -d '{
956 "dir1/dir2/bar": "2022-02-06T20:44:12+01:00",
957 "baz": "2022-02-06T20:44:20+01:00"
958 }'
959
961 GET /rest/db/browse
962 Returns the directory tree of the global model. Directories are always
963 JSON objects (map/dictionary), and files are always arrays of modifica‐
964 tion time and size. The first integer is the files modification time,
965 and the second integer is the file size.
966 The call takes one mandatory folder parameter and two optional parame‐
968 ters. Optional parameter levels defines how deep within the tree we
969 want to dwell down (0 based, defaults to unlimited depth) Optional pa‐
970 rameter prefix defines a prefix within the tree where to start building
971 the structure.
972 $ curl -s http://localhost:8384/rest/db/browse?folder=j663y-3ct3e&prefix=DCIM&levels=2
974 [
975 {
976 "modTime" : "2020-10-02T23:48:52.076996974+02:00",
977 "name" : "100ANDRO",
978 "size" : 128,
979 "type" : "FILE_INFO_TYPE_DIRECTORY"
980 },
981 {
982 "children" : [
983 {
984 "modTime" : "2020-12-16T23:31:34.5009668+01:00",
985 "name" : "IMG_20201114_124821.jpg",
986 "size" : 10682189,
987 "type" : "FILE_INFO_TYPE_FILE"
988 },
989 {
990 "modTime" : "2020-12-16T23:31:35.0106367+01:00",
991 "name" : "IMG_20201213_122451.jpg",
992 "size" : 7936351,
993 "type" : "FILE_INFO_TYPE_FILE"
994 },
995 {
996 "modTime" : "2020-12-13T12:25:05.017097469+01:00",
997 "name" : "IMG_20201213_122504.jpg",
998 "size" : 8406507,
999 "type" : "FILE_INFO_TYPE_FILE"
1000 },
1001 {
1002 "modTime" : "2020-12-13T12:25:06.127097469+01:00",
1003 "name" : "IMG_20201213_122505.jpg",
1004 "size" : 8381931,
1005 "type" : "FILE_INFO_TYPE_FILE"
1006 },
1007 {
1008 "modTime" : "2020-12-13T12:53:29.707298401+01:00",
1009 "name" : "IMG_20201213_125329.jpg",
1010 "size" : 4388331,
1011 "type" : "FILE_INFO_TYPE_FILE"
1012 },
1013 ],
1014 "modTime" : "2020-10-09T13:04:42.4410738+02:00",
1015 "name" : "Camera",
1016 "size" : 128,
1017 "type" : "FILE_INFO_TYPE_DIRECTORY"
1018 },
1019 ]
1020 NOTE:
1022 This is an expensive call, increasing CPU and RAM usage on the de‐
1023 vice. Use sparingly.
1024 GET /rest/db/completion
1026 Returns the completion percentage (0 to 100) and byte / item counts.
1027 Takes optional device and folder parameters:
1028 • folder specifies the folder ID to calculate completion for. An empty
1030 or absent folder parameter means all folders as an aggregate.
1031 • device specifies the device ID to calculate completion for. An empty
1033 or absent device parameter means the local device.
1034 If a device is specified but no folder, completion is calculated for
1036 all folders shared with that device.
1037 Example Queries
1039 Completion status for folder abcd-1234 on device I6KAH76-...-3PSROAU:
1040 /rest/db/completion?folder=abcd-1234&device=I6KAH76-...-3PSROAU
1042 Aggregated completion status for device I6KAH76-...-3PSROAU (all fold‐
1044 ers shared with them):
1045 /rest/db/completion?device=I6KAH76-...-3PSROAU
1047 Completion status for folder abcd-1234 on the local device:
1049 /rest/db/completion?folder=abcd-1234
1051 Aggregated completion status for all folders on the local device:
1053 /rest/db/completion
1055 Example Response
1057 {
1058 "completion": 99.9937565835,
1059 "globalBytes": 156793013575,
1060 "needBytes": 9789241,
1061 "globalItems": 7823,
1062 "needItems": 412,
1063 "needDeletes": 0,
1064 "remoteState": "valid",
1065 "sequence": 12
1066 }
1067 New in version 1.8.0: The ability to aggregate multiple folders by
1069 leaving out the folder ID. Querying data for the local device by leav‐
1070 ing out the device ID. Returning the globalItems counter in the re‐
1071 sponse.
1072 New in version 1.20.0: Indication whether the remote device has ac‐
1075 cepted the folder (shares it with us) as well, and whether it is
1076 paused. The remoteState field is meaningless for aggregated responses,
1077 unknown when the remote device is not connected. Otherwise it can be
1078 either paused, notSharing, or valid if the remote is sharing back.
1079 GET /rest/db/file
1082 Returns most data available about a given file, including version and
1083 availability. Takes folder and file parameters. local and global refer
1084 to the current file on disk and the globally newest file, respectively.
1085 {
1087 "availability": [
1088 {
1089 "id": "ITZRNXE-YNROGBZ-HXTH5P7-VK5NYE5-QHRQGE2-7JQ6VNJ-KZUEDIU-5PPR5AM",
1090 "fromTemporary": false
1091 }
1092 ],
1093 "global": { /* a file entry */ },
1094 "local": { /* a file entry */ }
1095 }
1096 A file entry looks like this:
1098 {
1100 {
1101 "deleted": false,
1102 "ignored": false,
1103 "inodeChange": "1970-01-01T01:00:00+01:00",
1104 "invalid": false,
1105 "localFlags": 0,
1106 "modified": "2022-09-28T08:07:19.979723+02:00",
1107 "modifiedBy": "523ITIE",
1108 "mustRescan": false,
1109 "name": "img",
1110 "noPermissions": false,
1111 "numBlocks": 0,
1112 "permissions": "0755",
1113 "platform": { /* platform specific data */ },
1114 "sequence": 914,
1115 "size": 128,
1116 "type": "FILE_INFO_TYPE_DIRECTORY",
1117 "version": [
1118 "523ITIE:1664345275"
1119 ]
1120 },
1121 "mtime": {
1122 "err": null,
1123 "value": {
1124 "real": "0001-01-01T00:00:00Z",
1125 "virtual": "0001-01-01T00:00:00Z"
1126 }
1127 }
1128 }
1129 Platform specific data may be ownership, extended attributes, etc. and
1131 is divided into entries per operating system / platform. An example
1132 platform entry containing ownership information for Unix systems and an
1133 extended attribute for macOS (“darwin”) looks as follows:
1134 {
1136 "darwin": {
1137 "xattrs": [
1138 {
1139 "name": "net.kastelo.xattrtest",
1140 "value": "aGVsbG8="
1141 }
1142 ]
1143 },
1144 "freebsd": null,
1145 "linux": null,
1146 "netbsd": null,
1147 "unix": {
1148 "gid": 20,
1149 "groupName": "staff",
1150 "ownerName": "jb",
1151 "uid": 501
1152 },
1153 "windows": null
1154 }
1155 GET /rest/db/ignores
1157 Takes one parameter, folder, and returns the content of the .stignore
1158 as the ignore field. A second field, expanded, provides a list of
1159 strings which represent globbing patterns described by gobwas/glob
1160 (based on standard wildcards) that match the patterns in .stignore and
1161 all the includes. If appropriate these globs are prepended by the fol‐
1162 lowing modifiers: ! to negate the glob, (?i) to do case insensitive
1163 matching and (?d) to enable removing of ignored files in an otherwise
1164 empty directory.
1165 {
1167 "ignore": [
1168 "(?i)/Backups"
1169 ],
1170 "expanded": [
1171 "(?i)Backups",
1172 "(?i)Backups/**"
1173 ]
1174 }
1175 POST /rest/db/ignores
1177 Expects a format similar to the output of db-ignores-get call, but only
1178 containing the ignore field (expanded field should be omitted). It
1179 takes one parameter, folder, and either updates the content of the
1180 .stignore echoing it back as a response, or returns an error.
1181 GET /rest/db/localchanged
1183 New in version 0.14.55.
1184 Takes one mandatory parameter, folder, and returns the list of files
1187 which were changed locally in a receive-only folder. Thus they differ
1188 from the global state and could be reverted by pulling from remote de‐
1189 vices again, see db-revert-post.
1190 The results can be paginated using the common pagination parameters.
1192 {
1194 "files": [
1195 {
1196 "flags": "0755",
1197 "sequence": 6,
1198 "modified": "2015-04-20T23:06:12+09:00",
1199 "name": "ls",
1200 "size": 34640,
1201 "version": [
1202 "5157751870738175669:1"
1203 ]
1204 }
1205 ],
1206 "page": 1,
1207 "perpage": 100
1208 }
1209 NOTE:
1211 This is an expensive call, increasing CPU and RAM usage on the de‐
1212 vice. Use sparingly.
1213 GET /rest/db/need
1215 Takes one mandatory parameter, folder, and returns lists of files which
1216 are needed by this device in order for it to become in sync.
1217 The results can be paginated using the common pagination parameters.
1219 Pagination happens, across the union of all needed files, that is -
1220 across all 3 sections of the response. For example, given the current
1221 need state is as follows:
1222 1. progress has 15 items
1224 2. queued has 3 items
1226 3. rest has 12 items
1228 If you issue a query with page=1 and perpage=10, only the progress sec‐
1230 tion in the response will have 10 items. If you issue a request query
1231 with page=2 and perpage=10, progress section will have the last 5
1232 items, queued section will have all 3 items, and rest section will have
1233 first 2 items. If you issue a query for page=3 and perpage=10, you will
1234 only have the last 10 items of the rest section.
1235 NOTE:
1237 Return format changed in version 0.14.43, removing the total count
1238 attribute.
1239 {
1241 # Files currently being downloaded
1242 "progress": [
1243 {
1244 "flags": "0755",
1245 "sequence": 6,
1246 "modified": "2015-04-20T23:06:12+09:00",
1247 "name": "ls",
1248 "size": 34640,
1249 "version": [
1250 "5157751870738175669:1"
1251 ]
1252 }
1253 ],
1254 # Files queued to be downloaded next (as per array order)
1255 "queued": [
1256 ...
1257 ],
1258 # Files to be downloaded after all queued files will be downloaded.
1259 # This happens when we start downloading files, and new files get added while we are downloading.
1260 "rest": [
1261 ...
1262 ],
1263 "page": 1,
1264 "perpage": 100
1265 }
1266 NOTE:
1268 This is an expensive call, increasing CPU and RAM usage on the de‐
1269 vice. Use sparingly.
1270 POST /rest/db/override
1272 Request override of a send only folder. Override means to make the lo‐
1273 cal version latest, overriding changes made on other devices. This API
1274 call does nothing if the folder is not a send only folder.
1275 Takes the mandatory parameter folder (folder ID).
1277 curl -X POST -H X-API-key:... http://127.0.0.1:8384/rest/db/override?folder=default
1279 POST /rest/db/prio
1281 Moves the file to the top of the download queue.
1282 curl -X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
1284 Response contains the same output as db-need-get.
1286 GET /rest/db/remoteneed
1288 New in version 0.14.43.
1289 Takes the mandatory parameters folder and device, and returns the list
1292 of files which are needed by that remote device in order for it to be‐
1293 come in sync with the shared folder.
1294 The results can be paginated using the common pagination parameters.
1296 {
1298 "files": [
1299 {
1300 "flags": "0755",
1301 "sequence": 6,
1302 "modified": "2015-04-20T23:06:12+09:00",
1303 "name": "ls",
1304 "size": 34640,
1305 "version": [
1306 "5157751870738175669:1"
1307 ]
1308 }
1309 ],
1310 "page": 1,
1311 "perpage": 100
1312 }
1313 NOTE:
1315 This is an expensive call, increasing CPU and RAM usage on the de‐
1316 vice. Use sparingly.
1317 POST /rest/db/revert
1319 New in version 0.14.50.
1320 Request revert of a receive only folder. Reverting a folder means to
1323 undo all local changes. This API call does nothing if the folder is not
1324 a receive only folder.
1325 Takes the mandatory parameter folder (folder ID).
1327 curl -X POST -H X-API-Key:... http://127.0.0.1:8384/rest/db/revert?folder=default
1329 POST /rest/db/scan
1331 Request immediate scan. Takes the optional parameters folder (folder
1332 ID), sub (path relative to the folder root) and next (time in seconds).
1333 If folder is omitted or empty all folders are scanned. If sub is given,
1334 only this path (and children, in case it’s a directory) is scanned. The
1335 next argument delays Syncthing’s automated rescan interval for a given
1336 amount of seconds.
1337 Requesting scan of a path that no longer exists, but previously did, is
1339 valid and will result in Syncthing noticing the deletion of the path in
1340 question.
1341 Returns status 200 and no content upon success, or status 500 and a
1343 plain text error if an error occurred during scanning.
1344 curl -X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar
1346 GET /rest/db/status
1348 Returns information about the current status of a folder.
1349 Parameters: folder, the ID of a folder.
1351 {
1353 "globalBytes": 0,
1354 "globalDeleted": 0,
1355 "globalDirectories": 0,
1356 "globalFiles": 0,
1357 "globalSymlinks": 0,
1358 "globalTotalItems": 0,
1359 "ignorePatterns": false,
1360 "inSyncBytes": 0,
1361 "inSyncFiles": 0,
1362 "invalid": "",
1363 "localBytes": 0,
1364 "localDeleted": 0,
1365 "localDirectories": 0,
1366 "localFiles": 0,
1367 "localSymlinks": 0,
1368 "localTotalItems": 0,
1369 "needBytes": 0,
1370 "needDeletes": 0,
1371 "needDirectories": 0,
1372 "needFiles": 0,
1373 "needSymlinks": 0,
1374 "needTotalItems": 0,
1375 "pullErrors": 0,
1376 "receiveOnlyChangedBytes": 0,
1377 "receiveOnlyChangedDeletes": 0,
1378 "receiveOnlyChangedDirectories": 0,
1379 "receiveOnlyChangedFiles": 0,
1380 "receiveOnlyChangedSymlinks": 0,
1381 "receiveOnlyTotalItems": 0,
1382 "sequence": 0,
1383 "state": "idle",
1384 "stateChanged": "2018-08-08T07:04:57.301064781+02:00",
1385 "version": 0
1386 }
1387 The various fields have the following meaning:
1389 global*:
1391 Data in the cluster latest version.
1392 inSync*:
1394 Data that is locally the same as the cluster latest version.
1395 local*:
1397 Data that is locally present, regardless of whether it’s the
1398 same or different version as the cluster latest version.
1399 need*: Data that is needed to become up to date with the cluster latest
1401 version (i.e., data that is out of sync).
1402 receiveOnlyChanged*:
1404 Data that has changed locally in a receive only folder, and thus
1405 not been sent to the cluster.
1406 invalid:
1408 Deprecated, always empty.
1409 pullErrors:
1411 The number of files that failed to sync during the last sync op‐
1412 erations.
1413 sequence:
1415 The current folder sequence number.
1416 state: The current folder state.
1418 stateChanged:
1420 When the folder state last changed.
1421 version:
1423 Deprecated, equivalent to the sequence number.
1424 NOTE:
1426 This is an expensive call, increasing CPU and RAM usage on the de‐
1427 vice. Use sparingly.
1428
1430 GET /rest/events
1431 To receive events, perform a HTTP GET of /rest/events.
1432 To filter the event list, in effect creating a specific subscription
1434 for only the desired event types, add a parameter events=EventTy‐
1435 peA,EventTypeB,... where the event types are any of the event-types.
1436 If no filter is specified, all events except /events/localchangede‐
1437 tected and /events/remotechangedetected are included.
1438 The optional parameter since=<lastSeenID> sets the ID of the last event
1440 you’ve already seen. Syncthing returns a JSON encoded array of event
1441 objects, starting at the event just after the one with this last seen
1442 ID. The default value is 0, which returns all events. There is a limit
1443 to the number of events buffered, so if the rate of events is high or
1444 the time between polling calls is long some events might be missed.
1445 This can be detected by noting a discontinuity in the event IDs.
1446 If no new events are produced since <lastSeenID>, the HTTP call blocks
1448 and waits for new events to happen before returning. By default it
1449 times out after 60 seconds returning an empty array. The time out dura‐
1450 tion can be customized with the optional parameter timeout=<seconds>.
1451 To receive only a limited number of events, add the limit=<n> parameter
1453 with a suitable value for n and only the last n events will be re‐
1454 turned. This can be used to catch up with the latest event ID after a
1455 disconnection for example: /rest/events?since=0&limit=1.
1456 GET /rest/events/disk
1458 This convenience endpoint provides the same event stream, but pre-fil‐
1459 tered to show only /events/localchangedetected and /events/re‐
1460 motechangedetected event types. The events parameter is not used.
1461
1463 GET /rest/stats/device
1464 Returns general statistics about devices. Currently, only contains the
1465 time the device was last seen.
1466 $ curl -s http://localhost:8384/rest/stats/device | json
1468 {
1469 "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
1470 "lastSeen" : "2015-04-18T11:21:31.3256277+01:00"
1471 }
1472 }
1473 GET /rest/stats/folder
1475 Returns general statistics about folders. Currently contains the last
1476 scan time and the last synced file.
1477 {
1479 "folderid": {
1480 "lastScan": "2016-06-02T13:28:01.288181412-04:00",
1481 "lastFile": {
1482 "filename": "file/name",
1483 "at": "2015-04-16T22:04:18.3066971+01:00"
1484 }
1485 }
1486 }
1487
1489 GET /rest/svc/deviceid
1490 Verifies and formats a device ID. Accepts all currently valid formats
1491 (52 or 56 characters with or without separators, upper or lower case,
1492 with trivial substitutions). Takes one parameter, id, and returns ei‐
1493 ther a valid device ID in modern format, or an error.
1494 $ curl -s http://localhost:8384/rest/svc/deviceid?id=1234 | json
1496 {
1497 "error": "device ID invalid: incorrect length"
1498 }
1499 $ curl -s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m--zjnu2iq-gdr-eydm-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json
1501 {
1502 "id": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2"
1503 }
1504 GET /rest/svc/lang
1506 Returns a list of canonicalized localization codes, as picked up from
1507 the Accept-Language header sent by the browser.
1508 ["sv_sv","sv","en_us","en"]
1510 GET /rest/svc/random/string
1512 Returns a strong random generated string (alphanumeric) of the speci‐
1513 fied length. Takes the length parameter.
1514 {
1516 "random": "FdPaEaZQ56sXEKYNxpgF"
1517 }
1518 GET /rest/svc/report
1520 Returns the data sent in the anonymous usage report.
1521 {
1523 "folderMaxMiB" : 0,
1524 "platform" : "linux-amd64",
1525 "totMiB" : 0,
1526 "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",
1527 "upgradeAllowedManual" : true,
1528 "totFiles" : 3,
1529 "folderUses" : {
1530 "ignorePerms" : 0,
1531 "autoNormalize" : 0,
1532 "sendonly" : 0,
1533 "ignoreDelete" : 0
1534 },
1535 "memoryUsageMiB" : 13,
1536 "version" : "v0.12.2",
1537 "sha256Perf" : 27.28,
1538 "numFolders" : 2,
1539 "memorySize" : 1992,
1540 "announce" : {
1541 "defaultServersIP" : 0,
1542 "otherServers" : 0,
1543 "globalEnabled" : false,
1544 "defaultServersDNS" : 1,
1545 "localEnabled" : false
1546 },
1547 "usesRateLimit" : false,
1548 "numCPU" : 2,
1549 "uniqueID" : "",
1550 "urVersion" : 2,
1551 "rescanIntvs" : [
1552 60,
1553 60
1554 ],
1555 "numDevices" : 2,
1556 "folderMaxFiles" : 3,
1557 "relays" : {
1558 "defaultServers" : 1,
1559 "enabled" : true,
1560 "otherServers" : 0
1561 },
1562 "deviceUses" : {
1563 "compressMetadata" : 1,
1564 "customCertName" : 0,
1565 "staticAddr" : 1,
1566 "compressAlways" : 0,
1567 "compressNever" : 1,
1568 "introducer" : 0,
1569 "dynamicAddr" : 1
1570 },
1571 "upgradeAllowedAuto" : false
1572 }
1573
1575 Debug Endpoints
1576 These endpoints require the gui.debugging configuration option to be
1577 enabled and yield an access denied error code otherwise.
1578 GET /rest/debug/peerCompletion
1580 Summarizes the completion precentage for each remote device. Returns
1581 an object with device IDs as keys and an integer percentage as values.
1582 GET /rest/debug/httpmetrics
1584 Returns statistics about each served REST API endpoint, to diagnose how
1585 much time was spent generating the responses.
1586 GET /rest/debug/cpuprof
1588 Used to capture a profile of what Syncthing is doing on the CPU. See
1589 /users/profiling.
1590 GET /rest/debug/heapprof
1592 Used to capture a profile of what Syncthing is doing with the heap mem‐
1593 ory. See /users/profiling.
1594 GET /rest/debug/support
1596 Collects information about the running instance for troubleshooting
1597 purposes. Returns a “support bundle” as a zipped archive, which should
1598 be sent to the developers after verifying it contains no sensitive per‐
1599 sonal information. Credentials for the web GUI and the API key are au‐
1600 tomatically redacted already.
1601 GET /rest/debug/file
1603 Shows diagnostics about a certain file in a shared folder. Takes the
1604 folder (folder ID) and file (folder relative path) parameters.
1605 $ curl -H X-API-Key:... "http://localhost:8384/rest/debug/file?folder=default&file=foo/bar"
1607 The returned object contains the same info as db-file-get, plus a sum‐
1609 mary of globalVersions.
1610
1612 Calls that do not require authentication.
1613 GET /rest/noauth/health
1615 Returns a {"status": "OK"} object.
1616 {
1618 "status": "OK"
1619 }
1620
1622 The Syncthing Authors
1623
1625 2014-2019, The Syncthing Authors
1626v1.22.2 Dec 29, 2022 SYNCTHING-REST-API(7)