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. With a credential scoped to a project, it may also be an agent another project shares with that project; the session is then that project's.

  • Source: body
  • Required: yes
  • Type: string
  • Example: agent_V1StGXR8Z5jdHi6B
--name​

Optional session name

  • Source: body
  • Required: no
  • Type: string
  • Example: Support chat
--tags​

—

  • Source: body
  • Required: no
  • Type: unknown
--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 stored exactly as sent and never case-converted. 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. session_id, actor_id and actor_external_id are server-derived and dropped from the stored bag, in any casing. Write-only: no read of a session returns it. It also does not outlive the session: closing or expiring it clears the bag.

  • 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
--max-context-messages​

Maximum number of recent conversation messages sent to the model on each generation, taking precedence over the agent's max_context_messages. null or absent defers to the agent.

  • Source: body
  • Required: no
  • Type: integer \| null
  • Default: null
  • Example: 20

soat list-sessions​

List sessions

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

Usage​

soat list-sessions

Options​

--project-id​

Filter by project public ID. Required for soat:ResourceTag policy conditions to narrow the listing: a policy is read per project, so without it the listing is scoped to the projects the caller can access and nothing further.

  • Source: query
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--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. Repeat the parameter to OR values. A value outside the enum, empty string included, is a 400.

  • Source: query
  • Required: no
  • Type: array<enum("open", "closed", "expired")>

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 stored exactly as sent and never case-converted. 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. session_id, actor_id and actor_external_id are server-derived and dropped from the stored bag, in any casing. Write-only: no read of a session returns it. It also does not outlive the session: closing or expiring it clears the bag.

  • 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
--max-context-messages​

Maximum number of recent conversation messages sent to the model on each generation, taking precedence over the agent's max_context_messages. Set to null to defer to the agent.

  • Source: body
  • Required: no
  • Type: integer \| null
  • Example: 20

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. A tool call, builtin or MCP, always waits.

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

—

  • Source: body
  • Required: no
  • Type: unknown
--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​

This command has no options.

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

Options​

--tags​

Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM soat:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.

  • Source: body
  • Required: yes
  • Type: object

soat merge-session-tags​

Merge session tags

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

Usage​

soat merge-session-tags --tags <object>

Options​

--tags​

Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM soat:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.

  • Source: body
  • Required: yes
  • Type: object