Sessions

Spawn a narrowed child session for the calling agent

POST/api/agent/spawn

Header Parameters

X-Compozy-Session-ID*string

Daemon-issued active session id

X-Compozy-Agent*string

Daemon-issued session agent name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

agent_name*string

Match^[a-z][a-z0-9_-]{0,105}$

Lengthlength <= 106

auto_stop_on_parent*boolean

idempotency_key?string

model?string

name?string

notify_creator?boolean|null

permissions*

prompt_overlay?string

provider?string

spawn_role*string

speed?string

Value in

"normal"
"fast"

ttl_seconds*integer

Formatint64

workspace?string

Response Body

`application/json`

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": {      "mcp_servers": [        "string"      ],      "network_channels": [        "string"      ],      "sandbox_profiles": [        "string"      ],      "skills": [        "string"      ],      "tools": [        "string"      ],      "workspace_paths": [        "string"      ]    },    "spawn_role": "string",    "ttl_seconds": 0  }'

{  "spawn": {    "lineage": {      "auto_stop_on_parent": true,      "notify_creator": true,      "parent_session_id": "string",      "permission_policy": {        "mcp_servers": [          "string"        ],        "network_channels": [          "string"        ],        "sandbox_profiles": [          "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"      ],      "network_channels": [        "string"      ],      "sandbox_profiles": [        "string"      ],      "skills": [        "string"      ],      "tools": [        "string"      ],      "workspace_paths": [        "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_changed_at": "2019-08-24T14:15:22Z",      "available_commands": [        {          "description": "string",          "input": {            "hint": "string"          },          "name": "string"        }      ],      "badge": "string",      "created_at": "2019-08-24T14:15:22Z",      "failure": {        "crash_bundle_path": "string",        "kind": "string",        "summary": "string"      },      "health": {        "active_prompt": true,        "agent_name": "string",        "attachable": true,        "eligible_for_wake": 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",        "session_id": "string",        "state": "idle",        "updated_at": "2019-08-24T14:15:22Z",        "workspace_id": "string"      },      "id": "string",      "lineage": {        "auto_stop_on_parent": true,        "notify_creator": true,        "parent_session_id": "string",        "permission_policy": {          "mcp_servers": [            "string"          ],          "network_channels": [            "string"          ],          "sandbox_profiles": [            "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"      },      "name": "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",          "turn_id": "string"        }      ],      "resolved_network_participation": {        "mode": "local",        "source": "explicit_request",        "version": "network-participation/v1"      },      "runtime": {        "acp_caps": {          "config_options": [            {              "current": "string",              "description": "string",              "id": "string",              "kind": "string",              "label": "string",              "values": [                {                  "description": "string",                  "label": "string",                  "value": "string"                }              ]            }          ],          "prompt_audio": true,          "prompt_embedded_context": true,          "prompt_image": true,          "supported_modes": [            "string"          ],          "supports_load_session": true        },        "acp_session_id": "string",        "effective": {          "model": "string",          "provider": "string",          "reasoning_effort": "none",          "speed": "normal",          "speed_resolution": {            "reason": "capability_absent",            "requested": "normal",            "status": "applied"          }        },        "failure": "string",        "selected": {          "model": "string",          "provider": "string",          "reasoning_effort": "none",          "speed": "normal"        },        "selection_revision": 0,        "status": "string",        "transition": "string"      },      "sandbox": {        "backend": "string",        "instance_id": "string",        "last_sync_error": "string",        "profile": "string",        "provider_state_json": null,        "sandbox_id": "string",        "state": "string"      },      "state": "starting",      "stop_detail": "string",      "stop_reason": "completed",      "transcript_epoch": 0,      "type": "user",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string",      "workspace_path": "string",      "worktree_id": "string"    }  }}

Prune materialized Memory v2 session ledger state

POST/api/memory/sessions/prune

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

dry_run?boolean

older_than_hours*integer

Response Body

`application/json`

curl -X POST "https://example.com/api/memory/sessions/prune" \  -H "Content-Type: application/json" \  -d '{    "older_than_hours": 0  }'

{  "dry_run": true,  "pruned_events": 0,  "pruned_sessions": 0}

Repair materialized Memory v2 session ledgers

POST/api/memory/sessions/repair

Response Body

`application/json`

curl -X POST "https://example.com/api/memory/sessions/repair"

{  "completed_at": "2019-08-24T14:15:22Z",  "repaired_ledgers": 0,  "skipped_ledgers": 0}

List sessions

GET/api/sessions

Query Parameters

workspace?string

Workspace id or path

include_health?boolean

Include metadata-only health for returned sessions

state?string

Filter by exact session state

Value in

"starting"
"active"
"stopping"
"stopped"

type?string

Filter by exact session type

Value in

"user"
"system"
"coordinator"
"spawned"

agent?string

Filter by exact agent definition name

parent?string

Filter by exact parent session id

root?string

Filter by exact root session id (includes the root itself)

worktree?string

Filter by exact bound worktree id

q?string

Search session id, name, agent, provider, or channel

resumable?boolean

Only list sessions eligible for explicit attach

attention?boolean

Only list sessions in the needs-you attention class

badge?string

Filter by comma-separated exact session badges

archive?string

Archived session visibility

Value in

"exclude"
"only"
"include"

sort?string

Stable session ordering

Value in

"recent"
"last_activity"
"attention"

cursor?string

Opaque next_cursor from the previous page

limit?integer

Sessions per page (1-100)

Formatint32

Response Body

`application/json`

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_changed_at": "2019-08-24T14:15:22Z",      "available_commands": [        {          "description": "string",          "input": {            "hint": "string"          },          "name": "string"        }      ],      "badge": "string",      "created_at": "2019-08-24T14:15:22Z",      "failure": {        "crash_bundle_path": "string",        "kind": "string",        "summary": "string"      },      "health": {        "active_prompt": true,        "agent_name": "string",        "attachable": true,        "eligible_for_wake": 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",        "session_id": "string",        "state": "idle",        "updated_at": "2019-08-24T14:15:22Z",        "workspace_id": "string"      },      "id": "string",      "lineage": {        "auto_stop_on_parent": true,        "notify_creator": true,        "parent_session_id": "string",        "permission_policy": {          "mcp_servers": [            "string"          ],          "network_channels": [            "string"          ],          "sandbox_profiles": [            "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"      },      "name": "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",          "turn_id": "string"        }      ],      "resolved_network_participation": {        "mode": "local",        "source": "explicit_request",        "version": "network-participation/v1"      },      "runtime": {        "acp_caps": {          "config_options": [            {              "current": "string",              "description": "string",              "id": "string",              "kind": "string",              "label": "string",              "values": [                {                  "description": "string",                  "label": "string",                  "value": "string"                }              ]            }          ],          "prompt_audio": true,          "prompt_embedded_context": true,          "prompt_image": true,          "supported_modes": [            "string"          ],          "supports_load_session": true        },        "acp_session_id": "string",        "effective": {          "model": "string",          "provider": "string",          "reasoning_effort": "none",          "speed": "normal",          "speed_resolution": {            "reason": "capability_absent",            "requested": "normal",            "status": "applied"          }        },        "failure": "string",        "selected": {          "model": "string",          "provider": "string",          "reasoning_effort": "none",          "speed": "normal"        },        "selection_revision": 0,        "status": "string",        "transition": "string"      },      "sandbox": {        "backend": "string",        "instance_id": "string",        "last_sync_error": "string",        "profile": "string",        "provider_state_json": null,        "sandbox_id": "string",        "state": "string"      },      "state": "starting",      "stop_detail": "string",      "stop_reason": "completed",      "transcript_epoch": 0,      "type": "user",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string",      "workspace_path": "string",      "worktree_id": "string"    }  ]}

Create a session

POST/api/sessions

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

agent_name?string

Match^(?:|[a-z][a-z0-9_-]{0,105})$

Lengthlength <= 106

name?string

network_participation?|||

new_worktree?|null

parent_session_id?string

workspace?string

workspace_path?string

worktree?string

Response Body

`application/json`

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_changed_at": "2019-08-24T14:15:22Z",    "available_commands": [      {        "description": "string",        "input": {          "hint": "string"        },        "name": "string"      }    ],    "badge": "string",    "created_at": "2019-08-24T14:15:22Z",    "failure": {      "crash_bundle_path": "string",      "kind": "string",      "summary": "string"    },    "health": {      "active_prompt": true,      "agent_name": "string",      "attachable": true,      "eligible_for_wake": 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",      "session_id": "string",      "state": "idle",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    },    "id": "string",    "lineage": {      "auto_stop_on_parent": true,      "notify_creator": true,      "parent_session_id": "string",      "permission_policy": {        "mcp_servers": [          "string"        ],        "network_channels": [          "string"        ],        "sandbox_profiles": [          "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"    },    "name": "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",        "turn_id": "string"      }    ],    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "runtime": {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "prompt_audio": true,        "prompt_embedded_context": true,        "prompt_image": true,        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "effective": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        }      },      "failure": "string",      "selected": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal"      },      "selection_revision": 0,      "status": "string",      "transition": "string"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "state": "starting",    "stop_detail": "string",    "stop_reason": "completed",    "transcript_epoch": 0,    "type": "user",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string",    "workspace_path": "string",    "worktree_id": "string"  }}

