---
title: "Create folder"
method: POST
path: "/v1/folders"
tags: ["Folders"]
---

# Create folder

`POST /v1/folders`

Create a new folder. Folders can be nested up to 7 levels.

Folder paths are automatically generated based on hierarchy. Child folder paths include the paths of their parents.

## Request body

- object
  - `name` string, required — Name of the folder.
  - `parentFolderId` string, uuid — ID of the parent folder. Use the [List folders](/api/folders/list-folders) endpoint to retrieve folder IDs. Maximum nesting depth is 7 levels. A `400` error is returned when the limit is reached.
  - `scope` 'organization' | 'restricted' — Scope of the folder. - If no scope is provided and no parent folder exists, defaults to `organization` - If no scope is provided but a parent folder exists, inherits the parent folder's scope - Child folder scope must match the parent folder's scope
  - `userId` string, uuid — ID of the folder owner. Use the [List users](/api/users/list-users) or [List embed users](/api/users/list-embed-users) endpoints to retrieve user IDs.
  - `breadcrumbRoot` boolean — When `true`, breadcrumbs for this folder and its descendants start at this folder, hiding ancestor folders and the scope crumb (`Shared`, `<name>'s Documents`). This is useful for scoping navigation to a subtree, for example in embed use cases built around a specific `contentPath` folder.

## Response `201`

Folder created successfully

- object
  - `id` string, uuid — Unique identifier for the folder
  - `name` string — Display name of the folder
  - `path` string — Full path to the folder
  - `scope` 'organization' | 'restricted' — Visibility scope of the folder
  - `ownerId` string — ID of the user that owns the folder
  - `breadcrumbRoot` boolean — Whether breadcrumbs start at this folder

## Other responses

- `400` — Bad Request Possible error messages: - `Bad Request: Invalid JSON` - `Bad Request: name: Required` - `Bad Request: Maximum folder nesting depth reached` - `Bad Request: Child folder scope must match parent folder scope`
- `403` — Forbidden Possible error messages/causes: - `User-scoped API keys cannot act on behalf of other users` - Operations targeting personal/restricted scope require the user's **Personal content access** setting (`omni_allows_personal_content` system attribute) to be enabled for the user. If not enabled, the API will respond with `403 Forbidden`.
- `404` — Not Found Possible error messages: - `Parent folder with id <parentFolderId> does not exist` - `User with id <userId> does not exist`
- `429` — Too Many Requests - Rate limit exceeded (60 requests/minute)

---

[API](https://skmtc.net/omni/apis/omni-api.md) · [All operations](https://skmtc.net/omni/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omni/omni-api/revisions/6b02f7349d0e/schema)