---
title: "Create a folder"
method: POST
path: "/v1/folders"
---

# Create a folder

`POST /v1/folders`

## Request

- Base URL: `https://api.payaion.com`
- URL: `https://api.payaion.com/v1/folders`
- Auth: one of:
  - API key in header `X-Aion-Key`
  - HTTP bearer

Creates a folder, optionally nested under `parentId`. Sibling names are
unique case-insensitively, names cannot contain slashes or control
characters, and nesting stops at 8 levels.

## Request body

- object
  - `name` string, required
  - `parentId` string, nullable: Parent folder id. Omit or null for a top-level folder.

## Response `201`

Folder created

- Folder
  - `folderId` string, uuid
  - `name` string
  - `parentId` string, nullable

## Other responses

- `401`: Invalid or missing credentials
- `403`: Scope denied or access forbidden
- `404`: Resource not found
- `409`: A folder with that name already exists in the same parent
- `422`: A field failed validation
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/payaion/apis/payaion-api.md) · [All operations](https://skmtc.dev/payaion/apis/payaion-api/llms.txt) · [OpenAPI document](https://skmtc.dev/payaion/apis/payaion-api/revisions/29927240cfc2?raw)