Get exact session attention counts

GET/api/sessions/attention-summary

Response Body

`application/json`

curl -X GET "https://example.com/api/sessions/attention-summary"

{  "by_workspace": [    {      "finished": 0,      "needs_you": 0,      "workspace_id": "string"    }  ],  "finished": 0,  "needs_you": 0}

Stream session catalog changes across workspaces

GET/api/sessions/catalog-stream

Response Body

`text/event-stream`

`application/json`

curl -X GET "https://example.com/api/sessions/catalog-stream"

{  "kind": "string",  "session_id": "string",  "workspace_id": "string"}

Get one session snapshot by id

GET/api/sessions/{session_id}

Path Parameters

session_id*string

Session id

Query Parameters

include_health?boolean

Include metadata-only session health when available

Response Body

`application/json`

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_changed_at": "2019-08-24T14:15:22Z",    "available_commands": [      {        "description": "string",        "input": {          "hint": "string"        },        "name": "string"      }    ],    "badge": "string",    "created_at": "2019-08-24T14:15:22Z",    "failure": {      "crash_bundle_path": "string",      "kind": "string",      "summary": "string"    },    "health": {      "active_prompt": true,      "agent_name": "string",      "attachable": true,      "eligible_for_wake": 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",      "session_id": "string",      "state": "idle",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    },    "id": "string",    "lineage": {      "auto_stop_on_parent": true,      "notify_creator": true,      "parent_session_id": "string",      "permission_policy": {        "mcp_servers": [          "string"        ],        "network_channels": [          "string"        ],        "sandbox_profiles": [          "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"    },    "name": "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",        "turn_id": "string"      }    ],    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "runtime": {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "prompt_audio": true,        "prompt_embedded_context": true,        "prompt_image": true,        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "effective": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        }      },      "failure": "string",      "selected": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal"      },      "selection_revision": 0,      "status": "string",      "transition": "string"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "state": "starting",    "stop_detail": "string",    "stop_reason": "completed",    "transcript_epoch": 0,    "type": "user",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string",    "workspace_path": "string",    "worktree_id": "string"  }}

