worktrees

Ensure Worktree Endpoint

Ensure a worktree exists, creating if needed.

If name is "main", returns the main worktree. Otherwise, creates/returns a named worktree.

post/api/v1/worktrees/ensure

Request

  • Base URL: https://docs.omnara.com (the document declares no server; this is the origin it was published from)
  • URL: https://docs.omnara.com/api/v1/worktrees/ensure
  • Auth: HTTP bearer

Request body

workspace_idstring required

Workspace ID to create worktree in

namestring nullable

Worktree name (null for main worktree)

pathstring nullable

Filesystem path for the worktree (null for main worktree)

Response

Successful Response

idstring required

Unique worktree identifier

workspace_idstring required

Parent workspace identifier

namestring nullable

Worktree name (null for the main worktree)

is_mainboolean required

Whether this is the main/default worktree for the workspace

pathstring nullable

Filesystem path for the worktree on the machine

worktree_type'LOCAL' | 'REMOTE' nullable

Type of worktree: LOCAL (user machine) or REMOTE (sandbox)

managed_machine_idstring nullable

Managed machine ID if worktree_type is REMOTE

last_heartbeat_atstring date-time nullable

Most recent liveness heartbeat received from the sandbox container (REMOTE only).

last_synced_checkpoint_idstring nullable

ID of the last checkpoint that was successfully synced to cloud storage. This may differ from current_checkpoint_id if a recent checkpoint failed to sync.

checkpoint_restore_pendingboolean

Whether a checkpoint needs to be restored on next local session start

current_checkpoint_idstring nullable

Identifier of the current checkpoint for this worktree

checkpoint_metadataobject nullable

Metadata associated with the current checkpoint (e.g., commit info)

created_atstring date-time required

Timestamp when the worktree was created

updated_atstring date-time required

Timestamp when the worktree was last updated

Changes

No recorded changes to this operation across all 1 revision of this API.