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

  • 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 injected as context headers into all tool call requests made during this session.

  • 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 injected as context headers into all tool call requests made during this session.

  • 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​

--async​

When true, generation runs in the background and 202 is returned immediately

  • Source: query
  • Required: no
  • Type: boolean
--model​

Optional model override

  • Source: body
  • Required: no
  • Type: string
  • Example: gpt-4o
--tool-context​

Key-value pairs injected as context headers into all tool call requests made during this generation.

  • 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 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.