Get a session workspace owner projection

GET/api/sessions/{session_id}/owner

Path Parameters

session_id*string

Session id

Response Body

`application/json`

curl -X GET "https://example.com/api/sessions/string/owner"

{  "session_id": "string",  "workspace_id": "string",  "workspace_name": "string"}

Get one materialized Memory v2 session ledger

GET/api/workspaces/{workspace_id}/memory/sessions/{session_id}/ledger

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

`application/json`

curl -X GET "https://example.com/api/workspaces/string/memory/sessions/string/ledger"

{  "events": [    {      "emitted_at": "2019-08-24T14:15:22Z",      "event_type": "string",      "payload": {        "property1": null,        "property2": null      },      "sequence": 0    }  ],  "meta": {    "checksum": "string",    "created_at": "2019-08-24T14:15:22Z",    "parent_session_id": "string",    "path": "string",    "root_session_id": "string",    "session_id": "string",    "spawn_depth": 0,    "stopped_at": "2019-08-24T14:15:22Z",    "version": 0,    "workspace_id": "string"  }}

Replay one materialized Memory v2 session ledger

POST/api/workspaces/{workspace_id}/memory/sessions/{session_id}/replay

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

include_memory?boolean

include_tool_events?boolean

Response Body

`application/json`

curl -X POST "https://example.com/api/workspaces/string/memory/sessions/string/replay" \  -H "Content-Type: application/json" \  -d '{}'

{  "events": [    {      "emitted_at": "2019-08-24T14:15:22Z",      "event_type": "string",      "payload": {        "property1": null,        "property2": null      },      "sequence": 0    }  ],  "session_id": "string"}

Get one session snapshot

GET/api/workspaces/{workspace_id}/sessions/{session_id}

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

include_health?boolean

Include metadata-only session health when available

Response Body

`application/json`

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_changed_at": "2019-08-24T14:15:22Z",    "available_commands": [      {        "description": "string",        "input": {          "hint": "string"        },        "name": "string"      }    ],    "badge": "string",    "created_at": "2019-08-24T14:15:22Z",    "failure": {      "crash_bundle_path": "string",      "kind": "string",      "summary": "string"    },    "health": {      "active_prompt": true,      "agent_name": "string",      "attachable": true,      "eligible_for_wake": 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",      "session_id": "string",      "state": "idle",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    },    "id": "string",    "lineage": {      "auto_stop_on_parent": true,      "notify_creator": true,      "parent_session_id": "string",      "permission_policy": {        "mcp_servers": [          "string"        ],        "network_channels": [          "string"        ],        "sandbox_profiles": [          "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"    },    "name": "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",        "turn_id": "string"      }    ],    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "runtime": {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "prompt_audio": true,        "prompt_embedded_context": true,        "prompt_image": true,        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "effective": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        }      },      "failure": "string",      "selected": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal"      },      "selection_revision": 0,      "status": "string",      "transition": "string"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "state": "starting",    "stop_detail": "string",    "stop_reason": "completed",    "transcript_epoch": 0,    "type": "user",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string",    "workspace_path": "string",    "worktree_id": "string"  }}

Rename one user session

PATCH/api/workspaces/{workspace_id}/sessions/{session_id}

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Response Body

`application/json`

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_changed_at": "2019-08-24T14:15:22Z",    "available_commands": [      {        "description": "string",        "input": {          "hint": "string"        },        "name": "string"      }    ],    "badge": "string",    "created_at": "2019-08-24T14:15:22Z",    "failure": {      "crash_bundle_path": "string",      "kind": "string",      "summary": "string"    },    "health": {      "active_prompt": true,      "agent_name": "string",      "attachable": true,      "eligible_for_wake": 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",      "session_id": "string",      "state": "idle",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    },    "id": "string",    "lineage": {      "auto_stop_on_parent": true,      "notify_creator": true,      "parent_session_id": "string",      "permission_policy": {        "mcp_servers": [          "string"        ],        "network_channels": [          "string"        ],        "sandbox_profiles": [          "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"    },    "name": "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",        "turn_id": "string"      }    ],    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "runtime": {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "prompt_audio": true,        "prompt_embedded_context": true,        "prompt_image": true,        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "effective": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        }      },      "failure": "string",      "selected": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal"      },      "selection_revision": 0,      "status": "string",      "transition": "string"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "state": "starting",    "stop_detail": "string",    "stop_reason": "completed",    "transcript_epoch": 0,    "type": "user",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string",    "workspace_path": "string",    "worktree_id": "string"  }}

Delete one session and remove it from persisted history

DELETE/api/workspaces/{workspace_id}/sessions/{session_id}

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

`application/json`

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

Empty

Approve or deny an interactive permission request

POST/api/workspaces/{workspace_id}/sessions/{session_id}/approve

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

decision*string

request_id*string

turn_id*string

Response Body

`application/json`

curl -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"}

Archive a stopped session

POST/api/workspaces/{workspace_id}/sessions/{session_id}/archive

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

`application/json`

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_changed_at": "2019-08-24T14:15:22Z",    "available_commands": [      {        "description": "string",        "input": {          "hint": "string"        },        "name": "string"      }    ],    "badge": "string",    "created_at": "2019-08-24T14:15:22Z",    "failure": {      "crash_bundle_path": "string",      "kind": "string",      "summary": "string"    },    "health": {      "active_prompt": true,      "agent_name": "string",      "attachable": true,      "eligible_for_wake": 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",      "session_id": "string",      "state": "idle",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    },    "id": "string",    "lineage": {      "auto_stop_on_parent": true,      "notify_creator": true,      "parent_session_id": "string",      "permission_policy": {        "mcp_servers": [          "string"        ],        "network_channels": [          "string"        ],        "sandbox_profiles": [          "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"    },    "name": "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",        "turn_id": "string"      }    ],    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "runtime": {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "prompt_audio": true,        "prompt_embedded_context": true,        "prompt_image": true,        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "effective": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        }      },      "failure": "string",      "selected": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal"      },      "selection_revision": 0,      "status": "string",      "transition": "string"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "state": "starting",    "stop_detail": "string",    "stop_reason": "completed",    "transcript_epoch": 0,    "type": "user",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string",    "workspace_path": "string",    "worktree_id": "string"  }}

