> 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/chat-api.md).

# Chat API

The Chat API lets you send a stateless chat message to a workspace.

Use this endpoint when you want a simple request-response flow without creating or managing a saved conversation.

### Endpoint

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

### When to use stateless chat

Use stateless chat when:

* You want a one-off answer
* You do not need to store conversation history
* You are building a simple integration
* You want to ask a question about a document, database, or workspace context

For multi-turn chat with saved history, use the **Conversations API**.

### Basic request

```
curl -X POST "https://<your-planck-domain>/api/v1/workspaces/WORKSPACE_ID/chat" \  -H "X-API-Key: pk_live_your_key_here" \  -H "Content-Type: application/json" \  -d '{    "message": "What can you help me with?"  }'
```

Replace:

```
<your-planck-domain>
```

with your Planck AI instance URL.

Replace:

```
WORKSPACE_ID
```

with the workspace ID.

### Chat with a document

To ask a question about a specific document, include the document reference in `settings.chat_metadata.documents`.

Example:

```
curl -X POST "https://<your-planck-domain>/api/v1/workspaces/WORKSPACE_ID/chat" \  -H "X-API-Key: pk_live_your_key_here" \  -H "Content-Type: application/json" \  -d '{    "message": "Summarize this document",    "settings": {      "chat_metadata": {        "documents": {          "report.pdf": {            "id": "DOCUMENT_ID"          }        }      }    }  }'
```

### Chat with a database

To ask a question about a connected database, include the database integration reference in `settings.chat_metadata.database`.

Example:

```
curl -X POST "https://<your-planck-domain>/api/v1/workspaces/WORKSPACE_ID/chat" \  -H "X-API-Key: pk_live_your_key_here" \  -H "Content-Type: application/json" \  -d '{    "message": "How has monthly revenue changed in the last two quarters?",    "settings": {      "chat_metadata": {        "database": {          "workspace_id": "WORKSPACE_ID",          "integration_id": "DATABASE_INTEGRATION_ID"        }      }    }  }'
```

### Chat metadata

The `chat_metadata` object can be used to pass additional context to the chat request.

Common fields include:

| Field           | Type   | Description                                  |
| --------------- | ------ | -------------------------------------------- |
| `documents`     | object | Document references to attach to the request |
| `database`      | object | Database integration reference               |
| `response_mode` | string | Optional response formatting mode            |
| `site_id`       | string | Tenant or site isolation key, if configured  |

### Concise response mode

For messaging clients such as WhatsApp or Telegram, you can request shorter answers by setting:

```
response_mode: concise
```

Example:

```
curl -X POST "https://<your-planck-domain>/api/v1/workspaces/WORKSPACE_ID/chat" \  -H "X-API-Key: pk_live_your_key_here" \  -H "Content-Type: application/json" \  -d '{    "message": "How are sales today?",    "settings": {      "chat_metadata": {        "response_mode": "concise",        "database": {          "workspace_id": "WORKSPACE_ID",          "integration_id": "DATABASE_INTEGRATION_ID"        }      }    }  }'
```

When `response_mode` is omitted, Planck AI may use richer formatting such as markdown tables, charts, code blocks, or other structured outputs.

### Streaming responses

Chat responses are streamed by default using Server-Sent Events.

Applications should be prepared to receive content incrementally.

Common stream events may include:

* `message_start`
* `content_block_start`
* `content_block_delta`
* `content_block_stop`
* `message_stop`

The final response may contain one or more content blocks.

### Response content

A chat response may include:

* Text
* Tables
* Code
* Charts
* Maps
* Images
* Tool-use information

See **Response Format** for details.

### Abort a chat request

To abort an active stateless chat request, use:

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

### Common errors

| Status code | Meaning                                                    |
| ----------- | ---------------------------------------------------------- |
| `401`       | Missing or invalid API key                                 |
| `403`       | API key does not have access to this endpoint or workspace |
| `404`       | Workspace, document, or integration not found              |
| `429`       | Rate limit exceeded                                        |
| `500`       | Server error                                               |

### Recommended next pages

* **Conversations API** — create multi-turn conversations with saved history
* **Response Format** — understand streamed responses and content blocks
* **Authentication** — learn how API keys work


---

# 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/chat-api.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.