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

# Chat Completions

> Send messages to your agent and receive AI-powered responses.

Send a message to your agent and receive a response. The API follows a conversational format — pass the full message history to maintain context across turns.

### Headers

| Header         | Required           | Description                |
| -------------- | ------------------ | -------------------------- |
| `api-key`      | For private agents | Your Tiny Talk API key     |
| `Content-Type` | Yes                | Must be `application/json` |

### Body parameters

<ParamField body="botId" type="string" required>
  Your agent's ID. Find it in the dashboard under **Settings → General**.
</ParamField>

<ParamField body="messages" type="array" required>
  The conversation history. Each message is an object with `role` and `content`.

  <Expandable title="Message object">
    <ParamField body="role" type="string" required>
      The role of the message author. One of `user` or `assistant`.
    </ParamField>

    <ParamField body="content" type="string" required>
      The message text.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="stream" type="boolean" default="true">
  Whether to stream the response as server-sent events (SSE). Defaults to the agent's stream setting if not specified.
</ParamField>

<ParamField body="model" type="string">
  Override the agent's default AI model. Must be a model available on your plan. If omitted, the agent's configured model is used.
</ParamField>

## Response

### Streaming (default)

The API streams the response as **server-sent events (SSE)**. Each chunk is prefixed with `data: ` and the stream terminates with `data: [DONE]`. After the stream completes, a `message_payload` event is sent containing any Knowledge Base sources cited in the response.

### Non-streaming

When `stream` is set to `false`, the API returns a single JSON response with the complete message, token usage, and cited resources.

<ResponseField name="payload.citedResources" type="array">
  Website URLs from the Knowledge Base that were cited in the response. Only returned when [Display Links to References](/features/messenger#behavior) is enabled in the messenger settings. Each object includes `id`, `url`, `title`, and `type`.
</ResponseField>

<RequestExample>
  ```bash Non-streaming theme={null}
  curl -X POST https://api.tinytalk.ai/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "api-key: <API_KEY>" \
    -d '{
      "botId": "your-agent-id",
      "stream": false,
      "messages": [
        { "role": "user", "content": "Good morning" }
      ]
    }'
  ```

  ```bash Streaming theme={null}
  curl -X POST https://api.tinytalk.ai/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "api-key: <API_KEY>" \
    -d '{
      "botId": "your-agent-id",
      "messages": [
        { "role": "user", "content": "Good morning" }
      ]
    }'
  ```

  ```bash Multi-turn theme={null}
  curl -X POST https://api.tinytalk.ai/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "api-key: <API_KEY>" \
    -d '{
      "botId": "your-agent-id",
      "stream": false,
      "messages": [
        { "role": "user", "content": "What plans do you offer?" },
        { "role": "assistant", "content": "We offer Basic, Pro, and Enterprise plans." },
        { "role": "user", "content": "What is included in the Pro plan?" }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Non-streaming (200) theme={null}
  {
    "id": "chatcmpl-DEiS3ZvDkqboJuwJAQxA3BEx283xK",
    "object": "chat.completion",
    "created": 1772399835,
    "model": "gpt-5.2-chat-latest",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "Good morning! How can I assist you today?",
          "refusal": null,
          "annotations": []
        },
        "logprobs": null,
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 441,
      "completion_tokens": 10,
      "total_tokens": 451
    },
    "payload": {
      "citedResources": []
    }
  }
  ```

  ```text Streaming (200) theme={null}
  data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"Good"},"finish_reason":null}]}

  data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" morning!"},"finish_reason":null}]}

  data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" How can I assist you?"},"finish_reason":"stop"}]}

  data: [DONE]

  event: message_payload
  data: {"type":"message_payload","payload":{"citedResources":[]}}
  ```
</ResponseExample>

## Multi-turn conversations

To maintain context across multiple exchanges, include previous messages in the `messages` array. The agent uses the full history to generate more relevant responses.

<Tip>
  Including conversation history improves response quality significantly. Without it, each request is treated as a standalone question and the agent loses context from earlier messages.
</Tip>