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