Skip to main content

Sessions

Sessions are the center of the public API.

The session route family is where you manage workspace lifecycle, promotion boundaries, and most higher-level workflow state.

Core session lifecycle routes​

The main routes are:

  • POST /v1/sessions
  • GET /v1/sessions
  • GET /v1/sessions/{sessionId}
  • DELETE /v1/sessions/{sessionId}

Use them to:

  • Create a new workspace.
  • Enumerate workspaces for a user, tenant, or UI.
  • Refresh the current source of truth for a session.
  • Retire sessions that are no longer needed.

How to think about session creation​

From a product perspective, session creation is the moment where you decide:

  • What the starting point is.
  • Who owns or may access the session.
  • Whether the session is disposable, review-oriented, or intended for a durable outcome.
  • Which metadata should be attached at creation time.

Most clients should treat the session identifier as the anchor for all later work. Once you have it, the rest of the workflow is usually session-scoped.

Listing sessions​

GET /v1/sessions is the route most UIs use for:

  • Workspace dashboards.
  • "Recent work" views.
  • Review queues.
  • Cleanup and retention tooling.

Good client behavior:

  • Treat list responses as summary views.
  • Fetch GET /v1/sessions/{sessionId} for authoritative detail before a high-impact action.
  • Do not assume a list response alone is enough for destructive or persistence actions.

Session detail​

GET /v1/sessions/{sessionId} is the route that should drive detail views and "refresh current state" flows.

Use it when you need to confirm:

  • The session still exists.
  • The user still has access.
  • The current workflow state has not changed.
  • The session metadata is still what your client expects before a commit, restore, or merge step.

Forks​

To branch work from an existing session:

  • POST /v1/sessions/{sourceSessionId}/fork

Forking is the right choice when you need:

  • Parallel proposals.
  • A stable baseline plus one or more candidate outcomes.
  • Isolation between reviewers or tools.
  • A new session for a different actor without mutating the original.

Forks are often safer than letting multiple actors mutate the same session directly.

Checkpoints and restore​

Checkpoint-related routes include:

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

Use checkpoints for:

  • Recoverable milestones.
  • Long-running work where rollback matters.
  • User-visible save points.
  • Protection before risky automated transformations.

Use restore when the current workspace should return to a known prior state instead of being repaired incrementally.

Tags and metadata-oriented updates​

The public contract includes:

  • PATCH /v1/sessions/{sessionId}/tags

Use tags to support:

  • Product classification.
  • Work queues.
  • Review state labels.
  • Search and filtering in dashboards.
  • Lifecycle labels such as draft, needs-review, or ready-to-promote.

Keep tags small and workflow-oriented. Do not try to overload them with information better represented as annotations or cache entries.

Commits and persistence actions​

Key persistence routes include:

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

The most useful pattern is:

  1. Generate a summary when a user needs to understand what is about to be persisted.
  2. Present that summary in the product.
  3. Commit only after the user or workflow logic is satisfied.

This is especially important when work may come from automation and a human needs a concise explanation before approving persistence.

Merge-oriented routes​

The public contract also includes merge-oriented actions such as:

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

These routes matter when your workflow does not simply keep forks isolated, but instead needs to reconcile results back into another session lineage.

Good candidates for merge flows:

  • Review branches that should be reintegrated after approval.
  • Parallel workstreams where one session becomes the accepted result.
  • Tool-generated proposals that should land back into a parent session only after review.

Because merge semantics are workflow-sensitive, use the OpenAPI contract for exact request and response details.

Environment specification routes​

Session-scoped environment helpers include:

  • /v1/sessions/{sessionId}/environmentSpec
  • /v1/sessions/{sessionId}/generateEnvironmentSpec

These are useful when your product needs to:

  • Display the environment definition associated with a session.
  • Generate an environment description for downstream tooling.
  • Make setup details visible without forcing users to infer them from the filesystem itself.

Session lifecycle patterns that work well​

Session per task​

Use one session for one concrete task or change request. This is the best default because it keeps ownership, review state, and persistence clean.

Session per proposal​

Use a fresh forked session for each proposed approach. This is the best default for agent-assisted or reviewer-heavy workflows.

Session per user handoff​

Use a new session when a different user or tool should take responsibility for the next phase of work.

Long-lived session with checkpoints​

Use this only when the workspace really is ongoing and continuity matters more than clean branch boundaries.

Safe client behavior​

Good clients usually follow these rules:

  • Re-fetch session detail before destructive or durable actions.
  • Create checkpoints before risky automated edits.
  • Prefer forks over shared mutation when multiple actors may diverge.
  • Treat delete as retirement of temporary workspace, not as the primary persistence mechanism.
  • Keep review and workflow state adjacent to the session using annotations, approvals, or cache entries.

What belongs in session metadata versus elsewhere​

Use session-level routes and metadata for:

  • Identity of the workspace.
  • Ownership and summary labels.
  • Lifecycle stage.
  • High-level status.

Use other public surfaces for:

  • Filesystem content.
  • Review notes on specific items.
  • Event-style progress communication.
  • Structured tool output.

See also: