# Sessions Commands > See [Sessions module docs](../../modules/sessions) for permissions and data model. # Sessions Commands See [Sessions module docs](../../modules/sessions) for permissions and data model. ### `soat create-session` Create a session - Method: `POST` - Path: `/api/v1/sessions` #### Usage ```bash soat create-session --agent-id ``` #### Options ##### `--agent-id` Agent this session belongs to - Source: `body` - Required: yes - Type: `string` - Example: `agent_V1StGXR8Z5jdHi6B` ##### `--name` Optional session name - Source: `body` - Required: no - Type: `string` - Example: `Support chat` ##### `--actor-id` Optional public ID of an existing actor to use as the user actor. Actors are created separately (POST /actors); this field only links one. Omit it and the session has no end user, so its generations match no actor-scoped quota. - Source: `body` - Required: no - Type: `string` - Example: `actor_V1StGXR8Z5jdHi6B` ##### `--auto-generate` When true, automatically triggers generation after each user message. - Source: `body` - Required: no - Type: `boolean` - Default: `false` ##### `--tool-context` Key-value pairs forwarded as `X-Soat-Context-` headers on every `http`, `mcp` and `builtin` tool call in this session. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with `400 INVALID_TOOL_CONTEXT_KEY`. - Source: `body` - Required: no - Type: `object` ##### `--inactivity-ttl-seconds` Number of seconds of inactivity after which the session expires. 0 means the session never expires. - Source: `body` - Required: no - Type: `integer` - Default: `0` - Example: `300` ##### `--message-delay-seconds` Number of seconds to wait after the last user message before sending to the LLM. Acts as a debounce: each new message resets the timer. null or absent means no delay (immediate processing). - Source: `body` - Required: no - Type: `integer \| null` - Default: `null` - Example: `3` ### `soat list-sessions` List sessions - Method: `GET` - Path: `/api/v1/sessions` #### Usage ```bash soat list-sessions ``` #### Options ##### `--agent-id` Filter by agent public ID - Source: `query` - Required: no - Type: `string` - Example: `agent_V1StGXR8Z5jdHi6B` ##### `--actor-id` Filter by actor public ID - Source: `query` - Required: no - Type: `string` ##### `--status` Filter by session status (open, closed, or expired) - Source: `query` - Required: no - Type: `enum("open", "closed", "expired")` ##### `--limit` — - Source: `query` - Required: no - Type: `integer` - Default: `50` ##### `--offset` — - Source: `query` - Required: no - Type: `integer` - Default: `0` ### `soat get-session` Get a session - Method: `GET` - Path: `/api/v1/sessions/{session_id}` #### Usage ```bash soat get-session ``` #### Options This command has no options. ### `soat update-session` Update a session - Method: `PATCH` - Path: `/api/v1/sessions/{session_id}` #### Usage ```bash soat update-session ``` #### Options ##### `--name` Session name (set to null to clear) - Source: `body` - Required: no - Type: `string \| null` ##### `--status` Session status - Source: `body` - Required: no - Type: `enum("open", "closed", "expired")` ##### `--auto-generate` Enable or disable automatic generation after user messages. - Source: `body` - Required: no - Type: `boolean` ##### `--tool-context` Key-value pairs forwarded as `X-Soat-Context-` headers on every `http`, `mcp` and `builtin` tool call in this session. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with `400 INVALID_TOOL_CONTEXT_KEY`. - Source: `body` - Required: no - Type: `object` ##### `--inactivity-ttl-seconds` Number of seconds of inactivity after which the session expires. 0 means the session never expires. Updates the stored TTL; the inactivity clock continues from the last activity timestamp. - Source: `body` - Required: no - Type: `integer` - Example: `300` ##### `--message-delay-seconds` Number of seconds to wait after the last user message before sending to the LLM. Acts as a debounce: each new message resets the timer. Set to null to disable the delay. - Source: `body` - Required: no - Type: `integer \| null` - Example: `3` ### `soat delete-session` Delete a session - Method: `DELETE` - Path: `/api/v1/sessions/{session_id}` #### Usage ```bash soat delete-session ``` #### Options This command has no options. ### `soat add-session-message` Add a user message - Method: `POST` - Path: `/api/v1/sessions/{session_id}/messages` #### Usage ```bash soat add-session-message ``` #### Options This command has no options. ### `soat generate-session-response` Trigger agent generation - Method: `POST` - Path: `/api/v1/sessions/{session_id}/generate` #### Usage ```bash soat generate-session-response ``` #### Options ##### `--wait` When omitted or `false` (default), generation runs in the background and `202 Accepted` is returned immediately. Pass `true` to block until the generation settles and receive the result. - Source: `query` - Required: no - Type: `boolean` - Default: `false` ##### `--model` Optional model override - Source: `body` - Required: no - Type: `string` - Example: `gpt-4o` ##### `--tool-context` Key-value pairs forwarded as `X-Soat-Context-` headers on every `http`, `mcp` and `builtin` tool call in this generation. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. An invalid or colliding key is rejected with `400 INVALID_TOOL_CONTEXT_KEY`. - Source: `body` - Required: no - Type: `object` ### `soat submit-session-tool-outputs` Submit tool outputs - Method: `POST` - Path: `/api/v1/sessions/{session_id}/tool-outputs` #### Usage ```bash soat submit-session-tool-outputs --generation-id --tool-outputs > ``` #### Options ##### `--generation-id` The generation ID from the requires_action response - Source: `body` - Required: yes - Type: `string` ##### `--tool-outputs` — - Source: `body` - Required: yes - Type: `array` ### `soat fork-session` Fork a session - Method: `POST` - Path: `/api/v1/sessions/{session_id}/fork` #### Usage ```bash soat fork-session ``` #### Options ##### `--fork-at-position` The parent conversation `position` to branch after. Messages at positions 0..N are carried into the fork. Omit it to branch at the tip (the whole history). - Source: `body` - Required: no - Type: `integer` - Example: `7` ##### `--agent-id` Agent the fork runs against. Defaults to the parent session's agent; overriding it is the point of forking — same context, a different agent or agent version. Must belong to the same project as the session being forked. - Source: `body` - Required: no - Type: `string` - Example: `agent_V1StGXR8Z5jdHi6B` ##### `--name` Optional name for the forked session - Source: `body` - Required: no - Type: `string` - Example: `retry with stricter system prompt` ##### `--tags` Optional tags for the forked session - Source: `body` - Required: no - Type: `object` ##### `--tool-context` Overrides the parent's `tool_context` on the fork. Omit it and the fork inherits the parent's, so the branch is faithful to the run it came from. - Source: `body` - Required: no - Type: `object` ### `soat list-session-forks` List a session's forks - Method: `GET` - Path: `/api/v1/sessions/{session_id}/forks` #### Usage ```bash soat list-session-forks ``` #### Options ##### `--limit` — - Source: `query` - Required: no - Type: `integer` - Default: `50` ##### `--offset` — - Source: `query` - Required: no - Type: `integer` - Default: `0` ### `soat get-session-tags` Get session tags - Method: `GET` - Path: `/api/v1/sessions/{session_id}/tags` #### Usage ```bash soat get-session-tags ``` #### Options This command has no options. ### `soat replace-session-tags` Replace session tags - Method: `PUT` - Path: `/api/v1/sessions/{session_id}/tags` #### Usage ```bash soat replace-session-tags ``` #### Options This command has no options. ### `soat merge-session-tags` Merge session tags - Method: `PATCH` - Path: `/api/v1/sessions/{session_id}/tags` #### Usage ```bash soat merge-session-tags ``` #### Options This command has no options.