Folders

Update a folder

PATCH/folders/{id}
documents:writeupdate_folderIdempotent

Changes the fields you send and returns the folder: rename, move, merge metadata, set access keys, lock or unlock, hide, pin, release. A move rewrites the hierarchy and inherited permissions, subfolders and documents too. 409 folder_name_taken, folder_cycle (into itself or a subfolder) or folder_locked (a locked folder or target, unless the call unlocks it). namespace, deal_id, permissions are read-only. Needs write access to the folder, else 403 forbidden. Emits folder.updated after commit; no email. Sending the old values undoes it, except inherited permissions.

Path parameters

  • idstring (uuid)Required#

    The record's id.

Query parameters

  • dry_runboolean#

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

Request body

application/json, required · FolderUpdate

  • namestring#

    The new name. A live sibling can't have the same name; a locked folder can't be renamed.

  • parent_idstring (uuid)#

    The folder to move it into. It must be a folder you can see, and not the folder itself or one of its subfolders. Permissions inherited from the old ancestors are stripped and the new ones inherited, through subfolders and documents.

  • metadataobject | null#

    Keys to merge into the folder's metadata. A null value removes that key.

  • lockedboolean#

    Whether the folder is locked. Send false to unlock it, which the platform never does.

  • hiddenboolean#

    Whether the folder is hidden.

  • pinnedboolean#

    Whether the folder is pinned.

  • releasedboolean#

    Whether its documents are released to the people it is shared with. Recomputed through subfolders and documents.

  • 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. On update only the keys you send change.

{
  "name": "Due Diligence (Final)",
  "pinned": true
}

Responses

200

The updated folder.

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
404

Resource not found (error.code = not_found).

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 PATCH https://your-org-domain/kong/core/api/v2/folders/{id}\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "name": "Due Diligence (Final)",
  "pinned": true
}'