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

# API Overview

The Planck AI API lets developers build integrations, automate workflows, and create custom applications on top of Planck AI.

Use the API to access workspaces, documents, conversations, and AI-powered chat capabilities programmatically.

### What you can do with the API

The API supports common workflows such as:

* Listing workspaces
* Listing documents in a workspace
* Checking document processing status
* Sending stateless chat messages
* Creating and managing conversations
* Sending messages inside conversations
* Querying connected databases through chat
* Asking questions about specific documents
* Receiving streaming responses
* Creating users and issuing API keys through admin endpoints

### Main API areas

| Area                  | Description                                                        |
| --------------------- | ------------------------------------------------------------------ |
| Workspaces            | List and access workspaces                                         |
| Documents             | List documents and check document status                           |
| Chat                  | Send stateless chat messages                                       |
| Conversations         | Create conversations, send messages, and retrieve history          |
| Database integrations | Query connected databases using natural language                   |
| Response formats      | Receive text, tables, charts, maps, code, and other content blocks |
| Admin API             | Provision users, add users to workspaces, and issue API keys       |

### Base URL

The API base URL depends on your Planck AI deployment.

Use this format:

```
https://<your-planck-domain>/api/v1
```

For local or self-hosted deployments, your base URL may look like:

```
http://<your-server>/api/v1
```

Replace `<your-planck-domain>` or `<your-server>` with the actual URL for your Planck AI instance.

### Authentication

API requests use an API key.

Include the API key in the request header:

```
X-API-Key: pk_live_your_key_here
```

Example:

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

API keys inherit the permissions of the user account that created them.

### Common API flows

#### Chat with a document

1. List workspaces
2. List documents in a workspace
3. Send a chat message with the document reference

#### Chat with a database

1. List workspaces
2. List database integrations in a workspace
3. Send a chat message with the database integration reference

#### Stateful conversation

1. Create a conversation
2. Send a message inside the conversation
3. Send follow-up messages
4. Retrieve conversation history

#### Admin provisioning

Admin users can use admin endpoints to:

* Create users
* Look up users by email
* Add users to workspaces
* Issue API keys for users

Admin endpoints require an API key owned by a user with the Admin role.

### Streaming responses

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

Streaming allows applications to receive the response progressively instead of waiting for the full answer to complete.

### Response content blocks

Planck AI responses can include different content block types, such as:

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

Your application should handle multiple content block types when building a rich user experience.

### Recommended next pages

* **Authentication** — learn how to create and use API keys
* **Chat API** — send stateless chat messages
* **Conversations API** — create multi-turn conversations
* **Admin API** — provision users and issue API keys
* **Response Format** — understand streamed responses and content blocks


---

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