Skip to main content
GET
/
api
/
v1
/
worktrees
/
workspace
/
{workspace_id}
List Workspace Worktrees
curl --request GET \
  --url https://api.example.com/api/v1/worktrees/workspace/{workspace_id} \
  --header 'Authorization: Bearer <token>'
[
  {
    "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

​
workspace_id
string
required

Response

Successful Response

​
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)