---
title: "Create a folder"
method: POST
path: "/folders"
tags: ["Files"]
---

# Create a folder

`POST /folders`

## Request

- Base URL: `https://api.parley.so/v1`
- URL: `https://api.parley.so/v1/folders`
- Auth: HTTP bearer

Create a folder in a project, account, contact, intake, or the Library, at the top level or inside another folder: pass exactly one of projectId, accountId, contactId, intakeId, or library. If a folder with that name is already there, a number is appended, as in "Evidence (2)". The folder is a file of type folder, read and changed at /files/{id}.

## Request body

- object
  - `projectId` string: Create it in this project's files. Pass exactly one of projectId, accountId, contactId, intakeId, or library.
  - `accountId` string: Create it in this account's files. Pass exactly one of projectId, accountId, contactId, intakeId, or library.
  - `contactId` string: Create it in this contact's files. Pass exactly one of projectId, accountId, contactId, intakeId, or library.
  - `intakeId` string: Create it in this intake's files. Pass exactly one of projectId, accountId, contactId, intakeId, or library.
  - `library` unknown
  - `name` string, required: Folder name. If a folder with this name is already there, a number is appended, as in "Evidence (2)".
  - `folderId` string: Put it inside this folder. Omit for the top level.

## Response `201`

Created.

- union: A file or a folder, told apart by type.
  - FileItem
    - `type` 'file', required
    - `id` string, required: The file or folder ID.
    - `name` string, required: The name, including any file extension.
    - `location` union, required: Whose files these are: a project's, an account's, a contact's, or an intake's, or the organization's Library.
      - RecordRef: A reference to a project, account, or contact.
        - `type` 'project' | 'account' | 'contact', required: The kind of record: project, account, or contact.
        - `id` string, required: Its ID.
        - `name` string, required: The record's name. A contact's is its first and last name, or an email address when it has no name.
      - object: The intake's type, ID, and name.
        - `type` 'intake', required
        - `id` string, required: Its ID.
        - `name` string, required: The intake title.
      - object: The organization's shared Library.
        - `type` 'library', required
    - `folder` object, nullable, required: The folder's type, ID, and name.
      - `type` 'folder', required
      - `id` string, required: Its ID.
      - `name` string, required: The folder name.
    - `createdAt` string, date-time, required: When it was added.
    - `updatedAt` string, date-time, required: When it was last updated, including processing, renames, and moves.
    - `mediaType` string, nullable, required: The file's media type, such as application/pdf, from its extension, or null when the extension isn't recognized.
    - `status` 'pending' | 'processing' | 'ready' | 'failed', required: Whether Parley has extracted the file's text: pending (queued), processing, ready (its text can be read), or failed (download it instead).
  - FolderItem
    - `type` 'folder', required
    - `id` string, required: The file or folder ID.
    - `name` string, required: The name, including any file extension.
    - `location` union, required: Whose files these are: a project's, an account's, a contact's, or an intake's, or the organization's Library.
      - RecordRef: A reference to a project, account, or contact.
        - `type` 'project' | 'account' | 'contact', required: The kind of record: project, account, or contact.
        - `id` string, required: Its ID.
        - `name` string, required: The record's name. A contact's is its first and last name, or an email address when it has no name.
      - object: The intake's type, ID, and name.
        - `type` 'intake', required
        - `id` string, required: Its ID.
        - `name` string, required: The intake title.
      - object: The organization's shared Library.
        - `type` 'library', required
    - `folder` object, nullable, required: The folder's type, ID, and name.
      - `type` 'folder', required
      - `id` string, required: Its ID.
      - `name` string, required: The folder name.
    - `createdAt` string, date-time, required: When it was added.
    - `updatedAt` string, date-time, required: When it was last updated, including processing, renames, and moves.

## Other responses

- `400`: The request was invalid. VALIDATION_FAILED, INVALID_REFERENCE.
- `401`: Missing or invalid credentials. UNAUTHORIZED.
- `403`: You don't have permission. FORBIDDEN.
- `429`: Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS.

## Changes

- **2026-11-02** `6b78aeee07bc`: 1 breaking
  - added the pattern `^[^\p{Cc}\p{Bidi_Control}]*$` to the request property `name`

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

---

[API](https://skmtc.dev/parley/apis/parley-api.md) - [All operations](https://skmtc.dev/parley/apis/parley-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parley/apis/parley-api/revisions/6b78aeee07bc?raw)