1SYNCTHING-EVENT-API(7) Syncthing SYNCTHING-EVENT-API(7)
2
6 syncthing-event-api - Event API
7
9 Syncthing provides a simple long polling interface for exposing events
10 from the core utility towards a GUI. To receive events, see events-get.
11
13 Each event is represented by an object similar to the following:
14 {
16 "id": 2,
17 "globalID": 3,
18 "type": "DeviceConnected",
19 "time": "2014-07-13T21:04:33.687836696+02:00",
20 "data": {
21 "addr": "172.16.32.25:22000",
22 "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
23 }
24 }
25 The top level keys id, globalID, time, type and data are always
27 present, though data may be null.
28 id A unique ID for this event on the events API. It always in‐
30 creases by 1: the first event generated has id 1, the next has
31 id 2 etc. If this increases by more than 1, then one or more
32 events have been skipped by the events API.
33 globalID
35 A global ID for this event, across the events API, the audit
36 log, and any other sources. It may increase by more than 1, but
37 it will always be greater than or equal to the id.
38 time The time the event was generated.
40 type Indicates the type of (i.e. reason for) the event and is one of
42 the event types below.
43 data An object containing optional extra information; the exact
45 structure is determined by the event type.
46
48 ConfigSaved
49 Emitted after the config has been saved by the user or by Syncthing it‐
50 self.
51 {
53 "id": 50,
54 "globalID": 50,
55 "type": "ConfigSaved",
56 "time": "2014-12-13T00:09:13.5166486Z",
57 "data": {
58 "version": 7,
59 "folders": [{"..."}],
60 "devices": [{"..."}],
61 "gui": {"..."},
62 "ldap": {"..."},
63 "options": {"..."},
64 "remoteIgnoredDevices": [{"..."}],
65 "defaults": {"..."}
66 }
67 }
68 DeviceConnected
70 Generated each time a connection to a device has been established.
71 {
73 "id": 2,
74 "globalID": 2,
75 "type": "DeviceConnected",
76 "time": "2014-07-13T21:04:33.687836696+02:00",
77 "data": {
78 "addr": "172.16.32.25:22000",
79 "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG",
80 "deviceName": "Laptop",
81 "clientName": "syncthing",
82 "clientVersion": "v0.13.4",
83 "type": "TCP (Client)"
84 }
85 }
86 DeviceDisconnected
88 Generated each time a connection to a device has been terminated.
89 {
91 "id": 48,
92 "globalID": 48,
93 "type": "DeviceDisconnected",
94 "time": "2014-07-13T21:18:52.859929215+02:00",
95 "data": {
96 "error": "unexpected EOF",
97 "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
98 }
99 }
100 NOTE:
102 The error key contains the cause for disconnection, which might not
103 necessarily be an error as such. Specifically, “EOF” and “unexpected
104 EOF” both signify TCP connection termination, either due to the
105 other device restarting or going offline or due to a network change.
106 DeviceDiscovered
108 Emitted when a new device is discovered using local discovery.
109 {
111 "id": 13,
112 "globalID": 13,
113 "type": "DeviceDiscovered",
114 "time": "2014-07-17T13:28:05.043465207+02:00",
115 "data": {
116 "addrs": [
117 "172.16.32.25:22000"
118 ],
119 "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
120 }
121 }
122 DevicePaused
124 Emitted when a device was paused.
125 {
127 "id": 13,
128 "globalID": 13,
129 "type": "DevicePaused",
130 "time": "2014-07-17T13:28:05.043465207+02:00",
131 "data": {
132 "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
133 }
134 }
135 DeviceRejected
137 Deprecated since version v1.13.0: This event is still emitted for com‐
138 patibility, but deprecated. Use the replacement pending-de‐
139 vices-changed event instead.
140 Emitted when there is a connection from a device we are not configured
143 to talk to.
144 {
146 "id": 24,
147 "globalID": 24,
148 "type": "DeviceRejected",
149 "time": "2014-08-19T10:43:00.562821045+02:00",
150 "data": {
151 "address": "127.0.0.1:51807",
152 "name": "My dusty computer",
153 "device": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK"
154 }
155 }
156 DeviceResumed
158 Generated each time a device was resumed.
159 {
161 "id": 2,
162 "globalID": 2,
163 "type": "DeviceResumed",
164 "time": "2014-07-13T21:04:33.687836696+02:00",
165 "data": {
166 "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
167 }
168 }
169 DownloadProgress
171 Emitted during file downloads for each folder for each file. By default
172 only a single file in a folder is handled at the same time, but custom
173 configuration can cause multiple files to be shown.
174 {
176 "id": 221,
177 "globalID": 221,
178 "type": "DownloadProgress",
179 "time": "2014-12-13T00:26:12.9876937Z",
180 "data": {
181 "folder1": {
182 "file1": {
183 "total": 800,
184 "pulling": 2,
185 "copiedFromOrigin": 0,
186 "reused": 633,
187 "copiedFromElsewhere": 0,
188 "pulled": 38,
189 "bytesTotal": 104792064,
190 "bytesDone": 87883776
191 },
192 "dir\\file2": {
193 "total": 80,
194 "pulling": 2,
195 "copiedFromOrigin": 0,
196 "reused": 0,
197 "copiedFromElsewhere": 0,
198 "pulled": 32,
199 "bytesTotal": 10420224,
200 "bytesDone": 4128768
201 }
202 },
203 "folder2": {
204 "file3": {
205 "total": 800,
206 "pulling": 2,
207 "copiedFromOrigin": 0,
208 "reused": 633,
209 "copiedFromElsewhere": 0,
210 "pulled": 38,
211 "bytesTotal": 104792064,
212 "bytesDone": 87883776
213 },
214 "dir\\file4": {
215 "total": 80,
216 "pulling": 2,
217 "copiedFromOrigin": 0,
218 "reused": 0,
219 "copiedFromElsewhere": 0,
220 "pulled": 32,
221 "bytesTotal": 10420224,
222 "bytesDone": 4128768
223 }
224 }
225 }
226 }
227 • total - total number of blocks in the file
229 • pulling - number of blocks currently being downloaded
231 • copiedFromOrigin - number of blocks copied from the file we are about
233 to replace
234 • reused - number of blocks reused from a previous temporary file
236 • copiedFromElsewhere - number of blocks copied from other files or po‐
238 tentially other folders
239 • pulled - number of blocks actually downloaded so far
241 • bytesTotal - approximate total file size
243 • bytesDone - approximate number of bytes already handled (already
245 reused, copied or pulled)
246 Where block size is 128KB.
248 Files/folders appearing in the event data imply that the download has
250 been started for that file/folder, where disappearing implies that the
251 downloads have been finished or failed for that file/folder. There is
252 always a last event emitted with no data, which implies all downloads
253 have finished/failed.
254 Failure
256 Generated for specific errors that will also be sent to the usage re‐
257 porting server, if enabled in the configuration. These are usually of
258 special interest to the developers to troubleshoot complex errors. The
259 data field contains a textual error message.
260 {
262 "id": 93,
263 "globalID": 93,
264 "type": "Failure",
265 "time": "2021-06-07T21:22:03.414609034+02:00",
266 "data": "index handler got paused while already paused"
267 }
268 FolderCompletion
270 The FolderCompletion event is emitted when the local or remote contents
271 for a folder changes. It contains the completion percentage for a given
272 remote device and is emitted once per currently connected remote de‐
273 vice.
274 {
276 "id": 84,
277 "globalID": 84,
278 "type": "FolderCompletion",
279 "time": "2015-04-17T14:14:27.043576583+09:00",
280 "data": {
281 "completion": 100,
282 "device": "I6KAH76-66SLLLB-5PFXSOA-UFJCDZC-YAOMLEK-CP2GB32-BV5RQST-3PSROAU",
283 "folder": "default"
284 }
285 }
286 FolderErrors
288 The FolderErrors event is emitted when a folder cannot be successfully
289 synchronized. The event contains the ID of the affected folder and a
290 list of errors for files or directories therein. This list of errors is
291 obsolete once the folder changes state to syncing - if errors remain
292 after the next synchronization attempt, a new FolderErrors event is
293 emitted.
294 {
296 "id": 132,
297 "type": "FolderErrors",
298 "time": "2015-06-26T13:39:24.697401384+02:00",
299 "data": {
300 "errors": [
301 {
302 "error": "open /Users/jb/src/github.com/syncthing/syncthing/test/s2/h2j/.syncthing.aslkjd.tmp: permission denied",
303 "path": "h2j/aslkjd"
304 }
305 ],
306 "folder": "default"
307 }
308 }
309 New in version 0.11.12.
311 SEE ALSO:
314 The statechanged event.
315 FolderPaused
317 Generated when the configuration changes regarding the “paused” state
318 of a folder. Sent repeatedly for each changed folder.
319 {
321 "id": 93,
322 "globalID": 93,
323 "type": "FolderPaused",
324 "time": "2021-06-07T23:45:03.414609034+02:00",
325 "data": {
326 "id": "abcde-fghij",
327 "label": "My folder"
328 }
329 }
330 FolderRejected
332 Deprecated since version v1.13.0: This event is still emitted for com‐
333 patibility, but deprecated. Use the replacement pending-fold‐
334 ers-changed event instead.
335 Emitted when a device sends index information for a folder we do not
338 have, or have but do not share with the device in question.
339 {
341 "id": 27,
342 "globalID": 27,
343 "type": "FolderRejected",
344 "time": "2014-08-19T10:41:06.761751399+02:00",
345 "data": {
346 "device": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK",
347 "folder": "GXWxf-3zgnU",
348 "folderLabel": "My Pictures"
349 }
350 }
351 FolderResumed
353 Generated when the configuration changes regarding the “paused” state
354 of a folder. Sent repeatedly for each changed folder.
355 {
357 "id": 93,
358 "globalID": 93,
359 "type": "FolderResumed",
360 "time": "2021-06-07T23:45:03.414609034+02:00",
361 "data": {
362 "id": "abcde-fghij",
363 "label": "My folder"
364 }
365 }
366 FolderScanProgress
368 Emitted in regular intervals (folder setting ProgressIntervalS, 2s by
369 default) during scans giving the amount of bytes already scanned and to
370 be scanned in total , as well as the current scanning rates in bytes
371 per second.
372 {
374 "data" : {
375 "total" : 1,
376 "rate" : 0,
377 "current" : 0,
378 "folder" : "bd7q3-zskm5"
379 },
380 "globalID" : 29,
381 "type" : "FolderScanProgress",
382 "time" : "2017-03-06T15:00:58.072004209+01:00",
383 "id" : 29
384 }
385 FolderSummary
387 The FolderSummary event is emitted when folder contents have changed
388 locally. This can be used to calculate the current local completion
389 state.
390 {
392 "id": 16,
393 "globalID": 16,
394 "type": "FolderSummary",
395 "time": "2015-04-17T14:12:20.460121585+09:00",
396 "data": {
397 "folder": "default",
398 "summary": {
399 "globalBytes": 0,
400 "globalDeleted": 0,
401 "globalFiles": 0,
402 "ignorePatterns": false,
403 "inSyncBytes": 0,
404 "inSyncFiles": 0,
405 "invalid": "",
406 "localBytes": 0,
407 "localDeleted": 0,
408 "localFiles": 0,
409 "needBytes": 0,
410 "needFiles": 0,
411 "state": "idle",
412 "stateChanged": "2015-04-17T14:12:12.455224687+09:00",
413 "version": 0
414 }
415 }
416 }
417 ItemFinished
419 Generated when Syncthing ends synchronizing a file to a newer version.
420 A successful operation:
421 {
423 "id": 93,
424 "globalID": 93,
425 "type": "ItemFinished",
426 "time": "2014-07-13T21:22:03.414609034+02:00",
427 "data": {
428 "item": "test.txt",
429 "folder": "default",
430 "error": null,
431 "type": "file",
432 "action": "update"
433 }
434 }
435 An unsuccessful operation:
437 {
439 "id": 44,
440 "globalID": 44,
441 "type": "ItemFinished",
442 "time": "2015-05-27T11:21:05.711133004+02:00",
443 "data": {
444 "action": "update",
445 "error": "open /Users/jb/src/github.com/syncthing/syncthing/test/s2/foo/.syncthing.hej.tmp: permission denied",
446 "folder": "default",
447 "item": "foo/hej",
448 "type": "file"
449 }
450 }
451 The action field is either update (contents changed), metadata (file
453 metadata changed but not contents), or delete.
454 New in version 0.11.10: The metadata action.
456 ItemStarted
459 Generated when Syncthing begins synchronizing a file to a newer ver‐
460 sion.
461 {
463 "id": 93,
464 "globalID": 93,
465 "type": "ItemStarted",
466 "time": "2014-07-13T21:22:03.414609034+02:00",
467 "data": {
468 "item": "test.txt",
469 "folder": "default",
470 "type": "file",
471 "action": "update"
472 }
473 }
474 The action field is either update (contents changed), metadata (file
476 metadata changed but not contents), or delete.
477 New in version 0.11.10: The metadata action.
479 ListenAddressesChanged
482 This event is emitted when a listen address changes.
483 {
485 "type" : "ListenAddressesChanged",
486 "id" : 70,
487 "time" : "2017-03-06T15:01:24.88340663+01:00",
488 "globalID" : 70,
489 "data" : {
490 "address" : {
491 "Fragment" : "",
492 "RawQuery" : "",
493 "Scheme" : "dynamic+https",
494 "Path" : "/endpoint",
495 "RawPath" : "",
496 "User" : null,
497 "ForceQuery" : false,
498 "Host" : "relays.syncthing.net",
499 "Opaque" : ""
500 },
501 "wan" : [
502 {
503 "ForceQuery" : false,
504 "User" : null,
505 "Host" : "31.15.66.212:443",
506 "Opaque" : "",
507 "Path" : "/",
508 "RawPath" : "",
509 "RawQuery" : "id=F4HSJVO-CP2C3IL-YLQYLSU-XTYODAG-PPU4LGV-PH3MU4N-G6K56DV-IPN47A&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=",
510 "Scheme" : "relay",
511 "Fragment" : ""
512 }
513 ],
514 "lan" : [
515 {
516 "RawQuery" : "id=F4HSJVO-CP2C3IL-YLQYLSU-XTYODAG-PPU4LGV-PH3MU4N-G6K56DV-IPN47A&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=",
517 "Scheme" : "relay",
518 "Fragment" : "",
519 "RawPath" : "",
520 "Path" : "/",
521 "Host" : "31.15.66.212:443",
522 "Opaque" : "",
523 "ForceQuery" : false,
524 "User" : null
525 }
526 ]
527 }
528 }
529 LocalChangeDetected
531 Generated upon scan whenever the local disk has discovered an updated
532 file from the previous scan. This does not include events that are
533 discovered and copied from other devices (remote-change-detected), only
534 files that were changed on the local filesystem.
535 {
537 "id": 7,
538 "globalID": 59,
539 "time": "2016-09-26T22:07:10.7189141-04:00",
540 "type": "LocalChangeDetected",
541 "data": {
542 "action": "deleted",
543 "folderID": "vitwy-zjxqt",
544 "label": "TestSync",
545 "path": "C:\\Users\\Nate\\Sync\\testfolder\\test file.rtf",
546 "type": "file"
547 }
548 }
549 LocalIndexUpdated
551 Generated when the local index information has changed, due to synchro‐
552 nizing one or more items from the cluster or discovering local changes
553 during a scan.
554 {
556 "id": 59,
557 "globalID": 59,
558 "type": "LocalIndexUpdated",
559 "time": "2014-07-17T13:27:28.051369434+02:00",
560 "data": {
561 "folder": "default",
562 "items": 1000,
563 }
564 }
565 LoginAttempt
567 When authentication is enabled for the GUI, this event is emitted on
568 every login attempt. If either the username or password are incorrect,
569 success is false and in any case the given username is returned. The
570 included remote address concerns the immediate connecting host, which
571 may not be the origin of the request, but e.g. a reverse proxy.
572 {
574 "id" : 187,
575 "time" : "2017-03-07T00:19:24.420386143+01:00",
576 "data" : {
577 "remoteAddress" : "127.0.0.1:55530",
578 "username" : "somename",
579 "success" : false
580 },
581 "type" : "LoginAttempt",
582 "globalID" : 195
583 }
584 PendingDevicesChanged
586 New in version 1.14.0.
587 Emitted when pending devices were added / updated (connection from un‐
590 known ID) or removed (device is ignored, dismissed or added).
591 {
593 "id": 87,
594 "type": "PendingDevicesChanged",
595 "time": "2020-12-22T22:24:37.578586718+01:00",
596 "data": {
597 "added": [
598 {
599 "address": "127.0.0.1:51807",
600 "deviceID": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK",
601 "name": "My dusty computer"
602 }
603 ],
604 "removed": [
605 {
606 "deviceID": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2"
607 }
608 ]
609 }
610 }
611 PendingFoldersChanged
613 New in version 1.14.0.
614 Emitted when pending folders were added / updated (offered by some de‐
617 vice, but not shared to them) or removed (folder ignored, dismissed or
618 added or no longer offered from the remote device). A removed entry
619 without a deviceID attribute means that the folder is no longer pending
620 for any device.
621 {
623 "id": 101,
624 "type": "PendingFoldersChanged",
625 "time": "2020-12-22T22:36:55.66744317+01:00",
626 "data": {
627 "added": [
628 {
629 "deviceID": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK",
630 "folderID": "GXWxf-3zgnU",
631 "folderLabel": "My Pictures"
632 "receiveEncrypted": "false"
633 "remoteEncrypted": "false"
634 }
635 ],
636 "removed": [
637 {
638 "deviceID": "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2",
639 "folderID": "neyfh-sa2nu"
640 },
641 {
642 "folderID": "abcde-fghij"
643 }
644 ]
645 }
646 }
647 RemoteChangeDetected
649 Generated upon scan whenever a file is locally updated due to a remote
650 change. Files that are updated locally produce a local-change-detected
651 event.
652 {
654 "time" : "2017-03-06T23:58:21.844739891+01:00",
655 "globalID" : 123,
656 "data" : {
657 "type" : "file",
658 "action" : "deleted",
659 "path" : "/media/ntfs_data/Dokumente/testfile",
660 "label" : "Dokumente",
661 "folderID" : "Dokumente",
662 "modifiedBy" : "BPDFDTU"
663 },
664 "type" : "RemoteChangeDetected",
665 "id" : 2
666 }
667 RemoteDownloadProgress
669 This event is emitted when a download-progress message is received. It
670 returns a map data of filenames with a count of downloaded blocks. The
671 files in questions are currently being downloaded on the remote device
672 and belong to folder.
673 {
675 "time" : "2017-03-07T00:11:37.65838955+01:00",
676 "globalID" : 170,
677 "data" : {
678 "state" : {
679 "tahr64-6.0.5.iso" : 1784
680 },
681 "device" : "F4HSJVO-CP2C3IL-YLQYLSU-XTYODAG-PPU4LGV-PH3MU4N-G6K56DV-IPN47A",
682 "folder" : "Dokumente"
683 },
684 "type" : "RemoteDownloadProgress",
685 "id" : 163
686 }
687 RemoteIndexUpdated
689 Generated each time new index information is received from a device.
690 {
692 "id": 44,
693 "globalID": 44,
694 "type": "RemoteIndexUpdated",
695 "time": "2014-07-13T21:04:35.394184435+02:00",
696 "data": {
697 "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG",
698 "folder": "lightroom",
699 "items": 1000
700 }
701 }
702 Starting
704 Emitted exactly once, when Syncthing starts, before parsing configura‐
705 tion etc.
706 {
708 "id": 1,
709 "globalID": 1,
710 "type": "Starting",
711 "time": "2014-07-17T13:13:32.044470055+02:00",
712 "data": {
713 "home": "/home/jb/.config/syncthing"
714 }
715 }
716 StartupComplete
718 Emitted exactly once, when initialization is complete and Syncthing is
719 ready to start exchanging data with other devices.
720 {
722 "id": 1,
723 "globalID": 1,
724 "type": "StartupComplete",
725 "time": "2014-07-13T21:03:18.383239179+02:00",
726 "data": null
727 }
728 StateChanged
730 Emitted when a folder changes state. Possible states are idle, scan‐
731 ning, syncing and error. The field duration is the number of seconds
732 the folder spent in state from. In the example below, the folder de‐
733 fault was in state scanning for 0.198 seconds and is now in state idle.
734 {
736 "id": 8,
737 "globalID": 8,
738 "type": "StateChanged",
739 "time": "2014-07-17T13:14:28.697493016+02:00",
740 "data": {
741 "folder": "default",
742 "from": "scanning",
743 "duration": 0.19782869900000002,
744 "to": "idle"
745 }
746 }
747
749 The Syncthing Authors
750
752 2014-2019, The Syncthing Authors
753v1 Oct 17, 2021 SYNCTHING-EVENT-API(7)