Skip to main content

Conversations Commands

See Conversations module docs for permissions and data model.

soat list-conversations​

List conversations

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

Usage​

soat list-conversations

Options​

--project-id​

Project ID (optional)

  • Source: query
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--actor-id​

Filter by actor ID

  • Source: query
  • Required: no
  • Type: string
  • Example: actor_V1StGXR8Z5jdHi6B

soat create-conversation​

Create a conversation

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

Usage​

soat create-conversation

Options​

--project-id​

Project ID. Required for JWT auth; omit when using an project key.

  • Source: body
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--status​

Initial conversation status

  • Source: body
  • Required: no
  • Type: enum("open", "closed")
  • Default: open
--name​

Optional name for the conversation

  • Source: body
  • Required: no
  • Type: string \| null
--actor-id​

Actor ID to associate with this conversation

  • Source: body
  • Required: no
  • Type: string \| null
  • Example: actor_V1StGXR8Z5jdHi6B
--retrieval​

Whether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so none leaves them readable and reachable by full-text search without paying for an embedding. null (the default) inherits the project's default_conversation_retrieval.

  • Source: body
  • Required: no
  • Type: enum("embed", "none", null)

soat get-conversation​

Get a conversation by ID

  • Method: GET
  • Path: /api/v1/conversations/{conversation_id}

Usage​

soat get-conversation --conversation-id <string>

Options​

--conversation-id​

Conversation ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: conv_V1StGXR8Z5jdHi6B

soat update-conversation​

Update a conversation

  • Method: PATCH
  • Path: /api/v1/conversations/{conversation_id}

Usage​

soat update-conversation --conversation-id <string>

Options​

--conversation-id​

Conversation ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: conv_V1StGXR8Z5jdHi6B
--status​

New conversation status

  • Source: body
  • Required: no
  • Type: enum("open", "closed")
--name​

New conversation name

  • Source: body
  • Required: no
  • Type: string \| null
--retrieval​

Whether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so none leaves them readable and reachable by full-text search without paying for an embedding. null (the default) inherits the project's default_conversation_retrieval. Switching it on embeds the turns already in the conversation, so the whole conversation becomes retrievable rather than only what is said next.

  • Source: body
  • Required: no
  • Type: enum("embed", "none", null)

soat delete-conversation​

Delete a conversation

  • Method: DELETE
  • Path: /api/v1/conversations/{conversation_id}

Usage​

soat delete-conversation --conversation-id <string>

Options​

--conversation-id​

Conversation ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: conv_V1StGXR8Z5jdHi6B

soat list-conversation-messages​

List conversation messages

  • Method: GET
  • Path: /api/v1/conversations/{conversation_id}/messages

Usage​

soat list-conversation-messages --conversation-id <string>

Options​

--conversation-id​

Conversation ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: conv_V1StGXR8Z5jdHi6B

soat add-conversation-message​

Add a message to a conversation

  • Method: POST
  • Path: /api/v1/conversations/{conversation_id}/messages

Usage​

soat add-conversation-message --conversation-id <string> --message <string> --role <enum("user", "assistant")>

Options​

--conversation-id​

Conversation ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: conv_V1StGXR8Z5jdHi6B
--message​

Message text content to add to the conversation

  • Source: body
  • Required: yes
  • Type: string
  • Example: Hello, how can I help you?
--role​

Role of the message sender

  • Source: body
  • Required: yes
  • Type: enum("user", "assistant")
  • Example: user
--actor-id​

Optional actor ID to associate with this message (user identity)

  • Source: body
  • Required: no
  • Type: string \| null
  • Example: actor_V1StGXR8Z5jdHi6B
--position​

Zero-based position. Defaults to MAX+1 (append).

  • Source: body
  • Required: no
  • Type: integer
  • Example: 0
--metadata​

Caller-owned annotations on the message (e.g. a phone number, a channel), stored as sent and returned verbatim. The platform does not read the bag, so nothing in it reaches the model: a value the model should see belongs in message.

  • Source: body
  • Required: no
  • Type: unknown
  • Example: \{"phone":"5511999998888","channel":"whatsapp"\}

soat generate-conversation-message​

Generate the next message in a conversation

  • Method: POST
  • Path: /api/v1/conversations/{conversation_id}/generate

Usage​

soat generate-conversation-message --conversation-id <string> --agent-id <string>

Options​

--conversation-id​

—

  • Source: path
  • Required: yes
  • Type: string
--wait​

When omitted or false (default), the 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
--agent-id​

ID of the agent that will produce the next message.

  • Source: body
  • Required: yes
  • Type: string
--model​

Optional model override.

  • Source: body
  • Required: no
  • Type: string
--stream​

If true, stream tokens via SSE. NOT IMPLEMENTED in v1 — returns 501.

  • 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 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 and keys are never case-converted, so 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 remove-conversation-message​

Remove a message from a conversation

  • Method: DELETE
  • Path: /api/v1/conversations/{conversation_id}/messages/{document_id}

Usage​

soat remove-conversation-message --conversation-id <string> --document-id <string>

Options​

--conversation-id​

Conversation ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: conv_V1StGXR8Z5jdHi6B
--document-id​

Document ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: doc_V1StGXR8Z5jdHi6B

soat get-conversation-tags​

Get conversation tags

  • Method: GET
  • Path: /api/v1/conversations/{conversation_id}/tags

Usage​

soat get-conversation-tags --conversation-id <string>

Options​

--conversation-id​

Conversation ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: conv_V1StGXR8Z5jdHi6B

soat replace-conversation-tags​

Replace conversation tags

  • Method: PUT
  • Path: /api/v1/conversations/{conversation_id}/tags

Usage​

soat replace-conversation-tags --conversation-id <string> --tags <object>

Options​

--conversation-id​

Conversation ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: conv_V1StGXR8Z5jdHi6B
--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-conversation-tags​

Merge conversation tags

  • Method: PATCH
  • Path: /api/v1/conversations/{conversation_id}/tags

Usage​

soat merge-conversation-tags --conversation-id <string> --tags <object>

Options​

--conversation-id​

Conversation ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: conv_V1StGXR8Z5jdHi6B
--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