---
title: "Create folder"
method: POST
path: "/knowledgeBase/{kbId}/folder"
tags: ["Knowledge Base"]
---

# Create folder

`POST /knowledgeBase/{kbId}/folder`

Create a folder in a knowledge base. Omit `folderId` to create at the KB root;
pass `folderId` as a query parameter to create a nested subfolder inside an
existing parent folder.

**Required permission:** WRITER or higher

**Folder features:**

- Organize records hierarchically
- Support nested subfolders (unlimited depth)
- Inherit parent KB permissions

**Naming rules:**

- 1–255 characters
- XSS protection applied
- Spaces and special characters allowed
- Duplicate names rejected within the same parent (`409`)

**Response:** Returns `id` and `name` for the created folder.

## Path parameters

- `kbId` string, required

## Query parameters

- `folderId` string

## Request body

- object
  - `folderName` string, required — Name of the folder

## Response `200`

Folder created successfully

- FolderCreateResponseSchema — Response returned when a folder is created (root or nested subfolder)
  - `id` string, required — Unique folder identifier
  - `name` string, required — Name of the folder

## Other responses

- `400` — Invalid request. Possible reasons: - Missing or empty folder name - Folder name exceeds 255 characters - XSS or invalid characters in folder name
- `401` — Unauthorized - Valid bearer token required
- `403` — Forbidden. Possible reasons: - OAuth token lacks the `kb:write` scope - User lacks WRITER or higher permission on the knowledge base
- `404` — Knowledge base or parent folder not found
- `409` — Folder with this name already exists at the knowledge base root or within the parent folder
- `500` — Internal server error while creating folder
- `503` — Connector service unavailable or connection refused

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/versions/abd27cfefc73/schema)