Attach to a resumable live session

POST/api/workspaces/{workspace_id}/sessions/{session_id}/attach

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

attached_to?string

ttl_seconds?integer

Rangevalue <= 86400

Response Body

`application/json`

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_changed_at": "2019-08-24T14:15:22Z",    "available_commands": [      {        "description": "string",        "input": {          "hint": "string"        },        "name": "string"      }    ],    "badge": "string",    "created_at": "2019-08-24T14:15:22Z",    "failure": {      "crash_bundle_path": "string",      "kind": "string",      "summary": "string"    },    "health": {      "active_prompt": true,      "agent_name": "string",      "attachable": true,      "eligible_for_wake": 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",      "session_id": "string",      "state": "idle",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    },    "id": "string",    "lineage": {      "auto_stop_on_parent": true,      "notify_creator": true,      "parent_session_id": "string",      "permission_policy": {        "mcp_servers": [          "string"        ],        "network_channels": [          "string"        ],        "sandbox_profiles": [          "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"    },    "name": "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",        "turn_id": "string"      }    ],    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "runtime": {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "prompt_audio": true,        "prompt_embedded_context": true,        "prompt_image": true,        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "effective": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        }      },      "failure": "string",      "selected": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal"      },      "selection_revision": 0,      "status": "string",      "transition": "string"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "state": "starting",    "stop_detail": "string",    "stop_reason": "completed",    "transcript_epoch": 0,    "type": "user",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string",    "workspace_path": "string",    "worktree_id": "string"  }}

Upload a session attachment

POST/api/workspaces/{workspace_id}/sessions/{session_id}/attachments

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

multipart/form-data

Multipart upload with one required binary file field

TypeScript Definitions

Use the request body type in TypeScript.

file*string

Response Body

`application/json`

curl -X POST "https://example.com/api/workspaces/string/sessions/string/attachments" \  -F file="string"

{  "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 a session attachment

DELETE/api/workspaces/{workspace_id}/sessions/{session_id}/attachments/{attachment_id}

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

attachment_id*string

Attachment id

Response Body

`application/json`

curl -X DELETE "https://example.com/api/workspaces/string/sessions/string/attachments/string"

Empty

Read session attachment bytes

GET/api/workspaces/{workspace_id}/sessions/{session_id}/attachments/{attachment_id}/bytes

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

attachment_id*string

Attachment id

Response Body

`/`

`application/json`

curl -X GET "https://example.com/api/workspaces/string/sessions/string/attachments/string/bytes"

"string"

List the live pending clarification for a session

GET/api/workspaces/{workspace_id}/sessions/{session_id}/clarifications

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

`application/json`

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"    }  ]}

Answer a live session clarification

POST/api/workspaces/{workspace_id}/sessions/{session_id}/clarifications/{request_id}/answer

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

request_id*string

Clarification request id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

choice_index?integer|null

text?string

Response Body

`application/json`

curl -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"}

Clear conversation history and restart the session context

POST/api/workspaces/{workspace_id}/sessions/{session_id}/clear

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

`application/json`

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_changed_at": "2019-08-24T14:15:22Z",    "available_commands": [      {        "description": "string",        "input": {          "hint": "string"        },        "name": "string"      }    ],    "badge": "string",    "created_at": "2019-08-24T14:15:22Z",    "failure": {      "crash_bundle_path": "string",      "kind": "string",      "summary": "string"    },    "health": {      "active_prompt": true,      "agent_name": "string",      "attachable": true,      "eligible_for_wake": 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",      "session_id": "string",      "state": "idle",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    },    "id": "string",    "lineage": {      "auto_stop_on_parent": true,      "notify_creator": true,      "parent_session_id": "string",      "permission_policy": {        "mcp_servers": [          "string"        ],        "network_channels": [          "string"        ],        "sandbox_profiles": [          "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"    },    "name": "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",        "turn_id": "string"      }    ],    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "runtime": {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "prompt_audio": true,        "prompt_embedded_context": true,        "prompt_image": true,        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "effective": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        }      },      "failure": "string",      "selected": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal"      },      "selection_revision": 0,      "status": "string",      "transition": "string"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "state": "starting",    "stop_detail": "string",    "stop_reason": "completed",    "transcript_epoch": 0,    "type": "user",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string",    "workspace_path": "string",    "worktree_id": "string"  }}

List commands available to a session

GET/api/workspaces/{workspace_id}/sessions/{session_id}/commands

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

`application/json`

curl -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",        "scope": "string"      },      "unavailable_reason": "string"    }  ],  "revision": "string"}

List persisted session events

GET/api/workspaces/{workspace_id}/sessions/{session_id}/events

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

since?string

Only events emitted since this timestamp

Formatdate-time

limit?integer

Maximum number of records to return; defaults to the newest 200 and is capped at 1000

Formatint32

after_sequence?integer

Only return events after this sequence number

Formatint64

type?string

Event type

agent_name?string

Agent name

turn_id?string

Turn id

archive?string

Select active, archived, or all events

Value in

"active"
"archived"
"all"

Response Body

`application/json`

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

Read metadata-only session health and wake eligibility

