API

Checkpoints

Checkpoints give an application a stable name for a known-good namespace cut. Creating a checkpoint labels the newest durable snapshot body for the namespace and stores that small label record in S3. It does not run a scan or write rows.

Use checkpoints when a downstream app needs to browse, diff, or drop data by a named catalog cut instead of by an ad hoc catalog_run_id filter. The checkpoint response includes the snapshot watermark_ms, content sha, and row_count added since the previous checkpoint.

Routes

Route	Method	Behavior
`POST /v2/namespaces/{ns}/checkpoints`	POST	Create or return an immutable checkpoint label.
`GET /v2/namespaces/{ns}/checkpoints`	GET	List checkpoints newest first.
`GET /v2/namespaces/{ns}/checkpoints/{label}`	GET	Resolve one checkpoint label.

Create

checkpoint = await client.create_checkpoint("products", {
    "label": "catalog-2026-06-15",
})

checkpoint, err := client.CreateCheckpoint(ctx, "products",
    &hevlayer.CreateCheckpointRequest{Label: "catalog-2026-06-15"})

const checkpoint = await client.createCheckpoint("products", {
  label: "catalog-2026-06-15",
});

curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/products/checkpoints" \
  -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "catalog-2026-06-15"}'

Response:

{
  "namespace": "products",
  "label": "catalog-2026-06-15",
  "watermark_ms": 1749513600000,
  "sha": "3f9e8b21...",
  "row_count": 10000
}

Re-posting the same label returns the existing checkpoint unchanged, even if newer snapshots have landed. Labels are namespace-local and may contain ASCII letters, numbers, -, _, ., and :.

The namespace must already have at least one durable snapshot. If no snapshot body exists yet, creation returns 412 precondition_failed.

List

page = await client.list_checkpoints("products", limit=20)

page, err := client.ListCheckpoints(ctx, "products",
    &hevlayer.ListCheckpointsParams{Limit: 20})

const page = await client.listCheckpoints("products", { limit: 20 });

curl "$LAYER_GATEWAY_URL/v2/namespaces/products/checkpoints?limit=20" \
  -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY"

{
  "checkpoints": [
    {
      "namespace": "products",
      "label": "catalog-2026-06-15",
      "watermark_ms": 1749513600000,
      "sha": "3f9e8b21...",
      "row_count": 10000
    }
  ],
  "next_cursor": null
}

Query param	Default	Purpose
`limit`	50	Maximum entries returned. Capped at 500.
`before`	none	Opaque cursor from the previous page’s `next_cursor`.

Resolve

checkpoint = await client.get_checkpoint("products", "catalog-2026-06-15")

checkpoint, err := client.GetCheckpoint(ctx, "products", "catalog-2026-06-15")

const checkpoint = await client.getCheckpoint("products", "catalog-2026-06-15");

curl "$LAYER_GATEWAY_URL/v2/namespaces/products/checkpoints/catalog-2026-06-15" \
  -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY"

Resolve returns 404 not_found when the label does not exist in that namespace.