Skip to content

Graph Checkpoints

A graph checkpoint packages a graph’s contents as a downloadable point-in-time archive captured at one exact graphSeq. You can verify it offline. This page covers checkpoint lifecycle operations for both the TypeScript and Python SDKs. The TypeScript client ships as @warmhub/sdk-ts — see the SDK overview for installation and auth setup. The Python client ships as the warmhub package — see Python setup below for installation and auth details.

The SDK exposes graph checkpoint read operations at client.graph.checkpoint. It returns status records and signed-access descriptors; it never downloads checkpoint bytes for you.

import { WarmHubClient } from '@warmhub/sdk-ts'
import { verifyGraphCheckpointArchive } from '@warmhub/sdk-ts/checkpoint'
import { createHash } from 'node:crypto'
import { createReadStream } from 'node:fs'
import { writeFile } from 'node:fs/promises'
const client = new WarmHubClient({
apiUrl: 'https://api.warmhub.ai',
auth: { getToken: async () => process.env.WH_TOKEN },
})
const checkpoint = await client.graph.checkpoint.latest('acme', 'widgets')
if (checkpoint === null) {
throw new Error('No stored checkpoint for acme/widgets')
}
const access = await client.graph.checkpoint.getAccess('acme', 'widgets', {
checkpoint: { checkpointId: checkpoint.checkpointId },
artifact: 'archive',
})
// access.url is short-lived. Fetch it directly, without a WarmHub
// Authorization header, and verify the descriptor before publishing bytes.
const response = await fetch(access.url)
if (!response.ok) throw new Error(`Checkpoint download failed: ${response.status}`)
const bytes = new Uint8Array(await response.arrayBuffer())
const sha256 = createHash('sha256').update(bytes).digest('hex')
if (bytes.byteLength !== access.byteLength || sha256 !== access.sha256) {
throw new Error('Checkpoint download did not match its access descriptor')
}
await writeFile('checkpoint.zip', bytes, { flag: 'wx' })
const verified = await verifyGraphCheckpointArchive(
createReadStream('checkpoint.zip'),
)

verified is a typed identity, count, and digest summary — checkpoint identity, sequence, record count, total bytes, and root digest. The verifier reads only supplied archive bytes; it makes no WarmHub client, transport, or network request. On failure it throws GraphCheckpointVerificationError with a stable verification reason on err.reason. Pass the access descriptor’s facts as GraphCheckpointVerificationExpected to have the verifier check identity as well as integrity.

MethodResult
client.graph.checkpoint.status(org, graph, { checkpointId } | { graphSeq })Returns one checkpoint status.
client.graph.checkpoint.latest(org, graph)Returns the latest completed checkpoint, or null.
client.graph.checkpoint.getAccess(org, graph, { checkpoint, artifact })Returns a short-lived signed descriptor for an archive, manifest, or chunk.

Checkpoint status, latest, and access requests require unrestricted repo:read plus repo:checkpoint-read (these scope names keep the repo spelling because a graph was formerly called a repo). Newly issued owner/admin role PATs include the narrow capability. A missing checkpoint is reported as NOT_FOUND; do not treat that response as evidence about graphs for which the caller has no checkpoint authority.

getAccess accepts checkpoint: 'latest', { checkpointId }, or { graphSeq }. Its artifact may be 'archive', 'manifest', or { chunkPath }. The descriptor (GraphCheckpointAccess) carries the same seven fields in both SDKs:

  • Shared fields — checkpointId, graphSeq, url, byteLength, sha256, contentType, and expiresAt in TypeScript; spelled checkpoint_id, graph_seq, url, byte_length, sha256, content_type, and expires_at in Python.
  • Python-only — the Python dataclass also carries an extra mapping holding any keys the server sent that the contract does not name.
  • Expiry handling — In the TypeScript SDK, expiresAt is normalized to a Date. In the Python SDK, expires_at is left as an epoch-millisecond integer (see Read and access). The signed URL is short-lived — one hour by default — and its lifetime is an environment-wide setting a caller cannot override per request. Treat the descriptor’s expiry field as authoritative and re-request access rather than caching a URL.