GET/api/workspaces/{workspace_id}/sessions/{session_id}/health

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

`application/json`

curl -X GET "https://example.com/api/workspaces/string/sessions/string/health"

{  "health": {    "active_prompt": true,    "agent_name": "string",    "attachable": true,    "eligible_for_wake": 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",    "session_id": "string",    "state": "idle",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string"  }}

List grouped session turn history

GET/api/workspaces/{workspace_id}/sessions/{session_id}/history

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

since?string

Only events emitted since this timestamp

Formatdate-time

limit?integer

Maximum number of turns to return; defaults to the newest 200 and is capped at 1000

Formatint32

after_sequence?integer

Only return events after this sequence number

Formatint64

type?string

Event type

agent_name?string

Agent name

turn_id?string

Turn id

archive?string

Select active, archived, or all events

Value in

"active"
"archived"
"all"

Response Body

`application/json`

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

Inspect session health, wake audit, and policy correlation metadata

GET/api/workspaces/{workspace_id}/sessions/{session_id}/inspect

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

include_recent_wake_events?boolean

Include recent wake audit rows

Response Body

`application/json`

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,    "eligible_for_wake": 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",    "session_id": "string",    "state": "idle",    "updated_at": "2019-08-24T14:15:22Z",    "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"  }}

List pending session interactions

GET/api/workspaces/{workspace_id}/sessions/{session_id}/interactions

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

status?string

Filter by interaction status

Value in

"pending"
"orphaned"
"resolved"
"timed_out"
"canceled"

Response Body

`application/json`

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",      "turn_id": "string"    }  ]}

Update operator session presence

POST/api/workspaces/{workspace_id}/sessions/{session_id}/presence

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

lease_id?string

visible*boolean

Response Body

`application/json`

curl -X POST "https://example.com/api/workspaces/string/sessions/string/presence" \  -H "Content-Type: application/json" \  -d '{    "visible": true  }'

{  "lease_id": "string"}

Send, queue, interrupt, or steer a session prompt

POST/api/workspaces/{workspace_id}/sessions/{session_id}/prompt

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

attachments?array<>

expected_turn_id?string

idempotency_key*string

message?string

message_id*string

messages?array<>

mode?string

runtime?|null

Response Body

`application/json`

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",    "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": {          "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",        "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,    "status": "string"  }}

Cancel the active session prompt

POST/api/workspaces/{workspace_id}/sessions/{session_id}/prompt/cancel

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

`application/json`

curl -X POST "https://example.com/api/workspaces/string/sessions/string/prompt/cancel"

{  "outcome": "string",  "session_id": "string",  "turn_id": "string"}

List pending session input

GET/api/workspaces/{workspace_id}/sessions/{session_id}/prompt/queue

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

`application/json`

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",      "message_id": "string",      "mode": "string",      "queue_generation": 0,      "runtime": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal"      },      "session_id": "string",      "skill_invocations": [        {          "command_id": "string",          "end": 0,          "name": "string",          "source": {            "id": "string",            "key": "string",            "kind": "string",            "scope": "string"          },          "start": 0,          "token": "string"        }      ],      "status": "string",      "target_turn_id": "string",      "text": "string"    }  ]}

Cancel a queued session prompt entry

DELETE/api/workspaces/{workspace_id}/sessions/{session_id}/prompt/queue/{queue_entry_id}

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

queue_entry_id*string

Queue entry id

Response Body

`application/json`

curl -X DELETE "https://example.com/api/workspaces/string/sessions/string/prompt/queue/string"

