Worktrees

CompozyOS Worktrees HTTP endpoints.

16 endpoints32 pages in API Reference

Open in ChatGPT Open in Claude

Endpoints16

GET/api/workspaces/{workspace_id}/worktreesList registered and discovered worktrees
POST/api/workspaces/{workspace_id}/worktreesAccept a worktree creation
POST/api/workspaces/{workspace_id}/worktrees/adoptAdopt an existing linked worktree
POST/api/workspaces/{workspace_id}/worktrees/discovered/removeRemove a discovered worktree
GET/api/workspaces/{workspace_id}/worktrees/{worktree_id}Inspect one worktree
DELETE/api/workspaces/{workspace_id}/worktrees/{worktree_id}Remove a worktree
POST/api/workspaces/{workspace_id}/worktrees/{worktree_id}/cancelCancel a pending worktree creation
POST/api/workspaces/{workspace_id}/worktrees/{worktree_id}/dismissDismiss a worktree tombstone
GET/api/workspaces/{workspace_id}/worktrees/{worktree_id}/exitRead the worktree exit plan
POST/api/workspaces/{workspace_id}/worktrees/{worktree_id}/exit/actionsRun a worktree exit action
POST/api/workspaces/{workspace_id}/worktrees/{worktree_id}/exit/cancelCancel a worktree exit action
POST/api/workspaces/{workspace_id}/worktrees/{worktree_id}/exit/prepareResolve forge capabilities and prepare the worktree exit plan

GET/api/workspaces/{workspace_id}/worktrees

List registered and discovered worktrees

httpuds

Path parameters

workspace_id*string

Workspace id or path

Query parameters

refresh?boolean

Refresh Git discovery and status

include_removed?boolean

Include removed records (excluded by default)

Responses

200: OK
400: Invalid worktree list query
404: Workspace not found
500: Internal server error
503: Worktree service is unavailable

Request

curl -X GET 'http://localhost:2123/api/workspaces/string/worktrees'

curl -X GET 'http://localhost:2123/api/workspaces/string/worktrees'

200 OK

{
  "discovered": [
    {
      "branch": "string",
      "detached": true,
      "name": "string",
      "path": "string",
      "reason": "string",
      "selectable": true,
      "stale": true,
      "unavailable": true
    }
  ],
  "repo": {
    "diagnostic": "string",
    "git_available": true,
    "git_backed": true
  },
  "worktrees": [
    {
      "agent_activity": "string",
      "ahead": 0,
      "base_ref": "string",
      "behind": 0,
      "branch": "string",
      "create_error": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_branch": true,
      "created_head": "string",
      "dirty": true,
      "id": "string",
      "name": "string",
      "origin": "string",
      "path": "string",
      "pending_phase": "string",
      "profile_archived": true,
      "profile_color": "string",
      "profile_emoji": "string",
      "profile_icon": "string",
      "profile_id": "string",
      "profile_name": "string",
      "run_id": "string",
      "run_namespace": "string",
      "setup_error": "string",
      "setup_state": "string",
      "state": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "workspace_id": "string"
    }
  ]
}

{  "discovered": [    {      "branch": "string",      "detached": true,      "name": "string",      "path": "string",      "reason": "string",      "selectable": true,      "stale": true,      "unavailable": true    }  ],  "repo": {    "diagnostic": "string",    "git_available": true,    "git_backed": true  },  "worktrees": [    {      "agent_activity": "string",      "ahead": 0,      "base_ref": "string",      "behind": 0,      "branch": "string",      "create_error": "string",      "created_at": "2019-08-24T14:15:22Z",      "created_branch": true,      "created_head": "string",      "dirty": true,      "id": "string",      "name": "string",      "origin": "string",      "path": "string",      "pending_phase": "string",      "profile_archived": true,      "profile_color": "string",      "profile_emoji": "string",      "profile_icon": "string",      "profile_id": "string",      "profile_name": "string",      "run_id": "string",      "run_namespace": "string",      "setup_error": "string",      "setup_state": "string",      "state": "string",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    }  ]}

POST/api/workspaces/{workspace_id}/worktrees

Accept a worktree creation

