Can't understand the events API

Support
1

Sorry if I did not understand the events API, but is the following expected? I does not make sense for me.

$ time curl -s -X GET -H "X-API-Key: Q...9" "http://localhost:8384/rest/events?since=31"
[
  {
    "id": 32,
    "globalID": 32,
    "time": "2025-02-15T22:11:43.848897534+01:00",
    "type": "ClusterConfigReceived",
    "data": {
      "device": "DLCFWAV-5YIL3ZS-DDYTSKS-AOE3X4E-ZTJGWTW-MFI6IIV-LJFHKSQ-YKFO2AJ"
    }
  }
]

real    0m0.052s
user    0m0.007s
sys     0m0.000s

$ time curl -s -X GET -H "X-API-Key: Q...9" "http://localhost:8384/rest/events?since=31&events=ClusterConfigReceived"
[]

real    1m0.029s
user    0m0.006s
sys     0m0.006s
2

Yes.

To filter the event list, in effect creating a specific subscription for only the desired event types, add a parameter

(GET /rest/events — Syncthing documentation)

The IDs are per event subscription. The first time you use that combination of events in the filter you create a subscription for those event types.

2 Likes
3

Do you mean that this API call waits for at least 31 ClusterConfigReceived events being generated before returning an answer?

4

Yes. You’re creating a new subscription for only cluster config events, and then asking for the event with id 32 or higher within that stream.

5

This means also that if I want all events generated since the server started, I should make an API call as soon as the server starts.

For example calling /rest/events?events=ClusterConfigReceived would create a subscription for events of type ClusterConfigReceived. After the first call, another identical call would retrieve all the events since the first call, because since=0 is the default. Correct?

  1. Is the same subscription matched irrespective of the ip address sending the API call?
  2. How can I just create the subscription without waiting for 60 seconds?
  3. Does /rest/events (without parameters) generate a subscription for every possibile event type, or only the event types that already happened, or a single type-less subscription that is accessible only with that identical API call?
6

The IP address does not matter, no. The rest of your questions are answered quite well, I think, by the few paragraphs on the documentation page I already linked to: GET /rest/events — Syncthing documentation