Skip to main content

Sessions Commands

See Sessions module docs for permissions and data model.

soat create-session​

Create a session

  • Method: POST
  • Path: /api/v1/sessions

Usage​

soat create-session --agent-id <string>

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-<key> 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<string, string>
--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​

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​

soat get-session

Options​

This command has no options.

soat update-session​

Update a session

  • Method: PATCH
  • Path: /api/v1/sessions/{session_id}

Usage​

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-<key> 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<string, string>
--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​

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​

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​

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-<key> 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<string, string>

soat submit-session-tool-outputs​

Submit tool outputs

  • Method: POST
  • Path: /api/v1/sessions/{session_id}/tool-outputs

Usage​

soat submit-session-tool-outputs --generation-id <string> --tool-outputs <array<object>>

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<object>

soat fork-session​

Fork a session

  • Method: POST
  • Path: /api/v1/sessions/{session_id}/fork

Usage​

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<string, string>
--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<string, string>

soat list-session-forks​

List a session's forks

  • Method: GET
  • Path: /api/v1/sessions/{session_id}/forks

Usage​

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​

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​

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​

soat merge-session-tags

Options​

This command has no options.