Skip to main content
POST
/
api
/
v1
/
worktrees
/
{worktree_id}
/
migrate
Migrate Worktree
curl --request POST \
  --url https://api.example.com/api/v1/worktrees/{worktree_id}/migrate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "target_type": "LOCAL",
  "target_machine_id": "<string>",
  "source": "checkpoint",
  "worktree_name": "<string>"
}
'
{
  "worktree": {
    "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": {}
  },
  "status": "<string>"
}

Authorizations

Authorization
string
header
required

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

Path Parameters

worktree_id
string
required

Body

application/json

Request to migrate a worktree to a different machine type.

target_type
enum<string>
required

Target type: LOCAL (user machine) or REMOTE (sandbox)

Available options:
LOCAL,
REMOTE
target_machine_id
string | null

Target user machine ID (required for LOCAL, ignored for REMOTE)

source
enum<string>
default:checkpoint

Source for REMOTE migration: 'checkpoint' uses current checkpoint, 'base_ref' starts fresh from workspace base ref (requires sync enabled)

Available options:
checkpoint,
base_ref
worktree_name
string | null

Name for new worktree when using source='base_ref'. If provided, creates a new worktree with this name instead of migrating existing one.

Response

Successful Response

Response after migrating a worktree.

worktree
WorktreeDescriptor · object
required

Updated worktree descriptor

status
string
required

Status of the migration: 'migrated' on success

Allowed value: "migrated"