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.
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 $ curl -H "X-API-Key: yourkey" localhost:8384/rest/system/browse | json_pp
31 [
32 "/"
33 ]
34 $ 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 $ 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 GET /rest/system/config
60 Returns the current configuration.
61 {
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 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 {
172 "configInSync": true
173 }
174 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 GET /rest/system/connections
182 NOTE:
183 Return format changed in 0.13.0.
184 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 The connection types are TCP (Client), TCP (Server), Relay (Client) and
190 Relay (Server).
191 {
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 GET /rest/system/debug
238 New in version 0.12.0.
239 Returns the set of debug facilities and which of them are currently
242 enabled.
243 {
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 POST /rest/system/debug
271 New in version 0.12.0.
272 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 $ curl -H X-API-Key:abc123 -X POST 'http://localhost:8384/rest/system/debug?disable=beacon,discovery&enable=config,db'
280 GET /rest/system/discovery
282 Returns the contents of the local discovery cache.
283 {
285 "LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q": [
286 "192.162.129.11:22000"
287 ]
288 }
289 POST /rest/system/discovery
291 NOTE:
292 Removed in v0.12.0.
293 Post with the query parameters device and addr to add entries to the
295 discovery cache.
296 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 POST /rest/system/error/clear
302 Post with empty to body to remove all recent errors.
303 GET /rest/system/error
305 NOTE:
306 Return format changed in 0.12.0.
307 Returns the list of recent errors.
309 {
311 "errors": [
312 {
313 "when": "2014-09-18T12:59:26.549953186+02:00",
314 "message": "This is an error string"
315 }
316 ]
317 }
318 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 GET /rest/system/log
324 New in version 0.12.0.
325 Returns the list of recent log entries.
328 {
330 "messages": [
331 {
332 "when": "2014-09-18T12:59:26.549953186+02:00",
333 "message": "This is a log entry"
334 }
335 ]
336 }
337 POST /rest/system/pause
339 Pause the given device or all devices.
340 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 GET /rest/system/ping
346 Returns a {"ping": "pong"} object.
347 {
349 "ping": "pong"
350 }
351 POST /rest/system/ping
353 Returns a {"ping": "pong"} object.
354 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 $ curl -X POST -H "X-API-Key: abc123" http://localhost:8384/rest/system/reset?folder=default
362 Caution: See -reset-database for .stfolder creation side-effect and
364 caution regarding mountpoints.
365 POST /rest/system/restart
367 Post with empty body to immediately restart Syncthing.
368 POST /rest/system/resume
370 Resume the given device or all devices.
371 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 POST /rest/system/shutdown
377 Post with empty body to cause Syncthing to exit and not restart.
378 GET /rest/system/status
380 Returns information about current system status and resource usage.
381 {
383 "alloc": 30618136,
384 "connectionServiceStatus": {
385 "dynamic+https://relays.syncthing.net/endpoint": {
386 "lanAddresses": [
387 "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"
388 ],
389 "wanAddresses": [
390 "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"
391 ]
392 },
393 "tcp://0.0.0.0:22000": {
394 "lanAddresses": [
395 "tcp://0.0.0.0:22000"
396 ],
397 "wanAddresses": [
398 "tcp://0.0.0.0:22000"
399 ]
400 }
401 },
402 "cpuPercent": 0.006944836512046966,
403 "discoveryEnabled": true,
404 "discoveryErrors": {
405 "global@https://discovery-v4-1.syncthing.net/v2/": "500 Internal Server Error",
406 "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)",
407 "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)",
408 "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",
409 "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",
410 "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"
411 },
412 "discoveryMethods": 8,
413 "goroutines": 49,
414 "myID": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2",
415 "pathSeparator": "/",
416 "startTime": "2016-06-06T19:41:43.039284753+02:00",
417 "sys": 42092792,
418 "themes": [
419 "default",
420 "dark"
421 ],
422 "tilde": "/Users/jb",
423 "uptime": 2635
424 }
425 GET /rest/system/upgrade
427 Checks for a possible upgrade and returns an object describing the new‐
428 est version and upgrade possibility.
429 {
431 "latest": "v0.14.47",
432 "majorNewer": false,
433 "newer": true,
434 "running": "v0.14.46"
435 }
436 POST /rest/system/upgrade
438 Perform an upgrade to the newest released version and restart. Does
439 nothing if there is no newer version than currently running.
440 GET /rest/system/version
442 Returns the current Syncthing version information.
443 {
445 "arch": "amd64",
446 "longVersion": "syncthing v0.10.27+3-gea8c3de (go1.4 darwin-amd64 default) jb@syno 2015-03-16 11:01:29 UTC",
447 "os": "darwin",
448 "version": "v0.10.27+3-gea8c3de"
449 }
450
452 GET /rest/db/browse
453 Returns the directory tree of the global model. Directories are always
454 JSON objects (map/dictionary), and files are always arrays of modifica‐
455 tion time and size. The first integer is the files modification time,
456 and the second integer is the file size.
457 The call takes one mandatory folder parameter and two optional parame‐
459 ters. Optional parameter levels defines how deep within the tree we
460 want to dwell down (0 based, defaults to unlimited depth) Optional
461 parameter prefix defines a prefix within the tree where to start build‐
462 ing the structure.
463 $ curl -s http://localhost:8384/rest/db/browse?folder=default | json_pp
465 {
466 "directory": {
467 "file": ["2015-04-20T22:20:45+09:00", 130940928],
468 "subdirectory": {
469 "another file": ["2015-04-20T22:20:45+09:00", 130940928]
470 }
471 },
472 "rootfile": ["2015-04-20T22:20:45+09:00", 130940928]
473 }
474 $ curl -s http://localhost:8384/rest/db/browse?folder=default&levels=0 | json_pp
476 {
477 "directory": {},
478 "rootfile": ["2015-04-20T22:20:45+09:00", 130940928]
479 }
480 $ curl -s http://localhost:8384/rest/db/browse?folder=default&levels=1 | json_pp
482 {
483 "directory": {
484 "file": ["2015-04-20T22:20:45+09:00", 130940928],
485 "subdirectory": {}
486 },
487 "rootfile": ["2015-04-20T22:20:45+09:00", 130940928]
488 }
489 $ curl -s http://localhost:8384/rest/db/browse?folder=default&prefix=directory/subdirectory | json_pp
491 {
492 "another file": ["2015-04-20T22:20:45+09:00", 130940928]
493 }
494 $ curl -s http://localhost:8384/rest/db/browse?folder=default&prefix=directory&levels=0 | json_pp
496 {
497 "file": ["2015-04-20T22:20:45+09:00", 130940928],
498 "subdirectory": {}
499 }
500 NOTE:
502 This is an expensive call, increasing CPU and RAM usage on the
503 device. Use sparingly.
504 GET /rest/db/completion
506 Returns the completion percentage (0 to 100) for a given device and
507 folder. Takes device and folder parameters.
508 {
510 "completion": 100,
511 "globalBytes": 156793013575,
512 "needBytes": 0,
513 "needDeletes": 0
514 }
515 NOTE:
517 This is an expensive call, increasing CPU and RAM usage on the
518 device. Use sparingly.
519 GET /rest/db/file
521 Returns most data available about a given file, including version and
522 availability. Takes folder and file parameters.
523 {
525 "availability": [
526 {
527 "id": "ITZRNXE-YNROGBZ-HXTH5P7-VK5NYE5-QHRQGE2-7JQ6VNJ-KZUEDIU-5PPR5AM",
528 "fromTemporary": false
529 }
530 ],
531 "global": {
532 "deleted": false,
533 "ignored": false,
534 "invalid": false,
535 "localFlags": 0,
536 "modified": "2018-08-18T12:21:13.836784059+02:00",
537 "modifiedBy": "SYNO4VL",
538 "mustRescan": false,
539 "name": "testfile",
540 "noPermissions": false,
541 "numBlocks": 1,
542 "permissions": "0755",
543 "sequence": 107499,
544 "size": 1234,
545 "type": 0,
546 "version": [
547 "SYNO4VL:1"
548 ]
549 },
550 "local": {
551 "deleted": false,
552 "ignored": false,
553 "invalid": false,
554 "localFlags": 0,
555 "modified": "2018-08-18T12:21:13.836784059+02:00",
556 "modifiedBy": "SYNO4VL",
557 "mustRescan": false,
558 "name": "testfile",
559 "noPermissions": false,
560 "numBlocks": 1,
561 "permissions": "0755",
562 "sequence": 111038,
563 "size": 1234,
564 "type": 0,
565 "version": [
566 "SYNO4VL:1"
567 ]
568 }
569 }
570 GET /rest/db/ignores
572 Takes one parameter, folder, and returns the content of the .stignore
573 as the ignore field. A second field, expanded, provides a list of
574 strings which represent globbing patterns described by gobwas/glob
575 (based on standard wildcards) that match the patterns in .stignore and
576 all the includes. If appropriate these globs are prepended by the fol‐
577 lowing modifiers: ! to negate the glob, (?i) to do case insensitive
578 matching and (?d) to enable removing of ignored files in an otherwise
579 empty directory.
580 {
582 "ignore": [
583 "(?i)/Backups"
584 ],
585 "expanded": [
586 "(?i)Backups",
587 "(?i)Backups/**"
588 ]
589 }
590 POST /rest/db/ignores
592 Expects a format similar to the output of GET call, but only containing
593 the ignore field (expanded field should be omitted). It takes one
594 parameter, folder, and either updates the content of the .stignore
595 echoing it back as a response, or returns an error.
596 GET /rest/db/need
598 Takes one mandatory parameter, folder, and returns lists of files which
599 are needed by this device in order for it to become in sync.
600 Furthermore takes an optional page and perpage arguments for pagina‐
602 tion. Pagination happens, across the union of all needed files, that
603 is - across all 3 sections of the response. For example, given the
604 current need state is as follows:
605 1. progress has 15 items
607 2. queued has 3 items
609 3. rest has 12 items
611 If you issue a query with page=1 and perpage=10, only the progress sec‐
613 tion in the response will have 10 items. If you issue a request query
614 with page=2 and perpage=10, progress section will have the last 5
615 items, queued section will have all 3 items, and rest section will have
616 first 2 items. If you issue a query for page=3 and perpage=10, you will
617 only have the last 10 items of the rest section.
618 In all these calls, total will be 30 to indicate the total number of
620 available items.
621 {
623 # Files currently being downloaded
624 "progress": [
625 {
626 "flags": "0755",
627 "sequence": 6,
628 "modified": "2015-04-20T23:06:12+09:00",
629 "name": "ls",
630 "size": 34640,
631 "version": [
632 "5157751870738175669:1"
633 ]
634 }
635 ],
636 # Files queued to be downloaded next (as per array order)
637 "queued": [
638 ...
639 ],
640 # Files to be downloaded after all queued files will be downloaded.
641 # This happens when we start downloading files, and new files get added while we are downloading.
642 "rest": [
643 ...
644 ],
645 "page": 1,
646 "perpage": 100,
647 "total": 2000
648 }
649 NOTE:
651 This is an expensive call, increasing CPU and RAM usage on the
652 device. Use sparingly.
653 POST /rest/db/override
655 Request override of a send only folder. Override means to make the
656 local version latest, overriding changes made on other devices. This
657 API call does nothing if the folder is not a send only folder.
658 Takes the mandatory parameter folder (folder ID).
660 curl -X POST -H X-API-key:... http://127.0.0.1:8384/rest/db/override?folder=default
662 POST /rest/db/prio
664 Moves the file to the top of the download queue.
665 curl -X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
667 Response contains the same output as GET /rest/db/need
669 POST /rest/db/revert
671 New in version 0.14.50.
672 Request revert of a receive only folder. Reverting a folder means to
675 undo all local changes. This API call does nothing if the folder is not
676 a receive only folder.
677 Takes the mandatory parameter folder (folder ID).
679 curl -X POST -H X-API-Key:... http://127.0.0.1:8384/rest/db/revert?folder=default
681 POST /rest/db/scan
683 Request immediate scan. Takes the optional parameters folder (folder
684 ID), sub (path relative to the folder root) and next (time in seconds).
685 If folder is omitted or empty all folders are scanned. If sub is given,
686 only this path (and children, in case it’s a directory) is scanned. The
687 next argument delays Syncthing’s automated rescan interval for a given
688 amount of seconds.
689 Requesting scan of a path that no longer exists, but previously did, is
691 valid and will result in Syncthing noticing the deletion of the path in
692 question.
693 Returns status 200 and no content upon success, or status 500 and a
695 plain text error if an error occurred during scanning.
696 curl -X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar
698 GET /rest/db/status
700 Returns information about the current status of a folder.
701 Parameters: folder, the ID of a folder.
703 {
705 "globalBytes": 0,
706 "globalDeleted": 0,
707 "globalDirectories": 0,
708 "globalFiles": 0,
709 "globalSymlinks": 0,
710 "ignorePatterns": false,
711 "inSyncBytes": 0,
712 "inSyncFiles": 0,
713 "invalid": "",
714 "localBytes": 0,
715 "localDeleted": 0,
716 "localDirectories": 0,
717 "localFiles": 0,
718 "localSymlinks": 0,
719 "needBytes": 0,
720 "needDeletes": 0,
721 "needDirectories": 0,
722 "needFiles": 0,
723 "needSymlinks": 0,
724 "pullErrors": 0,
725 "receiveOnlyChangedBytes": 0,
726 "receiveOnlyChangedDeletes": 0,
727 "receiveOnlyChangedDirectories": 0,
728 "receiveOnlyChangedFiles": 0,
729 "receiveOnlyChangedSymlinks": 0,
730 "sequence": 0,
731 "state": "idle",
732 "stateChanged": "2018-08-08T07:04:57.301064781+02:00",
733 "version": 0
734 }
735 The various fields have the following meaning:
737 global*:
739 Data in the cluster latest version.
740 inSync*:
742 Data that is locally the same as the cluster latest version.
743 local*:
745 Data that is locally present, regardless of whether it’s the
746 same or different version as the cluster latest version.
747 need*: Data that is needed to become up to date with the cluster latest
749 version (i.e., data that is out of sync).
750 receiveOnlyChanged*:
752 Data that has changed locally in a receive only folder, and thus
753 not been sent to the cluster.
754 invalid:
756 Deprecated, always empty.
757 pullErrors:
759 The number of files that failed to sync during the last sync
760 operations.
761 sequence:
763 The current folder sequence number.
764 state: The current folder state.
766 stateChanged:
768 When the folder state last changed.
769 version:
771 Deprecated, equivalent to the sequence number.
772 NOTE:
774 This is an expensive call, increasing CPU and RAM usage on the
775 device. Use sparingly.
776
778 GET /rest/events
779 To receive events, perform a HTTP GET of /rest/events.
780 To filter the event list, in effect creating a specific subscription
782 for only the desired event types, add a parameter events=EventTy‐
783 peA,EventTypeB,... where the event types are any of the event-types.
784 The optional parameter since=<lastSeenID> sets the ID of the last event
786 you’ve already seen. Syncthing returns a JSON encoded array of event
787 objects, starting at the event just after the one with this last seen
788 ID. The default value is 0, which returns all events. There is a limit
789 to the number of events buffered, so if the rate of events is high or
790 the time between polling calls is long some events might be missed.
791 This can be detected by noting a discontinuity in the event IDs.
792 If no new events are produced since <lastSeenID>, the HTTP call blocks
794 and waits for new events to happen before returning. By default it
795 times out after 60 seconds returning an empty array. The time out dura‐
796 tion can be customized with the optional parameter timeout=seconds.
797 To receive only a limited number of events, add the limit=n parameter
799 with a suitable value for n and only the last n events will be
800 returned. This can be used to catch up with the latest event ID after a
801 disconnection for example: /rest/events?since=0&limit=1.
802
804 GET /rest/stats/device
805 Returns general statistics about devices. Currently, only contains the
806 time the device was last seen.
807 $ curl -s http://localhost:8384/rest/stats/device | json
809 {
810 "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2": {
811 "lastSeen" : "2015-04-18T11:21:31.3256277+01:00"
812 }
813 }
814 GET /rest/stats/folder
816 Returns general statistics about folders. Currently contains the last
817 scan time and the last synced file.
818 $ curl -s http://localhost:8384/rest/stats/folder | json
820 {
821 "folderid" : {
822 "lastScan": "2016-06-02T13:28:01.288181412-04:00",
823 "lastFile" : {
824 "filename" : "file/name",
825 "at" : "2015-04-16T22:04:18.3066971+01:00"
826 }
827 }
828 }
829
831 GET /rest/svc/deviceid
832 Verifies and formats a device ID. Accepts all currently valid formats
833 (52 or 56 characters with or without separators, upper or lower case,
834 with trivial substitutions). Takes one parameter, id, and returns
835 either a valid device ID in modern format, or an error.
836 $ curl -s http://localhost:8384/rest/svc/deviceid?id=1234 | json
838 {
839 "error": "device ID invalid: incorrect length"
840 }
841 $ curl -s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m--zjnu2iq-gdr-eydm-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json
843 {
844 "id": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2"
845 }
846 GET /rest/svc/lang
848 Returns a list of canonicalized localization codes, as picked up from
849 the Accept-Language header sent by the browser.
850 ["sv_sv","sv","en_us","en"]
852 GET /rest/svc/random/string
854 Returns a strong random generated string (alphanumeric) of the speci‐
855 fied length. Takes the length parameter.
856 {
858 "random": "FdPaEaZQ56sXEKYNxpgF"
859 }
860 GET /rest/svc/report
862 Returns the data sent in the anonymous usage report.
863 {
865 "folderMaxMiB" : 0,
866 "platform" : "linux-amd64",
867 "totMiB" : 0,
868 "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",
869 "upgradeAllowedManual" : true,
870 "totFiles" : 3,
871 "folderUses" : {
872 "ignorePerms" : 0,
873 "autoNormalize" : 0,
874 "sendonly" : 0,
875 "ignoreDelete" : 0
876 },
877 "memoryUsageMiB" : 13,
878 "version" : "v0.12.2",
879 "sha256Perf" : 27.28,
880 "numFolders" : 2,
881 "memorySize" : 1992,
882 "announce" : {
883 "defaultServersIP" : 0,
884 "otherServers" : 0,
885 "globalEnabled" : false,
886 "defaultServersDNS" : 1,
887 "localEnabled" : false
888 },
889 "usesRateLimit" : false,
890 "numCPU" : 2,
891 "uniqueID" : "",
892 "urVersion" : 2,
893 "rescanIntvs" : [
894 60,
895 60
896 ],
897 "numDevices" : 2,
898 "folderMaxFiles" : 3,
899 "relays" : {
900 "defaultServers" : 1,
901 "enabled" : true,
902 "otherServers" : 0
903 },
904 "deviceUses" : {
905 "compressMetadata" : 1,
906 "customCertName" : 0,
907 "staticAddr" : 1,
908 "compressAlways" : 0,
909 "compressNever" : 1,
910 "introducer" : 0,
911 "dynamicAddr" : 1
912 },
913 "upgradeAllowedAuto" : false
914 }
915
917 The Syncthing Authors
918
920 2014-2019, The Syncthing Authors
921v1 Apr 13, 2019 SYNCTHING-REST-API(7)