Skip to main content

Persistence routes

Persistence is how you turn session work into durable outcomes.

Checkpoints and restore​

Checkpoint routes:

  • POST /v1/sessions/{sessionId}/checkpoints
  • POST /v1/sessions/{sessionId}/restore

Use checkpoints for recoverable milestones. Use restore when you need to return a session to a saved state.

Commits​

Commit-oriented routes include:

  • /v1/sessions/{sessionId}/commit
  • /v1/sessions/{sessionId}/generateCommitSummary

Use commit summaries to present a user-facing explanation or preview before asking a user to persist the result.

Merge-oriented persistence​

The public contract also exposes merge-style routes:

  • /v1/sessions/{parentSessionId}:merge
  • /v1/sessions/{targetSessionId}:mergeFrom

These matter when your workflow needs to reconcile work across sessions rather than simply keeping them separate.

Promotion into a source​

Source-related persistence routes include:

  • /v1/sources/{sourceId}/promoteSession

Use this when a session result should become part of a reusable source or baseline rather than remain only a session outcome.

Persistence design guidance​

Use this rule set:

  • Use checkpoints for recovery.
  • Use commits for durable outcomes.
  • Use merge when you need controlled reconciliation.
  • Use source promotion when the outcome should become a reusable starting point for future sessions.