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
30 increases 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
50 itself.
51 {
53 "id": 50,
54 "globalID": 50,
55 "type": "ConfigSaved",
56 "time": "2014-12-13T00:09:13.5166486Z",
57 "data": {
58 "Version": 7,
59 "Options": {"..."},
60 "GUI": {"..."},
61 "Devices": [{"..."}],
62 "Folders": [{"..."}]
63 }
64 }
65 DeviceConnected
67 Generated each time a connection to a device has been established.
68 {
70 "id": 2,
71 "globalID": 2,
72 "type": "DeviceConnected",
73 "time": "2014-07-13T21:04:33.687836696+02:00",
74 "data": {
75 "addr": "172.16.32.25:22000",
76 "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG",
77 "deviceName": "Laptop",
78 "clientName": "syncthing",
79 "clientVersion": "v0.13.4",
80 "type": "TCP (Client)"
81 }
82 }
83 DeviceDisconnected
85 Generated each time a connection to a device has been terminated.
86 {
88 "id": 48,
89 "globalID": 48,
90 "type": "DeviceDisconnected",
91 "time": "2014-07-13T21:18:52.859929215+02:00",
92 "data": {
93 "error": "unexpected EOF",
94 "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
95 }
96 }
97 NOTE:
99 The error key contains the cause for disconnection, which might not
100 necessarily be an error as such. Specifically, “EOF” and “unexpected
101 EOF” both signify TCP connection termination, either due to the
102 other device restarting or going offline or due to a network change.
103 DeviceDiscovered
105 Emitted when a new device is discovered using local discovery.
106 {
108 "id": 13,
109 "globalID": 13,
110 "type": "DeviceDiscovered",
111 "time": "2014-07-17T13:28:05.043465207+02:00",
112 "data": {
113 "addrs": [
114 "172.16.32.25:22000"
115 ],
116 "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
117 }
118 }
119 DevicePaused
121 Emitted when a device was paused.
122 {
124 "id": 13,
125 "globalID": 13,
126 "type": "DevicePaused",
127 "time": "2014-07-17T13:28:05.043465207+02:00",
128 "data": {
129 "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
130 }
131 }
132 DeviceRejected
134 Emitted when there is a connection from a device we are not configured
135 to talk to.
136 {
138 "id": 24,
139 "globalID": 24,
140 "type": "DeviceRejected",
141 "time": "2014-08-19T10:43:00.562821045+02:00",
142 "data": {
143 "address": "127.0.0.1:51807",
144 "name": "My dusty computer",
145 "device": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK"
146 }
147 }
148 DeviceResumed
150 Generated each time a device was resumed.
151 {
153 "id": 2,
154 "globalID": 2,
155 "type": "DeviceResumed",
156 "time": "2014-07-13T21:04:33.687836696+02:00",
157 "data": {
158 "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
159 }
160 }
161 DownloadProgress
163 Emitted during file downloads for each folder for each file. By default
164 only a single file in a folder is handled at the same time, but custom
165 configuration can cause multiple files to be shown.
166 {
168 "id": 221,
169 "globalID": 221,
170 "type": "DownloadProgress",
171 "time": "2014-12-13T00:26:12.9876937Z",
172 "data": {
173 "folder1": {
174 "file1": {
175 "total": 800,
176 "pulling": 2,
177 "copiedFromOrigin": 0,
178 "reused": 633,
179 "copiedFromElsewhere": 0,
180 "pulled": 38,
181 "bytesTotal": 104792064,
182 "bytesDone": 87883776
183 },
184 "dir\\file2": {
185 "total": 80,
186 "pulling": 2,
187 "copiedFromOrigin": 0,
188 "reused": 0,
189 "copiedFromElsewhere": 0,
190 "pulled": 32,
191 "bytesTotal": 10420224,
192 "bytesDone": 4128768
193 }
194 },
195 "folder2": {
196 "file3": {
197 "total": 800,
198 "pulling": 2,
199 "copiedFromOrigin": 0,
200 "reused": 633,
201 "copiedFromElsewhere": 0,
202 "pulled": 38,
203 "bytesTotal": 104792064,
204 "bytesDone": 87883776
205 },
206 "dir\\file4": {
207 "total": 80,
208 "pulling": 2,
209 "copiedFromOrigin": 0,
210 "reused": 0,
211 "copiedFromElsewhere": 0,
212 "pulled": 32,
213 "bytesTotal": 10420224,
214 "bytesDone": 4128768
215 }
216 }
217 }
218 }
219 · total - total number of blocks in the file
221 · pulling - number of blocks currently being downloaded
223 · copiedFromOrigin - number of blocks copied from the file we are about
225 to replace
226 · reused - number of blocks reused from a previous temporary file
228 · copiedFromElsewhere - number of blocks copied from other files or
230 potentially other folders
231 · pulled - number of blocks actually downloaded so far
233 · bytesTotal - approximate total file size
235 · bytesDone - approximate number of bytes already handled (already
237 reused, copied or pulled)
238 Where block size is 128KB.
240 Files/folders appearing in the event data imply that the download has
242 been started for that file/folder, where disappearing implies that the
243 downloads have been finished or failed for that file/folder. There is
244 always a last event emitted with no data, which implies all downloads
245 have finished/failed.
246 FolderCompletion
248 The FolderCompletion event is emitted when the local or remote contents
249 for a folder changes. It contains the completion percentage for a given
250 remote device and is emitted once per currently connected remote
251 device.
252 {
254 "id": 84,
255 "globalID": 84,
256 "type": "FolderCompletion",
257 "time": "2015-04-17T14:14:27.043576583+09:00",
258 "data": {
259 "completion": 100,
260 "device": "I6KAH76-66SLLLB-5PFXSOA-UFJCDZC-YAOMLEK-CP2GB32-BV5RQST-3PSROAU",
261 "folder": "default"
262 }
263 }
264 FolderErrors
266 The FolderErrors event is emitted when a folder cannot be successfully
267 synchronized. The event contains the ID of the affected folder and a
268 list of errors for files or directories therein. This list of errors is
269 obsolete once the folder changes state to syncing - if errors remain
270 after the next synchronization attempt, a new FolderErrors event is
271 emitted.
272 {
274 "id": 132,
275 "type": "FolderErrors",
276 "time": "2015-06-26T13:39:24.697401384+02:00",
277 "data": {
278 "errors": [
279 {
280 "error": "open /Users/jb/src/github.com/syncthing/syncthing/test/s2/h2j/.syncthing.aslkjd.tmp: permission denied",
281 "path": "h2j/aslkjd"
282 }
283 ],
284 "folder": "default"
285 }
286 }
287 New in version 0.11.12.
289 SEE ALSO:
292 The statechanged event.
293 FolderRejected
295 Emitted when a device sends index information for a folder we do not
296 have, or have but do not share with the device in question.
297 {
299 "id": 27,
300 "globalID": 27,
301 "type": "FolderRejected",
302 "time": "2014-08-19T10:41:06.761751399+02:00",
303 "data": {
304 "device": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK",
305 "folder": "GXWxf-3zgnU",
306 "folderLabel": "My Pictures"
307 }
308 }
309 Folder Scan Progress
311 Emitted in regular intervals (folder setting ProgressIntervalS, 2s by
312 default) during scans giving the amount of bytes already scanned and to
313 be scanned in total , as well as the current scanning rates in bytes
314 per second.
315 {
317 "data" : {
318 "total" : 1,
319 "rate" : 0,
320 "current" : 0,
321 "folder" : "bd7q3-zskm5"
322 },
323 "globalID" : 29,
324 "type" : "FolderScanProgress",
325 "time" : "2017-03-06T15:00:58.072004209+01:00",
326 "id" : 29
327 }
328 FolderSummary
330 The FolderSummary event is emitted when folder contents have changed
331 locally. This can be used to calculate the current local completion
332 state.
333 {
335 "id": 16,
336 "globalID": 16,
337 "type": "FolderSummary",
338 "time": "2015-04-17T14:12:20.460121585+09:00",
339 "data": {
340 "folder": "default",
341 "summary": {
342 "globalBytes": 0,
343 "globalDeleted": 0,
344 "globalFiles": 0,
345 "ignorePatterns": false,
346 "inSyncBytes": 0,
347 "inSyncFiles": 0,
348 "invalid": "",
349 "localBytes": 0,
350 "localDeleted": 0,
351 "localFiles": 0,
352 "needBytes": 0,
353 "needFiles": 0,
354 "state": "idle",
355 "stateChanged": "2015-04-17T14:12:12.455224687+09:00",
356 "version": 0
357 }
358 }
359 }
360 ItemFinished
362 Generated when Syncthing ends synchronizing a file to a newer version.
363 A successful operation:
364 {
366 "id": 93,
367 "globalID": 93,
368 "type": "ItemFinished",
369 "time": "2014-07-13T21:22:03.414609034+02:00",
370 "data": {
371 "item": "test.txt",
372 "folder": "default",
373 "error": null,
374 "type": "file",
375 "action": "update"
376 }
377 }
378 An unsuccessful operation:
380 {
382 "id": 44,
383 "globalID": 44,
384 "type": "ItemFinished",
385 "time": "2015-05-27T11:21:05.711133004+02:00",
386 "data": {
387 "action": "update",
388 "error": "open /Users/jb/src/github.com/syncthing/syncthing/test/s2/foo/.syncthing.hej.tmp: permission denied",
389 "folder": "default",
390 "item": "foo/hej",
391 "type": "file"
392 }
393 }
394 The action field is either update (contents changed), metadata (file
396 metadata changed but not contents), or delete.
397 New in version 0.11.10: The metadata action.
399 ItemStarted
402 Generated when Syncthing begins synchronizing a file to a newer ver‐
403 sion.
404 {
406 "id": 93,
407 "globalID": 93,
408 "type": "ItemStarted",
409 "time": "2014-07-13T21:22:03.414609034+02:00",
410 "data": {
411 "item": "test.txt",
412 "folder": "default",
413 "type": "file",
414 "action": "update"
415 }
416 }
417 The action field is either update (contents changed), metadata (file
419 metadata changed but not contents), or delete.
420 New in version 0.11.10: The metadata action.
422 Listen Addresses Changed
425 This event is emitted when a listen address changes.
426 {
428 "type" : "ListenAddressesChanged",
429 "id" : 70,
430 "time" : "2017-03-06T15:01:24.88340663+01:00",
431 "globalID" : 70,
432 "data" : {
433 "address" : {
434 "Fragment" : "",
435 "RawQuery" : "",
436 "Scheme" : "dynamic+https",
437 "Path" : "/endpoint",
438 "RawPath" : "",
439 "User" : null,
440 "ForceQuery" : false,
441 "Host" : "relays.syncthing.net",
442 "Opaque" : ""
443 },
444 "wan" : [
445 {
446 "ForceQuery" : false,
447 "User" : null,
448 "Host" : "31.15.66.212:443",
449 "Opaque" : "",
450 "Path" : "/",
451 "RawPath" : "",
452 "RawQuery" : "id=F4HSJVO-CP2C3IL-YLQYLSU-XTYODAG-PPU4LGV-PH3MU4N-G6K56DV-IPN47A&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=",
453 "Scheme" : "relay",
454 "Fragment" : ""
455 }
456 ],
457 "lan" : [
458 {
459 "RawQuery" : "id=F4HSJVO-CP2C3IL-YLQYLSU-XTYODAG-PPU4LGV-PH3MU4N-G6K56DV-IPN47A&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=",
460 "Scheme" : "relay",
461 "Fragment" : "",
462 "RawPath" : "",
463 "Path" : "/",
464 "Host" : "31.15.66.212:443",
465 "Opaque" : "",
466 "ForceQuery" : false,
467 "User" : null
468 }
469 ]
470 }
471 }
472 LocalChangeDetected
474 Generated upon scan whenever the local disk has discovered an updated
475 file from the previous scan. This does not include events that are
476 discovered and copied from other devices (remote-change-detected), only
477 files that were changed on the local filesystem.
478 {
480 "id": 7,
481 "globalID": 59,
482 "time": "2016-09-26T22:07:10.7189141-04:00",
483 "type": "LocalChangeDetected",
484 "data": {
485 "action": "deleted",
486 "folderID": "vitwy-zjxqt",
487 "label": "TestSync",
488 "path": "C:\\Users\\Nate\\Sync\\testfolder\\test file.rtf",
489 "type": "file"
490 }
491 }
492 LocalIndexUpdated
494 Generated when the local index information has changed, due to synchro‐
495 nizing one or more items from the cluster or discovering local changes
496 during a scan.
497 {
499 "id": 59,
500 "globalID": 59,
501 "type": "LocalIndexUpdated",
502 "time": "2014-07-17T13:27:28.051369434+02:00",
503 "data": {
504 "folder": "default",
505 "items": 1000,
506 }
507 }
508 Login Attempt
510 When authentication is enabled for the GUI, this event is emitted on
511 every login attempt. If either the username or password are incorrect,
512 success is false and in any case the given username is returned.
513 {
515 "id" : 187,
516 "time" : "2017-03-07T00:19:24.420386143+01:00",
517 "data" : {
518 "username" : "somename",
519 "success" : false
520 },
521 "type" : "LoginAttempt",
522 "globalID" : 195
523 }
524 RemoteChangeDetected
526 Generated upon scan whenever a file is locally updated due to a remote
527 change. Files that are updated locally produce a local-change-detected
528 event.
529 {
531 "time" : "2017-03-06T23:58:21.844739891+01:00",
532 "globalID" : 123,
533 "data" : {
534 "type" : "file",
535 "action" : "deleted",
536 "path" : "/media/ntfs_data/Dokumente/testfile",
537 "label" : "Dokumente",
538 "folderID" : "Dokumente",
539 "modifiedBy" : "BPDFDTU"
540 },
541 "type" : "RemoteChangeDetected",
542 "id" : 2
543 }
544 Remote Download Progress
546 This event is emitted when a download-progress message is received. It
547 returns a map data of filenames with a count of downloaded blocks. The
548 files in questions are currently being downloaded on the remote device
549 and belong to folder.
550 {
552 "time" : "2017-03-07T00:11:37.65838955+01:00",
553 "globalID" : 170,
554 "data" : {
555 "state" : {
556 "tahr64-6.0.5.iso" : 1784
557 },
558 "device" : "F4HSJVO-CP2C3IL-YLQYLSU-XTYODAG-PPU4LGV-PH3MU4N-G6K56DV-IPN47A",
559 "folder" : "Dokumente"
560 },
561 "type" : "RemoteDownloadProgress",
562 "id" : 163
563 }
564 RemoteIndexUpdated
566 Generated each time new index information is received from a device.
567 {
569 "id": 44,
570 "globalID": 44,
571 "type": "RemoteIndexUpdated",
572 "time": "2014-07-13T21:04:35.394184435+02:00",
573 "data": {
574 "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG",
575 "folder": "lightroom",
576 "items": 1000
577 }
578 }
579 Starting
581 Emitted exactly once, when Syncthing starts, before parsing configura‐
582 tion etc.
583 {
585 "id": 1,
586 "globalID": 1,
587 "type": "Starting",
588 "time": "2014-07-17T13:13:32.044470055+02:00",
589 "data": {
590 "home": "/home/jb/.config/syncthing"
591 }
592 }
593 StartupComplete
595 Emitted exactly once, when initialization is complete and Syncthing is
596 ready to start exchanging data with other devices.
597 {
599 "id": 1,
600 "globalID": 1,
601 "type": "StartupComplete",
602 "time": "2014-07-13T21:03:18.383239179+02:00",
603 "data": null
604 }
605 StateChanged
607 Emitted when a folder changes state. Possible states are idle, scan‐
608 ning, syncing and error. The field duration is the number of seconds
609 the folder spent in state from. In the example below, the folder
610 default was in state scanning for 0.198 seconds and is now in state
611 idle.
612 {
614 "id": 8,
615 "globalID": 8,
616 "type": "StateChanged",
617 "time": "2014-07-17T13:14:28.697493016+02:00",
618 "data": {
619 "folder": "default",
620 "from": "scanning",
621 "duration": 0.19782869900000002,
622 "to": "idle"
623 }
624 }
625
627 The Syncthing Authors
628
630 2014-2019, The Syncthing Authors
631v1 Mar 17, 2020 SYNCTHING-EVENT-API(7)