Session data structures

Session object

Returned by create, get, list, update, and archive endpoints.

Field	Type	Description
`id`	string	Session ID with the `sess_` prefix
`type`	string	Always `"session"`
`agent`	Agent object	Agent snapshot captured when the session was created
`agent_id`	string	Agent ID used by this session
`environment_id`	string	Environment ID used by this session
`status`	string	Session lifecycle status, such as `idle`, `running`, or `terminated`
`turn_status`	string	Current turn status. Defaults to `idle` when empty
`title`	string	Session title
`metadata`	object	Metadata object
`resources`	array of Session resource	Files or repositories attached to the session. Defaults to `[]`
`vault_ids`	array of string	Vault IDs attached to the session. Defaults to `[]`
`memory_store_ids`	array of string	Memory Store IDs attached to the session. Defaults to `[]`
`stats`	Session stats	Session statistics
`archived_at`	string \| null	Archive time, or `null` when not archived
`created_at`	string	Creation time
`updated_at`	string	Last update time

agent in create requests can be either a string Agent ID or this object:

Field	Type	Required	Description
`id`	string	Yes	Agent ID with the `agent_` prefix
`type`	string	No	Optional marker
`version`	integer	No	Agent version to snapshot. Omit or pass `0` to use the latest active version

environment in create requests can be an Environment ID string or this object.

Field	Type	Required	Description
`name`	string	No	Environment name. Defaults to `"Session Environment"` when omitted or blank
`description`	string	No	Environment description
`config`	Environment config	Yes	Environment configuration
`metadata`	object	No	Metadata object

resources[] is a union distinguished by type.

Field	Type	Required	Description
`type`	string	No	`"file"`. Defaults to `"file"` when omitted
`file_id`	string	Yes	File ID with the `file_` prefix. The file must be in `ready` status
`path`	string	No	Mount path in the container. Defaults to `/data/{file_id}`. Relative values are prefixed with `/data/`; the normalized path must stay under `/data/` and be at most 512 characters
`mount_path`	string	No	Request alias for `path`. If both are provided, they must be identical. Responses store the normalized value as `path`

Field	Type	Required	Description
`type`	string	Yes	`"github_repository"`
`url`	string	Yes	Repository URL
`mount_path`	string	No	Clone target path in the container
`authorization_token`	string	No	Token for private repository access

Field	Type	Description
`active_seconds`	number	Active processing time in seconds. New sessions start at `0`
`duration_seconds`	number	Session duration in seconds. New sessions start at `0`

Events returned by the send-event, list-events, and stream endpoints are event-specific JSON objects with these common fields.

Field	Type	Description
`id`	string	Event ID with the `evt_` prefix
`type`	string	Event type
`schema_version`	string	Event schema version, currently `"1.0"` for CAS-created user events
`session_id`	string	Owning Session ID
`turn_id`	string	Present when the event belongs to a turn
`created_at`	string	Creation time
`processed_at`	string \| null	Processing time

Type	Required fields	Notes
`user.message`	`content`	Starts a new turn. `content` can be a string or an array of content blocks
`user.interrupt`	none	Requests interruption/cancellation
`user.tool_confirmation`	`tool_use_id`, `result`	`result` must be `allow` or `deny`; `deny_message` is optional
`user.custom_tool_result`	`custom_tool_use_id`	`content` is optional and is stored as text content blocks
`user.define_outcome`	none enforced	Additional fields are preserved

Run an agent against an environment as a stateful conversation.