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