# Conversations Commands > See [Conversations module docs](../../modules/conversations) for permissions and data model. # Conversations Commands See [Conversations module docs](../../modules/conversations) for permissions and data model. ### `soat list-conversations` List conversations - Method: `GET` - Path: `/api/v1/conversations` #### Usage ```bash 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` ##### `--limit` Maximum number of results to return - Source: `query` - Required: no - Type: `integer` - Default: `50` ##### `--offset` Number of results to skip - Source: `query` - Required: no - Type: `integer` - Default: `0` ### `soat create-conversation` Create a conversation - Method: `POST` - Path: `/api/v1/conversations` #### Usage ```bash 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` ### `soat get-conversation` Get a conversation by ID - Method: `GET` - Path: `/api/v1/conversations/{conversation_id}` #### Usage ```bash soat get-conversation --conversation-id ``` #### 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 ```bash soat update-conversation --conversation-id ``` #### 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` ### `soat delete-conversation` Delete a conversation - Method: `DELETE` - Path: `/api/v1/conversations/{conversation_id}` #### Usage ```bash soat delete-conversation --conversation-id ``` #### 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 ```bash soat list-conversation-messages --conversation-id ``` #### Options ##### `--conversation-id` Conversation ID - Source: `path` - Required: yes - Type: `string` - Example: `conv_V1StGXR8Z5jdHi6B` ##### `--limit` Maximum number of results to return - Source: `query` - Required: no - Type: `integer` - Default: `50` ##### `--offset` Number of results to skip - Source: `query` - Required: no - Type: `integer` - Default: `0` ### `soat add-conversation-message` Add a message to a conversation - Method: `POST` - Path: `/api/v1/conversations/{conversation_id}/messages` #### Usage ```bash soat add-conversation-message --conversation-id --message --role ``` #### 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` Optional structured metadata to attach to the message (e.g. phone number, channel). Stored as-is and injected into the AI prompt context. - Source: `body` - Required: no - Type: `object` - 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 ```bash soat generate-conversation-message --conversation-id --agent-id ``` #### 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 `builtin` tool call 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-` 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` ### `soat remove-conversation-message` Remove a message from a conversation - Method: `DELETE` - Path: `/api/v1/conversations/{conversation_id}/messages/{document_id}` #### Usage ```bash soat remove-conversation-message --conversation-id --document-id ``` #### 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 ```bash soat get-conversation-tags --conversation-id ``` #### 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 ```bash soat replace-conversation-tags --conversation-id ``` #### Options ##### `--conversation-id` Conversation ID - Source: `path` - Required: yes - Type: `string` - Example: `conv_V1StGXR8Z5jdHi6B` ### `soat merge-conversation-tags` Merge conversation tags - Method: `PATCH` - Path: `/api/v1/conversations/{conversation_id}/tags` #### Usage ```bash soat merge-conversation-tags --conversation-id ``` #### Options ##### `--conversation-id` Conversation ID - Source: `path` - Required: yes - Type: `string` - Example: `conv_V1StGXR8Z5jdHi6B`