> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osis.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat completions

> POST /api/v1/comms/chat/completions — OpenAI-shaped Comms Router completions.

Call Comms Router from your backend. The request and response match OpenAI chat completions. Tokens are billed per model — no plan includes AI usage.

**Scope:** `comms_ai`

<Note>
  This is Comms Router. You do not bring your own model key. Usage from this endpoint and from hosted agent replies share one meter.
</Note>

## Request

```bash theme={null}
curl -X POST "https://osis.co/api/v1/comms/chat/completions" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      { "role": "system", "content": "You write short SMS replies." },
      { "role": "user", "content": "Confirm Tuesday at 3pm in one sentence." }
    ]
  }'
```

### Headers

| Header          | Required | Description              |
| --------------- | -------- | ------------------------ |
| `Authorization` | Yes      | `Bearer <COMMS_API_KEY>` |
| `Content-Type`  | Yes      | `application/json`       |

### Body parameters

<ParamField body="model" type="string">
  Comms Router model id. Use `default` or any id from `GET /api/v1/comms/ai/models`.
</ParamField>

<ParamField body="messages" type="array" required>
  Chat messages. Each item has `role` (`system`, `user`, `assistant`, or `tool`) and string `content`.
</ParamField>

<ParamField body="temperature" type="number">
  Optional. `0`–`2`. Defaults to `0.7`.
</ParamField>

<ParamField body="max_tokens" type="integer">
  Optional. `16`–`8192`. Defaults to `1024`.
</ParamField>

<ParamField body="stream" type="boolean">
  Must be omitted or `false`. Streaming is not supported yet.
</ParamField>

## Response

```json theme={null}
{
  "id": "chatcmpl_01HZX…",
  "object": "chat.completion",
  "created": 1771459200,
  "model": "claude-sonnet-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "You're confirmed for Tuesday at 3pm."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 12,
    "total_tokens": 36
  }
}
```

## Errors

| Status  | Meaning                                |
| ------- | -------------------------------------- |
| **400** | Invalid body, model, or `stream: true` |
| **401** | Missing or invalid key                 |
| **403** | Key is missing `comms_ai`              |
| **503** | Workspace AI is not configured         |

## Related

* [AI usage](/messages-api/ai-usage)
* [Comms Router](/guides/comms-router)
* [Authentication](/messages-api/authentication)