Sessions
CompozyOS Sessions HTTP endpoints.
POST
X-Compozy-Session-ID*stringDaemon-issued active session id
X-Compozy-Agent*stringDaemon-issued session agent name
JSON request body
application/json- body
acp_options?array<>agent_name*stringMatch
^[a-z][a-z0-9_-]{0,105}$Length
length <= 106auto_stop_on_parent*booleanidempotency_key?stringinherit_permissions?booleanmodel?stringname?stringnew_worktree?|notify_creator?boolean|nullpermissions*prompt?stringprompt_overlay?stringprovider?stringreasoning_effort?stringspawn_role*stringspeed?stringValue in
"normal""fast"toolsets?array<string>ttl_seconds*integerFormat
int64workspace?stringworktree?stringCreated
application/json- response
spawn*curl -X POST "https://example.com/api/agent/spawn" \ -H "X-Compozy-Session-ID: string" \ -H "X-Compozy-Agent: string" \ -H "Content-Type: application/json" \ -d '{ "agent_name": "string", "auto_stop_on_parent": true, "permissions": {}, "spawn_role": "string", "ttl_seconds": 0 }'{ "spawn": { "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "permissions": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "prompt": { "error": "string", "message_id": "string", "reply_watch_id": "string", "reply_watch_state": "string", "status": "string" }, "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }, "worktree": { "base_sha": "string", "branch": "string", "created": true, "id": "string", "name": "string", "path": "string" } }}GET
workspace_id?stringWorkspace id or path
all_workspaces?booleanUse the explicit all-workspaces aggregate
workspace_ids?array<string>Project IDs or @user; repeatable, requires all_workspaces
include_health?booleanInclude metadata-only health for returned sessions
skip_total?booleanOmit the exact catalog count for a bounded cursor read
state?stringFilter by exact session state
Value in
"starting""active""stopping""stopped"type?stringFilter by exact session type
Value in
"user""system""coordinator""spawned"agent?stringFilter by exact agent definition name
subagents?stringSubagent session visibility (default include)
Value in
"include""exclude""only"children?stringManaged child visibility
Value in
"include""exclude"parent?stringFilter by exact parent session id
root?stringFilter by exact root session id (includes the root itself)
worktree?stringFilter by exact bound worktree id
q?stringSearch session id, name, agent, or provider; title_agent searches visible title and agent
search_fields?"title_agent"Select visible title/agent search instead of the default catalog fields
Value in
"title_agent"resumable?booleanOnly list sessions eligible for explicit attach
attention?booleanOnly list sessions in the needs-you attention class
board_column?array<string>Repeatable board column filter: needs_you, working, in_review, done
badge?stringFilter by comma-separated exact session badges
archive?stringArchived session visibility
Value in
"exclude""only""include"sort?stringStable session ordering
Value in
"recent""created""name""last_activity""attention""navigator""manual"cursor?stringOpaque next_cursor from the previous page
limit?integerSessions per page (1-100)
Format
int32profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
OK
application/json- response
page*sessions*array<>curl -X GET "https://example.com/api/sessions"{ "page": { "has_more": true, "limit": 0, "next_cursor": "string", "total": 0 }, "sessions": [ { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" } ]}POST
profile?stringAct as this profile by name
JSON request body
application/json- body
agent_name?stringMatch
^(?:|[a-z][a-z0-9_-]{0,105})$Length
length <= 106folder_id?stringlineage_kind?stringname?stringnew_worktree?|parent_session_id?stringscope?stringworkspace?stringworkspace_path?stringworktree?stringCreated
application/json- response
session*curl -X POST "https://example.com/api/sessions" \ -H "Content-Type: application/json" \ -d '{}'{ "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}GET
OK
application/json- response
by_workspace*array<>finished*integerneeds_you*integercurl -X GET "https://example.com/api/sessions/attention-summary"{ "by_workspace": [ { "finished": 0, "needs_you": 0, "workspace_id": "string" } ], "finished": 0, "needs_you": 0}GET
workspace_id?stringWorkspace id or path
all_workspaces?booleanSubscribe to the explicit all-workspaces aggregate
last_event_id?stringResume cursor when Last-Event-ID cannot be set; the header takes precedence
profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
Last-Event-ID?stringResume after this catalog sequence
WebSocket upgrade; each text message contains one complete SSE frame
curl -X GET "https://example.com/api/sessions/catalog-stream"Empty
GET
workspace_id?stringWorkspace id or path
all_workspaces?booleanUse the explicit all-workspaces aggregate
workspace_ids?array<string>Project IDs or @user; repeatable, requires all_workspaces
worktree?stringFilter by bound worktree id
agent?stringFilter by exact agent name
subagents?stringSubagent session visibility (default include)
Value in
"include""exclude""only"children?stringManaged child visibility
Value in
"include""exclude"parent?stringFilter by exact parent session id
root?stringFilter by exact root session id (includes the root itself)
resumable?booleanOnly count sessions eligible for explicit attach
state?stringFilter by exact session state
Value in
"starting""active""stopping""stopped"type?stringFilter by exact session type
Value in
"user""system""coordinator""spawned"archive?stringArchived session visibility
Value in
"exclude""only""include"profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
Exact scope counts, independent of text query and selected badge
application/json- response
by_profile*array<>by_workspace*array<>facets*curl -X GET "https://example.com/api/sessions/facets"{ "by_profile": [ { "facets": { "all": 0, "board": { "done": 0, "in_review": 0, "needs_you": 0, "working": 0 }, "finished": 0, "idle": 0, "needs_you": 0, "terminal_approvals": 0, "working": 0 }, "profile_id": "string" } ], "by_workspace": [ { "facets": { "all": 0, "board": { "done": 0, "in_review": 0, "needs_you": 0, "working": 0 }, "finished": 0, "idle": 0, "needs_you": 0, "terminal_approvals": 0, "working": 0 }, "workspace_id": "string" } ], "facets": { "all": 0, "board": { "done": 0, "in_review": 0, "needs_you": 0, "working": 0 }, "finished": 0, "idle": 0, "needs_you": 0, "terminal_approvals": 0, "working": 0 }}GET
session_id*stringSession id
include_health?booleanInclude metadata-only session health when available
profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
OK
application/json- response
session*curl -X GET "https://example.com/api/sessions/string"{ "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}GET
session_id*stringSession id
since?stringOnly events emitted since this timestamp
Format
date-timelimit?integerMaximum number of records to return; defaults to the newest 200 and is capped at 1000
Format
int32after_sequence?integerOnly return events after this sequence number
Format
int64type?stringEvent type
agent_name?stringAgent name
turn_id?stringTurn id
archive?stringSelect active, archived, or all events
Value in
"active""archived""all"profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
OK
application/json- response
events*array<>curl -X GET "https://example.com/api/sessions/string/events"{ "events": [ { "actor_id": "string", "actor_kind": "string", "agent_name": "string", "claim_token_hash": "string", "content": null, "coordinator_session_id": "string", "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "generation": 0, "goal": { "generation": 0, "item_index": 0, "kind": "goal-work", "node_id": "string", "prompt_attempt": 0, "prompt_id": "string", "run_id": "string", "turn": 0 }, "hook_event": "string", "hook_name": "string", "id": "string", "lease_until": "2019-08-24T14:15:22Z", "origin": { "agent_name": "string", "hop": 0, "in_reply_to": "string", "kind": "string", "notify_on_complete": true, "reply_watch_id": "string", "session_id": "string", "title_at_send": "string", "workspace_id": "string" }, "parent_session_id": "string", "provider_error": { "code": "string", "first_seen_at": "2019-08-24T14:15:22Z", "guidance": "string", "last_seen_at": "2019-08-24T14:15:22Z", "next_action": "string", "occurrence_count": 0, "provider": "string" }, "release_reason": "string", "root_session_id": "string", "run_id": "string", "scheduler_reason": "string", "sequence": 0, "session_id": "string", "spawn_depth": 0, "stop_detail": "string", "stop_reason": "completed", "task_id": "string", "timestamp": "2019-08-24T14:15:22Z", "turn_id": "string", "type": "string", "workflow_id": "string", "workspace_id": "string", "workspace_path": "string", "worktree_id": "string" } ]}GET
session_id*stringSession id
since?stringOnly events emitted since this timestamp
Format
date-timelimit?integerMaximum number of turns to return; defaults to the newest 200 and is capped at 1000
Format
int32after_sequence?integerOnly return events after this sequence number
Format
int64type?stringEvent type
agent_name?stringAgent name
turn_id?stringTurn id
archive?stringSelect active, archived, or all events
Value in
"active""archived""all"profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
OK
application/json- response
history*array<>curl -X GET "https://example.com/api/sessions/string/history"{ "history": [ { "events": [ { "actor_id": "string", "actor_kind": "string", "agent_name": "string", "claim_token_hash": "string", "content": null, "coordinator_session_id": "string", "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "generation": 0, "goal": { "generation": 0, "item_index": 0, "kind": "goal-work", "node_id": "string", "prompt_attempt": 0, "prompt_id": "string", "run_id": "string", "turn": 0 }, "hook_event": "string", "hook_name": "string", "id": "string", "lease_until": "2019-08-24T14:15:22Z", "origin": { "agent_name": "string", "hop": 0, "in_reply_to": "string", "kind": "string", "notify_on_complete": true, "reply_watch_id": "string", "session_id": "string", "title_at_send": "string", "workspace_id": "string" }, "parent_session_id": "string", "provider_error": { "code": "string", "first_seen_at": "2019-08-24T14:15:22Z", "guidance": "string", "last_seen_at": "2019-08-24T14:15:22Z", "next_action": "string", "occurrence_count": 0, "provider": "string" }, "release_reason": "string", "root_session_id": "string", "run_id": "string", "scheduler_reason": "string", "sequence": 0, "session_id": "string", "spawn_depth": 0, "stop_detail": "string", "stop_reason": "completed", "task_id": "string", "timestamp": "2019-08-24T14:15:22Z", "turn_id": "string", "type": "string", "workflow_id": "string", "workspace_id": "string", "workspace_path": "string", "worktree_id": "string" } ], "turn_id": "string" } ]}GET
session_id*stringSession id
OK
application/json- response
session_id*stringworkspace_id*stringworkspace_name*stringcurl -X GET "https://example.com/api/sessions/string/owner"{ "session_id": "string", "workspace_id": "string", "workspace_name": "string"}POST
session_id*stringSession id
profile?stringAct as this profile by name
Refreshed or retained cached facts
application/json- response
branch*stringpull_request*|pull_request_lookup*|session_id*stringcurl -X POST "https://example.com/api/sessions/string/pull-request/refresh"{ "branch": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "session_id": "string"}GET
session_id*stringSession id
profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
OK
application/json- response
active_prompt*booleanagent_name*stringattachable*booleanattention?stringbadge*stringValue in
"running""idle""unhealthy""hung""waiting-for-auth""waiting-for-input""done""stopped""failed""unknown""needs-attention""waiting"derivation?|diagnostics?array<>eligible_for_wake*booleanescalated?boolean|nullhealth*stringValue in
"healthy""degraded""stale""dead""unknown"ineligibility_reason?stringValue in
"session_prompt_active""session_not_attachable""session_unhealthy""session_health_stale""session_health_hung""session_health_dead""session_health_unknown"lifecycle_state?stringValue in
"starting""active""stopping""stopped"lineage?|pending_interactions*array<>queue?|reply_watches?array<>session_id*stringstate*stringValue in
"idle""prompting""stopped""detached"updated_at*stringFormat
date-timeverified?boolean|nullwake_state?|workspace_id*stringcurl -X GET "https://example.com/api/sessions/string/status"{ "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "badge": "running", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "lifecycle_state": "starting", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "wake_state": { "agent_name": "string", "coalesced_count": 0, "last_reason": "wake_sent", "last_result": "sent", "last_wake_at": "2019-08-24T14:15:22Z", "next_allowed_at": "2019-08-24T14:15:22Z", "policy_snapshot_id": "string", "session_id": "string", "updated_at": "2019-08-24T14:15:22Z", "workspace_id": "string" }, "workspace_id": "string"}GET
session_id*stringSession id
after_sequence?integerInitial cursor when Last-Event-ID is not supplied
Format
int64frames?stringFrame mode; transcript is the default and raw preserves persisted event frames
Value in
"raw""transcript"epoch?integerExpected transcript epoch for a fenced reconnect
Format
int64generation?integerExpected materialized projection generation for a fenced reconnect
Format
int64limit?integerMaximum entries per transcript snapshot or change batch
Format
int32profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
Last-Event-ID?stringResume after the last applied SSE cursor; transcript reconnects also require epoch and generation
Session event stream
text/event-stream- response
session_id*stringsubagents*array<>curl -X GET "https://example.com/api/sessions/string/stream"{ "session_id": "string", "subagents": [ { "child_activity": "working", "child_session_id": "string", "created_at": "2019-08-24T14:15:22Z", "delivery": "string", "depth": 0, "error": "string", "hint": "string", "isolation": "string", "origin": "string", "parent_session_id": "string", "parent_turn_id": "string", "progress": "string", "provider_tool_call_id": "string", "result": "string", "result_preview": "string", "result_truncated": true, "role": "string", "runtime": { "agent": "string", "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "string" }, "settled_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z", "status": "string", "subagent_id": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "wait_timed_out": true, "work_state": "string", "workspace_id": "string", "worktree": { "base_ref": "string", "base_sha": "string", "branch": "string", "commits_ahead": 0, "dirty_files": 0, "head_sha": "string", "id": "string", "name": "string", "observed_at": "2019-08-24T14:15:22Z", "path": "string", "pull_request": { "number": 0, "state": "string", "url": "string" }, "pull_request_status": "string" } } ]}GET
session_id*stringSession id
limit?integerMaximum page size; defaults to the newest 200 entries and is capped at 1000
Format
int32before_sequence?integerReturn entries whose stable start sequence is before this cursor
Format
int64profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
OK
application/json- response
entries*array<>epoch*integerFormat
int64generation*integerFormat
int64has_older*booleanlimit*integermax_sequence*integerFormat
int64next_before_sequence?integerFormat
int64curl -X GET "https://example.com/api/sessions/string/transcript"{ "entries": [ { "message": { "id": "string", "metadata": null, "parts": [ { "data": null, "errorText": "string", "filename": "string", "id": "string", "input": null, "mediaType": "string", "output": null, "parentToolCallId": "string", "preliminary": true, "rawInput": null, "state": "string", "text": "string", "title": "string", "toolCallId": "string", "toolName": "string", "type": "string", "url": "string" } ], "role": "string" }, "sequence": 0, "start_sequence": 0 } ], "epoch": 0, "generation": 0, "has_older": true, "limit": 0, "max_sequence": 0, "next_before_sequence": 0}GET
session_id*stringSession id
profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
OK
application/json- response
entries*array<>curl -X GET "https://example.com/api/sessions/string/transcript/outline"{ "entries": [ { "at": "2019-08-24T14:15:22Z", "preview": "string", "reply_preview": "string", "sequence": 0, "turn_id": "string" } ]}GET
session_id*stringSession id
q*stringLiteral case-insensitive text; 1 to 4096 bytes
limit?integerMaximum matches; defaults to 200, capped at 1000; truncated reports omitted matches
Format
int32profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
OK
application/json- response
matches*array<>truncated*booleancurl -X GET "https://example.com/api/sessions/string/transcript/search?q=string"{ "matches": [ { "field": "string", "part_index": 0, "role": "string", "sequence": 0, "snippet": "string", "turn_id": "string" } ], "truncated": true}GET
workspace_id*stringWorkspace id
profile?stringAct as this profile by name
OK
application/json- response
folders*array<>curl -X GET "https://example.com/api/workspaces/string/session-folders"{ "folders": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "position": 0, "profile_id": "string", "session_count": 0, "updated_at": "2019-08-24T14:15:22Z", "workspace_id": "string" } ]}POST
workspace_id*stringWorkspace id
profile?stringAct as this profile by name
JSON request body
application/json- body
name*stringOK
application/json- response
folder*curl -X POST "https://example.com/api/workspaces/string/session-folders" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "folder": { "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "position": 0, "profile_id": "string", "session_count": 0, "updated_at": "2019-08-24T14:15:22Z", "workspace_id": "string" }}PATCH
workspace_id*stringWorkspace id
folder_id*stringSession folder id
profile?stringAct as this profile by name
JSON request body
application/json- body
name*stringOK
application/json- response
folder*curl -X PATCH "https://example.com/api/workspaces/string/session-folders/string" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "folder": { "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "position": 0, "profile_id": "string", "session_count": 0, "updated_at": "2019-08-24T14:15:22Z", "workspace_id": "string" }}DELETE
workspace_id*stringWorkspace id
folder_id*stringSession folder id
profile?stringAct as this profile by name
OK
application/json- response
folders*array<>curl -X DELETE "https://example.com/api/workspaces/string/session-folders/string"{ "folders": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "position": 0, "profile_id": "string", "session_count": 0, "updated_at": "2019-08-24T14:15:22Z", "workspace_id": "string" } ]}PUT
workspace_id*stringWorkspace id
profile?stringAct as this profile by name
JSON request body
application/json- body
folder_ids*array<string>OK
application/json- response
folders*array<>curl -X PUT "https://example.com/api/workspaces/string/session-order/folders" \ -H "Content-Type: application/json" \ -d '{ "folder_ids": [ "string" ] }'{ "folders": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "position": 0, "profile_id": "string", "session_count": 0, "updated_at": "2019-08-24T14:15:22Z", "workspace_id": "string" } ]}PUT
workspace_id*stringWorkspace id
profile?stringAct as this profile by name
JSON request body
application/json- body
folder_id?stringsession_ids*array<string>OK
application/json- response
folders*array<>curl -X PUT "https://example.com/api/workspaces/string/session-order/sessions" \ -H "Content-Type: application/json" \ -d '{ "session_ids": [ "string" ] }'{ "folders": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "position": 0, "profile_id": "string", "session_count": 0, "updated_at": "2019-08-24T14:15:22Z", "workspace_id": "string" } ]}GET
workspace_id*stringWorkspace id
workspace_ids?array<string>Project IDs or @user; repeatable, requires all_workspaces
include_health?booleanInclude metadata-only health for returned sessions
skip_total?booleanOmit the exact catalog count for a bounded cursor read
state?stringFilter by exact session state
Value in
"starting""active""stopping""stopped"type?stringFilter by exact session type
Value in
"user""system""coordinator""spawned"agent?stringFilter by exact agent definition name
subagents?stringSubagent session visibility (default include)
Value in
"include""exclude""only"children?stringManaged child visibility
Value in
"include""exclude"parent?stringFilter by exact parent session id
root?stringFilter by exact root session id (includes the root itself)
worktree?stringFilter by exact bound worktree id
q?stringSearch session id, name, agent, or provider; title_agent searches visible title and agent
search_fields?"title_agent"Select visible title/agent search instead of the default catalog fields
Value in
"title_agent"resumable?booleanOnly list sessions eligible for explicit attach
attention?booleanOnly list sessions in the needs-you attention class
board_column?array<string>Repeatable board column filter: needs_you, working, in_review, done
badge?stringFilter by comma-separated exact session badges
archive?stringArchived session visibility
Value in
"exclude""only""include"sort?stringStable session ordering
Value in
"recent""created""name""last_activity""attention""navigator""manual"cursor?stringOpaque next_cursor from the previous page
limit?integerSessions per page (1-100)
Format
int32profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
OK
application/json- response
page*sessions*array<>curl -X GET "https://example.com/api/workspaces/string/sessions"{ "page": { "has_more": true, "limit": 0, "next_cursor": "string", "total": 0 }, "sessions": [ { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" } ]}GET
workspace_id*stringWorkspace id
session_id*stringSession id
include_health?booleanInclude metadata-only session health when available
profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
OK
application/json- response
session*curl -X GET "https://example.com/api/workspaces/string/sessions/string"{ "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}PATCH
workspace_id*stringWorkspace id
session_id*stringSession id
profile?stringAct as this profile by name
JSON request body
application/json- body
name*stringOK
application/json- response
session*curl -X PATCH "https://example.com/api/workspaces/string/sessions/string" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}DELETE
workspace_id*stringWorkspace id
session_id*stringSession id
profile?stringAct as this profile by name
No Content
curl -X DELETE "https://example.com/api/workspaces/string/sessions/string"Empty
POST
workspace_id*stringWorkspace id
session_id*stringSession id
JSON request body
application/json- body
decision*stringrequest_id*stringturn_id*stringOK
application/json- response
decision*stringinteraction_id?stringoutcome*stringrequest_id*stringresolved_decision?stringcurl -X POST "https://example.com/api/workspaces/string/sessions/string/approve" \ -H "Content-Type: application/json" \ -d '{ "decision": "string", "request_id": "string", "turn_id": "string" }'{ "decision": "string", "interaction_id": "string", "outcome": "string", "request_id": "string", "resolved_decision": "string"}POST
workspace_id*stringWorkspace id
session_id*stringSession id
stop?booleanStop a live session through the normal stop path before archiving it; a failed stop leaves it unarchived
profile?stringAct as this profile by name
OK
application/json- response
session*curl -X POST "https://example.com/api/workspaces/string/sessions/string/archive"{ "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}POST
workspace_id*stringWorkspace id
session_id*stringSession id
JSON request body
application/json- body
attached_to?stringttl_seconds?integerRange
value <= 86400OK
application/json- response
attach*session*curl -X POST "https://example.com/api/workspaces/string/sessions/string/attach" \ -H "Content-Type: application/json" \ -d '{}'{ "attach": { "attach_expires_at": "2019-08-24T14:15:22Z", "attached_at": "2019-08-24T14:15:22Z", "attached_to": "string", "session_id": "string" }, "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}POST
workspace_id*stringWorkspace id
session_id*stringSession id
Multipart upload with one required binary file field
multipart/form-data- body
file*unknownCreated
application/json- response
attachment*curl -X POST "https://example.com/api/workspaces/string/sessions/string/attachments" \ -F file="null"{ "attachment": { "bytes": 0, "created_at": "2019-08-24T14:15:22Z", "height": 0, "id": "string", "kind": "string", "mime_type": "string", "name": "string", "sha256": "string", "width": 0 }}DELETE
workspace_id*stringWorkspace id
session_id*stringSession id
attachment_id*stringAttachment id
No Content
curl -X DELETE "https://example.com/api/workspaces/string/sessions/string/attachments/string"Empty
GET
workspace_id*stringWorkspace id
session_id*stringSession id
attachment_id*stringAttachment id
Attachment bytes
response?unknown*/*curl -X GET "https://example.com/api/workspaces/string/sessions/string/attachments/string/bytes"nullGET
workspace_id*stringWorkspace id
session_id*stringSession id
OK
application/json- response
clarifications*array<>curl -X GET "https://example.com/api/workspaces/string/sessions/string/clarifications"{ "clarifications": [ { "agent_name": "string", "asked_at": "2019-08-24T14:15:22Z", "choices": [ "string" ], "deadline": "2019-08-24T14:15:22Z", "question": "string", "request_id": "string", "session_id": "string" } ]}POST
workspace_id*stringWorkspace id
session_id*stringSession id
request_id*stringClarification request id
JSON request body
application/json- body
choice_index?integer|nulltext?stringOK
application/json- response
choice*integer|nullfallback*booleantext*stringcurl -X POST "https://example.com/api/workspaces/string/sessions/string/clarifications/string/answer" \ -H "Content-Type: application/json" \ -d '{}'{ "choice": 0, "fallback": true, "text": "string"}POST
workspace_id*stringWorkspace id
session_id*stringSession id
OK
application/json- response
session*curl -X POST "https://example.com/api/workspaces/string/sessions/string/clear"{ "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}GET
workspace_id*stringWorkspace id
session_id*stringSession id
OK
application/json- response
commands*array<>revision*stringcurl -X GET "https://example.com/api/workspaces/string/sessions/string/commands"{ "commands": [ { "available": true, "canonical_token": "string", "description": "string", "display_name": "string", "id": "string", "input_hint": "string", "lane": "string", "placements": [ "string" ], "source": { "id": "string", "key": "string", "kind": "string", "origin": "string", "scope": "string" }, "unavailable_reason": "string" } ], "revision": "string"}POST
workspace_id*stringWorkspace id
session_id*stringSession id
JSON request body
body*SessionCompactRequestapplication/jsonCompaction accepted
application/json- response
command*stringprompt_id*stringsession_id*stringstatus*stringcurl -X POST "https://example.com/api/workspaces/string/sessions/string/compact"{ "command": "string", "prompt_id": "string", "session_id": "string", "status": "string"}POST
workspace_id*stringWorkspace id
session_id*stringSource session id
JSON request body
application/json- body
agent_name*stringexpected_epoch?|Format
int64expected_generation?|Format
int64expected_max_sequence?|Format
int64idempotency_key*stringmessage?stringname?stringroute?integerruntime?|Recorded outcome replayed
application/json- response
derived*session?|curl -X POST "https://example.com/api/workspaces/string/sessions/string/continue" \ -H "Content-Type: application/json" \ -d '{ "agent_name": "string", "idempotency_key": "string" }'{ "derived": { "acp_session_id": "string", "child_deleted": true, "child_session_id": "string", "first_prompt": "string", "kind": "string", "native_fork_error": "string", "native_state": "string", "omitted_count": 0, "origin_agent_name": "string", "origin_message_id": "string", "replay_bytes": 0, "replay_message_count": 0, "replayed": true, "seed": "string", "source_session_id": "string", "source_turn_in_progress": true, "through_turn_id": "string", "truncated": true }, "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}GET
workspace_id*stringWorkspace id
session_id*stringSource session id
message_id?stringDurable user message to cut through (fork from here)
OK
application/json- response
cut?|message_count*integernative_fork_possible*booleanomitted_count*integerreplay_bytes*integersource_message_count*integersource_turn_in_progress*booleantranscript*truncated*booleancurl -X GET "https://example.com/api/workspaces/string/sessions/string/derive/preview"{ "cut": { "message_id": "string", "turn_id": "string", "turn_settled": true }, "message_count": 0, "native_fork_possible": true, "omitted_count": 0, "replay_bytes": 0, "source_message_count": 0, "source_turn_in_progress": true, "transcript": { "epoch": 0, "generation": 0, "max_sequence": 0 }, "truncated": true}GET
workspace_id*stringWorkspace id
session_id*stringSession id
q?stringSearch text; empty returns the shallowest entries
limit?integerMaximum entries returned
Format
int32Range
1 <= value <= 200Default
50profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
OK
application/json- response
entries*array<>truncated*booleancurl -X GET "https://example.com/api/workspaces/string/sessions/string/files"{ "entries": [ { "kind": "file", "name": "string", "path": "string" } ], "truncated": true}POST
workspace_id*stringWorkspace id
session_id*stringSource session id
JSON request body
application/json- body
expected_epoch?|Format
int64expected_generation?|Format
int64expected_max_sequence?|Format
int64idempotency_key*stringmessage_id?stringname?stringRecorded outcome replayed
application/json- response
derived*session?|curl -X POST "https://example.com/api/workspaces/string/sessions/string/fork" \ -H "Content-Type: application/json" \ -d '{ "idempotency_key": "string" }'{ "derived": { "acp_session_id": "string", "child_deleted": true, "child_session_id": "string", "first_prompt": "string", "kind": "string", "native_fork_error": "string", "native_state": "string", "omitted_count": 0, "origin_agent_name": "string", "origin_message_id": "string", "replay_bytes": 0, "replay_message_count": 0, "replayed": true, "seed": "string", "source_session_id": "string", "source_turn_in_progress": true, "through_turn_id": "string", "truncated": true }, "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}GET
workspace_id*stringWorkspace id
session_id*stringSession id
OK
application/json- response
health*curl -X GET "https://example.com/api/workspaces/string/sessions/string/health"{ "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }}GET
workspace_id*stringWorkspace id
session_id*stringSession id
include_recent_wake_events?booleanInclude recent wake audit rows
OK
application/json- response
config_digest?stringdiagnostics?array<>health*policy_digest?stringsession_id*stringwake_events?array<>wake_state?|curl -X GET "https://example.com/api/workspaces/string/sessions/string/inspect"{ "config_digest": "string", "diagnostics": [ { "code": "string", "column": 0, "field": "string", "line": 0, "message": "string", "owner_surface": "string", "section": "string", "severity": "info", "source_path": "string" } ], "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "policy_digest": "string", "session_id": "string", "wake_events": [ { "agent_name": "string", "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "id": "string", "policy_snapshot_id": "string", "reason": "wake_sent", "result": "sent", "session_id": "string", "source": "scheduler", "synthetic_prompt_id": "string", "workspace_id": "string" } ], "wake_state": { "agent_name": "string", "coalesced_count": 0, "last_reason": "wake_sent", "last_result": "sent", "last_wake_at": "2019-08-24T14:15:22Z", "next_allowed_at": "2019-08-24T14:15:22Z", "policy_snapshot_id": "string", "session_id": "string", "updated_at": "2019-08-24T14:15:22Z", "workspace_id": "string" }}GET
workspace_id*stringWorkspace id
session_id*stringSession id
status?stringFilter by interaction status
Value in
"pending""orphaned""resolved""timed_out""canceled"OK
application/json- response
interactions*array<>curl -X GET "https://example.com/api/workspaces/string/sessions/string/interactions"{ "interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ]}GET
workspace_id*stringWorkspace id
session_id*stringSession id
profile?stringRead one profile's rows by name
all_profiles?booleanRead the owner-labeled all-profiles aggregate
Success
application/json- response
monitors*array<>curl -X GET "https://example.com/api/workspaces/string/sessions/string/monitors"{ "monitors": [ { "created_at": "2019-08-24T14:15:22Z", "deadline_at": "2019-08-24T14:15:22Z", "description": "string", "exit_code": 0, "fired_at": "2019-08-24T14:15:22Z", "kind": "string", "monitor_id": "string", "pattern": "string", "reason": "string", "session_id": "string", "status": "string", "terminal_id": "string", "until": "string" } ]}POST
workspace_id*stringWorkspace id
session_id*stringSession id
monitor_id*stringMonitor id
profile?stringAct as this profile by name
Success
application/json- response
monitor*curl -X POST "https://example.com/api/workspaces/string/sessions/string/monitors/string/cancel"{ "monitor": { "created_at": "2019-08-24T14:15:22Z", "deadline_at": "2019-08-24T14:15:22Z", "description": "string", "exit_code": 0, "fired_at": "2019-08-24T14:15:22Z", "kind": "string", "monitor_id": "string", "pattern": "string", "reason": "string", "session_id": "string", "status": "string", "terminal_id": "string", "until": "string" }}POST
workspace_id*stringWorkspace id
session_id*stringSession id
profile?stringAct as this profile by name
JSON request body
application/json- body
folder_id?stringOK
application/json- response
folders*array<>curl -X POST "https://example.com/api/workspaces/string/sessions/string/move" \ -H "Content-Type: application/json" \ -d '{}'{ "folders": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "position": 0, "profile_id": "string", "session_count": 0, "updated_at": "2019-08-24T14:15:22Z", "workspace_id": "string" } ]}DELETE
workspace_id*stringWorkspace id
session_id*stringSession id
profile?stringAct as this profile by name
OK
application/json- response
session*curl -X DELETE "https://example.com/api/workspaces/string/sessions/string/parent"{ "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}PUT
workspace_id*stringWorkspace id
session_id*stringSession id
profile?stringAct as this profile by name
JSON request body
application/json- body
parent_session_id*stringOK
application/json- response
session*curl -X PUT "https://example.com/api/workspaces/string/sessions/string/parent" \ -H "Content-Type: application/json" \ -d '{ "parent_session_id": "string" }'{ "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}POST
workspace_id*stringWorkspace id
session_id*stringSession id
JSON request body
application/json- body
lease_id?stringvisible*booleanPresence lease acquired
application/json- response
lease_id*stringcurl -X POST "https://example.com/api/workspaces/string/sessions/string/presence" \ -H "Content-Type: application/json" \ -d '{ "visible": true }'{ "lease_id": "string"}POST
workspace_id*stringWorkspace id
session_id*stringSession id
JSON request body
application/json- body
attachments?array<>expected_turn_id?stringidempotency_key*stringin_reply_to?stringmessage?stringmessage_id*stringmessages?array<>mode?stringruntime?|supersede?booleanPrompt accepted or Goal command completed; streams UI message chunks for an active turn
- response
prompt*curl -X POST "https://example.com/api/workspaces/string/sessions/string/prompt" \ -H "Content-Type: application/json" \ -d '{ "idempotency_key": "string", "message_id": "string" }'{ "prompt": { "canceled_queued_entries": 0, "delivery": "string", "disposition": "direct", "entry_id": "string", "estimated_send_at": "2019-08-24T14:15:22Z", "goal": { "outcome": "started", "reason_code": "goal_not_active", "replaced_run_id": "string", "snapshot": { "bound_session_id": "string", "cause": "goal_not_active", "context": { "diagnostic": "string", "nudge_ratio": 0.1, "ratio": 0, "reported_at": "2019-08-24T14:15:22Z", "size": 0, "state": "known", "used": 0 }, "contract_summary": "string", "last_verdict": { "blocking_issues": [ { "id": "string", "note": "string" } ], "evaluated_at": "2019-08-24T14:15:22Z", "evidence_ref": "string", "outcome": "approved" }, "live": true, "node_id": "string", "objective": "string", "origin_session_id": "string", "pause_requested": true, "run_id": "string", "run_status": "queued", "status": "active", "turn_limit": 0, "turns_used": 0 } }, "idempotency_key": "string", "message_id": "string", "mode": "string", "new_turn_id": "string", "previous_turn_id": "string", "queue_entry_id": "string", "queue_generation": 0, "queue_position": 0, "replayed": true, "reply_watch": { "id": "string", "state": "string" }, "status": "string", "steer_delivery": "injected", "target_workspace_id": "string", "turn_id": "string" }}POST
workspace_id*stringWorkspace id
session_id*stringSession id
Cancellation result
application/json- response
outcome*stringsession_id*stringturn_id?stringcurl -X POST "https://example.com/api/workspaces/string/sessions/string/prompt/cancel"{ "outcome": "string", "session_id": "string", "turn_id": "string"}GET
workspace_id*stringWorkspace id
session_id*stringSession id
Pending session input
application/json- response
inputs*array<>queue?|curl -X GET "https://example.com/api/workspaces/string/sessions/string/prompt/queue"{ "inputs": [ { "attachments": [ { "bytes": 0, "height": 0, "id": "string", "kind": "string", "mime_type": "string", "name": "string", "sha256": "string", "width": 0 } ], "delivery": "string", "enqueued_at": "2019-08-24T14:15:22Z", "id": "string", "idempotency_key": "string", "mentions": [ { "end": 0, "kind": "file", "label": "string", "start": 0, "target": "string", "token": "string" } ], "message_id": "string", "mode": "string", "origin": { "agent_name": "string", "hop": 0, "in_reply_to": "string", "kind": "string", "notify_on_complete": true, "reply_watch_id": "string", "session_id": "string", "title_at_send": "string", "workspace_id": "string" }, "owner_id": "string", "owner_kind": "string", "queue_generation": 0, "runtime": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "session_id": "string", "skill_invocations": [ { "command_id": "string", "end": 0, "name": "string", "source": { "id": "string", "key": "string", "kind": "string", "origin": "string", "scope": "string" }, "start": 0, "token": "string" } ], "status": "queued", "steer_delivery": "injected", "target_turn_id": "string", "text": "string" } ], "queue": { "cap": 0, "entries": 0 }}DELETE
workspace_id*stringWorkspace id
session_id*stringSession id
Per-entry clear outcomes
application/json- response
cleared_count*integerinputs*array<>queue_generation*integerFormat
int64curl -X DELETE "https://example.com/api/workspaces/string/sessions/string/prompt/queue"{ "cleared_count": 0, "inputs": [ { "attachments": [ { "bytes": 0, "height": 0, "id": "string", "kind": "string", "mime_type": "string", "name": "string", "sha256": "string", "width": 0 } ], "delivery": "string", "enqueued_at": "2019-08-24T14:15:22Z", "id": "string", "idempotency_key": "string", "mentions": [ { "end": 0, "kind": "file", "label": "string", "start": 0, "target": "string", "token": "string" } ], "message_id": "string", "mode": "string", "origin": { "agent_name": "string", "hop": 0, "in_reply_to": "string", "kind": "string", "notify_on_complete": true, "reply_watch_id": "string", "session_id": "string", "title_at_send": "string", "workspace_id": "string" }, "owner_id": "string", "owner_kind": "string", "queue_generation": 0, "runtime": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "session_id": "string", "skill_invocations": [ { "command_id": "string", "end": 0, "name": "string", "source": { "id": "string", "key": "string", "kind": "string", "origin": "string", "scope": "string" }, "start": 0, "token": "string" } ], "status": "queued", "steer_delivery": "injected", "target_turn_id": "string", "text": "string" } ], "queue_generation": 0}DELETE
workspace_id*stringWorkspace id
session_id*stringSession id
queue_entry_id*stringQueue entry id
Queued prompt canceled
application/json- response
prompt*curl -X DELETE "https://example.com/api/workspaces/string/sessions/string/prompt/queue/string"{ "prompt": { "canceled_queued_entries": 0, "delivery": "string", "disposition": "direct", "entry_id": "string", "estimated_send_at": "2019-08-24T14:15:22Z", "goal": { "outcome": "started", "reason_code": "goal_not_active", "replaced_run_id": "string", "snapshot": { "bound_session_id": "string", "cause": "goal_not_active", "context": { "diagnostic": "string", "nudge_ratio": 0.1, "ratio": 0, "reported_at": "2019-08-24T14:15:22Z", "size": 0, "state": "known", "used": 0 }, "contract_summary": "string", "last_verdict": { "blocking_issues": [ { "id": "string", "note": "string" } ], "evaluated_at": "2019-08-24T14:15:22Z", "evidence_ref": "string", "outcome": "approved" }, "live": true, "node_id": "string", "objective": "string", "origin_session_id": "string", "pause_requested": true, "run_id": "string", "run_status": "queued", "status": "active", "turn_limit": 0, "turns_used": 0 } }, "idempotency_key": "string", "message_id": "string", "mode": "string", "new_turn_id": "string", "previous_turn_id": "string", "queue_entry_id": "string", "queue_generation": 0, "queue_position": 0, "replayed": true, "reply_watch": { "id": "string", "state": "string" }, "status": "string", "steer_delivery": "injected", "target_workspace_id": "string", "turn_id": "string" }}PUT
workspace_id*stringWorkspace id
session_id*stringSession id
queue_entry_id*stringQueue entry id
JSON request body
application/json- body
idempotency_key*stringmessage_id*stringtext*stringQueued input replaced
application/json- response
input*curl -X PUT "https://example.com/api/workspaces/string/sessions/string/prompt/queue/string" \ -H "Content-Type: application/json" \ -d '{ "idempotency_key": "string", "message_id": "string", "text": "string" }'{ "input": { "attachments": [ { "bytes": 0, "height": 0, "id": "string", "kind": "string", "mime_type": "string", "name": "string", "sha256": "string", "width": 0 } ], "delivery": "string", "enqueued_at": "2019-08-24T14:15:22Z", "id": "string", "idempotency_key": "string", "mentions": [ { "end": 0, "kind": "file", "label": "string", "start": 0, "target": "string", "token": "string" } ], "message_id": "string", "mode": "string", "origin": { "agent_name": "string", "hop": 0, "in_reply_to": "string", "kind": "string", "notify_on_complete": true, "reply_watch_id": "string", "session_id": "string", "title_at_send": "string", "workspace_id": "string" }, "owner_id": "string", "owner_kind": "string", "queue_generation": 0, "runtime": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "session_id": "string", "skill_invocations": [ { "command_id": "string", "end": 0, "name": "string", "source": { "id": "string", "key": "string", "kind": "string", "origin": "string", "scope": "string" }, "start": 0, "token": "string" } ], "status": "queued", "steer_delivery": "injected", "target_turn_id": "string", "text": "string" }}POST
workspace_id*stringWorkspace id
session_id*stringSession id
queue_entry_id*stringQueue entry id
JSON request body
application/json- body
expected_turn_id?stringidempotency_key*stringmessage_id*stringtext*stringQueued input promoted to steering
application/json- response
prompt*curl -X POST "https://example.com/api/workspaces/string/sessions/string/prompt/queue/string/steer" \ -H "Content-Type: application/json" \ -d '{ "idempotency_key": "string", "message_id": "string", "text": "string" }'{ "prompt": { "canceled_queued_entries": 0, "delivery": "string", "disposition": "direct", "entry_id": "string", "estimated_send_at": "2019-08-24T14:15:22Z", "goal": { "outcome": "started", "reason_code": "goal_not_active", "replaced_run_id": "string", "snapshot": { "bound_session_id": "string", "cause": "goal_not_active", "context": { "diagnostic": "string", "nudge_ratio": 0.1, "ratio": 0, "reported_at": "2019-08-24T14:15:22Z", "size": 0, "state": "known", "used": 0 }, "contract_summary": "string", "last_verdict": { "blocking_issues": [ { "id": "string", "note": "string" } ], "evaluated_at": "2019-08-24T14:15:22Z", "evidence_ref": "string", "outcome": "approved" }, "live": true, "node_id": "string", "objective": "string", "origin_session_id": "string", "pause_requested": true, "run_id": "string", "run_status": "queued", "status": "active", "turn_limit": 0, "turns_used": 0 } }, "idempotency_key": "string", "message_id": "string", "mode": "string", "new_turn_id": "string", "previous_turn_id": "string", "queue_entry_id": "string", "queue_generation": 0, "queue_position": 0, "replayed": true, "reply_watch": { "id": "string", "state": "string" }, "status": "string", "steer_delivery": "injected", "target_workspace_id": "string", "turn_id": "string" }}GET
workspace_id*stringWorkspace id
session_id*stringSession id
limit?integerMaximum recent messages to include
Format
int32OK
application/json- response
recap*curl -X GET "https://example.com/api/workspaces/string/sessions/string/recap"{ "recap": { "active_run": { "attempt": 0, "claim_token_hash": "string", "claimed_at": "2019-08-24T14:15:22Z", "claimed_by": { "kind": "human", "ref": "string" }, "designation": { "brief": "string", "index": 0 }, "designation_group_id": "string", "ended_at": "2019-08-24T14:15:22Z", "error": "string", "failure_kind": "string", "heartbeat_at": "2019-08-24T14:15:22Z", "id": "string", "idempotency_key": "string", "lease_until": "2019-08-24T14:15:22Z", "metadata": null, "origin": { "kind": "cli", "ref": "string" }, "previous_run_id": "string", "profile_color": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "queued_at": "2019-08-24T14:15:22Z", "recovery_count": 0, "resolved_worktree_mode": "none", "resolved_worktree_ref": "string", "result": null, "result_bytes": 0, "result_ref": "string", "session_id": "string", "started_at": "2019-08-24T14:15:22Z", "status": "queued", "task_id": "string", "worktree_id": "string" }, "pending_inputs": 0, "pending_markers": 0, "recent_markers": [ { "diagnostic": null, "evidence": { "property1": null, "property2": null }, "kind": "string", "occurred_at": "2019-08-24T14:15:22Z", "summary": "string" } ], "recent_messages": [ { "id": "string", "metadata": null, "parts": [ { "data": null, "errorText": "string", "filename": "string", "id": "string", "input": null, "mediaType": "string", "output": null, "parentToolCallId": "string", "preliminary": true, "rawInput": null, "state": "string", "text": "string", "title": "string", "toolCallId": "string", "toolName": "string", "type": "string", "url": "string" } ], "role": "string" } ], "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }, "snapshot": { "consistency": "string", "event_cursor": 0, "generated_at": "2019-08-24T14:15:22Z", "queue_generation": 0, "transcript_cursor": 0 } }}POST
workspace_id*stringWorkspace id
session_id*stringSession id
dry_run?booleanReport planned repairs without persisting new events
force?booleanAllow repair for stopped sessions whose stop reason is not crash or error
OK
application/json- response
repair*curl -X POST "https://example.com/api/workspaces/string/sessions/string/repair"{ "repair": { "actions": [ { "code": "string", "event_id": "string", "persisted": true, "tool_call_id": "string", "tool_name": "string", "turn_id": "string" } ], "issues": [ { "code": "string", "detail": "string", "event_id": "string", "severity": "string", "turn_id": "string" } ], "persisted": true, "session_id": "string" }}POST
workspace_id*stringWorkspace id
session_id*stringSession id
profile?stringAct as this profile by name
JSON request body
application/json- body
expected_epoch*|Format
int64expected_generation*|Format
int64expected_max_sequence*|Format
int64idempotency_key*stringmessage_id*stringOK
application/json- response
rewind*session*curl -X POST "https://example.com/api/workspaces/string/sessions/string/rewind" \ -H "Content-Type: application/json" \ -d '{ "expected_epoch": 0, "expected_generation": 0, "expected_max_sequence": 0, "idempotency_key": "string", "message_id": "string" }'{ "rewind": { "archived_event_count": 0, "archived_from_sequence": 0, "archived_through_sequence": 0, "draft_text": "string", "generation": 0, "max_sequence": 0, "replayed": true, "target_message_id": "string", "transcript_epoch": 0 }, "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}DELETE
workspace_id*stringWorkspace id
session_id*stringSession id
expected_revision*integerCurrent runtime selection revision
Format
int64OK
application/json- response
session*curl -X DELETE "https://example.com/api/workspaces/string/sessions/string/runtime?expected_revision=0"{ "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}PUT
workspace_id*stringWorkspace id
session_id*stringSession id
JSON request body
application/json- body
expected_revision*|Format
int64runtime*OK
application/json- response
session*curl -X PUT "https://example.com/api/workspaces/string/sessions/string/runtime" \ -H "Content-Type: application/json" \ -d '{ "expected_revision": 0, "runtime": { "provider": "string" } }'{ "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}POST
workspace_id*stringWorkspace id
session_id*stringSession id
JSON request body
application/json- body
expected_digest*stringidempotency_key?stringOK
application/json- response
active*booleanagent_name?stringbody?stringconfig_provenance*created_at?|Format
date-timediagnostics?array<>digest?stringenabled*booleanfrontmatter*limits*present*booleanrevision_id?stringsnapshot_id?stringsource_path?stringtruncated?booleanvalid*booleanvalidation_status*stringValue in
"missing""inactive""valid""invalid"curl -X POST "https://example.com/api/workspaces/string/sessions/string/soul/refresh" \ -H "Content-Type: application/json" \ -d '{ "expected_digest": "string" }'{ "active": true, "agent_name": "string", "body": "string", "config_provenance": { "context_projection_bytes": 0, "digest": "string", "enabled": true, "max_body_bytes": 0, "source": "string" }, "created_at": "2019-08-24T14:15:22Z", "diagnostics": [ { "code": "string", "column": 0, "field": "string", "line": 0, "message": "string", "owner_surface": "string", "section": "string", "severity": "info", "source_path": "string" } ], "digest": "string", "enabled": true, "frontmatter": { "collaboration": [ "string" ], "constraints": [ "string" ], "principles": [ "string" ], "role": "string", "tags": [ "string" ], "tone": [ "string" ], "version": "string" }, "limits": { "context_projection_bytes": 0, "max_body_bytes": 0, "max_bytes": 0 }, "present": true, "revision_id": "string", "snapshot_id": "string", "source_path": "string", "truncated": true, "valid": true, "validation_status": "missing"}POST
workspace_id*stringWorkspace id
session_id*stringSession id
JSON request body
application/json- body
attachments?array<>expected_turn_id?stringidempotency_key*stringmessage_id*stringtext*stringPrompt steering accepted
application/json- response
prompt*curl -X POST "https://example.com/api/workspaces/string/sessions/string/steer" \ -H "Content-Type: application/json" \ -d '{ "idempotency_key": "string", "message_id": "string", "text": "string" }'{ "prompt": { "canceled_queued_entries": 0, "delivery": "string", "disposition": "direct", "entry_id": "string", "estimated_send_at": "2019-08-24T14:15:22Z", "goal": { "outcome": "started", "reason_code": "goal_not_active", "replaced_run_id": "string", "snapshot": { "bound_session_id": "string", "cause": "goal_not_active", "context": { "diagnostic": "string", "nudge_ratio": 0.1, "ratio": 0, "reported_at": "2019-08-24T14:15:22Z", "size": 0, "state": "known", "used": 0 }, "contract_summary": "string", "last_verdict": { "blocking_issues": [ { "id": "string", "note": "string" } ], "evaluated_at": "2019-08-24T14:15:22Z", "evidence_ref": "string", "outcome": "approved" }, "live": true, "node_id": "string", "objective": "string", "origin_session_id": "string", "pause_requested": true, "run_id": "string", "run_status": "queued", "status": "active", "turn_limit": 0, "turns_used": 0 } }, "idempotency_key": "string", "message_id": "string", "mode": "string", "new_turn_id": "string", "previous_turn_id": "string", "queue_entry_id": "string", "queue_generation": 0, "queue_position": 0, "replayed": true, "reply_watch": { "id": "string", "state": "string" }, "status": "string", "steer_delivery": "injected", "target_workspace_id": "string", "turn_id": "string" }}POST
workspace_id*stringWorkspace id
session_id*stringSession id
profile?stringAct as this profile by name
JSON request body
application/json- body
wait?boolean|nullSettled stop result or already stopped
application/json- response
attention?stringescalated*booleanphase?stringsession_id*stringstate*stringValue in
"starting""active""stopping""stopped"status*stringstop_cause?stringstopped_after?stringverified*booleancurl -X POST "https://example.com/api/workspaces/string/sessions/string/stop" \ -H "Content-Type: application/json" \ -d '{}'{ "attention": "string", "escalated": true, "phase": "string", "session_id": "string", "state": "starting", "status": "string", "stop_cause": "string", "stopped_after": "string", "verified": true}GET
workspace_id*stringWorkspace id
session_id*stringParent session id
origin?stringSubagent origin
Value in
"delegated""provider_native"status?stringComma-separated subagent statuses
limit?integerSubagents per page (default 50, maximum 200)
Format
int32cursor?stringOpaque next_cursor from the previous page
order?stringRow order: newest first (default), or most urgent first (waiting, failed, working, queued, settled) then newest
Value in
"newest""urgency"Success
application/json- response
next_cursor*string|nullsubagents*array<>curl -X GET "https://example.com/api/workspaces/string/sessions/string/subagents"{ "next_cursor": "string", "subagents": [ { "child_activity": "working", "child_session_id": "string", "created_at": "2019-08-24T14:15:22Z", "delivery": "string", "depth": 0, "error": "string", "hint": "string", "isolation": "string", "origin": "string", "parent_session_id": "string", "parent_turn_id": "string", "progress": "string", "provider_tool_call_id": "string", "result": "string", "result_preview": "string", "result_truncated": true, "role": "string", "runtime": { "agent": "string", "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "string" }, "settled_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z", "status": "string", "subagent_id": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "wait_timed_out": true, "work_state": "string", "workspace_id": "string", "worktree": { "base_ref": "string", "base_sha": "string", "branch": "string", "commits_ahead": 0, "dirty_files": 0, "head_sha": "string", "id": "string", "name": "string", "observed_at": "2019-08-24T14:15:22Z", "path": "string", "pull_request": { "number": 0, "state": "string", "url": "string" }, "pull_request_status": "string" } } ]}GET
workspace_id*stringWorkspace id
session_id*stringSession id
agent_name?stringEffective agent name
OK
application/json- response
tools*array<>curl -X GET "https://example.com/api/workspaces/string/sessions/string/tools"{ "tools": [ { "availability": { "authorized": true, "available": true, "conflicted": true, "enabled": true, "executable": true, "reason_codes": [ "approval_canceled" ], "registered": true }, "decision": { "agent_policy_result": "string", "approval_required": true, "availability_result": "string", "callable": true, "hook_result": "string", "reason_codes": [ "approval_canceled" ], "registry_policy_result": "string", "session_policy_result": "string", "source_policy_result": "string", "system_permission_mode": "string", "visible_to_operator": true, "visible_to_session": true }, "descriptor": { "backend": { "extension_id": "string", "handler": "string", "kind": "native_go", "mcp_server": "string", "mcp_tool": "string", "native_name": "string", "requires_capabilities": [ "string" ] }, "concurrency_safe": true, "description": "string", "destructive": true, "display_title": "string", "friendly_verb": "string", "input_schema": null, "input_schema_digest": "string", "max_result_bytes": 0, "open_world": true, "output_schema": null, "output_schema_digest": "string", "preview": "string", "read_only": true, "requires_interaction": true, "risk": "read", "search_hints": [ "string" ], "source": { "kind": "builtin", "owner": "string", "raw_server_name": "string", "raw_tool_name": "string", "resource_id": "string", "resource_version": "string", "scope": "string", "workspace_id": "string" }, "tags": [ "string" ], "tool_id": "string", "toolsets": [ "string" ], "visibility": "internal" } } ]}POST
workspace_id*stringWorkspace id
session_id*stringSession id
JSON request body
application/json- body
agent_name?stringlimit?integerquery*stringsession_id?stringworkspace_id?stringOK
application/json- response
tools*array<>curl -X POST "https://example.com/api/workspaces/string/sessions/string/tools/search" \ -H "Content-Type: application/json" \ -d '{ "query": "string" }'{ "tools": [ { "availability": { "authorized": true, "available": true, "conflicted": true, "enabled": true, "executable": true, "reason_codes": [ "approval_canceled" ], "registered": true }, "decision": { "agent_policy_result": "string", "approval_required": true, "availability_result": "string", "callable": true, "hook_result": "string", "reason_codes": [ "approval_canceled" ], "registry_policy_result": "string", "session_policy_result": "string", "source_policy_result": "string", "system_permission_mode": "string", "visible_to_operator": true, "visible_to_session": true }, "descriptor": { "backend": { "extension_id": "string", "handler": "string", "kind": "native_go", "mcp_server": "string", "mcp_tool": "string", "native_name": "string", "requires_capabilities": [ "string" ] }, "concurrency_safe": true, "description": "string", "destructive": true, "display_title": "string", "friendly_verb": "string", "input_schema": null, "input_schema_digest": "string", "max_result_bytes": 0, "open_world": true, "output_schema": null, "output_schema_digest": "string", "preview": "string", "read_only": true, "requires_interaction": true, "risk": "read", "search_hints": [ "string" ], "source": { "kind": "builtin", "owner": "string", "raw_server_name": "string", "raw_tool_name": "string", "resource_id": "string", "resource_version": "string", "scope": "string", "workspace_id": "string" }, "tags": [ "string" ], "tool_id": "string", "toolsets": [ "string" ], "visibility": "internal" } } ]}POST
workspace_id*stringWorkspace id
session_id*stringSession id
profile?stringAct as this profile by name
OK
application/json- response
session*curl -X POST "https://example.com/api/workspaces/string/sessions/string/unarchive"{ "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}GET
workspace_id*stringWorkspace id
session_id*stringSession id
OK
application/json- response
usage*curl -X GET "https://example.com/api/workspaces/string/sessions/string/usage"{ "usage": { "cache_read_tokens": 0, "cache_write_tokens": 0, "context": { "cleared_by": { "compaction_id": "string", "sequence": 0 }, "injected": { "estimate": "string", "rows": [ { "bytes": 0, "delivered_turn_id": "string", "delivery": "string", "delivery_sequence": 0, "hook_modified": true, "key": "string", "kind": "string", "label": "string", "last_seen_turn_id": "string", "name": "string", "owner_kind": "string", "sent_at": "2019-08-24T14:15:22Z", "stale": true, "tokens": 0, "unchanged": true } ], "stale": true, "tokens": 0 }, "ratio": 0, "reported_at": "2019-08-24T14:15:22Z", "reported_turn_id": "string", "sequence": 0, "size": 0, "size_source": "string", "stale": true, "state": "reported", "used": 0 }, "cost_currency": "string", "cost_source": "agent_reported", "cost_status": "actual", "input_tokens": 0, "output_tokens": 0, "total_cost": 0, "total_tokens": 0, "turn_count": 0, "work_time": { "active_duration_ms": 0, "last_completed_turn_id": "string", "turn_count": 0 } }}GET
workspace_id*stringWorkspace id
session_id*stringSession id
OK
application/json- response
compactions*array<>turns*array<>curl -X GET "https://example.com/api/workspaces/string/sessions/string/usage/turns"{ "compactions": [ { "at": "2019-08-24T14:15:22Z", "compaction_id": "string", "context_after": { "sequence": 0, "size": 0, "used": 0 }, "context_size": 0, "context_used": 0, "sequence": 0, "status": "string", "trigger": "string", "turn_id": "string" } ], "turns": [ { "injected": { "estimate": "string", "sent_at": "2019-08-24T14:15:22Z", "sequence": 0, "spans": [ { "bytes": 0, "delivery": "string", "hook_modified": true, "key": "string", "kind": "string", "name": "string", "startup_dedup": true, "tokens": 0, "unchanged": true } ], "tokens": 0 }, "sequence": 0, "turn_id": "string", "usage": { "cache_read_tokens": 0, "cache_write_tokens": 0, "context_size": 0, "context_used": 0, "cost_amount": 0, "cost_currency": "string", "input_tokens": 0, "meta": { "property1": null, "property2": null }, "output_tokens": 0, "sequence": 0, "thought_tokens": 0, "timestamp": "2019-08-24T14:15:22Z", "total_tokens": 0, "turn_id": "string" } } ]}POST
workspace_id*stringWorkspace id
session_id*stringSession id
JSON request body
application/json- body
epoch?integerFormat
int64resume_id?stringtimeout_ms*integerFormat
int64until?array<string>Wait completed or timed out
application/json- response
outcome*stringresume_id?stringrevision*integerFormat
int64session_id*stringstate?stringuntil?array<string>waited_ms*integerFormat
int64curl -X POST "https://example.com/api/workspaces/string/sessions/string/wait" \ -H "Content-Type: application/json" \ -d '{ "timeout_ms": 0 }'{ "outcome": "string", "resume_id": "string", "revision": 0, "session_id": "string", "state": "string", "until": [ "string" ], "waited_ms": 0}DELETE
workspace_id*stringWorkspace id
session_id*stringSession id
profile?stringAct as this profile by name
expected_worktree_id?stringExpected current worktree id; empty for workspace root
Same session with updated execution location
application/json- response
session*curl -X DELETE "https://example.com/api/workspaces/string/sessions/string/worktree"{ "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}PUT
workspace_id*stringWorkspace id
session_id*stringSession id
profile?stringAct as this profile by name
JSON request body
application/json- body
expected_worktree_id?string|nullworktree*stringSame session with updated execution location
application/json- response
session*curl -X PUT "https://example.com/api/workspaces/string/sessions/string/worktree" \ -H "Content-Type: application/json" \ -d '{ "worktree": "string" }'{ "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}POST
workspace_id*stringWorkspace id
session_id*stringOrigin session id
JSON request body
application/json- body
confirmed*booleannew_worktree?|worktree?stringCreated
application/json- response
session*curl -X POST "https://example.com/api/workspaces/string/sessions/string/worktree-fork" \ -H "Content-Type: application/json" \ -d '{ "confirmed": true }'{ "session": { "activity": { "current_tool": "string", "deadline_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "elapsed_seconds": 0, "idle_seconds": 0, "iteration_current": 0, "iteration_max": 0, "last_activity_at": "2019-08-24T14:15:22Z", "last_activity_detail": "string", "last_activity_kind": "string", "last_progress_at": "2019-08-24T14:15:22Z", "tool_call_id": "string", "turn_id": "string", "turn_source": "string", "turn_started_at": "2019-08-24T14:15:22Z" }, "agent_name": "string", "archived_at": "2019-08-24T14:15:22Z", "attach_expires_at": "2019-08-24T14:15:22Z", "attachable": true, "attached_to": "string", "attention": "string", "attention_changed_at": "2019-08-24T14:15:22Z", "available_commands": [ { "description": "string", "input": { "hint": "string" }, "name": "string" } ], "badge": "running", "board_column": "needs_you", "branch": "string", "busy_input": { "default_mode": "string", "steer_capability": "steer_ext", "steer_delivery": "injected" }, "children": { "done": 0, "in_review": 0, "needs_you": 0, "total": 0, "working": 0 }, "created_at": "2019-08-24T14:15:22Z", "derivation": { "first_prompt": "string", "kind": "", "native_fork_error": "string", "native_state": "string", "seed": "string", "source_session_id": "string" }, "diagnostics": [ { "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" } ], "effective_workspace_access": "string", "escalated": true, "failure": { "crash_bundle_path": "string", "kind": "string", "reason_code": "string", "summary": "string" }, "folder_id": "string", "health": { "active_prompt": true, "agent_name": "string", "attachable": true, "attention": "string", "eligible_for_wake": true, "escalated": true, "health": "healthy", "ineligibility_reason": "session_prompt_active", "last_activity_at": "2019-08-24T14:15:22Z", "last_error": "string", "last_presence_at": "2019-08-24T14:15:22Z", "lifecycle_state": "starting", "session_id": "string", "state": "idle", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "workspace_id": "string" }, "id": "string", "lineage": { "auto_stop_on_parent": true, "kind": "", "notify_creator": true, "origin_agent_name": "string", "origin_message_id": "string", "parent_session_id": "string", "permission_policy": { "mcp_servers": [ "string" ], "skills": [ "string" ], "tools": [ "string" ], "workspace_paths": [ "string" ] }, "root_session_id": "string", "spawn_budget": { "max_active_per_workspace": 0, "max_children": 0, "max_depth": 0, "ttl_seconds": 0 }, "spawn_depth": 0, "spawn_role": "string", "ttl_expires_at": "2019-08-24T14:15:22Z" }, "monitor_summary": { "active": 0 }, "name": "string", "parent_title": "string", "pending_interactions": [ { "choices": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "decisions": [ "string" ], "interaction_id": "string", "kind": "string", "provider_request_id": "string", "resolution": "string", "resolved_at": "2019-08-24T14:15:22Z", "resolved_by": "string", "status": "string", "title": "string", "tool_id": "string", "turn_id": "string" } ], "profile_archived": true, "profile_color": "string", "profile_emoji": "string", "profile_icon": "string", "profile_id": "string", "profile_name": "string", "pull_request": { "checks": { "failed": 0, "failed_names": [ "string" ], "passed": 0, "pending": 0, "state": "passing" }, "draft": true, "head_sha": "string", "mergeable": "mergeable", "number": 0, "provider": "string", "ready_to_merge": true, "review_decision": "approved", "state": "open", "url": "string" }, "pull_request_lookup": { "cause": "string", "observed_at": "2019-08-24T14:15:22Z", "stale": true, "state": "ok" }, "queue": { "cap": 0, "entries": 0 }, "reply_watches": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "message_id": "string", "state": "string", "target_session_id": "string" } ], "runtime": { "acp_caps": { "config_options": [ { "category": "string", "current_bool": true, "current_value_id": "string", "description": "string", "id": "string", "kind": "string", "label": "string", "values": [ { "description": "string", "group_id": "string", "group_label": "string", "label": "string", "value": "string" } ] } ], "prompt_audio": true, "prompt_embedded_context": true, "prompt_image": true, "supported_modes": [ "string" ], "supports_fork_session": true, "supports_load_session": true, "supports_resume_session": true }, "acp_session_id": "string", "effective": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "failure": "string", "generation": 0, "last_known": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal", "speed_resolution": { "reason": "capability_absent", "requested": "normal", "status": "applied" } }, "recovery": { "attempt": 0, "generation": 0, "last_attempt_at": "2019-08-24T14:15:22Z", "last_error": "string", "max_attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z" }, "requested": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selected": { "acp_options": [ { "bool_value": true, "id": "string", "value_id": "string" } ], "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "normal" }, "selection_revision": 0, "status": "string", "transition": "string" }, "scope": "string", "state": "starting", "stop_cause": "string", "stop_detail": "string", "stop_reason": "completed", "subagent_summary": { "attention": 0, "failed": 0, "live": 0, "most_urgent": "string", "total": 0 }, "supervision": { "quiet_warning": { "quiet_since": "2019-08-24T14:15:22Z", "stop_at": "2019-08-24T14:15:22Z", "warned_at": "2019-08-24T14:15:22Z" }, "sources": [ { "error": "string", "kind": "agent_progress", "ref": "string", "state": "string" } ], "work_signals": [ { "kind": "agent_progress", "ref": "string", "since": "2019-08-24T14:15:22Z" } ] }, "transcript_epoch": 0, "type": "user", "updated_at": "2019-08-24T14:15:22Z", "verified": true, "waiting_on": "sessions", "workspace_id": "string", "workspace_path": "string", "worktree_binding": { "available": true, "unavailable_reason": "string" }, "worktree_id": "string" }}GET
workspace_id*stringWorkspace id
subagent_id*stringSubagent id
Success
application/json- response
child_activity?stringValue in
"working""idle""stopped"child_session_id*string|nullcreated_at*stringFormat
date-timedelivery*stringdepth*integererror*string|nullhint?stringisolation*stringorigin*stringparent_session_id*stringparent_turn_id*stringprogress*stringprovider_tool_call_id*string|nullresult*string|nullresult_preview*stringresult_truncated*booleanrole*stringruntime*settled_at*|Format
date-timestarted_at*|Format
date-timestatus*stringsubagent_id*stringtitle*stringupdated_at*stringFormat
date-timewait_timed_out*booleanwork_state*stringworkspace_id*stringworktree?|curl -X GET "https://example.com/api/workspaces/string/subagents/string"{ "child_activity": "working", "child_session_id": "string", "created_at": "2019-08-24T14:15:22Z", "delivery": "string", "depth": 0, "error": "string", "hint": "string", "isolation": "string", "origin": "string", "parent_session_id": "string", "parent_turn_id": "string", "progress": "string", "provider_tool_call_id": "string", "result": "string", "result_preview": "string", "result_truncated": true, "role": "string", "runtime": { "agent": "string", "model": "string", "provider": "string", "reasoning_effort": "string", "speed": "string" }, "settled_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z", "status": "string", "subagent_id": "string", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "wait_timed_out": true, "work_state": "string", "workspace_id": "string", "worktree": { "base_ref": "string", "base_sha": "string", "branch": "string", "commits_ahead": 0, "dirty_files": 0, "head_sha": "string", "id": "string", "name": "string", "observed_at": "2019-08-24T14:15:22Z", "path": "string", "pull_request": { "number": 0, "state": "string", "url": "string" }, "pull_request_status": "string" }}POST
workspace_id*stringWorkspace id
subagent_id*stringSubagent id
profile?stringAct as this profile by name
JSON request body
application/json- body
reason*stringSuccess
application/json- response
status*stringsubagent_id*stringcurl -X POST "https://example.com/api/workspaces/string/subagents/string/cancel" \ -H "Content-Type: application/json" \ -d '{ "reason": "string" }'{ "status": "string", "subagent_id": "string"}