1SYNCTHING-REST-API(7) Syncthing SYNCTHING-REST-API(7)
2
3
4
6 syncthing-rest-api - REST API
7
8 Syncthing exposes a REST interface over HTTP on the GUI port. This is
9 used by the GUI (from Javascript) and can be used by other processes
10 wishing to control Syncthing. In most cases both the input and output
11 data is in JSON format. The interface is subject to change.
12
14 To use the REST API an API key must be set and used. The API key can be
15 generated in the GUI, or set in the configuration/gui/apikey element in
16 the configuration file. To use an API key, set the request header
17 X-API-Key to the API key value. For example, curl -X POST -H
18 "X-API-Key: abc123" http://localhost:8384/rest/... can be used to
19 invoke with curl.
20
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
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
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
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
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
940 The Syncthing Authors
941
943 2014-2019, The Syncthing Authors
944
945
946
947
948v1 Jun 11, 2019 SYNCTHING-REST-API(7)