{  "prompt": {    "canceled_queued_entries": 0,    "delivery": "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": {          "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",        "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,    "status": "string"  }}

Replace queued session input atomically

PUT/api/workspaces/{workspace_id}/sessions/{session_id}/prompt/queue/{queue_entry_id}

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

queue_entry_id*string

Queue entry id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

idempotency_key*string

message_id*string

text*string

Response Body

`application/json`

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",    "message_id": "string",    "mode": "string",    "queue_generation": 0,    "runtime": {      "model": "string",      "provider": "string",      "reasoning_effort": "none",      "speed": "normal"    },    "session_id": "string",    "skill_invocations": [      {        "command_id": "string",        "end": 0,        "name": "string",        "source": {          "id": "string",          "key": "string",          "kind": "string",          "scope": "string"        },        "start": 0,        "token": "string"      }    ],    "status": "string",    "target_turn_id": "string",    "text": "string"  }}

Promote queued session input to steering

POST/api/workspaces/{workspace_id}/sessions/{session_id}/prompt/queue/{queue_entry_id}/steer

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

queue_entry_id*string

Queue entry id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

expected_turn_id*string

idempotency_key*string

message_id*string

text*string

Response Body

`application/json`

curl -X POST "https://example.com/api/workspaces/string/sessions/string/prompt/queue/string/steer" \  -H "Content-Type: application/json" \  -d '{    "expected_turn_id": "string",    "idempotency_key": "string",    "message_id": "string",    "text": "string"  }'

{  "prompt": {    "canceled_queued_entries": 0,    "delivery": "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": {          "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",        "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,    "status": "string"  }}

Get a deterministic session recap

GET/api/workspaces/{workspace_id}/sessions/{session_id}/recap

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

limit?integer

Maximum recent messages to include

Formatint32

Response Body

`application/json`

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"      },      "coordination_channel": {        "allowed_message_kinds": [          "status"        ],        "display_name": "string",        "id": "string",        "last_activity_at": "2019-08-24T14:15:22Z",        "purpose": "string",        "run_id": "string",        "task_id": "string",        "workflow_id": "string",        "workspace_id": "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",      "queued_at": "2019-08-24T14:15:22Z",      "recovery_count": 0,      "resolved_network_participation": {        "mode": "local",        "source": "explicit_request",        "version": "network-participation/v1"      },      "resolved_worktree_mode": "none",      "resolved_worktree_ref": "string",      "result": null,      "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,            "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_changed_at": "2019-08-24T14:15:22Z",      "available_commands": [        {          "description": "string",          "input": {            "hint": "string"          },          "name": "string"        }      ],      "badge": "string",      "created_at": "2019-08-24T14:15:22Z",      "failure": {        "crash_bundle_path": "string",        "kind": "string",        "summary": "string"      },      "health": {        "active_prompt": true,        "agent_name": "string",        "attachable": true,        "eligible_for_wake": 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",        "session_id": "string",        "state": "idle",        "updated_at": "2019-08-24T14:15:22Z",        "workspace_id": "string"      },      "id": "string",      "lineage": {        "auto_stop_on_parent": true,        "notify_creator": true,        "parent_session_id": "string",        "permission_policy": {          "mcp_servers": [            "string"          ],          "network_channels": [            "string"          ],          "sandbox_profiles": [            "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"      },      "name": "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",          "turn_id": "string"        }      ],      "resolved_network_participation": {        "mode": "local",        "source": "explicit_request",        "version": "network-participation/v1"      },      "runtime": {        "acp_caps": {          "config_options": [            {              "current": "string",              "description": "string",              "id": "string",              "kind": "string",              "label": "string",              "values": [                {                  "description": "string",                  "label": "string",                  "value": "string"                }              ]            }          ],          "prompt_audio": true,          "prompt_embedded_context": true,          "prompt_image": true,          "supported_modes": [            "string"          ],          "supports_load_session": true        },        "acp_session_id": "string",        "effective": {          "model": "string",          "provider": "string",          "reasoning_effort": "none",          "speed": "normal",          "speed_resolution": {            "reason": "capability_absent",            "requested": "normal",            "status": "applied"          }        },        "failure": "string",        "selected": {          "model": "string",          "provider": "string",          "reasoning_effort": "none",          "speed": "normal"        },        "selection_revision": 0,        "status": "string",        "transition": "string"      },      "sandbox": {        "backend": "string",        "instance_id": "string",        "last_sync_error": "string",        "profile": "string",        "provider_state_json": null,        "sandbox_id": "string",        "state": "string"      },      "state": "starting",      "stop_detail": "string",      "stop_reason": "completed",      "transcript_epoch": 0,      "type": "user",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string",      "workspace_path": "string",      "worktree_id": "string"    },    "snapshot": {      "consistency": "string",      "event_cursor": 0,      "generated_at": "2019-08-24T14:15:22Z",      "queue_generation": 0,      "transcript_cursor": 0    }  }}

Inspect and repair an interrupted session transcript

POST/api/workspaces/{workspace_id}/sessions/{session_id}/repair

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

dry_run?boolean

Report planned repairs without persisting new events

force?boolean

Allow repair for stopped sessions whose stop reason is not crash or error

Response Body

`application/json`

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"  }}

Rewind a conversation before one durable user message

POST/api/workspaces/{workspace_id}/sessions/{session_id}/rewind

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

expected_epoch*|

Formatint64

expected_generation*|

Formatint64

expected_max_sequence*|

Formatint64

idempotency_key*string

message_id*string

Response Body

`application/json`

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_changed_at": "2019-08-24T14:15:22Z",    "available_commands": [      {        "description": "string",        "input": {          "hint": "string"        },        "name": "string"      }    ],    "badge": "string",    "created_at": "2019-08-24T14:15:22Z",    "failure": {      "crash_bundle_path": "string",      "kind": "string",      "summary": "string"    },    "health": {      "active_prompt": true,      "agent_name": "string",      "attachable": true,      "eligible_for_wake": 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",      "session_id": "string",      "state": "idle",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    },    "id": "string",    "lineage": {      "auto_stop_on_parent": true,      "notify_creator": true,      "parent_session_id": "string",      "permission_policy": {        "mcp_servers": [          "string"        ],        "network_channels": [          "string"        ],        "sandbox_profiles": [          "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"    },    "name": "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",        "turn_id": "string"      }    ],    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "runtime": {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "prompt_audio": true,        "prompt_embedded_context": true,        "prompt_image": true,        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "effective": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        }      },      "failure": "string",      "selected": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal"      },      "selection_revision": 0,      "status": "string",      "transition": "string"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "state": "starting",    "stop_detail": "string",    "stop_reason": "completed",    "transcript_epoch": 0,    "type": "user",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string",    "workspace_path": "string",    "worktree_id": "string"  }}

Clear the default runtime for future prompts

DELETE/api/workspaces/{workspace_id}/sessions/{session_id}/runtime

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

expected_revision*integer

Current runtime selection revision

Formatint64

Response Body

`application/json`

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_changed_at": "2019-08-24T14:15:22Z",    "available_commands": [      {        "description": "string",        "input": {          "hint": "string"        },        "name": "string"      }    ],    "badge": "string",    "created_at": "2019-08-24T14:15:22Z",    "failure": {      "crash_bundle_path": "string",      "kind": "string",      "summary": "string"    },    "health": {      "active_prompt": true,      "agent_name": "string",      "attachable": true,      "eligible_for_wake": 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",      "session_id": "string",      "state": "idle",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    },    "id": "string",    "lineage": {      "auto_stop_on_parent": true,      "notify_creator": true,      "parent_session_id": "string",      "permission_policy": {        "mcp_servers": [          "string"        ],        "network_channels": [          "string"        ],        "sandbox_profiles": [          "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"    },    "name": "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",        "turn_id": "string"      }    ],    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "runtime": {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "prompt_audio": true,        "prompt_embedded_context": true,        "prompt_image": true,        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "effective": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        }      },      "failure": "string",      "selected": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal"      },      "selection_revision": 0,      "status": "string",      "transition": "string"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "state": "starting",    "stop_detail": "string",    "stop_reason": "completed",    "transcript_epoch": 0,    "type": "user",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string",    "workspace_path": "string",    "worktree_id": "string"  }}

