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.
20

SYSTEM ENDPOINTS

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

DATABASE ENDPOINTS

475   GET /rest/db/browse
476       Returns  the directory tree of the global model. Directories are always
477       JSON objects (map/dictionary), and files are always arrays of modifica‐
478       tion  time  and size. The first integer is the files modification time,
479       and the second integer is the file size.
480
481       The call takes one mandatory folder parameter and two optional  parame‐
482       ters.  Optional  parameter  levels  defines how deep within the tree we
483       want to dwell down (0 based,  defaults  to  unlimited  depth)  Optional
484       parameter prefix defines a prefix within the tree where to start build‐
485       ing the structure.
486
487          $ curl -s http://localhost:8384/rest/db/browse?folder=default | json_pp
488          {
489             "directory": {
490                "file": ["2015-04-20T22:20:45+09:00", 130940928],
491                "subdirectory": {
492                   "another file": ["2015-04-20T22:20:45+09:00", 130940928]
493                }
494             },
495             "rootfile": ["2015-04-20T22:20:45+09:00", 130940928]
496          }
497
498          $ curl -s http://localhost:8384/rest/db/browse?folder=default&levels=0 | json_pp
499          {
500             "directory": {},
501             "rootfile": ["2015-04-20T22:20:45+09:00", 130940928]
502          }
503
504          $ curl -s http://localhost:8384/rest/db/browse?folder=default&levels=1 | json_pp
505          {
506             "directory": {
507                "file": ["2015-04-20T22:20:45+09:00", 130940928],
508                "subdirectory": {}
509             },
510             "rootfile": ["2015-04-20T22:20:45+09:00", 130940928]
511          }
512
513          $ curl -s http://localhost:8384/rest/db/browse?folder=default&prefix=directory/subdirectory | json_pp
514          {
515             "another file": ["2015-04-20T22:20:45+09:00", 130940928]
516          }
517
518          $ curl -s http://localhost:8384/rest/db/browse?folder=default&prefix=directory&levels=0 | json_pp
519          {
520             "file": ["2015-04-20T22:20:45+09:00", 130940928],
521             "subdirectory": {}
522          }
523
524       NOTE:
525          This is an expensive call, increasing  CPU  and  RAM  usage  on  the
526          device. Use sparingly.
527
528   GET /rest/db/completion
529       Returns  the  completion  percentage  (0 to 100) for a given device and
530       folder. Takes device and folder parameters.
531
532          {
533            "completion": 100,
534            "globalBytes": 156793013575,
535            "needBytes": 0,
536            "needDeletes": 0
537          }
538
539       NOTE:
540          This is an expensive call, increasing  CPU  and  RAM  usage  on  the
541          device. Use sparingly.
542
543   GET /rest/db/file
544       Returns  most  data available about a given file, including version and
545       availability. Takes folder and file parameters.
546
547          {
548            "availability": [
549              {
550                "id": "ITZRNXE-YNROGBZ-HXTH5P7-VK5NYE5-QHRQGE2-7JQ6VNJ-KZUEDIU-5PPR5AM",
551                "fromTemporary": false
552              }
553            ],
554            "global": {
555              "deleted": false,
556              "ignored": false,
557              "invalid": false,
558              "localFlags": 0,
559              "modified": "2018-08-18T12:21:13.836784059+02:00",
560              "modifiedBy": "SYNO4VL",
561              "mustRescan": false,
562              "name": "testfile",
563              "noPermissions": false,
564              "numBlocks": 1,
565              "permissions": "0755",
566              "sequence": 107499,
567              "size": 1234,
568              "type": 0,
569              "version": [
570                "SYNO4VL:1"
571              ]
572            },
573            "local": {
574              "deleted": false,
575              "ignored": false,
576              "invalid": false,
577              "localFlags": 0,
578              "modified": "2018-08-18T12:21:13.836784059+02:00",
579              "modifiedBy": "SYNO4VL",
580              "mustRescan": false,
581              "name": "testfile",
582              "noPermissions": false,
583              "numBlocks": 1,
584              "permissions": "0755",
585              "sequence": 111038,
586              "size": 1234,
587              "type": 0,
588              "version": [
589                "SYNO4VL:1"
590              ]
591            }
592          }
593
594   GET /rest/db/ignores
595       Takes one parameter, folder, and returns the content of  the  .stignore
596       as  the  ignore  field.  A  second  field, expanded, provides a list of
597       strings which represent  globbing  patterns  described  by  gobwas/glob
598       (based  on standard wildcards) that match the patterns in .stignore and
599       all the includes. If appropriate these globs are prepended by the  fol‐
600       lowing  modifiers:  !  to  negate the glob, (?i) to do case insensitive
601       matching and (?d) to enable removing of ignored files in  an  otherwise
602       empty directory.
603
604          {
605            "ignore": [
606              "(?i)/Backups"
607            ],
608            "expanded": [
609              "(?i)Backups",
610              "(?i)Backups/**"
611            ]
612          }
613
614   POST /rest/db/ignores
615       Expects a format similar to the output of GET call, but only containing
616       the ignore field (expanded field should  be  omitted).   It  takes  one
617       parameter,  folder,  and  either  updates  the content of the .stignore
618       echoing it back as a response, or returns an error.
619
620   GET /rest/db/need
621       Takes one mandatory parameter, folder, and returns lists of files which
622       are needed by this device in order for it to become in sync.
623
624       Furthermore  takes  an  optional page and perpage arguments for pagina‐
625       tion.  Pagination happens, across the union of all needed  files,  that
626       is  -  across  all  3 sections of the response.  For example, given the
627       current need state is as follows:
628
629       1. progress has 15 items
630
631       2. queued has 3 items
632
633       3. rest has 12 items
634
635       If you issue a query with page=1 and perpage=10, only the progress sec‐
636       tion  in  the response will have 10 items. If you issue a request query
637       with page=2 and perpage=10, progress  section  will  have  the  last  5
638       items, queued section will have all 3 items, and rest section will have
639       first 2 items. If you issue a query for page=3 and perpage=10, you will
640       only have the last 10 items of the rest section.
641
642       In  all  these  calls, total will be 30 to indicate the total number of
643       available items.
644
645          {
646            # Files currently being downloaded
647            "progress": [
648              {
649                "flags": "0755",
650                "sequence": 6,
651                "modified": "2015-04-20T23:06:12+09:00",
652                "name": "ls",
653                "size": 34640,
654                "version": [
655                  "5157751870738175669:1"
656                ]
657              }
658            ],
659            # Files queued to be downloaded next (as per array order)
660            "queued": [
661                ...
662            ],
663            # Files to be downloaded after all queued files will be downloaded.
664            # This happens when we start downloading files, and new files get added while we are downloading.
665            "rest": [
666                ...
667            ],
668            "page": 1,
669            "perpage": 100,
670            "total": 2000
671          }
672
673       NOTE:
674          This is an expensive call, increasing  CPU  and  RAM  usage  on  the
675          device. Use sparingly.
676
677   POST /rest/db/override
678       Request  override  of  a  send  only folder. Override means to make the
679       local version latest, overriding changes made on  other  devices.  This
680       API call does nothing if the folder is not a send only folder.
681
682       Takes the mandatory parameter folder (folder ID).
683
684          curl -X POST -H X-API-key:... http://127.0.0.1:8384/rest/db/override?folder=default
685
686   POST /rest/db/prio
687       Moves the file to the top of the download queue.
688
689          curl -X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
690
691       Response contains the same output as GET /rest/db/need
692
693   POST /rest/db/revert
694       New in version 0.14.50.
695
696
697       Request  revert  of  a receive only folder. Reverting a folder means to
698       undo all local changes. This API call does nothing if the folder is not
699       a receive only folder.
700
701       Takes the mandatory parameter folder (folder ID).
702
703          curl -X POST -H X-API-Key:... http://127.0.0.1:8384/rest/db/revert?folder=default
704
705   POST /rest/db/scan
706       Request  immediate  scan.  Takes the optional parameters folder (folder
707       ID), sub (path relative to the folder root) and next (time in seconds).
708       If folder is omitted or empty all folders are scanned. If sub is given,
709       only this path (and children, in case it’s a directory) is scanned. The
710       next  argument delays Syncthing’s automated rescan interval for a given
711       amount of seconds.
712
713       Requesting scan of a path that no longer exists, but previously did, is
714       valid and will result in Syncthing noticing the deletion of the path in
715       question.
716
717       Returns status 200 and no content upon success, or  status  500  and  a
718       plain text error if an error occurred during scanning.
719
720          curl -X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar
721
722   GET /rest/db/status
723       Returns information about the current status of a folder.
724
725       Parameters: folder, the ID of a folder.
726
727          {
728            "globalBytes": 0,
729            "globalDeleted": 0,
730            "globalDirectories": 0,
731            "globalFiles": 0,
732            "globalSymlinks": 0,
733            "ignorePatterns": false,
734            "inSyncBytes": 0,
735            "inSyncFiles": 0,
736            "invalid": "",
737            "localBytes": 0,
738            "localDeleted": 0,
739            "localDirectories": 0,
740            "localFiles": 0,
741            "localSymlinks": 0,
742            "needBytes": 0,
743            "needDeletes": 0,
744            "needDirectories": 0,
745            "needFiles": 0,
746            "needSymlinks": 0,
747            "pullErrors": 0,
748            "receiveOnlyChangedBytes": 0,
749            "receiveOnlyChangedDeletes": 0,
750            "receiveOnlyChangedDirectories": 0,
751            "receiveOnlyChangedFiles": 0,
752            "receiveOnlyChangedSymlinks": 0,
753            "sequence": 0,
754            "state": "idle",
755            "stateChanged": "2018-08-08T07:04:57.301064781+02:00",
756            "version": 0
757          }
758
759       The various fields have the following meaning:
760
761       global*:
762              Data in the cluster latest version.
763
764       inSync*:
765              Data that is locally the same as the cluster latest version.
766
767       local*:
768              Data  that  is  locally  present, regardless of whether it’s the
769              same or different version as the cluster latest version.
770
771       need*: Data that is needed to become up to date with the cluster latest
772              version (i.e., data that is out of sync).
773
774       receiveOnlyChanged*:
775              Data that has changed locally in a receive only folder, and thus
776              not been sent to the cluster.
777
778       invalid:
779              Deprecated, always empty.
780
781       pullErrors:
782              The number of files that failed to sync  during  the  last  sync
783              operations.
784
785       sequence:
786              The current folder sequence number.
787
788       state: The current folder state.
789
790       stateChanged:
791              When the folder state last changed.
792
793       version:
794              Deprecated, equivalent to the sequence number.
795
796       NOTE:
797          This  is  an  expensive  call,  increasing  CPU and RAM usage on the
798          device. Use sparingly.
799

