# Create a folder { name, workspace, parentFolder? } `POST /folders` **Required scope:** `folders:write` Creating a duplicate under the same parent returns an "already exists" error. Re-list with parentFolder=all to get the existing id. Upload documents into a folder with POST /documents field folder=. ## Request body Content type: `application/json` (required) | Field | Type | Required | Description | |---|---|---|---| | `name` | string | **yes** | folder name (required) | | `workspace` | string | **yes** | workspace id (required) | | `parentFolder` | string | no | parent folder id (optional). Omit for a top-level folder. | ## Responses | Status | Meaning | |---|---| | `200` | Success | | `400` | BadRequest | | `401` | Unauthorized | | `403` | Forbidden | | `429` | RateLimited | ## Example ```bash curl -X POST "https://backend.immut.io/api/v1/folders" \ -H "Authorization: Bearer $IMMUT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"","workspace":"","parentFolder":""}' ``` ## OpenAPI fragment ```json { "/folders": { "post": { "operationId": "postfolders", "summary": "Create a folder { name, workspace, parentFolder? }. Creating a duplicate under the same parent returns an \"already exists\" error. Re-list with parentFolder=all to get the existing id. Upload documents into a folder with POST /documents field folder=.", "description": "Create a folder { name, workspace, parentFolder? }. Creating a duplicate under the same parent returns an \"already exists\" error. Re-list with parentFolder=all to get the existing id. Upload documents into a folder with POST /documents field folder=.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "folder name (required)" }, "workspace": { "type": "string", "description": "workspace id (required)" }, "parentFolder": { "type": "string", "description": "parent folder id (optional). Omit for a top-level folder." } }, "required": [ "name", "workspace" ] } } } }, "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Folders" ], "x-required-scope": "folders:write" } } } ```