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

# POST /v1/knowledge/folders

> Create a folder in the knowledge base, optionally nested under another folder.

Creates an empty folder in the knowledge base. Folders are containers: they group documents and other folders, but have no content of their own. To create documents use [`POST /v1/knowledge/documents`](/dev/endpoints/knowledge-document-create).

## Endpoint

```
POST https://api.keebai.com/v1/knowledge/folders
```

## Required scope

`knowledge:write`

## Headers

| Header          | Required | Value                    |
| --------------- | -------- | ------------------------ |
| `Authorization` | Yes      | `Bearer kbai_pk_<token>` |
| `Content-Type`  | Yes      | `application/json`       |

## Body

| Field       | Type     | Required | Description                                                  |
| ----------- | -------- | -------- | ------------------------------------------------------------ |
| `title`     | `string` | Yes      | Folder name. Max. 200 characters.                            |
| `parent_id` | `string` | No       | `ObjectId` of the parent folder. Omit to create at the root. |

## Example request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.keebai.com/v1/knowledge/folders \
    -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Soporte",
      "parent_id": "65f3a1b2c3d4e5f6a7b8c9d0"
    }'
  ```

  ```js JavaScript theme={null}
  const resp = await fetch("https://api.keebai.com/v1/knowledge/folders", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Soporte",
      parent_id: "65f3a1b2c3d4e5f6a7b8c9d0",
    }),
  });
  const folder = await resp.json();
  ```

  ```python Python theme={null}
  import os, requests

  resp = requests.post(
      "https://api.keebai.com/v1/knowledge/folders",
      headers={
          "Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}",
          "Content-Type": "application/json",
      },
      json={"title": "Soporte", "parent_id": "65f3a1b2c3d4e5f6a7b8c9d0"},
      timeout=10,
  )
  resp.raise_for_status()
  folder = resp.json()
  ```
</CodeGroup>

## Response

### 201 Created

```json theme={null}
{
  "id": "65f3a1b2c3d4e5f6a7b8c9d2",
  "title": "Soporte",
  "node_type": "folder",
  "parent_id": "65f3a1b2c3d4e5f6a7b8c9d0",
  "position": 3,
  "path_cache": "/Catálogo/Soporte",
  "created_at": "2026-04-27T15:30:00.000Z",
  "updated_at": "2026-04-27T15:30:00.000Z"
}
```

| Field        | Type             | Description                                |
| ------------ | ---------------- | ------------------------------------------ |
| `id`         | `string`         | `ObjectId` of the newly created node.      |
| `title`      | `string`         | Saved title.                               |
| `node_type`  | `string`         | Always `folder`.                           |
| `parent_id`  | `string \| null` | Parent if provided, `null` if at the root. |
| `position`   | `number`         | Assigned position (last in its level).     |
| `path_cache` | `string`         | Absolute path computed at creation.        |

### 400 / 401 / 403 / 404 / 429

* `400 BAD_REQUEST`: `title` empty or longer than 200, `parent_id` with invalid format, or `parent_id` pointing to a document (not a folder).
* `403 FORBIDDEN` with `code: INSUFFICIENT_SCOPE`: the PAT doesn't have `knowledge:write`.
* `404 NOT_FOUND`: the `parent_id` doesn't exist or doesn't belong to your company.


## OpenAPI

````yaml POST /v1/knowledge/folders
openapi: 3.0.0
info:
  title: Keebai Public API
  description: Superficie pública REST autenticada con Personal Access Tokens (PAT).
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.keebai.com
    description: Production
security: []
tags: []
paths:
  /v1/knowledge/folders:
    post:
      tags:
        - knowledge
      summary: Crear una carpeta en la base de conocimientos.
      operationId: PublicKnowledgeController_createFolder
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFolderDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeNodeDto'
      security:
        - PAT: []
components:
  schemas:
    CreateFolderDto:
      type: object
      properties:
        title:
          type: string
          description: Título de la carpeta.
          example: Soporte
          maxLength: 200
        parent_id:
          type: string
          description: ObjectId de la carpeta padre. Omitir para crear en la raíz.
      required:
        - title
    KnowledgeNodeDto:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        node_type:
          type: string
          enum:
            - folder
            - document
        parent_id:
          type: object
          nullable: true
        position:
          type: number
        path_cache:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
      required:
        - id
        - title
        - node_type
        - position
        - path_cache
  securitySchemes:
    PAT:
      scheme: bearer
      bearerFormat: kbai_pk_<hex>
      type: http
      description: >-
        Personal Access Token con prefijo `kbai_pk_`. Generar desde el portal
        con permiso `developer.manage_tokens`.

````