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

auto_stop_on_parent*boolean

idempotency_key?string

model?string

name?string

permissions*

prompt_overlay?string

provider?string

spawn_role*string

speed?string

Value in

"normal"
"fast"

ttl_seconds*integer

Formatint64

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,      "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": {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "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",      "attach_expires_at": "2019-08-24T14:15:22Z",      "attachable": true,      "attached_to": "string",      "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,        "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"      },      "model": "string",      "name": "string",      "provider": "string",      "reasoning_effort": "none",      "resolved_network_participation": {        "mode": "local",        "source": "explicit_request",        "version": "network-participation/v1"      },      "sandbox": {        "backend": "string",        "instance_id": "string",        "last_sync_error": "string",        "profile": "string",        "provider_state_json": null,        "sandbox_id": "string",        "state": "string"      },      "speed": "normal",      "speed_resolution": {        "reason": "capability_absent",        "requested": "normal",        "status": "applied"      },      "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"    }  }}

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

q?string

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

resumable?boolean

Only list sessions eligible for explicit attach

sort?string

Stable session ordering

Value in

"recent"
"last_activity"

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": [    {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "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",      "attach_expires_at": "2019-08-24T14:15:22Z",      "attachable": true,      "attached_to": "string",      "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,        "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"      },      "model": "string",      "name": "string",      "provider": "string",      "reasoning_effort": "none",      "resolved_network_participation": {        "mode": "local",        "source": "explicit_request",        "version": "network-participation/v1"      },      "sandbox": {        "backend": "string",        "instance_id": "string",        "last_sync_error": "string",        "profile": "string",        "provider_state_json": null,        "sandbox_id": "string",        "state": "string"      },      "speed": "normal",      "speed_resolution": {        "reason": "capability_absent",        "requested": "normal",        "status": "applied"      },      "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"    }  ]}

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

model?string

name?string

network_participation?|||

prompt?string

provider?string

reasoning_effort?string

Value in

"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"

speed?string

Value in

"normal"
"fast"

workspace?string

workspace_path?string

Response Body

`application/json`

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

{  "session": {    "acp_caps": {      "config_options": [        {          "current": "string",          "description": "string",          "id": "string",          "kind": "string",          "label": "string",          "values": [            {              "description": "string",              "label": "string",              "value": "string"            }          ]        }      ],      "supported_modes": [        "string"      ],      "supports_load_session": true    },    "acp_session_id": "string",    "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",    "attach_expires_at": "2019-08-24T14:15:22Z",    "attachable": true,    "attached_to": "string",    "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,      "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"    },    "model": "string",    "name": "string",    "provider": "string",    "reasoning_effort": "none",    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "speed": "normal",    "speed_resolution": {      "reason": "capability_absent",      "requested": "normal",      "status": "applied"    },    "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"  }}

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": {    "acp_caps": {      "config_options": [        {          "current": "string",          "description": "string",          "id": "string",          "kind": "string",          "label": "string",          "values": [            {              "description": "string",              "label": "string",              "value": "string"            }          ]        }      ],      "supported_modes": [        "string"      ],      "supports_load_session": true    },    "acp_session_id": "string",    "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",    "attach_expires_at": "2019-08-24T14:15:22Z",    "attachable": true,    "attached_to": "string",    "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,      "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"    },    "model": "string",    "name": "string",    "provider": "string",    "reasoning_effort": "none",    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "speed": "normal",    "speed_resolution": {      "reason": "capability_absent",      "requested": "normal",      "status": "applied"    },    "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"  }}

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": {    "acp_caps": {      "config_options": [        {          "current": "string",          "description": "string",          "id": "string",          "kind": "string",          "label": "string",          "values": [            {              "description": "string",              "label": "string",              "value": "string"            }          ]        }      ],      "supported_modes": [        "string"      ],      "supports_load_session": true    },    "acp_session_id": "string",    "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",    "attach_expires_at": "2019-08-24T14:15:22Z",    "attachable": true,    "attached_to": "string",    "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,      "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"    },    "model": "string",    "name": "string",    "provider": "string",    "reasoning_effort": "none",    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "speed": "normal",    "speed_resolution": {      "reason": "capability_absent",      "requested": "normal",      "status": "applied"    },    "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"  }}

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

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

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": {    "acp_caps": {      "config_options": [        {          "current": "string",          "description": "string",          "id": "string",          "kind": "string",          "label": "string",          "values": [            {              "description": "string",              "label": "string",              "value": "string"            }          ]        }      ],      "supported_modes": [        "string"      ],      "supports_load_session": true    },    "acp_session_id": "string",    "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",    "attach_expires_at": "2019-08-24T14:15:22Z",    "attachable": true,    "attached_to": "string",    "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,      "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"    },    "model": "string",    "name": "string",    "provider": "string",    "reasoning_effort": "none",    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "speed": "normal",    "speed_resolution": {      "reason": "capability_absent",      "requested": "normal",      "status": "applied"    },    "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"  }}

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": {    "acp_caps": {      "config_options": [        {          "current": "string",          "description": "string",          "id": "string",          "kind": "string",          "label": "string",          "values": [            {              "description": "string",              "label": "string",              "value": "string"            }          ]        }      ],      "supported_modes": [        "string"      ],      "supports_load_session": true    },    "acp_session_id": "string",    "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",    "attach_expires_at": "2019-08-24T14:15:22Z",    "attachable": true,    "attached_to": "string",    "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,      "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"    },    "model": "string",    "name": "string",    "provider": "string",    "reasoning_effort": "none",    "resolved_network_participation": {      "mode": "local",      "source": "explicit_request",      "version": "network-participation/v1"    },    "sandbox": {      "backend": "string",      "instance_id": "string",      "last_sync_error": "string",      "profile": "string",      "provider_state_json": null,      "sandbox_id": "string",      "state": "string"    },    "speed": "normal",    "speed_resolution": {      "reason": "capability_absent",      "requested": "normal",      "status": "applied"    },    "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"  }}

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

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

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

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