Validate bytes against the descriptor when your downloader does not already do so.

A broken export download resumes SDK-side, not through the CLI’s --resume, and only on the direct streaming path. The list below covers the TypeScript SDK; Python behavior follows it.

  • Pass the session the broken stream wrote, or rebuild one from the bytes you saved with restoreGraphExportSession(..., { partial: true }). partial is what accepts a file that stops before the trailer, as an interrupted download always does — without it the restore rejects the bytes as truncated.
  • A session carries its own cursor. afterDurableId is the fallback when it has none, and either way the session must carry the opening header.
  • A prepared export has no mid-point to resume from, because the token is redeemed as one stored object. Passing a cursor alongside a token or prefer: 'async' is rejected rather than ignored — start a new session and redeem the token again.

The Python SDK has no resume call to make: open_graph_export(...) resumes on its own. When a streamed response ends early, it re-requests from the last whole row it verified, up to resume_limit times (four by default), and then raises GraphExportError. A token download through open_graph_export_token(...) has no cursor, so it retries a failed transfer from the top, within the same limit, without returning any row twice.

Install the package and configure auth:

Terminal window
pip install warmhub

WarmHubClient.from_env() reads two environment variables:

  • WH_TOKEN — your WarmHub token (requires at minimum repo:read and repo:checkpoint-read for checkpoint operations)
  • WARMHUB_API_URL — the API base URL (e.g. https://api.warmhub.ai)

The Python SDK exposes the same read plane as client.graph.checkpoint. Use the graph handle when all calls target one graph:

from warmhub import WarmHubClient
with WarmHubClient.from_env() as client:
checkpoints = client.open_graph("acme/widgets").graph.checkpoint
latest = checkpoints.latest()
if latest is not None:
access = checkpoints.get_access(
checkpoint_id=latest.checkpoint_id,
artifact="archive",
)

Pass graph_seq= instead of checkpoint_id= to select a retained sequence. get_access(checkpoint="latest", artifact="manifest") selects the newest complete checkpoint; use artifact="chunk", chunk_path="..." for one chunk. Its URL is short-lived and must be fetched without a WarmHub authorization header. Verify the downloaded byte length and SHA-256 before using it.

In the Python SDK, GraphCheckpointAccess.expires_at is an integer epoch-millisecond value; it is not converted to a datetime.

The caller downloads access.url separately. Pass those local bytes to the verifier along with the identity and integrity facts from the access descriptor:

from warmhub import (
GraphCheckpointVerificationError,
GraphCheckpointVerificationExpected,
verify_graph_checkpoint_archive,
)
expected = GraphCheckpointVerificationExpected(
checkpoint_id=access.checkpoint_id,
graph_seq=access.graph_seq,
byte_length=access.byte_length,
sha256=access.sha256,
)
try:
verified = verify_graph_checkpoint_archive("checkpoint.zip", expected=expected)
except GraphCheckpointVerificationError as error:
print(error.reason) # stable failure category
else:
print(verified.checkpoint_id, verified.record_count, verified.root_digest)

This is local/offline: it returns a typed identity, count, and digest summary, or raises GraphCheckpointVerificationError with a stable reason. It accepts a path, bytes-like object, binary file, or Iterable[bytes]. There is no async variant of the verifier; only the synchronous verify_graph_checkpoint_archive(...) is exported. Use this verifier after downloading an archive and before trusting it as an external snapshot.

The Python verifier accepts only archives whose manifest carries formatVersion: 4. Passing an archive with any other format version raises GraphCheckpointVerificationError with reason == 'manifest_invalid'.

The async client surface covers the same checkpoint read methods:

from warmhub import AsyncWarmHubClient
async with AsyncWarmHubClient.from_env() as client:
checkpoints = client.open_graph("acme/widgets").graph.checkpoint
latest = await checkpoints.latest()
if latest is not None:
access = await checkpoints.get_access(
checkpoint_id=latest.checkpoint_id,
artifact="archive",
)