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

# Create Folder

> POST /v1/folders

# Create Folder

```
POST /v1/folders
```

Create a new folder. Requires the `folders:write` role.

## Request

### Headers

| Header         | Required | Description        |
| -------------- | -------- | ------------------ |
| `X-API-Key`    | Yes      | Your API key       |
| `Content-Type` | Yes      | `application/json` |

### Body

| Field       | Type   | Required | Description                  |
| ----------- | ------ | -------- | ---------------------------- |
| `name`      | string | Yes      | Folder name                  |
| `parent_id` | string | No       | Parent folder ID for nesting |

### Example

```bash theme={null}
curl -X POST https://api.surfacedocs.dev/v1/folders \
  -H "X-API-Key: sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Engineering"}'
```

## Response

**Status: 201 Created**

```json theme={null}
{
  "id": "fld_abc123",
  "name": "Engineering",
  "parent_id": null,
  "path": "/Engineering",
  "depth": 0,
  "created_at": "2025-01-15T10:30:00Z"
}
```

## Errors

| Code | Description             |
| ---- | ----------------------- |
| 404  | Parent folder not found |