Interrupt the active prompt turn for a session

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

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/interrupt"

{  "prompt": {    "canceled_queued_entries": 0,    "estimated_send_at": "2019-08-24T14:15:22Z",    "fallback_mode_if_no_tool_result": "string",    "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      }    },    "interrupted": true,    "mode": "string",    "new_turn_id": "string",    "previous_turn_id": "string",    "queue_entry_id": "string",    "queue_generation": 0,    "queue_position": 0,    "queued": true,    "staged": true,    "status": "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.

message?string

messageId?string

messages?array<>

mode?string

Response Body

`application/json`

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

{  "prompt": {    "canceled_queued_entries": 0,    "estimated_send_at": "2019-08-24T14:15:22Z",    "fallback_mode_if_no_tool_result": "string",    "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      }    },    "interrupted": true,    "mode": "string",    "new_turn_id": "string",    "previous_turn_id": "string",    "queue_entry_id": "string",    "queue_generation": 0,    "queue_position": 0,    "queued": true,    "staged": true,    "status": "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,    "estimated_send_at": "2019-08-24T14:15:22Z",    "fallback_mode_if_no_tool_result": "string",    "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      }    },    "interrupted": true,    "mode": "string",    "new_turn_id": "string",    "previous_turn_id": "string",    "queue_entry_id": "string",    "queue_generation": 0,    "queue_position": 0,    "queued": true,    "staged": 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"      },      "result": null,      "session_id": "string",      "started_at": "2019-08-24T14:15:22Z",      "status": "queued",      "task_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",            "id": "string",            "input": null,            "output": null,            "preliminary": true,            "rawInput": null,            "state": "string",            "text": "string",            "title": "string",            "toolCallId": "string",            "toolName": "string",            "type": "string"          }        ],        "role": "string"      }    ],    "session": {      "acp_caps": {        "config_options": [          {            "current": "string",            "description": "string",            "id": "string",            "kind": "string",            "label": "string",            "values": [              {                "description": "string",                "label": "string",                "value": "string"              }            ]          }        ],        "supported_modes": [          "string"        ],        "supports_load_session": true      },      "acp_session_id": "string",      "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",      "attach_expires_at": "2019-08-24T14:15:22Z",      "attachable": true,      "attached_to": "string",      "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,        "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"      },      "model": "string",      "name": "string",      "provider": "string",      "reasoning_effort": "none",      "resolved_network_participation": {        "mode": "local",        "source": "explicit_request",        "version": "network-participation/v1"      },      "sandbox": {        "backend": "string",        "instance_id": "string",        "last_sync_error": "string",        "profile": "string",        "provider_state_json": null,        "sandbox_id": "string",        "state": "string"      },      "speed": "normal",      "speed_resolution": {        "reason": "capability_absent",        "requested": "normal",        "status": "applied"      },      "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"    },    "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"  }}

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,  "eligible_for_wake": true,  "health": "healthy",  "ineligibility_reason": "session_prompt_active",  "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.

text*string

Response Body

`application/json`

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

{  "prompt": {    "canceled_queued_entries": 0,    "estimated_send_at": "2019-08-24T14:15:22Z",    "fallback_mode_if_no_tool_result": "string",    "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      }    },    "interrupted": true,    "mode": "string",    "new_turn_id": "string",    "previous_turn_id": "string",    "queue_entry_id": "string",    "queue_generation": 0,    "queue_position": 0,    "queued": true,    "staged": 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"  },  "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"  },  "transcript_delta": {    "cursor": 0,    "entries": [      {        "message": {          "id": "string",          "metadata": null,          "parts": [            {              "data": null,              "errorText": "string",              "id": "string",              "input": null,              "output": null,              "preliminary": true,              "rawInput": null,              "state": "string",              "text": "string",              "title": "string",              "toolCallId": "string",              "toolName": "string",              "type": "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",              "id": "string",              "input": null,              "output": null,              "preliminary": true,              "rawInput": null,              "state": "string",              "text": "string",              "title": "string",              "toolCallId": "string",              "toolName": "string",              "type": "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",            "id": "string",            "input": null,            "output": null,            "preliminary": true,            "rawInput": null,            "state": "string",            "text": "string",            "title": "string",            "toolCallId": "string",            "toolName": "string",            "type": "string"          }        ],        "role": "string"      },      "sequence": 0,      "start_sequence": 0    }  ],  "epoch": 0,  "generation": 0,  "has_older": true,  "limit": 0,  "max_sequence": 0,  "next_before_sequence": 0}

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

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

200text/event-stream

500application/json

503application/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

204

404application/json

500application/json

200application/json

400application/json

404application/json

500application/json

200application/json

404application/json

409application/json

500application/json

200application/json

404application/json

503application/json

200application/json

400application/json

404application/json

409application/json

503application/json

200application/json

404application/json

409application/json

500application/json

503application/json

200application/json

400application/json

404application/json

500application/json

200application/json

403application/json

404application/json

500application/json

200application/json

400application/json

404application/json

500application/json

200application/json

403application/json

404application/json

500application/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`

`application/json`

`application/json`

`application/json`