Skip to main content
POST
Allocate a fenced checkpoint capture plan

Authorizations

Authorization
string
header
required

Runner token beginning with agt_r, returned once by POST /v1/admin/runners

Path Parameters

lease_id
string
required

Native lease UUIDv7.

Body

application/json

Allocate immutable page identities before capture uploads.

entry_count
integer<int32>
required

Expanded entries, checked again against complete pages.

Required range: x >= 0
fencing_token
integer<int64>
required

Existing fleet-slot authority.

Required range: x >= 0
format_version
integer<int32>
required

Restore format, independently checked by the daemon.

Required range: x >= 0
logical_bytes
integer<int64>
required

Expanded logical state, independent of deduplication.

Required range: x >= 0
mode
enum<string>
required

Initial retained source or an incremental logical state.

Available options:
retain_base,
incremental
operation_id
string
required

Retry identity; replay returns this exact plan.

page_count
integer<int32>
required

Ordered page identities to allocate.

Required range: x >= 0
task
object
required

Current objective version.

toolbox_digest
string
required

Pinned host-local toolbox, excluded from checkpoint bytes.

upload_budget_bytes
integer<int64>
required

Declared unique new content allowance, clamped natively by mode.

Required range: x >= 0
base_id
string | null

An already verified base; omitted for repository-free tasks.

commit_oid
string | null

Captured repository head; an incremental plan can use an older retained base.

Response

Immutable checkpoint plan replay

Native recovery descriptor, bounded independently of manifest size.

base_page_ids
string[]
required

Verified retained base pages, read through the same scoped page resource.

checkpoint_id
string
required

Native task-bound plan.

covered_input_sequence
integer<int64>
required

Inputs actually incorporated in this state.

Required range: x >= 0
effect_watermark
integer<int64>
required

Confirmed outcomes incorporated in this state.

Required range: x >= 0
expires_at
string<date-time>
required

Deadline established once when the plan is created.

format_version
integer<int32>
required

Required restore format.

Required range: x >= 0
generation
integer<int64>
required

Checkpoint ordering, distinct from the task generation.

Required range: x >= 0
mode
enum<string>
required

Base or incremental state.

Available options:
retain_base,
incremental
page_ids
string[]
required

Complete ordered pages; never an unbounded inline manifest.

pin
object
required

Current writer/reader pin.

replayed
boolean
required

Immutable plan replay.

repository
string
required

Repository identity selected by native task authority.

toolbox_digest
string
required

Host-local toolbox compatibility.

base_commit_oid
string | null

Exact base commit, independent of a later published branch head.

base_id
string | null

Retained base identity when present.

base_manifest_root
string | null

Ordered retained-base root, checked before overlaying local changes.

history_digest
string | null

History state bound to the same file generation.

manifest_root
string | null

Absent until native verification commits.