Skip to main content
PATCH
/
api
/
v1
/
worktrees
/
session
/
{session_id}
Set User Session Worktree
curl --request PATCH \
  --url https://api.example.com/api/v1/worktrees/session/{session_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "worktree_id": "<string>"
}
'
{
  "id": "<string>",
  "workspace_id": "<string>",
  "is_main": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "name": "<string>",
  "path": "<string>",
  "worktree_type": "LOCAL",
  "user_machine_path": {
    "id": "<string>",
    "machine_id": "<string>",
    "local_path": "<string>"
  },
  "managed_machine_id": "<string>",
  "last_heartbeat_at": "2023-11-07T05:31:56Z",
  "last_synced_checkpoint_id": "<string>",
  "checkpoint_restore_pending": false,
  "current_checkpoint_id": "<string>",
  "checkpoint_metadata": {}
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
session_id
string
required

Body

application/json

Request to set a user session's worktree.

​
worktree_id
string
required

Worktree ID to associate with session

Response

Successful Response

Serialized worktree entity returned to API clients.

​
id
string
required

Unique worktree identifier

​
workspace_id
string
required

Parent workspace identifier

​
is_main
boolean
required

Whether this is the main/default worktree for the workspace

​
created_at
string<date-time>
required

Timestamp when the worktree was created

​
updated_at
string<date-time>
required

Timestamp when the worktree was last updated

​
name
string | null

Worktree name (null for the main worktree)

​
path
string | null

Filesystem path for the worktree on the machine

​
worktree_type
enum<string> | null

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

Available options:
LOCAL,
REMOTE
​
user_machine_path
UserMachinePathDescriptor · object

Machine+path link when worktree_type is LOCAL

​
managed_machine_id
string | null

Managed machine ID if worktree_type is REMOTE

​
last_heartbeat_at
string<date-time> | null

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

​
last_synced_checkpoint_id
string | null

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_pending
boolean
default:false

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

​
current_checkpoint_id
string | null

Identifier of the current checkpoint for this worktree

​
checkpoint_metadata
Checkpoint Metadata · object

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