Bootstrap
Bootstrap is the new-client initialization endpoint. A single request returns:
- The latest snapshot (if any)
- The updates after the snapshot (one part per record on a JSON stream, one part in all on any other stream), up to the stream's current tail or up to an honest stopping point
GET /{bucket}/{stream}/bootstrapThe response is multipart/mixed:
- First part. The snapshot. If no snapshot exists, this part is present but empty.
- Subsequent parts. Incremental updates from the snapshot offset (or from the earliest retained offset, if no snapshot exists).
Each part has its own Content-Type: the snapshot part uses snapshot_content_type. Update parts use the stream's content type. The client does not need to know in advance whether a snapshot exists. The same parsing path handles both cases.
Partial responses
Bootstrap only serves updates that are still in the hot tier, and at most 8 MiB of them per response. When updates after the snapshot have already moved to cold storage, or there are more than 8 MiB of them, the response stops early: Stream-Next-Offset is where it stopped and Stream-Up-To-Date is absent. In the cold case, and for a non-JSON stream above 8 MiB, the response holds only the snapshot part; a JSON stream above 8 MiB stops at a record boundary. It never skips bytes.
Clients therefore follow one rule: after applying the bootstrap response, read from Stream-Next-Offset with ordinary reads until Stream-Up-To-Date: true, then go live. A complete response simply makes that loop empty.
When to use bootstrap vs catch-up
| You want… | Use |
|---|---|
| Latest state, fastest first-load | /bootstrap |
| Replay every byte from the beginning | GET /{b}/{s}?offset=-1 |
| Resume from a known offset that's still retained | GET /{b}/{s}?offset=N |
Resume from an offset the server has since trimmed (410 Gone) | /bootstrap, then continue from its Stream-Next-Offset |
Live continuation
Bootstrap does not accept ?live=sse. Combining the multipart body with an SSE event stream is rejected with 400. To go live after bootstrap, finish reading the bootstrap response, then open a separate GET /{b}/{s}?offset=<Stream-Next-Offset>&live=sse. SSE delivers any remaining catch-up data first, so this also covers a partial response.