1SYNCTHING-REST-API(7) Syncthing SYNCTHING-REST-API(7)
2
6 syncthing-rest-api - REST API
7 Syncthing exposes a REST interface over HTTP on the GUI port. This is
9 used by the GUI (from Javascript) and can be used by other processes
10 wishing to control Syncthing. In most cases both the input and output
11 data is in JSON format. The interface is subject to change.
12
14 To use the REST API an API key must be set and used. The API key can be
15 generated in the GUI, or set in the configuration/gui/apikey element in
16 the configuration file. To use an API key, set the request header
17 X-API-Key to the API key value. For example, curl -X POST -H
18 "X-API-Key: abc123" http://localhost:8384/rest/... can be used to in‐
19 voke with curl (add -k flag when using HTTPS with a Syncthing generated
20 or self signed certificate).
21
23 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 $ curl -H "X-API-Key: yourkey" localhost:8384/rest/system/browse | json_pp
40 [
41 "/"
42 ]
43 $ 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 $ 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 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 Returns the current configuration.
74 {
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 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 Returns whether the config is in sync, i.e. whether the running config‐
337 uration is the same as that on disk.
338 {
340 "configInSync": true
341 }
342 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 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 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 GET /rest/system/connections
359 NOTE:
360 Return format changed in versions 0.13.0 and 1.19.0.
361 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 The connection types are TCP (Client), TCP (Server), Relay (Client) and
367 Relay (Server).
368 {
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 GET /rest/system/debug
413 New in version 0.12.0.
414 Returns the set of debug facilities and which of them are currently en‐
417 abled.
418 {
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 POST /rest/system/debug
446 New in version 0.12.0.
447 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 $ curl -H X-API-Key:abc123 -X POST 'http://localhost:8384/rest/system/debug?disable=beacon,discovery&enable=config,db'
455 GET /rest/system/discovery
457 Returns the contents of the local discovery cache.
458 {
460 "LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q": [
461 "192.162.129.11:22000"
462 ]
463 }
464 POST /rest/system/discovery
466 NOTE:
467 Removed in v0.12.0.
468 Post with the query parameters device and addr to add entries to the
470 discovery cache.
471 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 POST /rest/system/error/clear
477 Post with empty to body to remove all recent errors.
478 GET /rest/system/error
480 NOTE:
481 Return format changed in 0.12.0.
482 Returns the list of recent errors.
484 {
486 "errors": [
487 {
488 "when": "2014-09-18T12:59:26.549953186+02:00",
489 "message": "This is an error string"
490 }
491 ]
492 }
493 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 GET /rest/system/log
499 New in version 0.12.0.
500 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 {
507 "messages": [
508 {
509 "when": "2014-09-18T12:59:26.549953186+02:00",
510 "message": "This is a log entry"
511 }
512 ]
513 }
514 GET /rest/system/log.txt
516 Returns the same information, formatted as a text log instead of a JSON
517 object.
518 POST /rest/system/pause
520 Pause the given device or all devices.
521 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 GET /rest/system/ping
527 Returns a {"ping": "pong"} object.
528 {
530 "ping": "pong"
531 }
532 POST /rest/system/ping
534 Returns a {"ping": "pong"} object.
535 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 curl -X POST -H "X-API-Key: abc123" http://localhost:8384/rest/system/reset?folder=ab1c2-def3g
543 Caution: See --reset-database for .stfolder creation side-effect and
545 caution regarding mountpoints.
546 POST /rest/system/restart
548 Post with empty body to immediately restart Syncthing.
549 POST /rest/system/resume
551 Resume the given device or all devices.
552 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 POST /rest/system/shutdown
558 Post with empty body to cause Syncthing to exit and not restart.
559 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 {
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 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 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 GET /rest/system/upgrade
668 Checks for a possible upgrade and returns an object describing the new‐
669 est version and upgrade possibility.
670 {
672 "latest": "v0.14.47",
673 "majorNewer": false,
674 "newer": true,
675 "running": "v0.14.46"
676 }
677 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 GET /rest/system/version
683 Returns the current Syncthing version information.
684 {
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 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 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 /rest/config
712 GET returns the entire config and PUT replaces it.
713 /rest/config/restart-required
715 GET returns whether a restart of Syncthing is required for the current
716 config to take effect.
717 /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 /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 /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 /rest/config/defaults/ignores
736 New in version 1.19.0.
737 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 /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 DELETE /rest/cluster/pending/devices
752 New in version 1.18.0.
753 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 $ 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 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 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 GET /rest/cluster/pending/devices
769 New in version 1.13.0.
770 Lists remote devices which have tried to connect, but are not yet con‐
773 figured in our instance.
774 {
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 DELETE /rest/cluster/pending/folders
784 New in version 1.18.0.
785 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 $ 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 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 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 GET /rest/cluster/pending/folders
803 New in version 1.13.0.
804 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 {
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 GET /rest/folder/errors
844 New in version 0.14.53.
845 Takes one mandatory parameter, folder, and returns the list of errors
848 encountered during scanning or pulling.
849 The results can be paginated using the common pagination parameters.
851 {
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 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 See d510e3cca3d5caae42121fa206b3decc981ae59e <https://github.com/sync‐
870 thing/syncthing/commit/d510e3cca3d5caae42121fa206b3decc981ae59e>
871 GET /rest/folder/versions
874 New in version 0.14.44.
875 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 {
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 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 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 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 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 $ 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 NOTE:
989 This is an expensive call, increasing CPU and RAM usage on the de‐
990 vice. Use sparingly.
991 GET /rest/db/completion
993 Returns the completion percentage (0 to 100) and byte / item counts.
994 Takes optional device and folder parameters:
995 • folder specifies the folder ID to calculate completion for. An empty
997 or absent folder parameter means all folders as an aggregate.
998 • device specifies the device ID to calculate completion for. An empty
1000 or absent device parameter means the local device.
1001 If a device is specified but no folder, completion is calculated for
1003 all folders shared with that device.
1004 Example Queries
1006 Completion status for folder abcd-1234 on device I6KAH76-...-3PSROAU:
1007 /rest/db/completion?folder=abcd-1234&device=I6KAH76-...-3PSROAU
1009 Aggregated completion status for device I6KAH76-...-3PSROAU (all fold‐
1011 ers shared with them):
1012 /rest/db/completion?device=I6KAH76-...-3PSROAU
1014 Completion status for folder abcd-1234 on the local device:
1016 /rest/db/completion?folder=abcd-1234
1018 Aggregated completion status for all folders on the local device:
1020 /rest/db/completion
1022 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 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 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 GET /rest/db/file
1049 Returns most data available about a given file, including version and
1050 availability. Takes folder and file parameters.
1051 {
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 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 {
1110 "ignore": [
1111 "(?i)/Backups"
1112 ],
1113 "expanded": [
1114 "(?i)Backups",
1115 "(?i)Backups/**"
1116 ]
1117 }
1118 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 GET /rest/db/localchanged
1126 New in version 0.14.55.
1127 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 The results can be paginated using the common pagination parameters.
1135 {
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 NOTE:
1154 This is an expensive call, increasing CPU and RAM usage on the de‐
1155 vice. Use sparingly.
1156 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 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 1. progress has 15 items
1167 2. queued has 3 items
1169 3. rest has 12 items
1171 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 NOTE:
1180 Return format changed in version 0.14.43, removing the total count
1181 attribute.
1182 {
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 NOTE:
1211 This is an expensive call, increasing CPU and RAM usage on the de‐
1212 vice. Use sparingly.
1213 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 Takes the mandatory parameter folder (folder ID).
1220 curl -X POST -H X-API-key:... http://127.0.0.1:8384/rest/db/override?folder=default
1222 POST /rest/db/prio
1224 Moves the file to the top of the download queue.
1225 curl -X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
1227 Response contains the same output as db-need-get.
1229 GET /rest/db/remoteneed
1231 New in version 0.14.43.
1232 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 The results can be paginated using the common pagination parameters.
1239 {
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 NOTE:
1258 This is an expensive call, increasing CPU and RAM usage on the de‐
1259 vice. Use sparingly.
1260 POST /rest/db/revert
1262 New in version 0.14.50.
1263 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 Takes the mandatory parameter folder (folder ID).
1270 curl -X POST -H X-API-Key:... http://127.0.0.1:8384/rest/db/revert?folder=default
1272 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 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 Returns status 200 and no content upon success, or status 500 and a
1286 plain text error if an error occurred during scanning.
1287 curl -X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar
1289 GET /rest/db/status
1291 Returns information about the current status of a folder.
1292 Parameters: folder, the ID of a folder.
1294 {
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 The various fields have the following meaning:
1332 global*:
1334 Data in the cluster latest version.
1335 inSync*:
1337 Data that is locally the same as the cluster latest version.
1338 local*:
1340 Data that is locally present, regardless of whether it’s the
1341 same or different version as the cluster latest version.
1342 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 receiveOnlyChanged*:
1347 Data that has changed locally in a receive only folder, and thus
1348 not been sent to the cluster.
1349 invalid:
1351 Deprecated, always empty.
1352 pullErrors:
1354 The number of files that failed to sync during the last sync op‐
1355 erations.
1356 sequence:
1358 The current folder sequence number.
1359 state: The current folder state.
1361 stateChanged:
1363 When the folder state last changed.
1364 version:
1366 Deprecated, equivalent to the sequence number.
1367 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 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 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 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 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 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 $ 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 GET /rest/stats/folder
1418 Returns general statistics about folders. Currently contains the last
1419 scan time and the last synced file.
1420 {
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 $ curl -s http://localhost:8384/rest/svc/deviceid?id=1234 | json
1439 {
1440 "error": "device ID invalid: incorrect length"
1441 }
1442 $ 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 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 ["sv_sv","sv","en_us","en"]
1453 GET /rest/svc/random/string
1455 Returns a strong random generated string (alphanumeric) of the speci‐
1456 fied length. Takes the length parameter.
1457 {
1459 "random": "FdPaEaZQ56sXEKYNxpgF"
1460 }
1461 GET /rest/svc/report
1463 Returns the data sent in the anonymous usage report.
1464 {
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 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 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 GET /rest/debug/cpuprof
1531 Used to capture a profile of what Syncthing is doing on the CPU. See
1532 /users/profiling.
1533 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 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 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 $ curl -H X-API-Key:... "http://localhost:8384/rest/debug/file?folder=default&file=foo/bar"
1550 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
1559v1.20.0 May 08, 2022 SYNCTHING-REST-API(7)