Sync API

One endpoint.

Query parameters#

• since — stream position (int). Optional; default 0 (everything from the start, capped by limit).
• limit — max events returned. Default 100, max 500.
• timeout — max wait time in ms, default 30000 (30s). If no events arrive within this window, returns an empty list.

Behaviour#

Two modes:

1. Catch-up — if there are unread events since since, returns them immediately (up to limit). The client then advances its cursor and re-polls.
2. Long-poll — if there are none, the request blocks. As soon as a new event arrives in any room the caller can see, it returns. If the timeout elapses with nothing, returns an empty list (signal to re-poll).

Example#

1
2

curl "$BASE/v1/sync?since=12345&limit=100&timeout=30000" \
  -H "Authorization: Bearer $TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "data": {
    "events": [
      {
        "id": "evt-…",
        "stream_position": 12346,
        "room_id": "room-…",
        "event_type": "swp.room.message",
        "content": { ... },
        "sender_id": "5e4d…",
        "origin_ts": 1778939467
      },
      …
    ],
    "next_cursor": 12446,
    "has_more": true
  }
}

has_more tells you whether more events are available beyond the returned page; the client re-polls with the new cursor.

When to use sync vs. WebSocket#

Use the WebSocket stream as your primary subscription. Use /v1/sync on:

• Initial app open — catch up since the last cursor stored locally.
• Reconnect after WS drop — bridge the gap.
• Mobile or background — when WS isn't practical to keep open.

Stream position#

Stream positions are tenant-wide monotonic integers. They don't correspond to anything user-visible; treat them as opaque cursors.

Permission#

The endpoint only returns events for rooms you can see (membership state in join or leave). Cross-tenant events are filtered out.