EVENT ENDPOINTS

801   GET /rest/events
802       To receive events, perform a HTTP GET of /rest/events.
803
804       To filter the event list, in effect creating  a  specific  subscription
805       for  only  the  desired  event  types,  add a parameter events=EventTy‐
806       peA,EventTypeB,... where the event types are any of the event-types.
807
808       The optional parameter since=<lastSeenID> sets the ID of the last event
809       you’ve  already  seen.  Syncthing returns a JSON encoded array of event
810       objects, starting at the event just after the one with this  last  seen
811       ID.  The default value is 0, which returns all events. There is a limit
812       to the number of events buffered, so if the rate of events is  high  or
813       the  time  between  polling  calls is long some events might be missed.
814       This can be detected by noting a discontinuity in the event IDs.
815
816       If no new events are produced since <lastSeenID>, the HTTP call  blocks
817       and  waits  for  new  events  to happen before returning. By default it
818       times out after 60 seconds returning an empty array. The time out dura‐
819       tion can be customized with the optional parameter timeout=seconds.
820
821       To  receive  only a limited number of events, add the limit=n parameter
822       with a suitable value for  n  and  only  the  last  n  events  will  be
823       returned. This can be used to catch up with the latest event ID after a
824       disconnection for example: /rest/events?since=0&limit=1.
825

