# Copilot Chat

***

## POST /api/copilot/chat

Send a message to the AI Copilot. The response is streamed via **Server-Sent Events (SSE)**.

**Permission:** Admin, Member, or Contributor role

**Request:**

```json
{
  "message": "What are the most critical open incidents?",
  "conversationId": null
}
```

Pass `conversationId` from a previous `start` event to continue a conversation. Pass `null` to start a new one.

***

## SSE Stream Response

`Content-Type: text/event-stream`

```
data: {"type": "start", "conversationId": "uuid"}

data: {"type": "tool_use", "tool": "list_incidents", "toolStatus": "calling"}

data: {"type": "tool_use", "tool": "list_incidents", "toolStatus": "done"}

data: {"type": "token", "content": "Based on your current data,"}

data: {"type": "token", "content": " there are 3 critical open incidents:"}

data: {"type": "sources", "sources": [{"type": "List Incidents", "label": "List Incidents"}]}

data: {"type": "done"}
```

***

## SSE Event Types

| Type       | Fields               | Description                                                            |
| ---------- | -------------------- | ---------------------------------------------------------------------- |
| `start`    | `conversationId`     | Session started. Save `conversationId` for follow-up messages.         |
| `tool_use` | `tool`, `toolStatus` | Data fetching in progress. `toolStatus`: `calling` → `done` or `error` |
| `token`    | `content`            | Streamed text token. Append to build the full response.                |
| `sources`  | `sources[]`          | All data sources used during this response                             |
| `done`     | —                    | Response complete                                                      |
| `error`    | `error`              | Error message (stream ends)                                            |

***

## Consuming SSE in JavaScript

```javascript
const response = await fetch('/api/copilot/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({ message: 'Show me open incidents', conversationId: null })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let text = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  for (const line of chunk.split('\n')) {
    if (!line.startsWith('data: ')) continue;
    const event = JSON.parse(line.slice(6));

    if (event.type === 'token') text += event.content;
    if (event.type === 'start') console.log('conversationId:', event.conversationId);
    if (event.type === 'done') console.log('Full response:', text);
  }
}
```

***

## Notes

* Conversations are stateful within a session — use `conversationId` to ask follow-up questions
* Each response executes up to 10 tool call rounds before returning a final answer
* Viewer-role tokens will receive an error if they attempt write operations via the Copilot


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://fabric-docs.telm.ai/api-reference/copilot.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.