Skip to content

Worktrees

CompozyOS Worktrees HTTP endpoints.

For people running agent work32 pages in this section

List registered and discovered worktrees

GET/api/workspaces/{workspace_id}/worktrees

Path Parameters

workspace_id*string

Workspace id or path

Query Parameters

refresh?boolean

Refresh Git discovery and status

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/worktrees"
{  "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",      "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"    }  ]}

Accept a worktree creation

POST/api/workspaces/{workspace_id}/worktrees

Path Parameters

workspace_id*string

Workspace id or path

Query Parameters

profile?string

Act as this profile by name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/worktrees" \  -H "Content-Type: application/json" \  -d '{}'
{  "worktree": {    "agent_activity": "string",    "ahead": 0,    "base_ref": "string",    "behind": 0,    "branch": "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"  }}

Adopt an existing linked worktree

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

Path Parameters

workspace_id*string

Workspace id or path

Query Parameters

profile?string

Act as this profile by name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/worktrees/adopt" \  -H "Content-Type: application/json" \  -d '{    "path": "string"  }'
{  "worktree": {    "agent_activity": "string",    "ahead": 0,    "base_ref": "string",    "behind": 0,    "branch": "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"  }}

Inspect one worktree

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

Path Parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/worktrees/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",    "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"  }}

Remove a worktree

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

Path Parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Query Parameters

force?boolean

Confirm destructive removal

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/api/workspaces/string/worktrees/string"
Empty

Cancel a pending worktree creation

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

Path Parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/worktrees/string/cancel"
Empty

Dismiss a worktree tombstone

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

Path Parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Query Parameters

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/worktrees/string/dismiss"
Empty

Read the worktree exit plan

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

Path Parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/worktrees/string/exit"
{  "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,    "deletions": 0,    "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"}

Run a worktree exit action

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

Path Parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/worktrees/string/exit/actions" \  -H "Content-Type: application/json" \  -d '{    "action": "string"  }'
{  "op_id": "string"}

Cancel a worktree exit action

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

Path Parameters

workspace_id*string

Workspace id or path

worktree_id*string

Worktree id, name, or path

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/worktrees/string/exit/cancel" \  -H "Content-Type: application/json" \  -d '{    "op_id": "string"  }'
Empty

Read or refresh worktree status

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

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

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/worktrees/string/status"
{  "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"}

Stream durable worktree lifecycle events

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

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

Last-Event-ID?string

Resume after this durable sequence

Response Body

text/event-stream

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/worktrees/string/stream"
{  "property1": null,  "property2": null}

Stream worktree catalog changes across workspaces

GET/api/worktrees/catalog-stream

Response Body

text/event-stream

application/json

application/json

curl -X GET "https://example.com/api/worktrees/catalog-stream"
{  "error": "string",  "kind": "string",  "workspace_id": "string",  "worktree_id": "string"}

Workspaces

CompozyOS Workspaces HTTP endpoints.

Agents

CompozyOS Agents HTTP endpoints.