Create worktree

POST

/api/v1/projects/{projectId}/{agentType}/worktrees

• Local development server

Creates a new git worktree inside the container and automatically connects a terminal.

Parameters

Path Parameters

projectId

required

string

Project ID

Request Body ^required

Worktree name (must be a valid git branch name)

One of:

object

object

object

Worktree name (must be a valid git branch name)

object

name

Name is the worktree name (must be a valid git branch name).

string

Responses

201

Created

object

projectId

ProjectID is the deterministic project identifier the worktree belongs to.

string

state

State is the worktree’s terminal state after the mutation (“connected”, “shell”, “background”, “stopped”). Best-effort — may be empty if the state could not be determined (e.g. container not running).

string

worktreeId

WorktreeID is the worktree identifier.

string

400

Bad Request

object

code

string

Allowed values: INVALID_BODY INVALID_CONTAINER_ID INVALID_CONTAINER_NAME INVALID_WORKTREE_ID INVALID_WORKTREE_NAME REQUIRED_FIELD INVALID_PATH INVALID_NETWORK_CONFIG NOT_A_DIRECTORY NOT_FOUND NAME_TAKEN NOT_CONFIGURED STALE_MOUNTS BUDGET_EXCEEDED PROXY_ERROR INTERNAL

error

string

404

Not Found

object

code

string

Allowed values: INVALID_BODY INVALID_CONTAINER_ID INVALID_CONTAINER_NAME INVALID_WORKTREE_ID INVALID_WORKTREE_NAME REQUIRED_FIELD INVALID_PATH INVALID_NETWORK_CONFIG NOT_A_DIRECTORY NOT_FOUND NAME_TAKEN NOT_CONFIGURED STALE_MOUNTS BUDGET_EXCEEDED PROXY_ERROR INTERNAL

error

string

500

Internal Server Error

object

code

string

Allowed values: INVALID_BODY INVALID_CONTAINER_ID INVALID_CONTAINER_NAME INVALID_WORKTREE_ID INVALID_WORKTREE_NAME REQUIRED_FIELD INVALID_PATH INVALID_NETWORK_CONFIG NOT_A_DIRECTORY NOT_FOUND NAME_TAKEN NOT_CONFIGURED STALE_MOUNTS BUDGET_EXCEEDED PROXY_ERROR INTERNAL

error

string