Provided by: syncthing_0.14.43+ds1-6_amd64 bug

NAME

       syncthing-event-api - Event API

DESCRIPTION

       Syncthing  provides  a  simple  long  polling  interface for exposing events from the core
       utility towards a GUI.

       To receive events, perform a HTTP GET of /rest/events  or  /rest/events/disk.  The  latter
       returns only local-change-detected and remote-change-detected events, the former all other
       events unless filtered.

       To filter the event list, in effect creating a specific subscription for only the  desired
       event  types,  add  a parameter events=EventTypeA,EventTypeB,... where the event types are
       any from the list below.

       The optional parameter since=<lastSeenID> sets the ID of the  last  event  you’ve  already
       seen.  Syncthing returns a JSON encoded array of event objects, starting at the event just
       after the one with this last seen ID. The default value is 0, which  returns  all  events.
       There is a limit to the number of events buffered, so if the rate of events is high or the
       time between polling calls is long some events might be missed. This can  be  detected  by
       noting a discontinuity in the event IDs.

       If  no  new events are produced since <lastSeenID>, the HTTP call blocks and waits for new
       events to happen before returning. By default it times out after 60 seconds  returning  an
       empty  array.  The  time  out  duration  can  be  customized  with  the optional parameter
       timeout=seconds.

       To receive only a limited number of events, add the  limit=n  parameter  with  a  suitable
       value for n and only the last n events will be returned. This can be used to catch up with
       the latest event ID after a disconnection for example: /rest/events?since=0&limit=1.

EVENT STRUCTURE

       Each event is represented by an object similar to the following:

          {
              "id": 2,
              "globalID": 3,
              "type": "DeviceConnected",
              "time": "2014-07-13T21:04:33.687836696+02:00",
              "data": {
                  "addr": "172.16.32.25:22000",
                  "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
              }
          }

       The top level keys id, globalID, time, type and data are always present, though  data  may
       be null.

       id     A  unique  ID for this event on the events API. It always increases by 1: the first
              event generated has id 1, the next has id 2 etc. If this increases by more than  1,
              then one or more events have been skipped by the events API.

       globalID
              A  global  ID  for  this event, across the events API, the audit log, and any other
              sources. It may increase by more than 1, but it will  always  be  greater  than  or
              equal to the id.

       time   The time the event was generated.

       type   Indicates  the  type  of  (i.e. reason for) the event and is one of the event types
              below.

       data   An object containing optional extra information; the exact structure is  determined
              by the event type.