httpuds

Path parameters

workspace_id*string

Workspace id or path

Query parameters

profile?string

Act as this profile by name

Request body

JSON request body

application/json

body

base_ref?string

branch?string

existing_branch?string

name?string

path?string

Responses

202: Accepted
400: Invalid worktree request
403: Forbidden
404: Worktree or workspace not found
409: Worktree operation conflict
422: Invalid worktree configuration
500: Internal server error
503: Worktree service is unavailable

Request

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees' \
  -H 'Content-Type: application/json' \
  -d '{}'

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees' \  -H 'Content-Type: application/json' \  -d '{}'

202 Accepted

{
  "worktree": {
    "agent_activity": "string",
    "ahead": 0,
    "base_ref": "string",
    "behind": 0,
    "branch": "string",
    "create_error": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_branch": true,
    "created_head": "string",
    "dirty": true,
    "id": "string",
    "name": "string",
    "origin": "string",
    "path": "string",
    "pending_phase": "string",
    "profile_archived": true,
    "profile_color": "string",
    "profile_emoji": "string",
    "profile_icon": "string",
    "profile_id": "string",
    "profile_name": "string",
    "run_id": "string",
    "run_namespace": "string",
    "setup_error": "string",
    "setup_state": "string",
    "state": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "workspace_id": "string"
  }
}

