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

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​

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

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

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

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", "system")
  • 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<string, 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
--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 injected as context headers into all tool call requests made during this generation.

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

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​

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

Options​

--conversation-id​

Conversation ID

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