TreasurySpring Event Checkpoints API
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.