Folders

Create a folder

POST/folders
documents:writecreate_folder

Creates a folder inside a folder you can see and returns it with a Location. parent_id is required: root folders belong to deals and users. It inherits the permissions above it and the token's user gets write. Needs write access to the folder, else 403 forbidden. 422 when the parent is unknown or not visible. 409 folder_name_taken when a live sibling has the name, 409 folder_locked when the parent is locked. dry_run previews it. Emits folder.created after commit, not on a dry run; no email. DELETE /folders/{id} undoes it.

Query parameters

  • dry_runboolean#

    Validate and run the call without committing it, returning what the real call would return with meta.dry_run set.

Headers

  • Idempotency-Keystring#

    Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.

Request body

application/json, required · FolderCreate

  • namestringRequired#

    The folder's name. A live sibling can't have the same name.

  • parent_idstring (uuid)Required#

    The folder to create it in. It must be a folder you can see; root folders can't be created.

  • metadataobject | null#

    Free-form key-value data kept with the folder.

  • lockedboolean#

    Whether to create it locked. Defaults to false.

  • hiddenboolean#

    Whether to create it hidden. Defaults to false.

  • pinnedboolean#

    Whether to create it pinned. Defaults to false.

  • releasedboolean#

    Whether its documents are released to the people it is shared with. Defaults to false.

  • accessobject#

    Groups of users who may read and write the folder without being listed in its permissions. Granting a group reaches subfolders and documents through inheritance.

{
  "name": "Due Diligence",
  "parent_id": "4e5f6071-8293-4a4b-9c6d-7e8f90112233"
}

Responses

201

The folder was created.

Folder
{
  "data": {
    "id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
    "name": "string",
    "parent_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
    "path": "string",
    "deal_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
    "namespace": "attachment.sig.root",
    "type_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
    "locked": true,
    "hidden": true,
    "pinned": true,
    "released": true,
    "access": {
      "internal_users": true,
      "deal_managers": true,
      "file_uploaders": true,
      "entrepreneurs": true
    },
    "metadata": {},
    "permissions": {},
    "created_at": "2026-06-12T10:00:00+00:00",
    "updated_at": "2026-06-12T10:00:00+00:00"
  }
}
401

Authentication failed. error.code is one of invalid_token, expired, revoked.

Error
403

Authorization failed. error.code is forbidden when the token's user can't write the folder: any folder in the tree of a deal the token can see is writable, otherwise the folder's write list, write flags or super admin are needed. This is deliberately broader than the platform (no editor-role check) and stricter (the check applies where the platform skips it by role). Other codes are missing_scope, scope_disabled, org_disabled, ip_blocked, user_disabled.

Error
409

The request conflicts with the folder's state. error.code is folder_name_taken (a live sibling has the name), folder_locked (the folder or its parent is locked), folder_cycle (a move into itself or a subfolder), folder_deleted (the parent is deleted) invalid_state (a root folder, which can't be deleted or restored) or conflict (on delete: the folder or a subfolder holds a file a deal or team member uses as an image).

Error
422

The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per problem, or a code documented on the operation.

Error
429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl -X POST https://your-org-domain/kong/core/api/v2/folders\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "name": "Due Diligence",
  "parent_id": "4e5f6071-8293-4a4b-9c6d-7e8f90112233"
}'