1SYNCTHING-REST-API(7)              Syncthing             SYNCTHING-REST-API(7)
2
3
4

NAME

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

API KEY

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

RESULT PAGINATION

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

SYSTEM ENDPOINTS

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

CONFIG ENDPOINTS

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

CLUSTER ENDPOINTS

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

FOLDER ENDPOINTS

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

DATABASE ENDPOINTS

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
996folder  specifies the folder ID to calculate completion for. An empty
997         or absent folder parameter means all folders as an aggregate.
998
999device 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

EVENT ENDPOINTS

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

STATISTICS ENDPOINTS

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

MISC SERVICES ENDPOINTS

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

DEBUG ENDPOINTS

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

AUTHOR

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)
Impressum