STATISTICS ENDPOINTS

827   GET /rest/stats/device
828       Returns general statistics about devices. Currently, only contains  the
829       time the device was last seen.
830
831          $ curl -s http://localhost:8384/rest/stats/device | json
832          {
833            "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
834              "lastSeen" : "2015-04-18T11:21:31.3256277+01:00"
835            }
836          }
837
838   GET /rest/stats/folder
839       Returns  general  statistics about folders. Currently contains the last
840       scan time and the last synced file.
841
842          $ curl -s http://localhost:8384/rest/stats/folder | json
843          {
844            "folderid" : {
845              "lastScan": "2016-06-02T13:28:01.288181412-04:00",
846              "lastFile" : {
847                "filename" : "file/name",
848                  "at" : "2015-04-16T22:04:18.3066971+01:00"
849                }
850            }
851          }
852

MISC SERVICES ENDPOINTS

854   GET /rest/svc/deviceid
855       Verifies and formats a device ID. Accepts all currently  valid  formats
856       (52  or  56 characters with or without separators, upper or lower case,
857       with trivial substitutions).  Takes  one  parameter,  id,  and  returns
858       either a valid device ID in modern format, or an error.
859
860          $ curl -s http://localhost:8384/rest/svc/deviceid?id=1234 | json
861          {
862            "error": "device ID invalid: incorrect length"
863          }
864
865          $ curl -s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m--zjnu2iq-gdr-eydm-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json
866          {
867            "id": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2"
868          }
869
870   GET /rest/svc/lang
871       Returns  a  list of canonicalized localization codes, as picked up from
872       the Accept-Language header sent by the browser.
873
874          ["sv_sv","sv","en_us","en"]
875
876   GET /rest/svc/random/string
877       Returns a strong random generated string (alphanumeric) of  the  speci‐
878       fied length. Takes the length parameter.
879
880          {
881            "random": "FdPaEaZQ56sXEKYNxpgF"
882          }
883
884   GET /rest/svc/report
885       Returns the data sent in the anonymous usage report.
886
887          {
888             "folderMaxMiB" : 0,
889             "platform" : "linux-amd64",
890             "totMiB" : 0,
891             "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",
892             "upgradeAllowedManual" : true,
893             "totFiles" : 3,
894             "folderUses" : {
895                "ignorePerms" : 0,
896                "autoNormalize" : 0,
897                "sendonly" : 0,
898                "ignoreDelete" : 0
899             },
900             "memoryUsageMiB" : 13,
901             "version" : "v0.12.2",
902             "sha256Perf" : 27.28,
903             "numFolders" : 2,
904             "memorySize" : 1992,
905             "announce" : {
906                "defaultServersIP" : 0,
907                "otherServers" : 0,
908                "globalEnabled" : false,
909                "defaultServersDNS" : 1,
910                "localEnabled" : false
911             },
912             "usesRateLimit" : false,
913             "numCPU" : 2,
914             "uniqueID" : "",
915             "urVersion" : 2,
916             "rescanIntvs" : [
917                60,
918                60
919             ],
920             "numDevices" : 2,
921             "folderMaxFiles" : 3,
922             "relays" : {
923                "defaultServers" : 1,
924                "enabled" : true,
925                "otherServers" : 0
926             },
927             "deviceUses" : {
928                "compressMetadata" : 1,
929                "customCertName" : 0,
930                "staticAddr" : 1,
931                "compressAlways" : 0,
932                "compressNever" : 1,
933                "introducer" : 0,
934                "dynamicAddr" : 1
935             },
936             "upgradeAllowedAuto" : false
937          }
938

AUTHOR

940       The Syncthing Authors
941
943       2014-2019, The Syncthing Authors
944
945
946
947
948v1                               Jun 11, 2019            SYNCTHING-REST-API(7)
Impressum