Select the default runtime for future prompts

PUT/api/workspaces/{workspace_id}/sessions/{session_id}/runtime

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

expected_revision*|

Formatint64

runtime*

Response Body

`application/json`

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_changed_at": "2019-08-24T14:15:22Z",    "available_commands": [      {        "description": "string",        "input": {          "hint": "string"        },        "name": "string"      }    ],    "badge": "string",    "created_at": "2019-08-24T14:15:22Z",    "failure": {      "crash_bundle_path": "string",      "kind": "string",      "summary": "string"    },    "health": {      "active_prompt": true,      "agent_name": "string",      "attachable": true,      "eligible_for_wake": 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",      "session_id": "string",      "state": "idle",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    },    "id": "string",    "lineage": {      "auto_stop_on_parent": true,      "notify_creator": true,      "parent_session_id": "string",      "permission_policy": {        "mcp_servers": [          "string"        ],        "network_channels": [          "string"        ],        "sandbox_profiles": [          "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"    },    "name": "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",        "turn_id": "string"      }    ],    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "runtime": {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "prompt_audio": true,        "prompt_embedded_context": true,        "prompt_image": true,        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "effective": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        }      },      "failure": "string",      "selected": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal"      },      "selection_revision": 0,      "status": "string",      "transition": "string"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "state": "starting",    "stop_detail": "string",    "stop_reason": "completed",    "transcript_epoch": 0,    "type": "user",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string",    "workspace_path": "string",    "worktree_id": "string"  }}

Refresh an idle session's Soul snapshot through body-level CAS

POST/api/workspaces/{workspace_id}/sessions/{session_id}/soul/refresh

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

expected_digest*string

idempotency_key?string

Response Body

`application/json`

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"    ],    "memory_policy": [      "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"}

Read compact session status and wake eligibility

GET/api/workspaces/{workspace_id}/sessions/{session_id}/status

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

`application/json`

curl -X GET "https://example.com/api/workspaces/string/sessions/string/status"

{  "active_prompt": true,  "agent_name": "string",  "attachable": true,  "badge": "string",  "eligible_for_wake": true,  "health": "healthy",  "ineligibility_reason": "session_prompt_active",  "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",      "turn_id": "string"    }  ],  "session_id": "string",  "state": "idle",  "updated_at": "2019-08-24T14:15:22Z",  "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"}

Stage steering input for the active session turn

POST/api/workspaces/{workspace_id}/sessions/{session_id}/steer

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

expected_turn_id*string

idempotency_key*string

message_id*string

text*string

Response Body

`application/json`

curl -X POST "https://example.com/api/workspaces/string/sessions/string/steer" \  -H "Content-Type: application/json" \  -d '{    "expected_turn_id": "string",    "idempotency_key": "string",    "message_id": "string",    "text": "string"  }'

