Stream Checkpoint Management

A stream ingress persists its position per partition as durable checkpoints. The checkpoint management API is the operational surface for those positions: replay a stream after a data restore, skip a backlog, resume from a known position, or clear state for a fresh start.

Checkpoint management is a dedicated action — never an ordinary ingress PUT/PATCH — because it carries its own authorization, audit, and runtime coordination.

Reading checkpoints

Add ?checkpoints=true when fetching a stream ingress:

GET /resources/ingresses/{ingressId}?checkpoints=true

The response carries the ingress definition plus one checkpoint per partition:

{
  "ingress": { "id": "apps/my-app/events", "type": "stream", "...": "..." },
  "checkpoints": [
    {
      "partitionId": "0",
      "position": { "offset": "12345" },
      "observedPosition": { "sequenceNumber": 9, "enqueuedTime": "2026-09-20T10:12:35Z" },
      "updatedAt": "2026-09-20T10:12:41Z",
      "generation": 3
    }
  ]
}

• position is the adapter-owned opaque progress token, returned verbatim — for Event Hubs, an offset.
• observedPosition is optional adapter diagnostics (sequence number, enqueue time) for operator readability.
• generation increments on every operator reset; runtime writes must match it to land.

Resetting checkpoints

POST /resources/ingresses/{ingressId}/checkpoints

Every request requires a reason — it is audited together with the before/after positions:

{
  "reason": "Replaying after the downstream data restore",
  "position": {
    "kind": "earliest"
  }
}

The runtime pauses the ingress's partition processors, drains in-flight work, resolves the requested positions through the connection's adapter, applies the change atomically with generation fencing, and re-attaches at the new positions.

Position kinds

Kind	Body	Effect
earliest	{ "kind": "earliest" }	Replay the stream from the beginning.
latest	{ "kind": "latest" }	Skip the backlog; start from only new events.
provider	{ "kind": "provider", "providerPosition": { "offset": "12345" } }	Move to an adapter-native position (e.g. an Event Hubs offset).
clear	{ "kind": "clear" }	Remove all checkpoints; the ingress re-attaches at its configured startPosition.
timestamp	{ "kind": "timestamp", "timestamp": "2026-09-01T00:00:00Z" }	Rejected by the Event Hubs adapter — the AMQP offset selector is offset-only. Use provider offsets instead.

kind parsing is case-insensitive.

Authorization

ingresses/{id}:manage  # operate a specific stream ingress's checkpoints
ingresses:manage       # class-level wildcard

The manage permission is deliberately separate from write: operating a consumer's position is an operations concern, not a configuration change. The required reason and the before/after positions are audited with it.

Best practices

• Prefer earliest/latest over provider offsets unless you know the exact position — the tokens are adapter-native and only meaningful to the adapter.
• A reset is atomic across partitions — the whole consumer moves at once, with in-flight work drained first.
• Quarantined events are not skipped by resets alone — the poison policy already advanced past them; check the ingress signals and error records for quarantined events after an incident.

Related

• Stream ingresses — the consumption model
• Connections — the adapter that owns positions
• WebSocket events — reacting to changes in real time