---
title: "Create a new Folder"
method: POST
path: "/folders"
tags: ["Folders"]
---

# Create a new Folder

`POST /folders`

## Request

- Base URL: `https://api.carbonvoice.app`
- URL: `https://api.carbonvoice.app/folders`
- Auth: one of:
  - API key in header `pxtoken`
  - OAuth 2 (implicit, authorization URL `https://api.carbonvoice.app/oauth/authorize`)

## Request body

- CreateFolderPayload
  - `name` string, required: Name of the Folder
  - `type` 'voicememo' | 'prerecorded', required: Folder type
  - `workspace_id` string, required: Workspace ID
  - `parent_folder_id` string: Parent Folder ID

## Response `200`

- Folder
  - `id` string, required: Unique Identifier
  - `name` string, required: Name
  - `creator_id` string, required: Creator
  - `parent_folder_id` string: Parent Folder ID
  - `subfolder_ids` string[]: List of Subfolder IDs
  - `message_ids` string[]: List of Message IDs
  - `path` string[]: Ordered List of all folders in the path from root to this folder
  - `total_nested_folders_count` number, required: Total count for all Nested Folders
  - `total_nested_messages_count` number, required: Total count for all Nested Messages
  - `type` 'voicememo' | 'prerecorded', required: Folder type
  - `workspace_id` string, required: Workspace ID where folder belongs to
  - `created_at` string, date-time, required
  - `last_updated_at` string, date-time, required
  - `deleted_at` string, date-time
  - `subfolders` SubFolder[]: Subfolders (only one deep level)
    - `id` string, required: Unique Identifier
    - `name` string, required: Name
    - `creator_id` string, required: Creator
    - `parent_folder_id` string: Parent Folder ID
    - `subfolder_ids` string[]: List of Subfolder IDs
    - `message_ids` string[]: List of Message IDs
    - `path` string[]: Ordered List of all folders in the path from root to this folder
    - `total_nested_folders_count` number, required: Total count for all Nested Folders
    - `total_nested_messages_count` number, required: Total count for all Nested Messages
    - `type` 'voicememo' | 'prerecorded', required: Folder type
    - `workspace_id` string, required: Workspace ID where folder belongs to
    - `created_at` string, date-time, required
    - `last_updated_at` string, date-time, required
    - `deleted_at` string, date-time

## Other responses

- `400`
- `403`

---

[API](https://skmtc.dev/carbonvoice/apis/carbon-voice-api.md) · [All operations](https://skmtc.dev/carbonvoice/apis/carbon-voice-api/llms.txt) · [OpenAPI document](https://skmtc.dev/carbonvoice/apis/carbon-voice-api/revisions/b91c5c845122?raw)