> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Knowledge base

> Create a Knowledge base with a workspace API key

Creates a Knowledge base and grants this API key the Editor role. Use the returned id to upload files, rename the Knowledge base, or share access. Personal API keys cannot create a Knowledge base.

## Before You Start

* **API key scope**: Requires a workspace API key with the `KNOWLEDGE_FOLDER_API` scope. A key that already has this scope can call this endpoint. Personal keys are refused, even with this scope. The key's owner must have the **Upload documents** permission. See [Share Knowledge bases with the API](https://docs.langdock.com/en/developer/knowledge-folder-api/sharing.md) for setup instructions.
* **Knowledge bases**: The Knowledge Folder API manages resources that appear as Knowledge bases in the Library.

## Base URL

```
https://api.langdock.com
```

> [!WARNING]
>
> **Dedicated deployments**
>
> Replace `api.langdock.com` with `<your-deployment-url>/api/public` in all requests.

## Request Format

This endpoint accepts `application/json`.

### Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Trimmed, then must not be empty. Maximum: `2000` characters. |
| `description` | string | No | Optional text. Maximum: `2000` characters. Not trimmed. |

Unknown fields are rejected. There is no public endpoint to delete a Knowledge base.

## Examples

### Create with cURL

```bash theme={null}
curl -X POST "https://api.langdock.com/knowledge" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product handbook",
    "description": "Internal product documentation"
  }'
```

### Create with JavaScript

```javascript theme={null}
const axios = require("axios");

async function createKnowledgeBase(data) {
  const response = await axios.post(
    "https://api.langdock.com/knowledge",
    data,
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
    }
  );

  return response.data;
}

const result = await createKnowledgeBase({
  name: "Product handbook",
  description: "Internal product documentation",
});
console.log(result.result.id, result.result.role);
```

## Response Format

### Success Response (201 Created)

```typescript theme={null}
{
  status: "success";
  result: {
    id: string;                 // Knowledge base ID
    name: string;               // Trimmed Knowledge base name
    description: string | null; // Null when omitted
    createdAt: string;          // ISO 8601 timestamp
    updatedAt: string;          // ISO 8601 timestamp
    fileCount: number;          // 0 for a new Knowledge base
    role: "EDITOR";             // This key's role. EDITOR is Editor.
  };
}
```

`role` is `EDITOR`, and `fileCount` is `0`. You can upload, update, and delete files, rename the Knowledge base, and share access without a separate share step.

### Example Response

```json theme={null}
{
  "status": "success",
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Product handbook",
    "description": "Internal product documentation",
    "createdAt": "2026-10-27T09:15:00.000Z",
    "updatedAt": "2026-10-27T09:15:00.000Z",
    "fileCount": 0,
    "role": "EDITOR"
  }
}
```

## Error Handling

| Status | Meaning |
| - | - |
| `400` | Invalid body, empty name, a field over 2000 characters, or an unknown field |
| `401` | Invalid or missing API key |
| `403` | Missing scope, a personal key, or the owner cannot upload documents |
| `429` | Rate limit exceeded |
| `500` | Unexpected server error |

A blank name, a field over 2000 characters, or an unknown field returns `400` with `"Invalid request"`.

A personal key returns `403` with `"This API key cannot create knowledge folders."`

When the key's owner lacks **Upload documents**, the response is `403` with `"This API key's owner does not have permission to upload documents."`

A missing scope returns `403` with `error` `INSUFFICIENT_SCOPES`.

> [!NOTE]
>
> Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](https://docs.langdock.com/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.