api.md

CLI and local API

Start checkpoint serve first. CLI commands send requests to http://127.0.0.1:3038; use --url when the engine uses a different address. Responses are JSON. A submitted run is asynchronous: inspect its ID using the API or open it in the interface.

checkpoint version
checkpoint doctor
checkpoint run --entry example:supplier
checkpoint run --entry /absolute/path/own_workflow.py --input input.json
checkpoint list
checkpoint replay --source RUN_ID
checkpoint branch --source RUN_ID --step normalize --replacement replacement.json
checkpoint compare --source ORIGINAL_ID --other CHILD_ID
checkpoint review-export --source RUN_ID --mode reproduction
checkpoint review-export --source RUN_ID --mode reproduction --file manifest.json --digest REVIEW_DIGEST
checkpoint export --source RUN_ID --mode reproduction --digest REVIEW_DIGEST
checkpoint export --source RUN_ID --mode inspection
checkpoint import --path /absolute/path/inspection.zip

Use checkpoint.exe on Windows. JSON files contain values directly, not a wrapper with an input key. An omitted or JSON-null workflow input uses the workflow defaults in version 0.1.0. A branch replacement can be any JSON value, including null.

Routes

Method and /api path	Behavior
GET /bootstrap	Version, protocol, local session and fixture request counter
GET /health	Current session and storage diagnostic
GET /examples	Bundled workflow definitions; imports trusted bundled code
GET /runs?limit=50&offset=0	Latest run snapshots; at most 100 per page
GET /runs/{id}	A run snapshot
POST /runs	Start record, replay or branch
POST /runs/{id}/cancel	Persist cancellation and signal the worker
GET /runs/{id}/steps/{step}	Input/output/log evidence or explicit availability errors
GET /runs/{id}/events?after=0	Next 500 events after a sequence cursor
GET /runs/{id}/operations	Supported operations, including inherited provenance
GET /compare?a=ID&b=ID	Step-aligned comparison
GET /runs/{id}/export-review?mode=reproduction	Exact sorted file inventory, sizes, hashes and review digest; no ZIP is written
GET /runs/{id}/export-content?mode=reproduction&digest=DIGEST&path=manifest.json	Selected file text/base64 and readable captured response if applicable; rejects stale digest
POST /runs/{id}/export	{"mode":"reproduction"} or inspection; optional reviewedDigest rejects changed contents; saves locally and returns location/manifest
GET /exports/{name}	Download an already-saved ZIP
POST /import	{"path":"/local/bundle.zip"}; inspection-only import
GET /artifacts/{sha256}	Integrity-checked artifact bytes

Mutation requests require X-Checkpoint-Session from bootstrap and JSON Content-Type. The exact printed Host is required; a present Origin must match the local application. The supported worker-only HTTP route uses a different active worker credential. Do not expose this service through a public reverse proxy.

Start bodies:

{"entry":"example:supplier","mode":"record"}

{"mode":"replay","sourceId":"RUN_ID"}

{"mode":"branch","sourceId":"RUN_ID","boundary":"normalize","replacement":{"fetch":{"items":[]}}}

Errors use {"error":"message"} and a non-success HTTP status. Run execution failures live in the asynchronous run/step state; acceptance of a request is not completion.