> For the complete documentation index, see [llms.txt](https://planck-ai.gitbook.io/planck-ai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://planck-ai.gitbook.io/planck-ai-docs/documentation/reference/response-format.md).

# Response Format

Planck AI chat responses are streamed by default.

Streaming allows applications to receive the response progressively as it is generated, instead of waiting for the full answer to complete.

### Streaming protocol

Planck AI uses Server-Sent Events for streamed chat responses.

This applies to:

```
POST /api/v1/workspaces/{workspace_id}/chat
```

and:

```
POST /api/v1/workspaces/{workspace_id}/conversations/{conversation_id}/messages
```

Applications should be prepared to read events incrementally and assemble the final response.

### Common stream events

A streamed response may include events such as:

| Event                 | Description                                         |
| --------------------- | --------------------------------------------------- |
| `message_start`       | Indicates that the assistant response has started   |
| `content_block_start` | Starts a new content block                          |
| `content_block_delta` | Sends incremental content for the current block     |
| `content_block_stop`  | Ends the current content block                      |
| `message_stop`        | Indicates that the assistant response has completed |

### Example stream structure

A response may follow this general pattern:

```
event: message_startdata: {"id": "session-uuid", "role": "assistant"}event: content_block_startdata: {"index": 0, "type": "text"}event: content_block_deltadata: {"index": 0, "delta": {"type": "text_delta", "text": "Hello"}}event: content_block_stopdata: {"index": 0}event: message_stopdata: {"id": "session-uuid", "credits_consumed": 1}
```

### Content blocks

Planck AI responses are made up of content blocks.

A response can contain one or more blocks.

Example response:

```
{  "id": "msg-uuid",  "conversation_id": "conv-uuid",  "session_id": "session-uuid",  "role": "assistant",  "content_blocks": [    {      "type": "text",      "content": "Based on the data, here is the summary."    },    {      "type": "table",      "content": "| Server | Status |\n|--------|--------|\n| srv1 | Active |"    }  ],  "created_date": "2026-01-11T19:45:00Z"}
```

### Content block types

Planck AI may return different content block types depending on the question, available data, and requested output.

| Type       | Description                                                      |
| ---------- | ---------------------------------------------------------------- |
| `text`     | Plain text or markdown response                                  |
| `code`     | Code snippet, such as SQL or Python                              |
| `table`    | Markdown or structured table output                              |
| `chart`    | Chart output, such as bar, line, pie, scatter, or area           |
| `map`      | Map output, often using geographic data                          |
| `image`    | Image output or image reference                                  |
| `tool_use` | Tool invocation details, if enabled                              |
| `thinking` | Reasoning or thinking information, if enabled for the deployment |

Available block types may vary by deployment and feature configuration.

### Text block example

```
{  "type": "text",  "content": "Here is a summary of the servers:\n\n| Server | Region | Status |\n|--------|--------|--------|\n| srv-01 | eu-west-1 | Active |"}
```

### Code block example

```
{  "type": "code",  "language": "sql",  "content": "SELECT DATE_TRUNC('month', order_date) AS month, SUM(amount) AS total_revenue FROM orders GROUP BY month ORDER BY month;"}
```

### Chart block example

```
{  "type": "chart",  "chart": {    "type": "bar",    "title": "Monthly Revenue",    "data": [      {        "month": "2025-07",        "revenue": 125000      },      {        "month": "2025-08",        "revenue": 143000      }    ],    "config": {      "xKey": "month",      "yKeys": ["revenue"]    }  }}
```

### Credits consumed

The final `message_stop` event may include usage information such as credits consumed.

Example:

```
{  "id": "session-uuid",  "credits_consumed": 1}
```

Applications can use this value for usage tracking, billing visibility, or internal reporting.

### Handling responses in your application

When building a client application, you should:

1. Listen for Server-Sent Events
2. Track each content block by index
3. Append deltas to the correct content block
4. Render each block based on its type
5. Wait for `message_stop` before treating the response as complete
6. Capture usage metadata such as credits consumed, if present

### Recommended rendering behavior

| Block type | Suggested rendering                                   |
| ---------- | ----------------------------------------------------- |
| `text`     | Render as markdown                                    |
| `code`     | Render in a syntax-highlighted code block             |
| `table`    | Render as a table where possible                      |
| `chart`    | Render using your charting library                    |
| `map`      | Render using a map component                          |
| `image`    | Render as an image or linked media                    |
| `tool_use` | Show only in developer/debug views unless needed      |
| `thinking` | Show only if enabled and appropriate for your product |

### Best practices

Design your client to handle multiple content blocks.

Do not assume every response will be plain text.

For example, the same question may return:

* A text summary
* A table of supporting data
* A chart
* A SQL snippet
* Source context

For production applications, also handle partial streams, network interruptions, and server errors gracefully.

### Recommended next pages

* **Chat API** — send stateless chat messages
* **Conversations API** — create multi-turn conversations
* **Error Handling** — understand common API errors


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://planck-ai.gitbook.io/planck-ai-docs/documentation/reference/response-format.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.