> 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/workspaces-and-documents-api.md).

# Workspaces & Documents API

Use the Workspaces and Documents endpoints to discover what data is available to the authenticated user.

Most API workflows start by listing workspaces, then using a workspace ID to list documents or send chat requests.

### Workspaces

A workspace is the main container for documents, conversations, database integrations, and chat.

API keys inherit the permissions of the user who created them, so the API only returns workspaces that the user can access.

### List workspaces

```
GET /api/v1/workspaces
```

Example:

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

Example response:

```
{  "data": [    {      "id": "230e30c0-6fb0-4f6c-87fe-7391d769de8e",      "name": "My Workspace",      "description": "Project documents"    }  ],  "count": 1}
```

### Get workspace details

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

Example:

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

### Documents

Documents are files uploaded or synced into a workspace.

Depending on the workspace setup, documents may include PDFs, Excel files, CSV files, text files, or files synced from systems such as Microsoft 365, OneDrive, and SharePoint.

### List documents in a workspace

```
GET /api/v1/documents/?workspace_id={workspace_id}
```

Example:

```
curl -H "X-API-Key: pk_live_your_key_here" \  "https://<your-planck-domain>/api/v1/documents/?workspace_id=WORKSPACE_ID"
```

Example response:

```
{  "data": [    {      "id": "626c4a1f-143f-44a1-b67f-601b97d7ee7f",      "name": "servers.csv",      "status": "processed"    }  ],  "count": 1}
```

### Get document details

```
GET /api/v1/documents/{document_id}
```

Example:

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

### Document status

The `status` field tells you whether a document is ready to use.

Common statuses may include:

| Status       | Meaning                                                |
| ------------ | ------------------------------------------------------ |
| `uploaded`   | The file has been uploaded but not fully processed yet |
| `processing` | The file is being processed                            |
| `processed`  | The file is ready for search and chat                  |
| `failed`     | Processing failed                                      |

Status names may vary by deployment.

### Using documents in chat

After listing documents, use the document ID in a Chat API request.

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": {          "servers.csv": {            "id": "626c4a1f-143f-44a1-b67f-601b97d7ee7f"          }        }      }    }  }'
```

### Typical flow

A common document workflow looks like this:

1. List workspaces
2. Choose the relevant workspace ID
3. List documents in that workspace
4. Choose a processed document
5. Send a chat request with the document ID

### Permissions

The API only returns workspaces and documents the API key owner can access.

If a workspace or document does not appear, check:

* The API key is valid
* The user has access to the workspace
* The document is linked to the workspace
* The document has finished processing
* Source-system permissions allow access, if the document came from a cloud integration

### Common errors

| Status code | Meaning                         |
| ----------- | ------------------------------- |
| `401`       | Missing or invalid API key      |
| `403`       | User does not have access       |
| `404`       | Workspace or document not found |
| `500`       | Server error                    |

### Recommended next pages

* **Chat API** — ask questions using workspace, document, or database context
* **Conversations API** — create multi-turn conversations
* **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/workspaces-and-documents-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.