EVENT TYPES

   ConfigSaved
       Emitted after the config has been saved by the user or by Syncthing itself.

          {
              "id": 50,
              "type": "ConfigSaved",
              "time": "2014-12-13T00:09:13.5166486Z",
              "data": {
                  "Version": 7,
                  "Options": {"..."},
                  "GUI": {"..."},
                  "Devices": [{"..."}],
                  "Folders": [{"..."}]
              }
          }

   DeviceConnected
       Generated each time a connection to a device has been established.

          {
              "id": 2,
              "type": "DeviceConnected",
              "time": "2014-07-13T21:04:33.687836696+02:00",
              "data": {
                  "addr": "172.16.32.25:22000",
                  "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG",
                  "deviceName": "Laptop",
                  "clientName": "syncthing",
                  "clientVersion": "v0.13.4",
                  "type": "TCP (Client)"
              }
          }

   DeviceDisconnected
       Generated each time a connection to a device has been terminated.

          {
              "id": 48,
              "type": "DeviceDisconnected",
              "time": "2014-07-13T21:18:52.859929215+02:00",
              "data": {
                  "error": "unexpected EOF",
                  "id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
              }
          }

       NOTE:
          The  error  key contains the cause for disconnection, which might not necessarily be an
          error as such. Specifically, “EOF” and “unexpected EOF”  both  signify  TCP  connection
          termination,  either  due  to  the other device restarting or going offline or due to a
          network change.

   DeviceDiscovered
       Emitted when a new device is discovered using local discovery.

          {
              "id": 13,
              "type": "DeviceDiscovered",
              "time": "2014-07-17T13:28:05.043465207+02:00",
              "data": {
                  "addrs": [
                      "172.16.32.25:22000"
                  ],
                  "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
              }
          }

   DevicePaused
       Emitted when a device was paused.

          {
              "id": 13,
              "type": "DevicePaused",
              "time": "2014-07-17T13:28:05.043465207+02:00",
              "data": {
                  "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
              }
          }

   DeviceRejected
       Emitted when there is a connection from a device we are not configured to talk to.

          {
              "id": 24,
              "type": "DeviceRejected",
              "time": "2014-08-19T10:43:00.562821045+02:00",
              "data": {
                  "address": "127.0.0.1:51807",
                  "device": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK"
              }
          }

   DeviceResumed
       Generated each time a device was resumed.

          {
              "id": 2,
              "type": "DeviceResumed",
              "time": "2014-07-13T21:04:33.687836696+02:00",
              "data": {
                  "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
              }
          }

   DownloadProgress
       Emitted during file downloads for each folder for each file. By default only a single file
       in a folder is handled at the same time, but custom configuration can cause multiple files
       to be shown.

          {
              "id": 221,
              "type": "DownloadProgress",
              "time": "2014-12-13T00:26:12.9876937Z",
              "data": {
                  "folder1": {
                      "file1": {
                          "Total": 800,
                          "Pulling": 2,
                          "CopiedFromOrigin": 0,
                          "Reused": 633,
                          "CopiedFromElsewhere": 0,
                          "Pulled": 38,
                          "BytesTotal": 104792064,
                          "BytesDone": 87883776
                      },
                      "dir\\file2": {
                          "Total": 80,
                          "Pulling": 2,
                          "CopiedFromOrigin": 0,
                          "Reused": 0,
                          "CopiedFromElsewhere": 0,
                          "Pulled": 32,
                          "BytesTotal": 10420224,
                          "BytesDone": 4128768
                      }
                  },
                  "folder2": {
                      "file3": {
                          "Total": 800,
                          "Pulling": 2,
                          "CopiedFromOrigin": 0,
                          "Reused": 633,
                          "CopiedFromElsewhere": 0,
                          "Pulled": 38,
                          "BytesTotal": 104792064,
                          "BytesDone": 87883776
                      },
                      "dir\\file4": {
                          "Total": 80,
                          "Pulling": 2,
                          "CopiedFromOrigin": 0,
                          "Reused": 0,
                          "CopiedFromElsewhere": 0,
                          "Pulled": 32,
                          "BytesTotal": 10420224,
                          "BytesDone": 4128768
                      }
                  }
              }
          }

       • Total - total number of blocks in the file

       • Pulling - number of blocks currently being downloaded

       • CopiedFromOrigin - number of blocks copied from the file we are about to replace

       • Reused - number of blocks reused from a previous temporary file

       • CopiedFromElsewhere - number of blocks copied from  other  files  or  potentially  other
         folders

       • Pulled - number of blocks actually downloaded so far

       • BytesTotal - approximate total file size

       • BytesDone  -  approximate  number  of  bytes  already handled (already reused, copied or
         pulled)

       Where block size is 128KB.

       Files/folders appearing in the event data imply that the download  has  been  started  for
       that  file/folder,  where  disappearing  implies  that the downloads have been finished or
       failed for that file/folder. There is always a last event  emitted  with  no  data,  which
       implies all downloads have finished/failed.

   FolderCompletion
       The  FolderCompletion  event  is  emitted  when  the local or remote contents for a folder
       changes. It contains the completion percentage for a given remote device  and  is  emitted
       once per currently connected remote device.

          {
              "id": 84,
              "type": "FolderCompletion",
              "time": "2015-04-17T14:14:27.043576583+09:00",
              "data": {
                  "completion": 100,
                  "device": "I6KAH76-66SLLLB-5PFXSOA-UFJCDZC-YAOMLEK-CP2GB32-BV5RQST-3PSROAU",
                  "folder": "default"
              }
          }

   FolderErrors
       The  FolderErrors  event is emitted when a folder cannot be successfully synchronized. The
       event contains the ID of the affected folder and a list of errors for files or directories
       therein.  This  list  of  errors is obsolete once the folder changes state to syncing - if
       errors remain after the next synchronization attempt, a new FolderErrors event is emitted.

          {
              "id": 132,
              "type": "FolderErrors",
              "time": "2015-06-26T13:39:24.697401384+02:00",
              "data": {
                  "errors": [
                      {
                          "error": "open /Users/jb/src/github.com/syncthing/syncthing/test/s2/h2j/.syncthing.aslkjd.tmp: permission denied",
                          "path": "h2j/aslkjd"
                      }
                  ],
                  "folder": "default"
              }
          }

       New in version 0.11.12.

       SEE ALSO:
          The statechanged event.

   FolderRejected
       Emitted when a device sends index information for a folder we do not have, or have but  do
       not share with the device in question.

          {
              "id": 27,
              "type": "FolderRejected",
              "time": "2014-08-19T10:41:06.761751399+02:00",
              "data": {
                  "device": "EJHMPAQ-OGCVORE-ISB4IS3-SYYVJXF-TKJGLTU-66DIQPF-GJ5D2GX-GQ3OWQK",
                  "folder": "GXWxf-3zgnU",
                  "folderLabel": "My Pictures"
              }
          }

   Folder Scan Progress
       Emitted  in  regular  intervals  (folder  setting ProgressIntervalS, 2s by default) during
       scans giving the amount of bytes already scanned and to be scanned in total , as  well  as
       the current scanning rates in bytes per second.

          {
             "data" : {
                "total" : 1,
                "rate" : 0,
                "current" : 0,
                "folder" : "bd7q3-zskm5"
             },
             "globalID" : 29,
             "type" : "FolderScanProgress",
             "time" : "2017-03-06T15:00:58.072004209+01:00",
             "id" : 29
          }

   FolderSummary
       The  FolderSummary event is emitted when folder contents have changed locally. This can be
       used to calculate the current local completion state.

          {
              "id": 16,
              "type": "FolderSummary",
              "time": "2015-04-17T14:12:20.460121585+09:00",
              "data": {
                  "folder": "default",
                  "summary": {
                      "globalBytes": 0,
                      "globalDeleted": 0,
                      "globalFiles": 0,
                      "ignorePatterns": false,
                      "inSyncBytes": 0,
                      "inSyncFiles": 0,
                      "invalid": "",
                      "localBytes": 0,
                      "localDeleted": 0,
                      "localFiles": 0,
                      "needBytes": 0,
                      "needFiles": 0,
                      "state": "idle",
                      "stateChanged": "2015-04-17T14:12:12.455224687+09:00",
                      "version": 0
                  }
              }
          }

   ItemFinished
       Generated when Syncthing ends synchronizing a  file  to  a  newer  version.  A  successful
       operation:

          {
              "id": 93,
              "type": "ItemFinished",
              "time": "2014-07-13T21:22:03.414609034+02:00",
              "data": {
                  "item": "test.txt",
                  "folder": "default",
                  "error": null,
                  "type": "file",
                  "action": "update"
              }
          }

       An unsuccessful operation:

          {
              "id": 44,
              "type": "ItemFinished",
              "time": "2015-05-27T11:21:05.711133004+02:00",
              "data": {
                  "action": "update",
                  "error": "open /Users/jb/src/github.com/syncthing/syncthing/test/s2/foo/.syncthing.hej.tmp: permission denied",
                  "folder": "default",
                  "item": "foo/hej",
                  "type": "file"
              }
          }

       The  action field is either update (contents changed), metadata (file metadata changed but
       not contents), or delete.

       New in version 0.11.10: The metadata action.

   ItemStarted
       Generated when Syncthing begins synchronizing a file to a newer version.

          {
              "id": 93,
              "type": "ItemStarted",
              "time": "2014-07-13T21:22:03.414609034+02:00",
              "data": {
                  "item": "test.txt",
                  "folder": "default",
                  "type": "file",
                  "action": "update"
              }
          }

       The action field is either update (contents changed), metadata (file metadata changed  but
       not contents), or delete.

       New in version 0.11.10: The metadata action.

   Listen Addresses Changed
       This event is emitted when a listen address changes.

          {
             "type" : "ListenAddressesChanged",
             "id" : 70,
             "time" : "2017-03-06T15:01:24.88340663+01:00",
             "globalID" : 70,
             "data" : {
                "address" : {
                   "Fragment" : "",
                   "RawQuery" : "",
                   "Scheme" : "dynamic+https",
                   "Path" : "/endpoint",
                   "RawPath" : "",
                   "User" : null,
                   "ForceQuery" : false,
                   "Host" : "relays.syncthing.net",
                   "Opaque" : ""
                },
                "wan" : [
                   {
                      "ForceQuery" : false,
                      "User" : null,
                      "Host" : "31.15.66.212:443",
                      "Opaque" : "",
                      "Path" : "/",
                      "RawPath" : "",
                      "RawQuery" : "id=F4HSJVO-CP2C3IL-YLQYLSU-XTYODAG-PPU4LGV-PH3MU4N-G6K56DV-IPN47A&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=",
                      "Scheme" : "relay",
                      "Fragment" : ""
                   }
                ],
                "lan" : [
                   {
                      "RawQuery" : "id=F4HSJVO-CP2C3IL-YLQYLSU-XTYODAG-PPU4LGV-PH3MU4N-G6K56DV-IPN47A&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=",
                      "Scheme" : "relay",
                      "Fragment" : "",
                      "RawPath" : "",
                      "Path" : "/",
                      "Host" : "31.15.66.212:443",
                      "Opaque" : "",
                      "ForceQuery" : false,
                      "User" : null
                   }
                ]
             }
          }

   LocalChangeDetected
       Generated  upon  scan  whenever  the  local  disk  has discovered an updated file from the
       previous scan.  This does not include events that are discovered  and  copied  from  other
       devices (remote-change-detected), only files that were changed on the local filesystem.

          {
            "id": 7,
            "globalID": 59,
            "time": "2016-09-26T22:07:10.7189141-04:00",
            "type": "LocalChangeDetected",
            "data": {
              "action": "deleted",
              "folderID": "vitwy-zjxqt",
              "label": "TestSync",
              "path": "C:\\Users\\Nate\\Sync\\testfolder\\test file.rtf",
              "type": "file"
            }
          }

   LocalIndexUpdated
       Generated  when  the local index information has changed, due to synchronizing one or more
       items from the cluster or discovering local changes during a scan.

          {
              "id": 59,
              "type": "LocalIndexUpdated",
              "time": "2014-07-17T13:27:28.051369434+02:00",
              "data": {
                  "folder": "default",
                  "items": 1000,
              }
          }

   Login Attempt
       When authentication is enabled for the GUI, this event is emitted on every login  attempt.
       If  either  the  username  or password are incorrect, success is false and in any case the
       given username is returned.

          {
             "id" : 187,
             "time" : "2017-03-07T00:19:24.420386143+01:00",
             "data" : {
                "username" : "somename",
                "success" : false
             },
             "type" : "LoginAttempt",
             "globalID" : 195
          }

   RemoteChangeDetected
       Generated upon scan whenever a file is locally updated due to a remote change.  Files that
       are updated locally produce a local-change-detected event.

          {
             "time" : "2017-03-06T23:58:21.844739891+01:00",
             "globalID" : 123,
             "data" : {
                "type" : "file",
                "action" : "deleted",
                "path" : "/media/ntfs_data/Dokumente/testfile",
                "label" : "Dokumente",
                "folderID" : "Dokumente",
                "modifiedBy" : "BPDFDTU"
             },
             "type" : "RemoteChangeDetected",
             "id" : 2
          }

   Remote Download Progress
       This  event is emitted when a download-progress message is received. It returns a map data
       of filenames with a count of downloaded blocks. The files in questions are currently being
       downloaded on the remote device and belong to folder.

          {
             "time" : "2017-03-07T00:11:37.65838955+01:00",
             "globalID" : 170,
             "data" : {
                "state" : {
                   "tahr64-6.0.5.iso" : 1784
                },
                "device" : "F4HSJVO-CP2C3IL-YLQYLSU-XTYODAG-PPU4LGV-PH3MU4N-G6K56DV-IPN47A",
                "folder" : "Dokumente"
             },
             "type" : "RemoteDownloadProgress",
             "id" : 163
          }

   RemoteIndexUpdated
       Generated each time new index information is received from a device.

          {
              "id": 44,
              "type": "RemoteIndexUpdated",
              "time": "2014-07-13T21:04:35.394184435+02:00",
              "data": {
                  "device": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG",
                  "folder": "lightroom",
                  "items": 1000
              }
          }

   Starting
       Emitted exactly once, when Syncthing starts, before parsing configuration etc.

          {
              "id": 1,
              "type": "Starting",
              "time": "2014-07-17T13:13:32.044470055+02:00",
              "data": {
                  "home": "/home/jb/.config/syncthing"
              }
          }

   StartupComplete
       Emitted  exactly  once,  when  initialization  is complete and Syncthing is ready to start
       exchanging data with other devices.

          {
              "id": 1,
              "type": "StartupComplete",
              "time": "2014-07-13T21:03:18.383239179+02:00",
              "data": null
          }

   StateChanged
       Emitted when a folder changes state. Possible  states  are  idle,  scanning,  syncing  and
       error.  The field duration is the number of seconds the folder spent in state from. In the
       example below, the folder default was in state scanning for 0.198 seconds and  is  now  in
       state idle.

          {
              "id": 8,
              "type": "StateChanged",
              "time": "2014-07-17T13:14:28.697493016+02:00",
              "data": {
                  "folder": "default",
                  "from": "scanning",
                  "duration": 0.19782869900000002,
                  "to": "idle"
              }
          }

AUTHOR

       The Syncthing Authors

COPYRIGHT

       2015, The Syncthing Authors