Skip to main content

Event Checkpoints

Server-managed cursors for stateless event stream consumers.

In most cases, checkpoints are not needed. If your system can persist data locally (e.g. in a database, file, or key-value store), store the cursor value from GET /event yourself and pass it as start_cursor on the next request.

When to use checkpoints:

Use this endpoint if your system runs in an environment that cannot reliably persist state between invocations — for example, a stateless function, a script with no backing store, or a system that delegates position tracking to TreasurySpring entirely.

A checkpoint is a named record stored server-side that remembers where your last successful sync run ended. Instead of storing the cursor yourself, you store it here and retrieve it at the start of each sync run:

  1. Create a checkpoint once: PUT /event/checkpoint/{name} — the cursor is initialised to the current end of the event stream.
  2. Read the checkpoint at the start of each sync run: GET /event/checkpoint/{name} → cursor, checkpointVersion.
  3. Fetch events from that cursor: GET /event?start_cursor={cursor}.
  4. Advance the checkpoint after successful processing: PATCH /event/checkpoint/{name} with expectedCheckpointVersion and newCursor. The checkpointVersion acts as a safety check — if another process has already advanced the checkpoint since you last read it, the request returns a 409 Conflict with the current state so you can reconcile before retrying.

Checkpoints are scoped to the authenticated API user.