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

# Create Folder

`POST /v2/folders`

## Request

- Base URL: `https://api.lucid.co`
- URL: `https://api.lucid.co/v2/folders`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://lucid.app/oauth2/authorize`
    - Token URL: `https://api.lucid.co/oauth2/token` scopes: `folder`, `lucidchart.document.app.folder`, `lucidspark.document.app.folder`, `lucidscale.document.app.folder`
- TypeScript: <https://skmtc.dev/lucid/apis/lucid-rest-api/docs/v2/folders/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new folder.

## Valid Authentication Methods

**API Key Grants:**
- `FolderEdit`

**OAuth 2.0 User Token Scopes:**
- `folder`
- `lucidchart.document.app.folder`
- `lucidspark.document.app.folder`
- `lucidscale.document.app.folder`

## Request body

- object
  - `name` string, required: Name of the folder being created.
  - `type` 'folder' | 'team', required: * folder - Folders can live in other folders, team folders, or the root of a user’s folder manager ("My Documents"). A folder in "My Documents" will have a null parent field. * team - Team folders can never live in another folder and are always located in the "Team Folders" section of a user's folder manager. Team folders will not have a parent field. Learn more
  - `parent` union: Destination folder, repository, or Team to create the new folder in. For repositories, use the repository ID prefixed with `repo_` (e.g., `repo_12345`). For Teams, use the Team ID prefixed with `team_` (e.g., `team_99`), which creates the folder in the root of that Team. For folders, use the numeric folder ID. If it is not provided, the folder will be created in the root of the user's folder manager ("My Documents"). Ignored when `appFolder` is set to `true`. With only app-folder scope, an explicit parent must be inside the authenticated user's app project.
    - integer, nullable: Numeric folder ID.
    - string: Repository ID prefixed with `repo_`, or Team ID prefixed with `team_`.
  - `team` string: Deprecated. Team whose root should contain the new folder, as an ID prefixed with `team_`; the legacy numeric team ID is also accepted. Use `parent` with a `team_`-prefixed Team ID instead. Cannot be provided together with a Team `parent`.
  - `appFolder` boolean: When set to `true`, the folder is created inside the OAuth2 client's app project folder, overriding the `parent` field. With only a `document.app.folder` scope, omit this field or set it to `false` and supply a parent inside the app project to create a nested folder.

## Response `201`

Created with a Folder resource containing information about the newly created folder.

- FolderWithRepositoryV2: A standard representation of a folder. A folder at the root of a Team reports that Team as its parent.
  - `id` number, required: Unique ID of the folder
  - `type` 'folder' | 'team', required: * folder - Folders can live in other folders, team folders, or the root of a user’s folder manager ("My Documents"). A folder in "My Documents" will have a null parent field. * team - Team folders can never live in another folder and are always located in the "Team Folders" section of a user's folder manager. Team folders will not have a parent field. Learn more
  - `name` string, required: Name of the folder
  - `parent` union: Where the folder lives: the numeric ID of the parent folder, or the `team_`-prefixed ID of the Team whose root contains it. Null for a folder at the root of the user's folder manager ("My Documents").
    - number, nullable
    - string
  - `created` string, date-time, required: Date and time of when the folder was created
  - `trashed` string, date-time, nullable: Date and time of when the folder was trashed. Null when the folder is not trashed.
  - `attributes` FolderAttribute[]: An array of attributes assigned to the folder. Can be null or empty.
    - `name` string: Name of the attribute
    - `value` string: Value of the attribute. Can be any type, but attributes with the same name will always have the same type.
  - `repository` Repository
    - `repositoryId` string: the ID of the repository

## Other responses

- `400`: Bad Request. * A team folder cannot be created within another folder or team. * Both a Team `parent` and a `team` were provided. * Invalid parent ID. Must be a number (for folders), a string prefixed with repo_ (for repositories), or a string prefixed with team_ (for Teams). * When using a `document.app.folder` scope, `appFolder` cannot be false without a `parent`, a `team` cannot be supplied, the folder type must be `folder`, and an explicit `parent` must be a folder ID rather than a repository.
- `403`: Forbidden if the request is not authorized to create in the specified `parent` folder, repository, or Team, if the specified Team does not exist, or when using a `document.app.folder` scope without either `appFolder: true` or a parent inside the app project.

## Changes

- **2026-11-03** `9c2c917ec59c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/lucid/apis/lucid-rest-api/changes/v2/folders/post.md)

---

[API](https://skmtc.dev/lucid/apis/lucid-rest-api.md) - [All operations](https://skmtc.dev/lucid/apis/lucid-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lucid/apis/lucid-rest-api/revisions/9c2c917ec59c?raw)