1SYNCTHING-REST-API(7) Syncthing SYNCTHING-REST-API(7)
2
6 syncthing-rest-api - REST API
7 Syncthing exposes a REST interface over HTTP on the GUI port. This is
9 used by the GUI (from Javascript) and can be used by other processes
10 wishing to control Syncthing. In most cases both the input and output
11 data is in JSON format. The interface is subject to change.
12
14 To use the REST API an API key must be set and used. The API key can be
15 generated in the GUI, or set in the configuration/gui/apikey element in
16 the configuration file. To use an API key, set the request header
17 X-API-Key to the API key value. For example, curl -X POST -H
18 "X-API-Key: abc123" http://localhost:8384/rest/... can be used to
19 invoke with curl (add -k flag when using HTTPS with a Syncthing gener‐
20 ated or self signed certificate).
21
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 $ curl -H "X-API-Key: yourkey" localhost:8384/rest/system/browse | json_pp
32 [
33 "/"
34 ]
35 $ 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 $ 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 GET /rest/system/config
61 Returns the current configuration.
62 {
64 {
65 "version": 15,
66 "folders": [
67 {
68 "id": "GXWxf-3zgnU",
69 "label": "MyFolder",
70 "path": "...",
71 "type": "sendreceive",
72 "devices": [
73 {
74 "deviceID": "..."
75 }
76 ],
77 "rescanIntervalS": 60,
78 "ignorePerms": false,
79 "autoNormalize": true,
80 "minDiskFreePct": 1,
81 "versioning": {
82 "type": "simple",
83 "params": {
84 "keep": "5"
85 }
86 },
87 "copiers": 0,
88 "pullers": 0,
89 "hashers": 0,
90 "order": "random",
91 "ignoreDelete": false,
92 "scanProgressIntervalS": 0,
93 "pullerSleepS": 0,
94 "pullerPauseS": 0,
95 "maxConflicts": 10,
96 "disableSparseFiles": false,
97 "disableTempIndexes": false,
98 "fsync": false,
99 "invalid": ""
100 }
101 ],
102 "devices": [
103 {
104 "deviceID": "...",
105 "name": "Laptop",
106 "addresses": [
107 "dynamic",
108 "tcp://192.168.1.2:22000"
109 ],
110 "compression": "metadata",
111 "certName": "",
112 "introducer": false
113 }
114 ],
115 "gui": {
116 "enabled": true,
117 "address": "127.0.0.1:8384",
118 "user": "Username",
119 "password": "$2a$10$ZFws69T4FlvWwsqeIwL.TOo5zOYqsa/.TxlUnsGYS.j3JvjFTmxo6",
120 "useTLS": false,
121 "apiKey": "pGahcht56664QU5eoFQW6szbEG6Ec2Cr",
122 "insecureAdminAccess": false,
123 "theme": "default"
124 },
125 "options": {
126 "listenAddresses": [
127 "default"
128 ],
129 "globalAnnounceServers": [
130 "default"
131 ],
132 "globalAnnounceEnabled": true,
133 "localAnnounceEnabled": true,
134 "localAnnouncePort": 21027,
135 "localAnnounceMCAddr": "[ff12::8384]:21027",
136 "maxSendKbps": 0,
137 "maxRecvKbps": 0,
138 "reconnectionIntervalS": 60,
139 "relaysEnabled": true,
140 "relayReconnectIntervalM": 10,
141 "startBrowser": false,
142 "natEnabled": true,
143 "natLeaseMinutes": 60,
144 "natRenewalMinutes": 30,
145 "natTimeoutSeconds": 10,
146 "urAccepted": -1,
147 "urUniqueId": "",
148 "urURL": "https://data.syncthing.net/newdata",
149 "urPostInsecurely": false,
150 "urInitialDelayS": 1800,
151 "restartOnWakeup": true,
152 "autoUpgradeIntervalH": 12,
153 "keepTemporariesH": 24,
154 "cacheIgnoredFiles": false,
155 "progressUpdateIntervalS": 5,
156 "limitBandwidthInLan": false,
157 "minHomeDiskFreePct": 1,
158 "releasesURL": "https://upgrades.syncthing.net/meta.json",
159 "alwaysLocalNets": [],
160 "overwriteRemoteDeviceNamesOnConnect": false,
161 "tempIndexMinBlocks": 10
162 },
163 "ignoredDevices": [],
164 "ignoredFolders": []
165 }
166 }
167 GET /rest/system/config/insync
169 Returns whether the config is in sync, i.e. whether the running config‐
170 uration is the same as that on disk.
171 {
173 "configInSync": true
174 }
175 POST /rest/system/config
177 Post the full contents of the configuration, in the same format as
178 returned by the corresponding GET request. When posting the configura‐
179 tion succeeds, the posted configuration is immediately applied, except
180 for changes that require a restart. Query rest-config-insync to check
181 if a restart is required.
182 This endpoint is the main point to control Syncthing, even if the
184 change only concerns a very small part of the config: The usual work‐
185 flow is to get the config, modify the needed parts and post it again.
186 GET /rest/system/connections
188 NOTE:
189 Return format changed in 0.13.0.
190 Returns the list of configured devices and some metadata associated
192 with them. The list also contains the local device itself as not con‐
193 nected.
194 The connection types are TCP (Client), TCP (Server), Relay (Client) and
196 Relay (Server).
197 {
199 "total" : {
200 "paused" : false,
201 "clientVersion" : "",
202 "at" : "2015-11-07T17:29:47.691637262+01:00",
203 "connected" : false,
204 "inBytesTotal" : 1479,
205 "type" : "",
206 "outBytesTotal" : 1318,
207 "address" : ""
208 },
209 "connections" : {
210 "YZJBJFX-RDBL7WY-6ZGKJ2D-4MJB4E7-ZATSDUY-LD6Y3L3-MLFUYWE-AEMXJAC" : {
211 "connected" : true,
212 "inBytesTotal" : 556,
213 "paused" : false,
214 "at" : "2015-11-07T17:29:47.691548971+01:00",
215 "clientVersion" : "v0.12.1",
216 "address" : "127.0.0.1:22002",
217 "type" : "TCP (Client)",
218 "outBytesTotal" : 550
219 },
220 "DOVII4U-SQEEESM-VZ2CVTC-CJM4YN5-QNV7DCU-5U3ASRL-YVFG6TH-W5DV5AA" : {
221 "outBytesTotal" : 0,
222 "type" : "",
223 "address" : "",
224 "at" : "0001-01-01T00:00:00Z",
225 "clientVersion" : "",
226 "paused" : false,
227 "inBytesTotal" : 0,
228 "connected" : false
229 },
230 "UYGDMA4-TPHOFO5-2VQYDCC-7CWX7XW-INZINQT-LE4B42N-4JUZTSM-IWCSXA4" : {
231 "address" : "",
232 "type" : "",
233 "outBytesTotal" : 0,
234 "connected" : false,
235 "inBytesTotal" : 0,
236 "paused" : false,
237 "at" : "0001-01-01T00:00:00Z",
238 "clientVersion" : ""
239 }
240 }
241 }
242 GET /rest/system/debug
244 New in version 0.12.0.
245 Returns the set of debug facilities and which of them are currently
248 enabled.
249 {
251 "enabled": [
252 "beacon"
253 ],
254 "facilities": {
255 "beacon": "Multicast and broadcast discovery",
256 "config": "Configuration loading and saving",
257 "connections": "Connection handling",
258 "db": "The database layer",
259 "dialer": "Dialing connections",
260 "discover": "Remote device discovery",
261 "events": "Event generation and logging",
262 "http": "REST API",
263 "main": "Main package",
264 "model": "The root hub",
265 "protocol": "The BEP protocol",
266 "relay": "Relay connection handling",
267 "scanner": "File change detection and hashing",
268 "stats": "Persistent device and folder statistics",
269 "sync": "Mutexes",
270 "upgrade": "Binary upgrades",
271 "upnp": "UPnP discovery and port mapping",
272 "versioner": "File versioning"
273 }
274 }
275 POST /rest/system/debug
277 New in version 0.12.0.
278 Enables or disables debugging for specified facilities. Give one or
281 both of enable and disable query parameters, with comma separated
282 facility names. To disable debugging of the beacon and discovery pack‐
283 ages, and enable it for config and db:
284 $ curl -H X-API-Key:abc123 -X POST 'http://localhost:8384/rest/system/debug?disable=beacon,discovery&enable=config,db'
286 GET /rest/system/discovery
288 Returns the contents of the local discovery cache.
289 {
291 "LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q": [
292 "192.162.129.11:22000"
293 ]
294 }
295 POST /rest/system/discovery
297 NOTE:
298 Removed in v0.12.0.
299 Post with the query parameters device and addr to add entries to the
301 discovery cache.
302 curl -X POST http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\&addr=192.162.129.11:22000
304 # Or with the X-API-Key header:
305 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
306 POST /rest/system/error/clear
308 Post with empty to body to remove all recent errors.
309 GET /rest/system/error
311 NOTE:
312 Return format changed in 0.12.0.
313 Returns the list of recent errors.
315 {
317 "errors": [
318 {
319 "when": "2014-09-18T12:59:26.549953186+02:00",
320 "message": "This is an error string"
321 }
322 ]
323 }
324 POST /rest/system/error
326 Post with an error message in the body (plain text) to register a new
327 error. The new error will be displayed on any active GUI clients.
328 GET /rest/system/log
330 New in version 0.12.0.
331 Returns the list of recent log entries.
334 {
336 "messages": [
337 {
338 "when": "2014-09-18T12:59:26.549953186+02:00",
339 "message": "This is a log entry"
340 }
341 ]
342 }
343 POST /rest/system/pause
345 Pause the given device or all devices.
346 Takes the optional parameter device (device ID). When omitted, pauses
348 all devices. Returns status 200 and no content upon success, or status
349 500 and a plain text error on failure.
350 GET /rest/system/ping
352 Returns a {"ping": "pong"} object.
353 {
355 "ping": "pong"
356 }
357 POST /rest/system/ping
359 Returns a {"ping": "pong"} object.
360 POST /rest/system/reset
362 Post with empty body to erase the current index database and restart
363 Syncthing. With no query parameters, the entire database is erased from
364 disk. By specifying the folder parameter with a valid folder ID, only
365 information for that folder will be erased:
366 $ curl -X POST -H "X-API-Key: abc123" http://localhost:8384/rest/system/reset?folder=default
368 Caution: See -reset-database for .stfolder creation side-effect and
370 caution regarding mountpoints.
371 POST /rest/system/restart
373 Post with empty body to immediately restart Syncthing.
374 POST /rest/system/resume
376 Resume the given device or all devices.
377 Takes the optional parameter device (device ID). When omitted, resumes
379 all devices. Returns status 200 and no content upon success, or status
380 500 and a plain text error on failure.
381 POST /rest/system/shutdown
383 Post with empty body to cause Syncthing to exit and not restart.
384 GET /rest/system/status
386 Returns information about current system status and resource usage. The
387 CPU percent value has been deprecated from the API and will always
388 report 0.
389 {
391 "alloc": 30618136,
392 "connectionServiceStatus": {
393 "dynamic+https://relays.syncthing.net/endpoint": {
394 "error": null,
395 "lanAddresses": [
396 "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"
397 ],
398 "wanAddresses": [
399 "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"
400 ]
401 },
402 "tcp://0.0.0.0:22000": {
403 "error": null,
404 "lanAddresses": [
405 "tcp://0.0.0.0:22000"
406 ],
407 "wanAddresses": [
408 "tcp://0.0.0.0:22000"
409 ]
410 }
411 },
412 "cpuPercent": 0,
413 "discoveryEnabled": true,
414 "discoveryErrors": {
415 "global@https://discovery-v4-1.syncthing.net/v2/": "500 Internal Server Error",
416 "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)",
417 "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)",
418 "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",
419 "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",
420 "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"
421 },
422 "discoveryMethods": 8,
423 "goroutines": 49,
424 "lastDialStatus": {
425 "tcp://10.20.30.40": {
426 "when": "2019-05-16T07:41:23Z",
427 "error": "dial tcp 10.20.30.40:22000: i/o timeout"
428 },
429 "tcp://172.16.33.3:22000": {
430 "when": "2019-05-16T07:40:43Z",
431 "ok": true
432 },
433 "tcp://83.233.120.221:22000": {
434 "when": "2019-05-16T07:41:13Z",
435 "error": "dial tcp 83.233.120.221:22000: connect: connection refused"
436 }
437 },
438 "myID": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2",
439 "pathSeparator": "/",
440 "startTime": "2016-06-06T19:41:43.039284753+02:00",
441 "sys": 42092792,
442 "themes": [
443 "default",
444 "dark"
445 ],
446 "tilde": "/Users/jb",
447 "uptime": 2635
448 }
449 New in version 1.2.0: The lastDialStatus dictionary contains the last
451 error (or null for success) for each peer address that Syncthing has
452 attempted to contact. The connectionServiceStatus entries gained
453 "error": null attributes where previously there would be no error
454 attribute at all in the success case.
455 GET /rest/system/upgrade
458 Checks for a possible upgrade and returns an object describing the new‐
459 est version and upgrade possibility.
460 {
462 "latest": "v0.14.47",
463 "majorNewer": false,
464 "newer": true,
465 "running": "v0.14.46"
466 }
467 POST /rest/system/upgrade
469 Perform an upgrade to the newest released version and restart. Does
470 nothing if there is no newer version than currently running.
471 GET /rest/system/version
473 Returns the current Syncthing version information.
474 {
476 "arch": "amd64",
477 "longVersion": "syncthing v0.10.27+3-gea8c3de (go1.4 darwin-amd64 default) jb@syno 2015-03-16 11:01:29 UTC",
478 "os": "darwin",
479 "version": "v0.10.27+3-gea8c3de"
480 }
481
483 GET /rest/db/browse
484 Returns the directory tree of the global model. Directories are always
485 JSON objects (map/dictionary), and files are always arrays of modifica‐
486 tion time and size. The first integer is the files modification time,
487 and the second integer is the file size.
488 The call takes one mandatory folder parameter and two optional parame‐
490 ters. Optional parameter levels defines how deep within the tree we
491 want to dwell down (0 based, defaults to unlimited depth) Optional
492 parameter prefix defines a prefix within the tree where to start build‐
493 ing the structure.
494 $ curl -s http://localhost:8384/rest/db/browse?folder=default | json_pp
496 {
497 "directory": {
498 "file": ["2015-04-20T22:20:45+09:00", 130940928],
499 "subdirectory": {
500 "another file": ["2015-04-20T22:20:45+09:00", 130940928]
501 }
502 },
503 "rootfile": ["2015-04-20T22:20:45+09:00", 130940928]
504 }
505 $ curl -s http://localhost:8384/rest/db/browse?folder=default&levels=0 | json_pp
507 {
508 "directory": {},
509 "rootfile": ["2015-04-20T22:20:45+09:00", 130940928]
510 }
511 $ curl -s http://localhost:8384/rest/db/browse?folder=default&levels=1 | json_pp
513 {
514 "directory": {
515 "file": ["2015-04-20T22:20:45+09:00", 130940928],
516 "subdirectory": {}
517 },
518 "rootfile": ["2015-04-20T22:20:45+09:00", 130940928]
519 }
520 $ curl -s http://localhost:8384/rest/db/browse?folder=default&prefix=directory/subdirectory | json_pp
522 {
523 "another file": ["2015-04-20T22:20:45+09:00", 130940928]
524 }
525 $ curl -s http://localhost:8384/rest/db/browse?folder=default&prefix=directory&levels=0 | json_pp
527 {
528 "file": ["2015-04-20T22:20:45+09:00", 130940928],
529 "subdirectory": {}
530 }
531 NOTE:
533 This is an expensive call, increasing CPU and RAM usage on the
534 device. Use sparingly.
535 GET /rest/db/completion
537 Returns the completion percentage (0 to 100) for a given device and
538 folder. Takes device and folder parameters.
539 {
541 "completion": 100,
542 "globalBytes": 156793013575,
543 "needBytes": 0,
544 "needDeletes": 0
545 }
546 NOTE:
548 This is an expensive call, increasing CPU and RAM usage on the
549 device. Use sparingly.
550 GET /rest/db/file
552 Returns most data available about a given file, including version and
553 availability. Takes folder and file parameters.
554 {
556 "availability": [
557 {
558 "id": "ITZRNXE-YNROGBZ-HXTH5P7-VK5NYE5-QHRQGE2-7JQ6VNJ-KZUEDIU-5PPR5AM",
559 "fromTemporary": false
560 }
561 ],
562 "global": {
563 "deleted": false,
564 "ignored": false,
565 "invalid": false,
566 "localFlags": 0,
567 "modified": "2018-08-18T12:21:13.836784059+02:00",
568 "modifiedBy": "SYNO4VL",
569 "mustRescan": false,
570 "name": "testfile",
571 "noPermissions": false,
572 "numBlocks": 1,
573 "permissions": "0755",
574 "sequence": 107499,
575 "size": 1234,
576 "type": 0,
577 "version": [
578 "SYNO4VL:1"
579 ]
580 },
581 "local": {
582 "deleted": false,
583 "ignored": false,
584 "invalid": false,
585 "localFlags": 0,
586 "modified": "2018-08-18T12:21:13.836784059+02:00",
587 "modifiedBy": "SYNO4VL",
588 "mustRescan": false,
589 "name": "testfile",
590 "noPermissions": false,
591 "numBlocks": 1,
592 "permissions": "0755",
593 "sequence": 111038,
594 "size": 1234,
595 "type": 0,
596 "version": [
597 "SYNO4VL:1"
598 ]
599 }
600 }
601 GET /rest/db/ignores
603 Takes one parameter, folder, and returns the content of the .stignore
604 as the ignore field. A second field, expanded, provides a list of
605 strings which represent globbing patterns described by gobwas/glob
606 (based on standard wildcards) that match the patterns in .stignore and
607 all the includes. If appropriate these globs are prepended by the fol‐
608 lowing modifiers: ! to negate the glob, (?i) to do case insensitive
609 matching and (?d) to enable removing of ignored files in an otherwise
610 empty directory.
611 {
613 "ignore": [
614 "(?i)/Backups"
615 ],
616 "expanded": [
617 "(?i)Backups",
618 "(?i)Backups/**"
619 ]
620 }
621 POST /rest/db/ignores
623 Expects a format similar to the output of GET call, but only containing
624 the ignore field (expanded field should be omitted). It takes one
625 parameter, folder, and either updates the content of the .stignore
626 echoing it back as a response, or returns an error.
627 GET /rest/db/need
629 Takes one mandatory parameter, folder, and returns lists of files which
630 are needed by this device in order for it to become in sync.
631 Furthermore takes an optional page and perpage arguments for pagina‐
633 tion. Pagination happens, across the union of all needed files, that
634 is - across all 3 sections of the response. For example, given the
635 current need state is as follows:
636 1. progress has 15 items
638 2. queued has 3 items
640 3. rest has 12 items
642 If you issue a query with page=1 and perpage=10, only the progress sec‐
644 tion in the response will have 10 items. If you issue a request query
645 with page=2 and perpage=10, progress section will have the last 5
646 items, queued section will have all 3 items, and rest section will have
647 first 2 items. If you issue a query for page=3 and perpage=10, you will
648 only have the last 10 items of the rest section.
649 In all these calls, total will be 30 to indicate the total number of
651 available items.
652 {
654 # Files currently being downloaded
655 "progress": [
656 {
657 "flags": "0755",
658 "sequence": 6,
659 "modified": "2015-04-20T23:06:12+09:00",
660 "name": "ls",
661 "size": 34640,
662 "version": [
663 "5157751870738175669:1"
664 ]
665 }
666 ],
667 # Files queued to be downloaded next (as per array order)
668 "queued": [
669 ...
670 ],
671 # Files to be downloaded after all queued files will be downloaded.
672 # This happens when we start downloading files, and new files get added while we are downloading.
673 "rest": [
674 ...
675 ],
676 "page": 1,
677 "perpage": 100,
678 "total": 2000
679 }
680 NOTE:
682 This is an expensive call, increasing CPU and RAM usage on the
683 device. Use sparingly.
684 POST /rest/db/override
686 Request override of a send only folder. Override means to make the
687 local version latest, overriding changes made on other devices. This
688 API call does nothing if the folder is not a send only folder.
689 Takes the mandatory parameter folder (folder ID).
691 curl -X POST -H X-API-key:... http://127.0.0.1:8384/rest/db/override?folder=default
693 POST /rest/db/prio
695 Moves the file to the top of the download queue.
696 curl -X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
698 Response contains the same output as GET /rest/db/need
700 POST /rest/db/revert
702 New in version 0.14.50.
703 Request revert of a receive only folder. Reverting a folder means to
706 undo all local changes. This API call does nothing if the folder is not
707 a receive only folder.
708 Takes the mandatory parameter folder (folder ID).
710 curl -X POST -H X-API-Key:... http://127.0.0.1:8384/rest/db/revert?folder=default
712 POST /rest/db/scan
714 Request immediate scan. Takes the optional parameters folder (folder
715 ID), sub (path relative to the folder root) and next (time in seconds).
716 If folder is omitted or empty all folders are scanned. If sub is given,
717 only this path (and children, in case it’s a directory) is scanned. The
718 next argument delays Syncthing’s automated rescan interval for a given
719 amount of seconds.
720 Requesting scan of a path that no longer exists, but previously did, is
722 valid and will result in Syncthing noticing the deletion of the path in
723 question.
724 Returns status 200 and no content upon success, or status 500 and a
726 plain text error if an error occurred during scanning.
727 curl -X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar
729 GET /rest/db/status
731 Returns information about the current status of a folder.
732 Parameters: folder, the ID of a folder.
734 {
736 "globalBytes": 0,
737 "globalDeleted": 0,
738 "globalDirectories": 0,
739 "globalFiles": 0,
740 "globalSymlinks": 0,
741 "ignorePatterns": false,
742 "inSyncBytes": 0,
743 "inSyncFiles": 0,
744 "invalid": "",
745 "localBytes": 0,
746 "localDeleted": 0,
747 "localDirectories": 0,
748 "localFiles": 0,
749 "localSymlinks": 0,
750 "needBytes": 0,
751 "needDeletes": 0,
752 "needDirectories": 0,
753 "needFiles": 0,
754 "needSymlinks": 0,
755 "pullErrors": 0,
756 "receiveOnlyChangedBytes": 0,
757 "receiveOnlyChangedDeletes": 0,
758 "receiveOnlyChangedDirectories": 0,
759 "receiveOnlyChangedFiles": 0,
760 "receiveOnlyChangedSymlinks": 0,
761 "sequence": 0,
762 "state": "idle",
763 "stateChanged": "2018-08-08T07:04:57.301064781+02:00",
764 "version": 0
765 }
766 The various fields have the following meaning:
768 global*:
770 Data in the cluster latest version.
771 inSync*:
773 Data that is locally the same as the cluster latest version.
774 local*:
776 Data that is locally present, regardless of whether it’s the
777 same or different version as the cluster latest version.
778 need*: Data that is needed to become up to date with the cluster latest
780 version (i.e., data that is out of sync).
781 receiveOnlyChanged*:
783 Data that has changed locally in a receive only folder, and thus
784 not been sent to the cluster.
785 invalid:
787 Deprecated, always empty.
788 pullErrors:
790 The number of files that failed to sync during the last sync
791 operations.
792 sequence:
794 The current folder sequence number.
795 state: The current folder state.
797 stateChanged:
799 When the folder state last changed.
800 version:
802 Deprecated, equivalent to the sequence number.
803 NOTE:
805 This is an expensive call, increasing CPU and RAM usage on the
806 device. Use sparingly.
807
809 GET /rest/events
810 To receive events, perform a HTTP GET of /rest/events.
811 To filter the event list, in effect creating a specific subscription
813 for only the desired event types, add a parameter events=EventTy‐
814 peA,EventTypeB,... where the event types are any of the event-types.
815 The optional parameter since=<lastSeenID> sets the ID of the last event
817 you’ve already seen. Syncthing returns a JSON encoded array of event
818 objects, starting at the event just after the one with this last seen
819 ID. The default value is 0, which returns all events. There is a limit
820 to the number of events buffered, so if the rate of events is high or
821 the time between polling calls is long some events might be missed.
822 This can be detected by noting a discontinuity in the event IDs.
823 If no new events are produced since <lastSeenID>, the HTTP call blocks
825 and waits for new events to happen before returning. By default it
826 times out after 60 seconds returning an empty array. The time out dura‐
827 tion can be customized with the optional parameter timeout=<seconds>.
828 To receive only a limited number of events, add the limit=<n> parameter
830 with a suitable value for n and only the last n events will be
831 returned. This can be used to catch up with the latest event ID after a
832 disconnection for example: /rest/events?since=0&limit=1.
833
835 GET /rest/stats/device
836 Returns general statistics about devices. Currently, only contains the
837 time the device was last seen.
838 $ curl -s http://localhost:8384/rest/stats/device | json
840 {
841 "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
842 "lastSeen" : "2015-04-18T11:21:31.3256277+01:00"
843 }
844 }
845 GET /rest/stats/folder
847 Returns general statistics about folders. Currently contains the last
848 scan time and the last synced file.
849 $ curl -s http://localhost:8384/rest/stats/folder | json
851 {
852 "folderid" : {
853 "lastScan": "2016-06-02T13:28:01.288181412-04:00",
854 "lastFile" : {
855 "filename" : "file/name",
856 "at" : "2015-04-16T22:04:18.3066971+01:00"
857 }
858 }
859 }
860
862 GET /rest/svc/deviceid
863 Verifies and formats a device ID. Accepts all currently valid formats
864 (52 or 56 characters with or without separators, upper or lower case,
865 with trivial substitutions). Takes one parameter, id, and returns
866 either a valid device ID in modern format, or an error.
867 $ curl -s http://localhost:8384/rest/svc/deviceid?id=1234 | json
869 {
870 "error": "device ID invalid: incorrect length"
871 }
872 $ curl -s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m--zjnu2iq-gdr-eydm-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json
874 {
875 "id": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2"
876 }
877 GET /rest/svc/lang
879 Returns a list of canonicalized localization codes, as picked up from
880 the Accept-Language header sent by the browser.
881 ["sv_sv","sv","en_us","en"]
883 GET /rest/svc/random/string
885 Returns a strong random generated string (alphanumeric) of the speci‐
886 fied length. Takes the length parameter.
887 {
889 "random": "FdPaEaZQ56sXEKYNxpgF"
890 }
891 GET /rest/svc/report
893 Returns the data sent in the anonymous usage report.
894 {
896 "folderMaxMiB" : 0,
897 "platform" : "linux-amd64",
898 "totMiB" : 0,
899 "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",
900 "upgradeAllowedManual" : true,
901 "totFiles" : 3,
902 "folderUses" : {
903 "ignorePerms" : 0,
904 "autoNormalize" : 0,
905 "sendonly" : 0,
906 "ignoreDelete" : 0
907 },
908 "memoryUsageMiB" : 13,
909 "version" : "v0.12.2",
910 "sha256Perf" : 27.28,
911 "numFolders" : 2,
912 "memorySize" : 1992,
913 "announce" : {
914 "defaultServersIP" : 0,
915 "otherServers" : 0,
916 "globalEnabled" : false,
917 "defaultServersDNS" : 1,
918 "localEnabled" : false
919 },
920 "usesRateLimit" : false,
921 "numCPU" : 2,
922 "uniqueID" : "",
923 "urVersion" : 2,
924 "rescanIntvs" : [
925 60,
926 60
927 ],
928 "numDevices" : 2,
929 "folderMaxFiles" : 3,
930 "relays" : {
931 "defaultServers" : 1,
932 "enabled" : true,
933 "otherServers" : 0
934 },
935 "deviceUses" : {
936 "compressMetadata" : 1,
937 "customCertName" : 0,
938 "staticAddr" : 1,
939 "compressAlways" : 0,
940 "compressNever" : 1,
941 "introducer" : 0,
942 "dynamicAddr" : 1
943 },
944 "upgradeAllowedAuto" : false
945 }
946
948 The Syncthing Authors
949
951 2014-2019, The Syncthing Authors
952v1 Mar 17, 2020 SYNCTHING-REST-API(7)