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

# Conversations API

The Conversations API lets you create and manage saved chat threads inside a workspace.

Use conversations when you want multi-turn interactions with persisted history.

### When to use conversations

Use the Conversations API when:

* You want to keep chat history
* Users may ask follow-up questions
* You are building a chat interface
* You want to retrieve past messages
* You want context from earlier messages to be available in later turns

For one-off chat requests, use the **Chat API**.

### Create a conversation

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

Example:

```
curl -X POST "https://<your-planck-domain>/api/v1/workspaces/WORKSPACE_ID/conversations" \  -H "X-API-Key: pk_live_your_key_here" \  -H "Content-Type: application/json" \  -d '{    "name": "Revenue Analysis"  }'
```

Example response:

```
{  "id": "a1b2c3d4-5678-90ab-cdef-111111111111",  "name": "Revenue Analysis",  "workspace_id": "230e30c0-6fb0-4f6c-87fe-7391d769de8e",  "is_owner": true}
```

### Create a conversation from a prompt

You can also create a conversation from a prompt. The server may generate a conversation name automatically.

```
curl -X POST "https://<your-planck-domain>/api/v1/workspaces/WORKSPACE_ID/conversations" \  -H "X-API-Key: pk_live_your_key_here" \  -H "Content-Type: application/json" \  -d '{    "prompt": "How has monthly revenue changed?"  }'
```

### Send a message in a conversation

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

Example with database context:

```
curl -X POST "https://<your-planck-domain>/api/v1/workspaces/WORKSPACE_ID/conversations/CONVERSATION_ID/messages" \  -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"        }      }    }  }'
```

The response is streamed using the same Server-Sent Events format as the Chat API.

Both the user message and the assistant response are persisted to the conversation.

### Send a follow-up message

Because messages are persisted, follow-up questions can use context from previous turns.

Example:

```
curl -X POST "https://<your-planck-domain>/api/v1/workspaces/WORKSPACE_ID/conversations/CONVERSATION_ID/messages" \  -H "X-API-Key: pk_live_your_key_here" \  -H "Content-Type: application/json" \  -d '{    "message": "Break that down by product category",    "settings": {      "chat_metadata": {        "database": {          "workspace_id": "WORKSPACE_ID",          "integration_id": "DATABASE_INTEGRATION_ID"        }      }    }  }'
```

### Retrieve conversation messages

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

Example:

```
curl -H "X-API-Key: pk_live_your_key_here" \  "https://<your-planck-domain>/api/v1/workspaces/WORKSPACE_ID/conversations/CONVERSATION_ID/messages?limit=20&offset=0"
```

Example response:

```
{  "data": [    {      "id": "msg-uuid-1",      "conversation_id": "CONVERSATION_ID",      "role": "user",      "content_blocks": [        {          "type": "text",          "content": "How has monthly revenue changed in the last two quarters?"        }      ],      "status": "completed",      "created_date": "2026-01-11T19:45:00Z"    },    {      "id": "msg-uuid-2",      "conversation_id": "CONVERSATION_ID",      "role": "assistant",      "content_blocks": [        {          "type": "text",          "content": "Here is the revenue trend for the last two quarters..."        }      ],      "status": "completed",      "created_date": "2026-01-11T19:45:05Z"    }  ],  "total": 2,  "limit": 20,  "offset": 0,  "has_more": false}
```

### List conversations

```
GET /api/v1/workspaces/{workspace_id}/conversations
```

Example:

```
curl -H "X-API-Key: pk_live_your_key_here" \  "https://<your-planck-domain>/api/v1/workspaces/WORKSPACE_ID/conversations"
```

### Get conversation details

```
GET /api/v1/workspaces/{workspace_id}/conversations/{conversation_id}
```

### Delete a conversation

```
DELETE /api/v1/workspaces/{workspace_id}/conversations/{conversation_id}
```

### Common errors

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

### Recommended next pages

* **Chat API** — send stateless chat messages
* **Response Format** — understand streamed responses and content blocks
* **Admin API** — provision users and issue API keys


---

# 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/conversations-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.