# Chats Commands

> See [Chats module docs](../../modules/chats) for permissions and data model.

# Chats Commands

See [Chats module docs](../../modules/chats) for permissions and data model.

### `soat create-chat`

Create a chat

- Method: `POST`
- Path: `/api/v1/chats`

#### Usage

```bash
soat create-chat
```

#### Options

##### `--ai-provider-id`

Public ID of the AI provider to pin. Optional: omit it to inherit the project's `default_model_route_id`, which gives the chat provider failover. Omitting it returns `400` when the project has no default, and cannot be combined with `model` — each route target names its own.

- Source: `body`
- Required: no
- Type: `string`
- Example: `aip_V1StGXR8Z5jdHi6B`

##### `--project-id`

Public ID of the project. Required when the user belongs to multiple projects and no project key is used. 

- Source: `body`
- Required: no
- Type: `string`
- Example: `proj_V1StGXR8Z5jdHi6B`

##### `--name`

Optional human-readable name

- Source: `body`
- Required: no
- Type: `string`
- Example: `Support Bot`

##### `--instructions`

Optional system message applied to all completions on this chat

- Source: `body`
- Required: no
- Type: `string`
- Example: `You are a helpful support assistant.`

##### `--model`

Optional default model override

- Source: `body`
- Required: no
- Type: `string`
- Example: `gpt-4o`

### `soat list-chats`

List chats

- Method: `GET`
- Path: `/api/v1/chats`

#### Usage

```bash
soat list-chats
```

#### Options

##### `--project-id`

Project public ID to filter by

- Source: `query`
- Required: no
- Type: `string`

##### `--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 get-chat`

Get a chat

- Method: `GET`
- Path: `/api/v1/chats/{chat_id}`

#### Usage

```bash
soat get-chat --chat-id <string>
```

#### Options

##### `--chat-id`

—

- Source: `path`
- Required: yes
- Type: `string`

### `soat delete-chat`

Delete a chat

- Method: `DELETE`
- Path: `/api/v1/chats/{chat_id}`

#### Usage

```bash
soat delete-chat --chat-id <string>
```

#### Options

##### `--chat-id`

—

- Source: `path`
- Required: yes
- Type: `string`

### `soat create-chat-completion`

Create a chat completion

- Method: `POST`
- Path: `/api/v1/chat/completions`

#### Usage

```bash
soat create-chat-completion --messages <array<object>>
```

#### Options

##### `--ai-provider-id`

Public ID of the AI provider to run the completion against. Mutually exclusive with `chat_id`; exactly one of the two is required. 

- Source: `body`
- Required: no
- Type: `string`
- Example: `aip_V1StGXR8Z5jdHi6B`

##### `--chat-id`

Public ID of a stored chat supplying the provider, model and instructions. Mutually exclusive with `ai_provider_id`; exactly one of the two is required. 

- Source: `body`
- Required: no
- Type: `string`
- Example: `chat_V1StGXR8Z5jdHi6B`

##### `--model`

Model identifier. Overrides the provider's `default_model`, or the chat's `model`, when specified. 

- Source: `body`
- Required: no
- Type: `string`
- Example: `gpt-4o`

##### `--instructions`

System instructions for this call. Sent to the provider as its `instructions` argument rather than as a message, which is the only place the AI SDK accepts system content (`allowSystemInMessages` defaults to false). This field is the only channel — a `role: "system"` entry in `messages` is refused with `400 SYSTEM_MESSAGE_NOT_ALLOWED`. With `chat_id`, this replaces the chat's stored `instructions` for this call only; the stored value applies when the request carries none, and the two are never merged. 

- Source: `body`
- Required: no
- Type: `string`
- Example: `You are a helpful assistant.`

##### `--messages`

Ordered list of chat messages

- Source: `body`
- Required: yes
- Type: `array<object>`

##### `--stream`

When `true` the response is an SSE stream of delta chunks. When `false` (default) a single JSON object is returned. 

- Source: `body`
- Required: no
- Type: `boolean`
- Default: `false`