> For the complete documentation index, see [llms.txt](https://docs.castmagic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.castmagic.io/endpoints/chat.md).

# Chat

Ask questions grounded in one or more recordings' transcripts.

Ask a question grounded in the transcripts of up to **10 recordings**. The answer generates asynchronously — poll `GET /v1/chat/:id` until `status` is `"completed"`.

{% hint style="info" %}
**Tier:** `automation`. Base URL `https://app.castmagic.io`.
{% endhint %}

## Start a chat

<mark style="color:green;">`POST`</mark> `https://app.castmagic.io/v1/chat`

#### Request Body

| Name                                             | Type      | Description                                |
| ------------------------------------------------ | --------- | ------------------------------------------ |
| message<mark style="color:red;">\*</mark>        | String    | The question to ask                        |
| recording\_ids<mark style="color:red;">\*</mark> | String\[] | 1–10 recording ids to ground the answer in |

{% tabs %}
{% tab title="202: Accepted" %}

```json
{
    "chat_id": "c1...",
    "status": "queued"
}
```

{% endtab %}

{% tab title="400: Bad Request Too many recordings" %}

```json
{ "error": "recording_ids is capped at 10 recordings" }
```

{% endtab %}
{% endtabs %}

## Fetch a chat

<mark style="color:blue;">`GET`</mark> `https://app.castmagic.io/v1/chat/:id`

Poll until `status` is `"completed"`; the response text is then in `answer`.

{% tabs %}
{% tab title="200: OK completed" %}

```json
{
    "chat_id": "c1...",
    "status": "completed",
    "answer": "The main pricing objections were...",
    "recording_ids": ["e1...", "e2..."]
}
```

{% endtab %}

{% tab title="200: OK still processing" %}

```json
{
    "chat_id": "c1...",
    "status": "queued",
    "answer": null,
    "recording_ids": ["e1...", "e2..."]
}
```

{% endtab %}
{% endtabs %}