{  "worktree": {    "agent_activity": "string",    "ahead": 0,    "base_ref": "string",    "behind": 0,    "branch": "string",    "create_error": "string",    "created_at": "2019-08-24T14:15:22Z",    "created_branch": true,    "created_head": "string",    "dirty": true,    "id": "string",    "name": "string",    "origin": "string",    "path": "string",    "pending_phase": "string",    "profile_archived": true,    "profile_color": "string",    "profile_emoji": "string",    "profile_icon": "string",    "profile_id": "string",    "profile_name": "string",    "run_id": "string",    "run_namespace": "string",    "setup_error": "string",    "setup_state": "string",    "state": "string",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string"  }}

POST/api/workspaces/{workspace_id}/worktrees/adopt

Adopt an existing linked worktree

httpuds

Path parameters

workspace_id*string

Workspace id or path

Query parameters

profile?string

Act as this profile by name

Request body

JSON request body

application/json

body

path*string

Responses

200: OK
400: Invalid worktree request
403: Forbidden
404: Worktree or workspace not found
409: Worktree operation conflict
422: Invalid worktree configuration
500: Internal server error
503: Worktree service is unavailable

Request

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees/adopt' \
  -H 'Content-Type: application/json' \
  -d '{
  "path": "string"
}'

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees/adopt' \  -H 'Content-Type: application/json' \  -d '{  "path": "string"}'

200 OK

{
  "worktree": {
    "agent_activity": "string",
    "ahead": 0,
    "base_ref": "string",
    "behind": 0,
    "branch": "string",
    "create_error": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_branch": true,
    "created_head": "string",
    "dirty": true,
    "id": "string",
    "name": "string",
    "origin": "string",
    "path": "string",
    "pending_phase": "string",
    "profile_archived": true,
    "profile_color": "string",
    "profile_emoji": "string",
    "profile_icon": "string",
    "profile_id": "string",
    "profile_name": "string",
    "run_id": "string",
    "run_namespace": "string",
    "setup_error": "string",
    "setup_state": "string",
    "state": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "workspace_id": "string"
  }
}

{  "worktree": {    "agent_activity": "string",    "ahead": 0,    "base_ref": "string",    "behind": 0,    "branch": "string",    "create_error": "string",    "created_at": "2019-08-24T14:15:22Z",    "created_branch": true,    "created_head": "string",    "dirty": true,    "id": "string",    "name": "string",    "origin": "string",    "path": "string",    "pending_phase": "string",    "profile_archived": true,    "profile_color": "string",    "profile_emoji": "string",    "profile_icon": "string",    "profile_id": "string",    "profile_name": "string",    "run_id": "string",    "run_namespace": "string",    "setup_error": "string",    "setup_state": "string",    "state": "string",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string"  }}

POST/api/workspaces/{workspace_id}/worktrees/discovered/remove

Remove a discovered worktree

httpuds

Path parameters

workspace_id*string

Workspace id or path

Query parameters

profile?string

Act as this profile by name

Request body

JSON request body

application/json

body

expect_stale?boolean

force?boolean

path*string

Responses

204: No Content
400: Invalid discovered removal request
403: Hook or profile does not permit removal
404: Discovered worktree or workspace not found
409: Removal requires another decision
500: Internal server error
503: Worktree service is unavailable

Request

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees/discovered/remove' \
  -H 'Content-Type: application/json' \
  -d '{
  "path": "string"
}'

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees/discovered/remove' \  -H 'Content-Type: application/json' \  -d '{  "path": "string"}'

400 Invalid discovered removal request

{
  "blockers": [
    {
      "id": "string",
      "kind": "string",
      "name": "string"
    }
  ],
  "code": "string",
  "config_path": "string",
  "current_turn_id": "string",
  "details": {
    "property1": "string",
    "property2": "string"
  },
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string",
  "unknown_keys": [
    "string"
  ]
}

{  "blockers": [    {      "id": "string",      "kind": "string",      "name": "string"    }  ],  "code": "string",  "config_path": "string",  "current_turn_id": "string",  "details": {    "property1": "string",    "property2": "string"  },  "diagnostic": {    "category": "string",    "code": "string",    "data_freshness": "string",    "doc_url": "string",    "evidence": {      "property1": null,      "property2": null    },    "id": "string",    "message": "string",    "severity": "string",    "suggested_command": "string",    "title": "string"  },  "error": "string",  "unknown_keys": [    "string"  ]}

GET/api/workspaces/{workspace_id}/worktrees/{worktree_id}

Inspect one worktree

httpuds

Path parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Responses

200: OK
404: Worktree or workspace not found
500: Internal server error
503: Worktree service is unavailable

Request

curl -X GET 'http://localhost:2123/api/workspaces/string/worktrees/string'

curl -X GET 'http://localhost:2123/api/workspaces/string/worktrees/string'

200 OK

{
  "bindings": {
    "agent_activity": "string"
  },
  "forge": {
    "fetched_at": "2019-08-24T14:15:22Z",
    "merged": true,
    "pr_number": 0,
    "pr_state": "string",
    "pr_url": "string",
    "provider": "string"
  },
  "repo": {
    "diagnostic": "string",
    "git_available": true,
    "git_backed": true
  },
  "status": {
    "ahead": 0,
    "ahead_of_base": 0,
    "behind": 0,
    "branch": "string",
    "deletions": 0,
    "detached": true,
    "dirty_files": 0,
    "has_upstream": true,
    "head_sha": "string",
    "insertions": 0,
    "read_error": "string",
    "refreshed_at": "2019-08-24T14:15:22Z"
  },
  "worktree": {
    "agent_activity": "string",
    "ahead": 0,
    "base_ref": "string",
    "behind": 0,
    "branch": "string",
    "create_error": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_branch": true,
    "created_head": "string",
    "dirty": true,
    "id": "string",
    "name": "string",
    "origin": "string",
    "path": "string",
    "pending_phase": "string",
    "profile_archived": true,
    "profile_color": "string",
    "profile_emoji": "string",
    "profile_icon": "string",
    "profile_id": "string",
    "profile_name": "string",
    "run_id": "string",
    "run_namespace": "string",
    "setup_error": "string",
    "setup_state": "string",
    "state": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "workspace_id": "string"
  }
}

{  "bindings": {    "agent_activity": "string"  },  "forge": {    "fetched_at": "2019-08-24T14:15:22Z",    "merged": true,    "pr_number": 0,    "pr_state": "string",    "pr_url": "string",    "provider": "string"  },  "repo": {    "diagnostic": "string",    "git_available": true,    "git_backed": true  },  "status": {    "ahead": 0,    "ahead_of_base": 0,    "behind": 0,    "branch": "string",    "deletions": 0,    "detached": true,    "dirty_files": 0,    "has_upstream": true,    "head_sha": "string",    "insertions": 0,    "read_error": "string",    "refreshed_at": "2019-08-24T14:15:22Z"  },  "worktree": {    "agent_activity": "string",    "ahead": 0,    "base_ref": "string",    "behind": 0,    "branch": "string",    "create_error": "string",    "created_at": "2019-08-24T14:15:22Z",    "created_branch": true,    "created_head": "string",    "dirty": true,    "id": "string",    "name": "string",    "origin": "string",    "path": "string",    "pending_phase": "string",    "profile_archived": true,    "profile_color": "string",    "profile_emoji": "string",    "profile_icon": "string",    "profile_id": "string",    "profile_name": "string",    "run_id": "string",    "run_namespace": "string",    "setup_error": "string",    "setup_state": "string",    "state": "string",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string"  }}

DELETE/api/workspaces/{workspace_id}/worktrees/{worktree_id}

Remove a worktree

httpuds

Path parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Query parameters

force?boolean

Confirm destructive removal; with delete_branch, also delete an unmerged branch

delete_branch?boolean

Also delete the recorded local branch after cleanup. The root checkout HEAD and default branches are kept; an unmerged branch is kept unless force is set.

profile?string

Act as this profile by name. If omitted, operator requests infer the target record owner; authenticated agents remain scoped to their session profile.

Responses

200: Cleaned up; reports the requested local branch deletion
204: No Content
400: Invalid removal query
403: Profile does not permit removal
404: Worktree or workspace not found
409: Removal requires another decision
500: Internal server error
503: Worktree service is unavailable

Request

curl -X DELETE 'http://localhost:2123/api/workspaces/string/worktrees/string'

curl -X DELETE 'http://localhost:2123/api/workspaces/string/worktrees/string'

200 Cleaned up; reports the requested local branch deletion

{
  "branch": {
    "deleted": true,
    "detail": "string",
    "name": "string",
    "reason": "string"
  }
}

{  "branch": {    "deleted": true,    "detail": "string",    "name": "string",    "reason": "string"  }}

POST/api/workspaces/{workspace_id}/worktrees/{worktree_id}/cancel

Cancel a pending worktree creation

httpuds

Path parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Responses

204: No Content
400: Invalid worktree request
403: Forbidden
404: Worktree or workspace not found
409: Worktree operation conflict
422: Invalid worktree configuration
500: Internal server error
503: Worktree service is unavailable

Request

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees/string/cancel'

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees/string/cancel'

400 Invalid worktree request

{
  "blockers": [
    {
      "id": "string",
      "kind": "string",
      "name": "string"
    }
  ],
  "code": "string",
  "config_path": "string",
  "current_turn_id": "string",
  "details": {
    "property1": "string",
    "property2": "string"
  },
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string",
  "unknown_keys": [
    "string"
  ]
}

{  "blockers": [    {      "id": "string",      "kind": "string",      "name": "string"    }  ],  "code": "string",  "config_path": "string",  "current_turn_id": "string",  "details": {    "property1": "string",    "property2": "string"  },  "diagnostic": {    "category": "string",    "code": "string",    "data_freshness": "string",    "doc_url": "string",    "evidence": {      "property1": null,      "property2": null    },    "id": "string",    "message": "string",    "severity": "string",    "suggested_command": "string",    "title": "string"  },  "error": "string",  "unknown_keys": [    "string"  ]}

POST/api/workspaces/{workspace_id}/worktrees/{worktree_id}/dismiss

Dismiss a worktree tombstone

httpuds

Path parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Query parameters

delete_branch?boolean

Also delete the recorded local branch after cleanup. The root checkout HEAD and default branches are kept; an unmerged branch is kept unless force is set.

force?boolean

With delete_branch, also delete an unmerged branch

profile?string

Act as this profile by name. If omitted, operator requests infer the target record owner; authenticated agents remain scoped to their session profile.

Responses

200: Cleaned up; reports the requested local branch deletion
204: No Content
400: Invalid worktree request
403: Forbidden
404: Worktree or workspace not found
409: Worktree operation conflict
422: Invalid worktree configuration
500: Internal server error
503: Worktree service is unavailable

Request

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees/string/dismiss'

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees/string/dismiss'

200 Cleaned up; reports the requested local branch deletion

{
  "branch": {
    "deleted": true,
    "detail": "string",
    "name": "string",
    "reason": "string"
  }
}

{  "branch": {    "deleted": true,    "detail": "string",    "name": "string",    "reason": "string"  }}

GET/api/workspaces/{workspace_id}/worktrees/{worktree_id}/exit

Read the worktree exit plan

httpuds

Path parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Query parameters

include?array<string>

Exact worktree-relative reviewed file paths; scoped plans return a complete include set and fingerprint.

Responses

200: OK
404: Worktree or workspace not found
409: Worktree exit plan is unavailable
500: Internal server error
503: Worktree service is unavailable

Request

curl -X GET 'http://localhost:2123/api/workspaces/string/worktrees/string/exit'

curl -X GET 'http://localhost:2123/api/workspaces/string/worktrees/string/exit'

200 OK

{
  "actions": [
    {
      "action": "string",
      "blocked_reason": "string",
      "enabled": true,
      "label": "string",
      "pr_number": 0,
      "publish": true,
      "url": "string"
    }
  ],
  "base": "string",
  "browser_url": "string",
  "cleanup": {
    "blocker": "string",
    "downgraded": true,
    "forge_state": "string",
    "safe": true,
    "source": "string",
    "stale": true,
    "summary": "string"
  },
  "commit_scope": {
    "changed_files": 0,
    "complete": true,
    "deletions": 0,
    "fingerprint": "string",
    "include_paths": [
      "string"
    ],
    "insertions": 0,
    "untracked_files": [
      "string"
    ],
    "untracked_total": 0,
    "untracked_truncated": true
  },
  "forge": {
    "compare_url_template": "string",
    "credential_source": "string",
    "default_branch": "string",
    "open_action_label": "string",
    "provider": "string",
    "request_noun": "string",
    "supports_draft": true,
    "template_paths": [
      "string"
    ],
    "view_action_label": "string"
  },
  "forge_status": {
    "fetched_at": "2019-08-24T14:15:22Z",
    "merged": true,
    "pr_number": 0,
    "pr_state": "string",
    "pr_url": "string",
    "provider": "string"
  },
  "global_pause_cause": "string",
  "pr_prefill": {
    "body": "string",
    "title": "string"
  },
  "primary": "string",
  "worktree_id": "string"
}

{  "actions": [    {      "action": "string",      "blocked_reason": "string",      "enabled": true,      "label": "string",      "pr_number": 0,      "publish": true,      "url": "string"    }  ],  "base": "string",  "browser_url": "string",  "cleanup": {    "blocker": "string",    "downgraded": true,    "forge_state": "string",    "safe": true,    "source": "string",    "stale": true,    "summary": "string"  },  "commit_scope": {    "changed_files": 0,    "complete": true,    "deletions": 0,    "fingerprint": "string",    "include_paths": [      "string"    ],    "insertions": 0,    "untracked_files": [      "string"    ],    "untracked_total": 0,    "untracked_truncated": true  },  "forge": {    "compare_url_template": "string",    "credential_source": "string",    "default_branch": "string",    "open_action_label": "string",    "provider": "string",    "request_noun": "string",    "supports_draft": true,    "template_paths": [      "string"    ],    "view_action_label": "string"  },  "forge_status": {    "fetched_at": "2019-08-24T14:15:22Z",    "merged": true,    "pr_number": 0,    "pr_state": "string",    "pr_url": "string",    "provider": "string"  },  "global_pause_cause": "string",  "pr_prefill": {    "body": "string",    "title": "string"  },  "primary": "string",  "worktree_id": "string"}

POST/api/workspaces/{workspace_id}/worktrees/{worktree_id}/exit/actions

Run a worktree exit action

httpuds

Path parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Request body

JSON request body

application/json

body

action*string

base?string

body?string

delivery_id?string

draft?boolean

expected_head?string

expected_scope?string

include_paths?array<string>

message?string

title?string

Responses

202: Accepted
400: Invalid worktree exit request
404: Worktree or workspace not found
409: Worktree exit action conflict
500: Internal server error
502: Forge provider error
503: Worktree or forge service is unavailable

Request

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees/string/exit/actions' \
  -H 'Content-Type: application/json' \
  -d '{
  "action": "string"
}'

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees/string/exit/actions' \  -H 'Content-Type: application/json' \  -d '{  "action": "string"}'

202 Accepted

{
  "op_id": "string"
}

{  "op_id": "string"}

POST/api/workspaces/{workspace_id}/worktrees/{worktree_id}/exit/cancel

Cancel a worktree exit action

httpuds

Path parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Request body

JSON request body

application/json

body

op_id*string

Responses

204: No Content
400: Invalid worktree exit request
404: Worktree or workspace not found
409: Worktree exit action conflict
500: Internal server error
502: Forge provider error
503: Worktree or forge service is unavailable

Request

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees/string/exit/cancel' \
  -H 'Content-Type: application/json' \
  -d '{
  "op_id": "string"
}'

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees/string/exit/cancel' \  -H 'Content-Type: application/json' \  -d '{  "op_id": "string"}'

400 Invalid worktree exit request

{
  "blockers": [
    {
      "id": "string",
      "kind": "string",
      "name": "string"
    }
  ],
  "code": "string",
  "config_path": "string",
  "current_turn_id": "string",
  "details": {
    "property1": "string",
    "property2": "string"
  },
  "diagnostic": {
    "category": "string",
    "code": "string",
    "data_freshness": "string",
    "doc_url": "string",
    "evidence": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "message": "string",
    "severity": "string",
    "suggested_command": "string",
    "title": "string"
  },
  "error": "string",
  "unknown_keys": [
    "string"
  ]
}

{  "blockers": [    {      "id": "string",      "kind": "string",      "name": "string"    }  ],  "code": "string",  "config_path": "string",  "current_turn_id": "string",  "details": {    "property1": "string",    "property2": "string"  },  "diagnostic": {    "category": "string",    "code": "string",    "data_freshness": "string",    "doc_url": "string",    "evidence": {      "property1": null,      "property2": null    },    "id": "string",    "message": "string",    "severity": "string",    "suggested_command": "string",    "title": "string"  },  "error": "string",  "unknown_keys": [    "string"  ]}

POST/api/workspaces/{workspace_id}/worktrees/{worktree_id}/exit/prepare

Resolve forge capabilities and prepare the worktree exit plan

httpuds

Path parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Responses

200: OK
404: Worktree or workspace not found
409: Worktree exit plan is unavailable
500: Internal server error
503: Worktree service is unavailable

Request

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees/string/exit/prepare'

curl -X POST 'http://localhost:2123/api/workspaces/string/worktrees/string/exit/prepare'

200 OK

{
  "actions": [
    {
      "action": "string",
      "blocked_reason": "string",
      "enabled": true,
      "label": "string",
      "pr_number": 0,
      "publish": true,
      "url": "string"
    }
  ],
  "base": "string",
  "browser_url": "string",
  "cleanup": {
    "blocker": "string",
    "downgraded": true,
    "forge_state": "string",
    "safe": true,
    "source": "string",
    "stale": true,
    "summary": "string"
  },
  "commit_scope": {
    "changed_files": 0,
    "complete": true,
    "deletions": 0,
    "fingerprint": "string",
    "include_paths": [
      "string"
    ],
    "insertions": 0,
    "untracked_files": [
      "string"
    ],
    "untracked_total": 0,
    "untracked_truncated": true
  },
  "forge": {
    "compare_url_template": "string",
    "credential_source": "string",
    "default_branch": "string",
    "open_action_label": "string",
    "provider": "string",
    "request_noun": "string",
    "supports_draft": true,
    "template_paths": [
      "string"
    ],
    "view_action_label": "string"
  },
  "forge_status": {
    "fetched_at": "2019-08-24T14:15:22Z",
    "merged": true,
    "pr_number": 0,
    "pr_state": "string",
    "pr_url": "string",
    "provider": "string"
  },
  "global_pause_cause": "string",
  "pr_prefill": {
    "body": "string",
    "title": "string"
  },
  "primary": "string",
  "worktree_id": "string"
}

{  "actions": [    {      "action": "string",      "blocked_reason": "string",      "enabled": true,      "label": "string",      "pr_number": 0,      "publish": true,      "url": "string"    }  ],  "base": "string",  "browser_url": "string",  "cleanup": {    "blocker": "string",    "downgraded": true,    "forge_state": "string",    "safe": true,    "source": "string",    "stale": true,    "summary": "string"  },  "commit_scope": {    "changed_files": 0,    "complete": true,    "deletions": 0,    "fingerprint": "string",    "include_paths": [      "string"    ],    "insertions": 0,    "untracked_files": [      "string"    ],    "untracked_total": 0,    "untracked_truncated": true  },  "forge": {    "compare_url_template": "string",    "credential_source": "string",    "default_branch": "string",    "open_action_label": "string",    "provider": "string",    "request_noun": "string",    "supports_draft": true,    "template_paths": [      "string"    ],    "view_action_label": "string"  },  "forge_status": {    "fetched_at": "2019-08-24T14:15:22Z",    "merged": true,    "pr_number": 0,    "pr_state": "string",    "pr_url": "string",    "provider": "string"  },  "global_pause_cause": "string",  "pr_prefill": {    "body": "string",    "title": "string"  },  "primary": "string",  "worktree_id": "string"}

GET/api/workspaces/{workspace_id}/worktrees/{worktree_id}/status

Read or refresh worktree status

httpuds

Path parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Query parameters

refresh?boolean

Refresh local Git status

forge?boolean

Refresh the serving forge provider

Responses

200: OK
400: Invalid status query
404: Worktree or workspace not found
409: Worktree status is unavailable
500: Internal server error
502: Forge provider error
503: Worktree or forge service is unavailable

Request

curl -X GET 'http://localhost:2123/api/workspaces/string/worktrees/string/status'

curl -X GET 'http://localhost:2123/api/workspaces/string/worktrees/string/status'

200 OK

{
  "forge": {
    "fetched_at": "2019-08-24T14:15:22Z",
    "merged": true,
    "pr_number": 0,
    "pr_state": "string",
    "pr_url": "string",
    "provider": "string"
  },
  "status": {
    "ahead": 0,
    "ahead_of_base": 0,
    "behind": 0,
    "branch": "string",
    "deletions": 0,
    "detached": true,
    "dirty_files": 0,
    "has_upstream": true,
    "head_sha": "string",
    "insertions": 0,
    "read_error": "string",
    "refreshed_at": "2019-08-24T14:15:22Z"
  },
  "worktree_id": "string"
}

{  "forge": {    "fetched_at": "2019-08-24T14:15:22Z",    "merged": true,    "pr_number": 0,    "pr_state": "string",    "pr_url": "string",    "provider": "string"  },  "status": {    "ahead": 0,    "ahead_of_base": 0,    "behind": 0,    "branch": "string",    "deletions": 0,    "detached": true,    "dirty_files": 0,    "has_upstream": true,    "head_sha": "string",    "insertions": 0,    "read_error": "string",    "refreshed_at": "2019-08-24T14:15:22Z"  },  "worktree_id": "string"}

GET/api/workspaces/{workspace_id}/worktrees/{worktree_id}/stream

Stream durable worktree lifecycle events

httpuds

Path parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Query parameters

after_sequence?integer

Replay events after this durable sequence

Formatint64

Header parameters

Responses

200: Canonical worktree event stream
400: Invalid stream cursor
404: Worktree or workspace not found
500: Internal server error
503: Worktree stream is unavailable

Request

curl -X GET 'http://localhost:2123/api/workspaces/string/worktrees/string/stream'

curl -X GET 'http://localhost:2123/api/workspaces/string/worktrees/string/stream'

200 Canonical worktree event stream

{
  "property1": null,
  "property2": null
}

{  "property1": null,  "property2": null}

GET/api/worktrees

List registered and discovered worktrees

httpuds

Query parameters

all_workspaces?boolean

Read all projects and User rows

workspace_ids?array<string>

Repeatable project IDs or @user; requires all_workspaces=true

include_removed?boolean

Include removed records (excluded by default)

Responses

200: OK
400: Invalid worktree list query
404: Workspace not found
500: Internal server error
503: Worktree service is unavailable

Request

curl -X GET 'http://localhost:2123/api/worktrees'

curl -X GET 'http://localhost:2123/api/worktrees'

200 OK

{
  "discovered": [
    {
      "branch": "string",
      "detached": true,
      "name": "string",
      "path": "string",
      "reason": "string",
      "selectable": true,
      "stale": true,
      "unavailable": true
    }
  ],
  "repo": {
    "diagnostic": "string",
    "git_available": true,
    "git_backed": true
  },
  "worktrees": [
    {
      "agent_activity": "string",
      "ahead": 0,
      "base_ref": "string",
      "behind": 0,
      "branch": "string",
      "create_error": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_branch": true,
      "created_head": "string",
      "dirty": true,
      "id": "string",
      "name": "string",
      "origin": "string",
      "path": "string",
      "pending_phase": "string",
      "profile_archived": true,
      "profile_color": "string",
      "profile_emoji": "string",
      "profile_icon": "string",
      "profile_id": "string",
      "profile_name": "string",
      "run_id": "string",
      "run_namespace": "string",
      "setup_error": "string",
      "setup_state": "string",
      "state": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "workspace_id": "string"
    }
  ]
}

{  "discovered": [    {      "branch": "string",      "detached": true,      "name": "string",      "path": "string",      "reason": "string",      "selectable": true,      "stale": true,      "unavailable": true    }  ],  "repo": {    "diagnostic": "string",    "git_available": true,    "git_backed": true  },  "worktrees": [    {      "agent_activity": "string",      "ahead": 0,      "base_ref": "string",      "behind": 0,      "branch": "string",      "create_error": "string",      "created_at": "2019-08-24T14:15:22Z",      "created_branch": true,      "created_head": "string",      "dirty": true,      "id": "string",      "name": "string",      "origin": "string",      "path": "string",      "pending_phase": "string",      "profile_archived": true,      "profile_color": "string",      "profile_emoji": "string",      "profile_icon": "string",      "profile_id": "string",      "profile_name": "string",      "run_id": "string",      "run_namespace": "string",      "setup_error": "string",      "setup_state": "string",      "state": "string",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    }  ]}

GET/api/worktrees/catalog-stream

Stream worktree catalog changes across workspaces

httpuds

Responses

101: WebSocket upgrade; each text message contains one complete SSE frame
200: Workspace-identified worktree catalog event stream
500: Internal server error
503: Worktree catalog stream is unavailable

Request

curl -X GET 'http://localhost:2123/api/worktrees/catalog-stream'

curl -X GET 'http://localhost:2123/api/worktrees/catalog-stream'

200 Workspace-identified worktree catalog event stream

{
  "error": "string",
  "kind": "string",
  "workspace_id": "string",
  "worktree_id": "string"
}

{  "error": "string",  "kind": "string",  "workspace_id": "string",  "worktree_id": "string"}

List registered and discovered worktrees

Path parameters

Query parameters

Response body

Accept a worktree creation

Path parameters

Query parameters

Request body

Response body

Adopt an existing linked worktree

Path parameters

Query parameters

Request body

Response body

Remove a discovered worktree

Path parameters

Query parameters

Request body

Response body

Inspect one worktree

Path parameters

Response body

Remove a worktree

Path parameters

Query parameters

Response body

Cancel a pending worktree creation

Path parameters

Response body

Dismiss a worktree tombstone

Path parameters

Query parameters

Response body

Read the worktree exit plan

Path parameters

Query parameters

Response body

Run a worktree exit action

Path parameters

Request body

Response body

Cancel a worktree exit action

Path parameters

Request body

Response body

Resolve forge capabilities and prepare the worktree exit plan

Path parameters

Response body

Read or refresh worktree status

Path parameters

Query parameters

Response body

Stream durable worktree lifecycle events

Path parameters

Query parameters

Header parameters

Response body

List registered and discovered worktrees

Query parameters

Response body

Stream worktree catalog changes across workspaces

Response body