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
19       invoke  with curl (add -k flag when using HTTPS with a Syncthing gener‐
20       ated or self signed certificate).
21

SYSTEM ENDPOINTS

23   GET /rest/system/browse
24       Returns a list of directories matching the path given by  the  optional
25       parameter  current.  The  path  can  use  patterns as described in Go’s
26       filepath package <https://golang.org/pkg/path/filepath/#Match>.  A  ‘*’
27       will  always  be appended to the given path (e.g. /tmp/ matches all its
28       subdirectories). If the option current is not  given,  filesystem  root
29       paths are returned.
30
31          $ curl -H "X-API-Key: yourkey" localhost:8384/rest/system/browse | json_pp
32          [
33              "/"
34          ]
35
36          $ curl -H "X-API-Key: yourkey" localhost:8384/rest/system/browse?current=/var/ | json_pp
37          [
38              "/var/backups/",
39              "/var/cache/",
40              "/var/lib/",
41              "/var/local/",
42              "/var/lock/",
43              "/var/log/",
44              "/var/mail/",
45              "/var/opt/",
46              "/var/run/",
47              "/var/spool/",
48              "/var/tmp/"
49          ]
50
51          $ curl -H "X-API-Key: yourkey" localhost:8384/rest/system/browse?current=/var/*o | json_pp
52          [
53              "/var/local/",
54              "/var/lock/",
55              "/var/log/",
56              "/var/opt/",
57              "/var/spool/"
58          ]
59
60   GET /rest/system/config
61       Deprecated  since  version v1.12.0: This endpoint still works as before
62       but is deprecated. Use rest-config instead.
63
64
65       Returns the current configuration.
66
67          {
68            "version": 30,
69            "folders": [
70              {
71                "id": "GXWxf-3zgnU",
72                "label": "MyFolder",
73                "filesystemType": "basic",
74                "path": "...",
75                "type": "sendreceive",
76                "devices": [
77                  {
78                    "deviceID": "...",
79                    "introducedBy": ""
80                  }
81                ],
82                "rescanIntervalS": 60,
83                "fsWatcherEnabled": false,
84                "fsWatcherDelayS": 10,
85                "ignorePerms": false,
86                "autoNormalize": true,
87                "minDiskFree": {
88                  "value": 1,
89                  "unit": "%"
90                },
91                "versioning": {
92                  "type": "simple",
93                  "params": {
94                    "keep": "5"
95                  }
96                },
97                "copiers": 0,
98                "pullerMaxPendingKiB": 0,
99                "hashers": 0,
100                "order": "random",
101                "ignoreDelete": false,
102                "scanProgressIntervalS": 0,
103                "pullerPauseS": 0,
104                "maxConflicts": 10,
105                "disableSparseFiles": false,
106                "disableTempIndexes": false,
107                "paused": false,
108                "weakHashThresholdPct": 25,
109                "markerName": ".stfolder",
110                "copyOwnershipFromParent": false,
111                "modTimeWindowS": 0
112              }
113            ],
114            "devices": [
115              {
116                "deviceID": "...",
117                "name": "Laptop",
118                "addresses": [
119                  "dynamic",
120                  "tcp://192.168.1.2:22000"
121                ],
122                "compression": "metadata",
123                "certName": "",
124                "introducer": false,
125                "skipIntroductionRemovals": false,
126                "introducedBy": "",
127                "paused": false,
128                "allowedNetworks": [],
129                "autoAcceptFolders": false,
130                "maxSendKbps": 0,
131                "maxRecvKbps": 0,
132                "ignoredFolders": [],
133                "maxRequestKiB": 0
134              }
135            ],
136            "gui": {
137              "enabled": true,
138              "address": "127.0.0.1:8384",
139              "user": "Username",
140              "password": "$2a$10$ZFws69T4FlvWwsqeIwL.TOo5zOYqsa/.TxlUnsGYS.j3JvjFTmxo6",
141              "authMode": "static",
142              "useTLS": false,
143              "apiKey": "pGahcht56664QU5eoFQW6szbEG6Ec2Cr",
144              "insecureAdminAccess": false,
145              "theme": "default",
146              "debugging": false,
147              "insecureSkipHostcheck": false,
148              "insecureAllowFrameLoading": false
149            },
150            "ldap": {
151              "address": "",
152              "bindDN": "",
153              "transport": "plain",
154              "insecureSkipVerify": false
155            },
156            "options": {
157              "listenAddresses": [
158                "default"
159              ],
160              "globalAnnounceServers": [
161                "default"
162              ],
163              "globalAnnounceEnabled": true,
164              "localAnnounceEnabled": true,
165              "localAnnouncePort": 21027,
166              "localAnnounceMCAddr": "[ff12::8384]:21027",
167              "maxSendKbps": 0,
168              "maxRecvKbps": 0,
169              "reconnectionIntervalS": 60,
170              "relaysEnabled": true,
171              "relayReconnectIntervalM": 10,
172              "startBrowser": false,
173              "natEnabled": true,
174              "natLeaseMinutes": 60,
175              "natRenewalMinutes": 30,
176              "natTimeoutSeconds": 10,
177              "urAccepted": -1,
178              "urSeen": 2,
179              "urUniqueId": "",
180              "urURL": "https://data.syncthing.net/newdata",
181              "urPostInsecurely": false,
182              "urInitialDelayS": 1800,
183              "restartOnWakeup": true,
184              "autoUpgradeIntervalH": 12,
185              "upgradeToPreReleases": false,
186              "keepTemporariesH": 24,
187              "cacheIgnoredFiles": false,
188              "progressUpdateIntervalS": 5,
189              "limitBandwidthInLan": false,
190              "minHomeDiskFree": {
191                "value": 1,
192                "unit": "%"
193              },
194              "releasesURL": "https://upgrades.syncthing.net/meta.json",
195              "alwaysLocalNets": [],
196              "overwriteRemoteDeviceNamesOnConnect": false,
197              "tempIndexMinBlocks": 10,
198              "unackedNotificationIDs": [],
199              "trafficClass": 0,
200              "defaultFolderPath": "~",
201              "setLowPriority": true,
202              "maxFolderConcurrency": 0,
203              "crURL": "https://crash.syncthing.net/newcrash",
204              "crashReportingEnabled": true,
205              "stunKeepaliveStartS": 180,
206              "stunKeepaliveMinS": 20,
207              "stunServers": [
208                "default"
209              ],
210              "databaseTuning": "auto",
211              "maxConcurrentIncomingRequestKiB": 0
212            },
213            "remoteIgnoredDevices": []
214          }
215
216   GET /rest/system/config/insync
217       Deprecated since version v1.12.0: This endpoint still works  as  before
218       but is deprecated. Use rest-config-insync instead.
219
220
221       Returns whether the config is in sync, i.e. whether the running config‐
222       uration is the same as that on disk.
223
224          {
225            "configInSync": true
226          }
227
228   POST /rest/system/config
229       Deprecated since version v1.12.0: This endpoint still works  as  before
230       but is deprecated. Use rest-config instead.
231
232
233       Post  the  full  contents  of  the configuration, in the same format as
234       returned by the corresponding GET request. When posting the  configura‐
235       tion  succeeds, the posted configuration is immediately applied, except
236       for changes that require a restart. Query rest-config-insync  to  check
237       if a restart is required.
238
239       This  endpoint  is  the  main  point  to control Syncthing, even if the
240       change only concerns a very small part of the config: The  usual  work‐
241       flow is to get the config, modify the needed parts and post it again.
242
243   GET /rest/system/connections
244       NOTE:
245          Return format changed in 0.13.0.
246
247       Returns  the  list  of  configured devices and some metadata associated
248       with them. The list also contains the local device itself as  not  con‐
249       nected.
250
251       The connection types are TCP (Client), TCP (Server), Relay (Client) and
252       Relay (Server).
253
254          {
255             "total" : {
256                    "paused" : false,
257                    "clientVersion" : "",
258                    "at" : "2015-11-07T17:29:47.691637262+01:00",
259                    "connected" : false,
260                    "inBytesTotal" : 1479,
261                    "type" : "",
262                    "outBytesTotal" : 1318,
263                    "address" : ""
264             },
265             "connections" : {
266                    "YZJBJFX-RDBL7WY-6ZGKJ2D-4MJB4E7-ZATSDUY-LD6Y3L3-MLFUYWE-AEMXJAC" : {
267                       "connected" : true,
268                       "inBytesTotal" : 556,
269                       "paused" : false,
270                       "at" : "2015-11-07T17:29:47.691548971+01:00",
271                       "clientVersion" : "v0.12.1",
272                       "address" : "127.0.0.1:22002",
273                       "type" : "TCP (Client)",
274                       "outBytesTotal" : 550
275                    },
276                    "DOVII4U-SQEEESM-VZ2CVTC-CJM4YN5-QNV7DCU-5U3ASRL-YVFG6TH-W5DV5AA" : {
277                       "outBytesTotal" : 0,
278                       "type" : "",
279                       "address" : "",
280                       "at" : "0001-01-01T00:00:00Z",
281                       "clientVersion" : "",
282                       "paused" : false,
283                       "inBytesTotal" : 0,
284                       "connected" : false
285                    },
286                    "UYGDMA4-TPHOFO5-2VQYDCC-7CWX7XW-INZINQT-LE4B42N-4JUZTSM-IWCSXA4" : {
287                       "address" : "",
288                       "type" : "",
289                       "outBytesTotal" : 0,
290                       "connected" : false,
291                       "inBytesTotal" : 0,
292                       "paused" : false,
293                       "at" : "0001-01-01T00:00:00Z",
294                       "clientVersion" : ""
295                    }
296             }
297          }
298
299   GET /rest/system/debug
300       New in version 0.12.0.
301
302
303       Returns the set of debug facilities and which  of  them  are  currently
304       enabled.
305
306          {
307            "enabled": [
308              "beacon"
309            ],
310            "facilities": {
311              "beacon": "Multicast and broadcast discovery",
312              "config": "Configuration loading and saving",
313              "connections": "Connection handling",
314              "db": "The database layer",
315              "dialer": "Dialing connections",
316              "discover": "Remote device discovery",
317              "events": "Event generation and logging",
318              "http": "REST API",
319              "main": "Main package",
320              "model": "The root hub",
321              "protocol": "The BEP protocol",
322              "relay": "Relay connection handling",
323              "scanner": "File change detection and hashing",
324              "stats": "Persistent device and folder statistics",
325              "sync": "Mutexes",
326              "upgrade": "Binary upgrades",
327              "upnp": "UPnP discovery and port mapping",
328              "versioner": "File versioning"
329            }
330          }
331
332   POST /rest/system/debug
333       New in version 0.12.0.
334
335
336       Enables  or  disables  debugging  for specified facilities. Give one or
337       both of enable and  disable  query  parameters,  with  comma  separated
338       facility  names. To disable debugging of the beacon and discovery pack‐
339       ages, and enable it for config and db:
340
341          $ curl -H X-API-Key:abc123 -X POST 'http://localhost:8384/rest/system/debug?disable=beacon,discovery&enable=config,db'
342
343   GET /rest/system/discovery
344       Returns the contents of the local discovery cache.
345
346          {
347            "LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q": [
348              "192.162.129.11:22000"
349            ]
350          }
351
352   POST /rest/system/discovery
353       NOTE:
354          Removed in v0.12.0.
355
356       Post with the query parameters device and addr to add  entries  to  the
357       discovery cache.
358
359          curl -X POST http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\&addr=192.162.129.11:22000
360          # Or with the X-API-Key header:
361          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
362
363   POST /rest/system/error/clear
364       Post with empty to body to remove all recent errors.
365
366   GET /rest/system/error
367       NOTE:
368          Return format changed in 0.12.0.
369
370       Returns the list of recent errors.
371
372          {
373            "errors": [
374              {
375                "when": "2014-09-18T12:59:26.549953186+02:00",
376                "message": "This is an error string"
377              }
378            ]
379          }
380
381   POST /rest/system/error
382       Post  with  an error message in the body (plain text) to register a new
383       error. The new error will be displayed on any active GUI clients.
384
385   GET /rest/system/log
386       New in version 0.12.0.
387
388
389       Returns the list of recent log entries.
390
391          {
392            "messages": [
393              {
394                "when": "2014-09-18T12:59:26.549953186+02:00",
395                "message": "This is a log entry"
396              }
397            ]
398          }
399
400   POST /rest/system/pause
401       Pause the given device or all devices.
402
403       Takes the optional parameter device (device ID). When  omitted,  pauses
404       all devices.  Returns status 200 and no content upon success, or status
405       500 and a plain text error on failure.
406
407   GET /rest/system/ping
408       Returns a {"ping": "pong"} object.
409
410          {
411            "ping": "pong"
412          }
413
414   POST /rest/system/ping
415       Returns a {"ping": "pong"} object.
416
417   POST /rest/system/reset
418       Post with empty body to erase the current index  database  and  restart
419       Syncthing. With no query parameters, the entire database is erased from
420       disk.  By specifying the folder parameter with a valid folder ID,  only
421       information for that folder will be erased:
422
423          $ curl -X POST -H "X-API-Key: abc123" http://localhost:8384/rest/system/reset?folder=default
424
425       Caution:  See  -reset-database  for  .stfolder creation side-effect and
426       caution regarding mountpoints.
427
428   POST /rest/system/restart
429       Post with empty body to immediately restart Syncthing.
430
431   POST /rest/system/resume
432       Resume the given device or all devices.
433
434       Takes the optional parameter device (device ID). When omitted,  resumes
435       all devices.  Returns status 200 and no content upon success, or status
436       500 and a plain text error on failure.
437
438   POST /rest/system/shutdown
439       Post with empty body to cause Syncthing to exit and not restart.
440
441   GET /rest/system/status
442       Returns information about current system status and resource usage. The
443       CPU  percent  value  has  been  deprecated from the API and will always
444       report 0.
445
446          {
447            "alloc": 30618136,
448            "connectionServiceStatus": {
449              "dynamic+https://relays.syncthing.net/endpoint": {
450                "error": null,
451                "lanAddresses": [
452                  "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"
453                ],
454                "wanAddresses": [
455                  "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"
456                ]
457              },
458              "tcp://0.0.0.0:22000": {
459                "error": null,
460                "lanAddresses": [
461                  "tcp://0.0.0.0:22000"
462                ],
463                "wanAddresses": [
464                  "tcp://0.0.0.0:22000"
465                ]
466              }
467            },
468            "cpuPercent": 0,
469            "discoveryEnabled": true,
470            "discoveryErrors": {
471              "global@https://discovery-v4-1.syncthing.net/v2/": "500 Internal Server Error",
472              "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)",
473              "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)",
474              "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",
475              "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",
476              "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"
477            },
478            "discoveryMethods": 8,
479            "goroutines": 49,
480            "lastDialStatus": {
481                "tcp://10.20.30.40": {
482                  "when": "2019-05-16T07:41:23Z",
483                  "error": "dial tcp 10.20.30.40:22000: i/o timeout"
484                },
485                "tcp://172.16.33.3:22000": {
486                  "when": "2019-05-16T07:40:43Z",
487                  "ok": true
488                },
489                "tcp://83.233.120.221:22000": {
490                  "when": "2019-05-16T07:41:13Z",
491                  "error": "dial tcp 83.233.120.221:22000: connect: connection refused"
492                }
493            },
494            "myID": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2",
495            "pathSeparator": "/",
496            "startTime": "2016-06-06T19:41:43.039284753+02:00",
497            "sys": 42092792,
498            "themes": [
499              "default",
500              "dark"
501            ],
502            "tilde": "/Users/jb",
503            "uptime": 2635
504          }
505
506       New in version 1.2.0: The lastDialStatus dictionary contains  the  last
507       error  (or  null  for success) for each peer address that Syncthing has
508       attempted  to  contact.   The  connectionServiceStatus  entries  gained
509       "error":  null  attributes  where  previously  there  would be no error
510       attribute at all in the success case.
511
512
513   GET /rest/system/upgrade
514       Checks for a possible upgrade and returns an object describing the new‐
515       est version and upgrade possibility.
516
517          {
518            "latest": "v0.14.47",
519            "majorNewer": false,
520            "newer": true,
521            "running": "v0.14.46"
522          }
523
524   POST /rest/system/upgrade
525       Perform  an  upgrade  to  the newest released version and restart. Does
526       nothing if there is no newer version than currently running.
527
528   GET /rest/system/version
529       Returns the current Syncthing version information.
530
531          {
532            "arch": "amd64",
533            "longVersion": "syncthing v0.10.27+3-gea8c3de (go1.4 darwin-amd64 default) jb@syno 2015-03-16 11:01:29 UTC",
534            "os": "darwin",
535            "version": "v0.10.27+3-gea8c3de"
536          }
537

CONFIG ENDPOINTS

539   Config Endpoints
540       New in version 1.12.0.
541
542
543       These endpoints facilitate access and modification of the configuration
544       in  a  granular  way.  Config sent to the endpoints must be in the same
545       format as returned by the corresponding GET request. When  posting  the
546       configuration   succeeds,   the  posted  configuration  is  immediately
547       applied,  except  for   changes   that   require   a   restart.   Query
548       /rest/system/config/insync to check if a restart is required.
549
550       For  all  endpoints  supporting PATCH, it takes the existing config and
551       unmarshals the given JSON object on top of it.  This  means  all  child
552       objects will replace the existing objects, not extend them. For example
553       for RawListenAddresses` in options, which is an array of strings, send‐
554       ing ``{RawListenAddresses: ["tcp://10.0.0.2"] will replace all existing
555       listen addresses.
556
557   /rest/config
558       GET returns the entire config and PUT replaces it.
559
560   /rest/system/config/insync
561       GET returns whether the config is in sync,  i.e.  whether  the  running
562       configuration is the same as that on disk or if a restart is required.
563
564   /rest/config/folders, /rest/config/devices
565       GET  returns all folders respectively devices as an array. PUT takes an
566       array and POST a single object. In both cases if a given  folder/device
567       already exists, it’s replaced, otherwise a new one is added.
568
569   /rest/config/folders/*id*, /rest/config/devices/*id*
570       Put  the  desired  folder- respectively device-ID in place of *id*. GET
571       returns the folder/device for the given ID,  PUT  replaces  the  entire
572       config and PATCH replaces only the given child objects.
573
574   /rest/config/options, /rest/config/ldap, /rest/config/gui
575       GET  returns  the respective object, PUT replaces the entire object and
576       PATCH replaces only the given child objects.
577

CLUSTER ENDPOINTS

579       Concerns the mesh network structure.
580
581   GET /rest/cluster/pending/devices
582       New in version 1.13.0.
583
584
585       Lists remote devices which have tried to connect, but are not yet  con‐
586       figured in our instance.
587
588          {
589            "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
590              "time": "2020-03-18T11:43:07Z",
591              "name": "Friend Joe",
592              "address": "192.168.1.2:22000"
593            }
594          }
595
596   GET /rest/cluster/pending/folders
597       New in version 1.13.0.
598
599
600       Lists  folders which remote devices have offered to us, but are not yet
601       shared from our instance to them.  Takes the optional device  parameter
602       to  only  return  folders  offered  by a specific remote device.  Other
603       offering devices are also omitted from the result.
604
605          {
606            "cpkn4-57ysy": {
607              "offeredBy": {
608                "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
609                  "time": "2020-03-18T11:43:07Z",
610                  "label": "Joe's folder"
611                },
612                "DOVII4U-SQEEESM-VZ2CVTC-CJM4YN5-QNV7DCU-5U3ASRL-YVFG6TH-W5DV5AA": {
613                  "time": "2020-03-01T10:12:13Z",
614                  "label": "Jane's and Joe's folder"
615                }
616              }
617            },
618            "abcde-fghij": {
619              "offeredBy": {
620                "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
621                  "time": "2020-03-18T11:43:07Z",
622                  "label": "MyPics"
623                }
624              }
625            }
626          }
627

DATABASE ENDPOINTS

629   GET /rest/db/browse
630       Returns the directory tree of the global model. Directories are  always
631       JSON objects (map/dictionary), and files are always arrays of modifica‐
632       tion time and size. The first integer is the files  modification  time,
633       and the second integer is the file size.
634
635       The  call takes one mandatory folder parameter and two optional parame‐
636       ters. Optional parameter levels defines how deep  within  the  tree  we
637       want  to  dwell  down  (0  based, defaults to unlimited depth) Optional
638       parameter prefix defines a prefix within the tree where to start build‐
639       ing the structure.
640
641          $ curl -s http://localhost:8384/rest/db/browse?folder=j663y-3ct3e&prefix=DCIM&levels=2
642          [
643              {
644                  "modTime" : "2020-10-02T23:48:52.076996974+02:00",
645                  "name" : "100ANDRO",
646                  "size" : 128,
647                  "type" : "FILE_INFO_TYPE_DIRECTORY"
648              },
649              {
650                  "children" : [
651                      {
652                          "modTime" : "2020-12-16T23:31:34.5009668+01:00",
653                          "name" : "IMG_20201114_124821.jpg",
654                          "size" : 10682189,
655                          "type" : "FILE_INFO_TYPE_FILE"
656                      },
657                      {
658                          "modTime" : "2020-12-16T23:31:35.0106367+01:00",
659                          "name" : "IMG_20201213_122451.jpg",
660                          "size" : 7936351,
661                          "type" : "FILE_INFO_TYPE_FILE"
662                      },
663                      {
664                          "modTime" : "2020-12-13T12:25:05.017097469+01:00",
665                          "name" : "IMG_20201213_122504.jpg",
666                          "size" : 8406507,
667                          "type" : "FILE_INFO_TYPE_FILE"
668                      },
669                      {
670                          "modTime" : "2020-12-13T12:25:06.127097469+01:00",
671                          "name" : "IMG_20201213_122505.jpg",
672                          "size" : 8381931,
673                          "type" : "FILE_INFO_TYPE_FILE"
674                      },
675                      {
676                          "modTime" : "2020-12-13T12:53:29.707298401+01:00",
677                          "name" : "IMG_20201213_125329.jpg",
678                          "size" : 4388331,
679                          "type" : "FILE_INFO_TYPE_FILE"
680                      },
681                  ],
682                  "modTime" : "2020-10-09T13:04:42.4410738+02:00",
683                  "name" : "Camera",
684                  "size" : 128,
685                  "type" : "FILE_INFO_TYPE_DIRECTORY"
686              },
687          ]
688
689       NOTE:
690          This  is  an  expensive  call,  increasing  CPU and RAM usage on the
691          device. Use sparingly.
692
693   GET /rest/db/completion
694       Returns the completion percentage (0 to 100) and byte  /  item  counts.
695       Takes optional device and folder parameters:
696
697       · folder  specifies the folder ID to calculate completion for. An empty
698         or absent folder parameter means all folders as an aggregate.
699
700       · device specifies the device ID to calculate completion for. An  empty
701         or absent device parameter means the local device.
702
703       If  a  device  is specified but no folder, completion is calculated for
704       all folders shared with that device.
705
706   Example Queries
707       Completion status for folder abcd-1234 on device I6KAH76-...-3PSROAU:
708
709          /rest/db/completion?folder=abcd-1234&device=I6KAH76-...-3PSROAU
710
711       Aggregated completion status for device I6KAH76-...-3PSROAU (all  fold‐
712       ers shared with them):
713
714          /rest/db/completion?device=I6KAH76-...-3PSROAU
715
716       Completion status for folder abcd-1234 on the local device:
717
718          /rest/db/completion?folder=abcd-1234
719
720       Aggregated completion status for all folders on the local device:
721
722          /rest/db/completion
723
724   Example Response
725          {
726            "completion": 99.9937565835,
727            "globalBytes": 156793013575,
728            "needBytes": 9789241,
729            "globalItems": 7823,
730            "needItems": 412,
731            "needDeletes": 0
732          }
733
734       New  in  version  1.8.0:  The  ability to aggregate multiple folders by
735       leaving out the folder ID.  Querying data for the local device by leav‐
736       ing  out  the  device  ID.  Returning  the  globalItems  counter in the
737       response.
738
739
740   GET /rest/db/file
741       Returns most data available about a given file, including  version  and
742       availability. Takes folder and file parameters.
743
744          {
745            "availability": [
746              {
747                "id": "ITZRNXE-YNROGBZ-HXTH5P7-VK5NYE5-QHRQGE2-7JQ6VNJ-KZUEDIU-5PPR5AM",
748                "fromTemporary": false
749              }
750            ],
751            "global": {
752              "deleted": false,
753              "ignored": false,
754              "invalid": false,
755              "localFlags": 0,
756              "modified": "2018-08-18T12:21:13.836784059+02:00",
757              "modifiedBy": "SYNO4VL",
758              "mustRescan": false,
759              "name": "testfile",
760              "noPermissions": false,
761              "numBlocks": 1,
762              "permissions": "0755",
763              "sequence": 107499,
764              "size": 1234,
765              "type": 0,
766              "version": [
767                "SYNO4VL:1"
768              ]
769            },
770            "local": {
771              "deleted": false,
772              "ignored": false,
773              "invalid": false,
774              "localFlags": 0,
775              "modified": "2018-08-18T12:21:13.836784059+02:00",
776              "modifiedBy": "SYNO4VL",
777              "mustRescan": false,
778              "name": "testfile",
779              "noPermissions": false,
780              "numBlocks": 1,
781              "permissions": "0755",
782              "sequence": 111038,
783              "size": 1234,
784              "type": 0,
785              "version": [
786                "SYNO4VL:1"
787              ]
788            }
789          }
790
791   GET /rest/db/ignores
792       Takes  one  parameter, folder, and returns the content of the .stignore
793       as the ignore field. A second  field,  expanded,  provides  a  list  of
794       strings  which  represent  globbing  patterns  described by gobwas/glob
795       (based on standard wildcards) that match the patterns in .stignore  and
796       all  the includes. If appropriate these globs are prepended by the fol‐
797       lowing modifiers: ! to negate the glob, (?i)  to  do  case  insensitive
798       matching  and  (?d) to enable removing of ignored files in an otherwise
799       empty directory.
800
801          {
802            "ignore": [
803              "(?i)/Backups"
804            ],
805            "expanded": [
806              "(?i)Backups",
807              "(?i)Backups/**"
808            ]
809          }
810
811   POST /rest/db/ignores
812       Expects a format similar to the output of GET call, but only containing
813       the  ignore  field  (expanded  field  should be omitted).  It takes one
814       parameter, folder, and either updates  the  content  of  the  .stignore
815       echoing it back as a response, or returns an error.
816
817   GET /rest/db/need
818       Takes one mandatory parameter, folder, and returns lists of files which
819       are needed by this device in order for it to become in sync.
820
821       Furthermore takes an optional page and perpage  arguments  for  pagina‐
822       tion.   Pagination  happens, across the union of all needed files, that
823       is - across all 3 sections of the response.   For  example,  given  the
824       current need state is as follows:
825
826       1. progress has 15 items
827
828       2. queued has 3 items
829
830       3. rest has 12 items
831
832       If you issue a query with page=1 and perpage=10, only the progress sec‐
833       tion in the response will have 10 items. If you issue a  request  query
834       with  page=2  and  perpage=10,  progress  section  will have the last 5
835       items, queued section will have all 3 items, and rest section will have
836       first 2 items. If you issue a query for page=3 and perpage=10, you will
837       only have the last 10 items of the rest section.
838
839       In all these calls, total will be 30 to indicate the  total  number  of
840       available items.
841
842          {
843            # Files currently being downloaded
844            "progress": [
845              {
846                "flags": "0755",
847                "sequence": 6,
848                "modified": "2015-04-20T23:06:12+09:00",
849                "name": "ls",
850                "size": 34640,
851                "version": [
852                  "5157751870738175669:1"
853                ]
854              }
855            ],
856            # Files queued to be downloaded next (as per array order)
857            "queued": [
858                ...
859            ],
860            # Files to be downloaded after all queued files will be downloaded.
861            # This happens when we start downloading files, and new files get added while we are downloading.
862            "rest": [
863                ...
864            ],
865            "page": 1,
866            "perpage": 100,
867            "total": 2000
868          }
869
870       NOTE:
871          This  is  an  expensive  call,  increasing  CPU and RAM usage on the
872          device. Use sparingly.
873
874   POST /rest/db/override
875       Request override of a send only folder.  Override  means  to  make  the
876       local  version  latest,  overriding changes made on other devices. This
877       API call does nothing if the folder is not a send only folder.
878
879       Takes the mandatory parameter folder (folder ID).
880
881          curl -X POST -H X-API-key:... http://127.0.0.1:8384/rest/db/override?folder=default
882
883   POST /rest/db/prio
884       Moves the file to the top of the download queue.
885
886          curl -X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
887
888       Response contains the same output as GET /rest/db/need
889
890   POST /rest/db/revert
891       New in version 0.14.50.
892
893
894       Request revert of a receive only folder. Reverting a  folder  means  to
895       undo all local changes. This API call does nothing if the folder is not
896       a receive only folder.
897
898       Takes the mandatory parameter folder (folder ID).
899
900          curl -X POST -H X-API-Key:... http://127.0.0.1:8384/rest/db/revert?folder=default
901
902   POST /rest/db/scan
903       Request immediate scan. Takes the optional  parameters  folder  (folder
904       ID), sub (path relative to the folder root) and next (time in seconds).
905       If folder is omitted or empty all folders are scanned. If sub is given,
906       only this path (and children, in case it’s a directory) is scanned. The
907       next argument delays Syncthing’s automated rescan interval for a  given
908       amount of seconds.
909
910       Requesting scan of a path that no longer exists, but previously did, is
911       valid and will result in Syncthing noticing the deletion of the path in
912       question.
913
914       Returns  status  200  and  no content upon success, or status 500 and a
915       plain text error if an error occurred during scanning.
916
917          curl -X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar
918
919   GET /rest/db/status
920       Returns information about the current status of a folder.
921
922       Parameters: folder, the ID of a folder.
923
924          {
925            "globalBytes": 0,
926            "globalDeleted": 0,
927            "globalDirectories": 0,
928            "globalFiles": 0,
929            "globalSymlinks": 0,
930            "globalTotalItems": 0,
931            "ignorePatterns": false,
932            "inSyncBytes": 0,
933            "inSyncFiles": 0,
934            "invalid": "",
935            "localBytes": 0,
936            "localDeleted": 0,
937            "localDirectories": 0,
938            "localFiles": 0,
939            "localSymlinks": 0,
940            "localTotalItems": 0,
941            "needBytes": 0,
942            "needDeletes": 0,
943            "needDirectories": 0,
944            "needFiles": 0,
945            "needSymlinks": 0,
946            "needTotalItems": 0,
947            "pullErrors": 0,
948            "receiveOnlyChangedBytes": 0,
949            "receiveOnlyChangedDeletes": 0,
950            "receiveOnlyChangedDirectories": 0,
951            "receiveOnlyChangedFiles": 0,
952            "receiveOnlyChangedSymlinks": 0,
953            "receiveOnlyTotalItems": 0,
954            "sequence": 0,
955            "state": "idle",
956            "stateChanged": "2018-08-08T07:04:57.301064781+02:00",
957            "version": 0
958          }
959
960       The various fields have the following meaning:
961
962       global*:
963              Data in the cluster latest version.
964
965       inSync*:
966              Data that is locally the same as the cluster latest version.
967
968       local*:
969              Data that is locally present, regardless  of  whether  it’s  the
970              same or different version as the cluster latest version.
971
972       need*: Data that is needed to become up to date with the cluster latest
973              version (i.e., data that is out of sync).
974
975       receiveOnlyChanged*:
976              Data that has changed locally in a receive only folder, and thus
977              not been sent to the cluster.
978
979       invalid:
980              Deprecated, always empty.
981
982       pullErrors:
983              The  number  of  files  that failed to sync during the last sync
984              operations.
985
986       sequence:
987              The current folder sequence number.
988
989       state: The current folder state.
990
991       stateChanged:
992              When the folder state last changed.
993
994       version:
995              Deprecated, equivalent to the sequence number.
996
997       NOTE:
998          This is an expensive call, increasing  CPU  and  RAM  usage  on  the
999          device. Use sparingly.
1000

EVENT ENDPOINTS

1002   GET /rest/events
1003       To receive events, perform a HTTP GET of /rest/events.
1004
1005       To  filter  the  event list, in effect creating a specific subscription
1006       for only the desired  event  types,  add  a  parameter  events=EventTy‐
1007       peA,EventTypeB,... where the event types are any of the event-types.
1008
1009       The optional parameter since=<lastSeenID> sets the ID of the last event
1010       you’ve already seen. Syncthing returns a JSON encoded  array  of  event
1011       objects,  starting  at the event just after the one with this last seen
1012       ID. The default value is 0, which returns all events. There is a  limit
1013       to  the  number of events buffered, so if the rate of events is high or
1014       the time between polling calls is long some  events  might  be  missed.
1015       This can be detected by noting a discontinuity in the event IDs.
1016
1017       If  no new events are produced since <lastSeenID>, the HTTP call blocks
1018       and waits for new events to happen  before  returning.  By  default  it
1019       times out after 60 seconds returning an empty array. The time out dura‐
1020       tion can be customized with the optional parameter timeout=<seconds>.
1021
1022       To receive only a limited number of events, add the limit=<n> parameter
1023       with  a  suitable  value  for  n  and  only  the  last n events will be
1024       returned. This can be used to catch up with the latest event ID after a
1025       disconnection for example: /rest/events?since=0&limit=1.
1026

STATISTICS ENDPOINTS

1028   GET /rest/stats/device
1029       Returns  general statistics about devices. Currently, only contains the
1030       time the device was last seen.
1031
1032          $ curl -s http://localhost:8384/rest/stats/device | json
1033          {
1034            "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
1035              "lastSeen" : "2015-04-18T11:21:31.3256277+01:00"
1036            }
1037          }
1038
1039   GET /rest/stats/folder
1040       Returns general statistics about folders. Currently contains  the  last
1041       scan time and the last synced file.
1042
1043          $ curl -s http://localhost:8384/rest/stats/folder | json
1044          {
1045            "folderid" : {
1046              "lastScan": "2016-06-02T13:28:01.288181412-04:00",
1047              "lastFile" : {
1048                "filename" : "file/name",
1049                  "at" : "2015-04-16T22:04:18.3066971+01:00"
1050                }
1051            }
1052          }
1053

MISC SERVICES ENDPOINTS

1055   GET /rest/svc/deviceid
1056       Verifies  and  formats a device ID. Accepts all currently valid formats
1057       (52 or 56 characters with or without separators, upper or  lower  case,
1058       with  trivial  substitutions).  Takes  one  parameter,  id, and returns
1059       either a valid device ID in modern format, or an error.
1060
1061          $ curl -s http://localhost:8384/rest/svc/deviceid?id=1234 | json
1062          {
1063            "error": "device ID invalid: incorrect length"
1064          }
1065
1066          $ curl -s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m--zjnu2iq-gdr-eydm-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json
1067          {
1068            "id": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2"
1069          }
1070
1071   GET /rest/svc/lang
1072       Returns a list of canonicalized localization codes, as picked  up  from
1073       the Accept-Language header sent by the browser.
1074
1075          ["sv_sv","sv","en_us","en"]
1076
1077   GET /rest/svc/random/string
1078       Returns  a  strong random generated string (alphanumeric) of the speci‐
1079       fied length. Takes the length parameter.
1080
1081          {
1082            "random": "FdPaEaZQ56sXEKYNxpgF"
1083          }
1084
1085   GET /rest/svc/report
1086       Returns the data sent in the anonymous usage report.
1087
1088          {
1089             "folderMaxMiB" : 0,
1090             "platform" : "linux-amd64",
1091             "totMiB" : 0,
1092             "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",
1093             "upgradeAllowedManual" : true,
1094             "totFiles" : 3,
1095             "folderUses" : {
1096                "ignorePerms" : 0,
1097                "autoNormalize" : 0,
1098                "sendonly" : 0,
1099                "ignoreDelete" : 0
1100             },
1101             "memoryUsageMiB" : 13,
1102             "version" : "v0.12.2",
1103             "sha256Perf" : 27.28,
1104             "numFolders" : 2,
1105             "memorySize" : 1992,
1106             "announce" : {
1107                "defaultServersIP" : 0,
1108                "otherServers" : 0,
1109                "globalEnabled" : false,
1110                "defaultServersDNS" : 1,
1111                "localEnabled" : false
1112             },
1113             "usesRateLimit" : false,
1114             "numCPU" : 2,
1115             "uniqueID" : "",
1116             "urVersion" : 2,
1117             "rescanIntvs" : [
1118                60,
1119                60
1120             ],
1121             "numDevices" : 2,
1122             "folderMaxFiles" : 3,
1123             "relays" : {
1124                "defaultServers" : 1,
1125                "enabled" : true,
1126                "otherServers" : 0
1127             },
1128             "deviceUses" : {
1129                "compressMetadata" : 1,
1130                "customCertName" : 0,
1131                "staticAddr" : 1,
1132                "compressAlways" : 0,
1133                "compressNever" : 1,
1134                "introducer" : 0,
1135                "dynamicAddr" : 1
1136             },
1137             "upgradeAllowedAuto" : false
1138          }
1139

AUTHOR

1141       The Syncthing Authors
1142
1144       2014-2019, The Syncthing Authors
1145
1146
1147
1148
1149v1                               Feb 17, 2021            SYNCTHING-REST-API(7)
Impressum