Publish snapshot

Publishes a new checkpoint blob at the given offset. The snapshot replaces any previously published snapshot, but does not delete stream history. Retention advances only through the separate /retention endpoint.

bucketpathstringrequired

Bucket ID.

streampathstringrequired

Stream ID.

offsetpathstringrequired

Stream offset this snapshot represents: the 20-character zero-padded decimal token.

For JSON streams, PUT /{bucket}/{stream}/snapshot?record={record} resolves a stable record ordinal to its byte offset and publishes at that boundary.

Content-Typeheaderstring

Content type of the snapshot blob, stored separately from the stream's own content type. Defaults to application/octet-stream.

Stream-Snapshot-Matchheaderstring

Optional digest of the currently visible snapshot. The publish succeeds only if it still matches.

bodybodybinaryrequired

The snapshot blob bytes. Maximum size is 128 MiB. Larger bodies return 413.

Response

Status	Meaning
`204`	Snapshot published successfully.
`400`	Invalid offset or content type.
`404`	Stream not found or expired.
`409`	Stale publish (a newer snapshot exists) or offset out of range.
`410`	Snapshot offset is older than the retained stream history.
`413`	Snapshot body exceeds the maximum allowed size.

Response headers include Stream-Next-Offset, Stream-Snapshot-Offset, and Stream-Snapshot-Digest. Repeating the same offset, content type, and body is idempotent and returns the same digest. Reusing an offset with different content returns 409.

curl -X PUT 'http://127.0.0.1:4437/demo/hello/snapshot/00000000000000000042' \
  -H 'Content-Type: application/json' \
  --data-binary '{"state": "aggregated snapshot data"}'

Advance retention

PUT /{bucket}/{stream}/retention/{offset} explicitly discards history before a published checkpoint. For JSON streams, PUT /{bucket}/{stream}/retention?record={record} accepts a record ordinal. The boundary must be monotonic, aligned, and no newer than the visible checkpoint.

After a successful 204, reads before the retained offset return 410 Gone. This separate step lets clients publish and verify a checkpoint before making history unreachable.

Delete snapshot

DELETE /{bucket}/{stream}/snapshot/{offset}

Attempting to delete the current visible snapshot is not allowed.

Status	Meaning
`404`	No snapshot at the given offset.
`409`	Cannot delete the current snapshot.

Snapshots are immutable at a given offset. A byte-identical retry is idempotent; a different body at the same offset conflicts. Publishing does not advance retention.