---
title: "Create a folder or subfolder"
method: POST
path: "/folders"
tags: ["Folders"]
---

# Create a folder or subfolder

`POST /folders`

## Request

- Base URL: `https://api.braiv.co/v1`
- URL: `https://api.braiv.co/v1/folders`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Creates a Studio folder in the bound personal or workspace library.
Omit `parentId` for a root folder. Nesting is limited to 3 levels.
The reserved name All Videos cannot be created or used as a parent.
Required scope: `videos:write`.

## Headers

- `Idempotency-Key` string

## Request body

- CreateFolderRequest
  - `name` string, required: Folder display name. All Videos is reserved.
  - `parentId` string: Existing folder id in the same library. Omit to create a root folder. Max nesting is 3 levels.

## Response `201`

Folder created.

- Folder
  - `id` string, required: Studio folder id. Pass as folderId on createVideo.
  - `name` string, required: Display name.
  - `parentId` string, nullable, required: Parent folder id, or null at the library root.
  - `path` string[], required: Ancestor names from the root through this folder.
  - `workspaceId` string: Present when the folder belongs to a workspace library.

## Other responses

- `400`: Request fields are missing, malformed, out of bounds, or mutually inconsistent.
- `401`: A supported authentication header is missing or contains an invalid Public API key.
- `403`: Authentication succeeded, but the required scope, workspace role, or resource permission is missing.
- `404`: The resource does not exist or is not accessible to the caller.
- `429`: The API key exceeded its allowed concurrency or request rate. Retry after in-flight work completes or the limit resets.
- `500`: An unexpected server error occurred.

---

[API](https://skmtc.dev/braiv/apis/braiv-public-api.md) - [All operations](https://skmtc.dev/braiv/apis/braiv-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/braiv/apis/braiv-public-api/revisions/8ed0fd0d0a6f?raw)