{  "prompt": {    "canceled_queued_entries": 0,    "delivery": "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": {          "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",        "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,    "status": "string"  }}

Stop a session without deleting persisted history

POST/api/workspaces/{workspace_id}/sessions/{session_id}/stop

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

`application/json`

curl -X POST "https://example.com/api/workspaces/string/sessions/string/stop"

Empty

Stream raw session events or fenced transcript changes

GET/api/workspaces/{workspace_id}/sessions/{session_id}/stream

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

after_sequence?integer

Initial cursor when Last-Event-ID is not supplied

Formatint64

frames?string

Frame mode; transcript is the default and raw preserves persisted event frames

Value in

"raw"
"transcript"

epoch?integer

Expected transcript epoch for a fenced reconnect

Formatint64

generation?integer

Expected materialized projection generation for a fenced reconnect

Formatint64

limit?integer

Maximum entries per transcript snapshot or change batch

Formatint32

Header Parameters

Last-Event-ID?string

Resume after the last applied SSE cursor; transcript reconnects also require epoch and generation

Response Body

`text/event-stream`

`application/json`

curl -X GET "https://example.com/api/workspaces/string/sessions/string/stream"

{  "goal_snapshot_changed": {    "bound_session_id": "string",    "cause": "start",    "revision": 0,    "run_id": "string",    "session_id": "string"  },  "raw": {    "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",      "summary": "string"    },    "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",    "parent_session_id": "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"  },  "session_commands_changed": {    "revision": "string",    "session_id": "string"  },  "session_stopped": {    "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",      "summary": "string"    },    "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",    "parent_session_id": "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"  },  "transcript_delta": {    "cursor": 0,    "entries": [      {        "message": {          "id": "string",          "metadata": null,          "parts": [            {              "data": null,              "errorText": "string",              "filename": "string",              "id": "string",              "input": null,              "mediaType": "string",              "output": null,              "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_more": true,    "max_sequence": 0,    "session_id": "string",    "workspace_id": "string",    "workspace_path": "string"  },  "transcript_snapshot": {    "entries": [      {        "message": {          "id": "string",          "metadata": null,          "parts": [            {              "data": null,              "errorText": "string",              "filename": "string",              "id": "string",              "input": null,              "mediaType": "string",              "output": null,              "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,    "max_sequence": 0,    "next_before_sequence": 0,    "reason": "string",    "reset": true,    "session_id": "string",    "workspace_id": "string",    "workspace_path": "string"  }}

List session-callable registry tools

GET/api/workspaces/{workspace_id}/sessions/{session_id}/tools

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

agent_name?string

Effective agent name

Response Body

`application/json`

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"      }    }  ]}

Search session-callable registry tools

POST/api/workspaces/{workspace_id}/sessions/{session_id}/tools/search

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

agent_name?string

limit?integer

query*string

session_id?string

workspace_id?string

Response Body

`application/json`

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"      }    }  ]}

Get a bounded materialized transcript page

GET/api/workspaces/{workspace_id}/sessions/{session_id}/transcript

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Query Parameters

limit?integer

Maximum page size; defaults to the newest 200 entries and is capped at 1000

Formatint32

before_sequence?integer

Return entries whose stable start sequence is before this cursor

Formatint64

Response Body

`application/json`

curl -X GET "https://example.com/api/workspaces/string/sessions/string/transcript"

{  "entries": [    {      "message": {        "id": "string",        "metadata": null,        "parts": [          {            "data": null,            "errorText": "string",            "filename": "string",            "id": "string",            "input": null,            "mediaType": "string",            "output": null,            "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}

Restore an archived session

POST/api/workspaces/{workspace_id}/sessions/{session_id}/unarchive

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

`application/json`

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_changed_at": "2019-08-24T14:15:22Z",    "available_commands": [      {        "description": "string",        "input": {          "hint": "string"        },        "name": "string"      }    ],    "badge": "string",    "created_at": "2019-08-24T14:15:22Z",    "failure": {      "crash_bundle_path": "string",      "kind": "string",      "summary": "string"    },    "health": {      "active_prompt": true,      "agent_name": "string",      "attachable": true,      "eligible_for_wake": 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",      "session_id": "string",      "state": "idle",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    },    "id": "string",    "lineage": {      "auto_stop_on_parent": true,      "notify_creator": true,      "parent_session_id": "string",      "permission_policy": {        "mcp_servers": [          "string"        ],        "network_channels": [          "string"        ],        "sandbox_profiles": [          "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"    },    "name": "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",        "turn_id": "string"      }    ],    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "runtime": {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "prompt_audio": true,        "prompt_embedded_context": true,        "prompt_image": true,        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "effective": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        }      },      "failure": "string",      "selected": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal"      },      "selection_revision": 0,      "status": "string",      "transition": "string"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "state": "starting",    "stop_detail": "string",    "stop_reason": "completed",    "transcript_epoch": 0,    "type": "user",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string",    "workspace_path": "string",    "worktree_id": "string"  }}

Get aggregated token usage for a session

GET/api/workspaces/{workspace_id}/sessions/{session_id}/usage

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

`application/json`

curl -X GET "https://example.com/api/workspaces/string/sessions/string/usage"

{  "usage": {    "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  }}

Wait for a session state

POST/api/workspaces/{workspace_id}/sessions/{session_id}/wait

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

epoch?integer

Formatint64

resume_id?string

timeout_ms*integer

Formatint64

until?array<string>

Response Body

`application/json`

curl -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}

Fork a live session into a worktree

POST/api/workspaces/{workspace_id}/sessions/{session_id}/worktree-fork

Path Parameters

workspace_id*string

Workspace id

session_id*string

Origin session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

confirmed*boolean

new_worktree?|null

worktree?string

Response Body

`application/json`

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_changed_at": "2019-08-24T14:15:22Z",    "available_commands": [      {        "description": "string",        "input": {          "hint": "string"        },        "name": "string"      }    ],    "badge": "string",    "created_at": "2019-08-24T14:15:22Z",    "failure": {      "crash_bundle_path": "string",      "kind": "string",      "summary": "string"    },    "health": {      "active_prompt": true,      "agent_name": "string",      "attachable": true,      "eligible_for_wake": 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",      "session_id": "string",      "state": "idle",      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    },    "id": "string",    "lineage": {      "auto_stop_on_parent": true,      "notify_creator": true,      "parent_session_id": "string",      "permission_policy": {        "mcp_servers": [          "string"        ],        "network_channels": [          "string"        ],        "sandbox_profiles": [          "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"    },    "name": "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",        "turn_id": "string"      }    ],    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "runtime": {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "prompt_audio": true,        "prompt_embedded_context": true,        "prompt_image": true,        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "effective": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal",        "speed_resolution": {          "reason": "capability_absent",          "requested": "normal",          "status": "applied"        }      },      "failure": "string",      "selected": {        "model": "string",        "provider": "string",        "reasoning_effort": "none",        "speed": "normal"      },      "selection_revision": 0,      "status": "string",      "transition": "string"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "state": "starting",    "stop_detail": "string",    "stop_reason": "completed",    "transcript_epoch": 0,    "type": "user",    "updated_at": "2019-08-24T14:15:22Z",    "workspace_id": "string",    "workspace_path": "string",    "worktree_id": "string"  }}

201application/json

401application/json

403application/json

409application/json

422application/json

500application/json

503application/json

200application/json

400application/json

500application/json

200application/json

500application/json

200application/json

400application/json

404application/json

410application/json

500application/json

503application/json

201application/json

400application/json

404application/json

409application/json

500application/json

503application/json

200application/json

403application/json

500application/json

503application/json

200text/event-stream

500application/json

503application/json

200application/json

404application/json

500application/json

200application/json

404application/json

500application/json

200application/json

404application/json

500application/json

200application/json

400application/json

404application/json

500application/json

200application/json

404application/json

500application/json

200application/json

400application/json

404application/json

500application/json

503application/json

204

404application/json

500application/json

200application/json

400application/json

404application/json

500application/json

200application/json

404application/json

409application/json

500application/json

503application/json

200application/json

400application/json

404application/json

409application/json

500application/json

503application/json

201application/json

400application/json

404application/json

413application/json

415application/json

500application/json

503application/json

204

400application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`text/event-stream`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`