--- title: "Upgrade a folder" method: POST path: "/metadata/upgrade/folders.json" tags: ["Metadata upgrade"] --- # Upgrade a folder `POST /metadata/upgrade/folders.json` ## Request - Base URL: `https://passbolt.local` - URL: `https://passbolt.local/metadata/upgrade/folders.json` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) > *Encrypted metadata for this item is not supported on all clients.* Upgrade folders that are eligible for an upgrade to v5 format. ## Query parameters - `contain[permissions]` 1 | 0 ## Request body - E2eeMetadataBasedIdModifiedModifiedBy[] - `metadata` string, required: An armoured OpenPGP message. Its cleartext is a JSON object carrying an `object_type` field that names the payload, `PASSBOLT_RESOURCE_METADATA` for a resource, and the descriptive fields that used to travel in clear in the v4 format. The fields expected for a resource, and the two decryption paths, are described in the guide on working with v5 encrypted metadata. - `metadata_key_id` string, uuid, required - `metadata_key_type` 'user_key' | 'shared_key', required - `id` string, uuid, required - `modified` string, date-time, required - `modified_by` string, uuid, required ## Response `200` Operation is successful. - object - `header` HeaderWithPagination, required - `id` string, uuid, required - `status` 'success' | 'error', required - `servertime` integer, required - `action` string, uuid, required - `message` string, required - `url` string, uri, required - `code` integer, required - `pagination` object, required - `count` integer, required - `page` integer, required - `limit` integer, required - `body` FolderV4IndexAndView[], required - `id` string, uuid, required - `name` string, required - `created` string, date-time, required - `modified` string, date-time, required - `created_by` string, uuid, required - `modified_by` string, uuid, required - `folder_parent_id` string, uuid, required - `personal` boolean, required - `modifier` UserIndexAndView - `is_mfa_enabled` boolean - `id` string, uuid, required - `role_id` string, uuid, required - `username` string, required - `active` boolean, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `disabled` string, date-time, required - `profile` object - `id` string, uuid, required - `user_id` string, uuid, required - `first_name` string, required - `last_name` string, required - `created` string, date-time, required - `modified` string, date-time, required - `avatar` object, required - `id` string, uuid - `profile_id` string, uuid - `created` string, date-time - `modified` string, date-time - `url` object, required - `medium` string, url, required - `small` string, url, required - `groups_users` GroupsUsersIndexAndView - `id` string, uuid, required - `group_id` string, uuid, required - `user_id` string, uuid, required - `is_admin` boolean, required - `created` string, date-time, required - `user` UserIndexAndView (recursive) - `gpgkey` Gpgkey - `id` string, uuid, required - `user_id` string, uuid, required - `armored_key` string, required - `bits` integer, required - `uid` string, required - `key_id` string, required - `fingerprint` string, required - `type` 'RSA' | 'ECC', required - `expires` string, date-time, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `role` Role - `id` string, uuid, required - `name` 'admin' | 'guest' | 'user', required - `description` string, required - `created` string, date-time, required - `modified` string, date-time, required - `missing_metadata_key_ids` string[] - `last_logged_in` string, date-time - `creator` UserIndexAndView - `is_mfa_enabled` boolean - `id` string, uuid, required - `role_id` string, uuid, required - `username` string, required - `active` boolean, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `disabled` string, date-time, required - `profile` object - `id` string, uuid, required - `user_id` string, uuid, required - `first_name` string, required - `last_name` string, required - `created` string, date-time, required - `modified` string, date-time, required - `avatar` object, required - `id` string, uuid - `profile_id` string, uuid - `created` string, date-time - `modified` string, date-time - `url` object, required - `medium` string, url, required - `small` string, url, required - `groups_users` GroupsUsersIndexAndView - `id` string, uuid, required - `group_id` string, uuid, required - `user_id` string, uuid, required - `is_admin` boolean, required - `created` string, date-time, required - `user` UserIndexAndView (recursive) - `gpgkey` Gpgkey - `id` string, uuid, required - `user_id` string, uuid, required - `armored_key` string, required - `bits` integer, required - `uid` string, required - `key_id` string, required - `fingerprint` string, required - `type` 'RSA' | 'ECC', required - `expires` string, date-time, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `role` Role - `id` string, uuid, required - `name` 'admin' | 'guest' | 'user', required - `description` string, required - `created` string, date-time, required - `modified` string, date-time, required - `missing_metadata_key_ids` string[] - `last_logged_in` string, date-time - `permission` PermissionIndexAndView - `id` string, uuid, required - `aco` 'Resource' | 'Folder', required - `aco_foreign_key` string, uuid, required - `aro` 'User' | 'Group', required - `aro_foreign_key` string, uuid, required - `type` 1 | 7 | 15, required: * `1` - Read * `7` - Update * `15` - Owner - `created` string, date-time, required - `modified` string, date-time, required - `user` UserIndexAndView - `is_mfa_enabled` boolean - `id` string, uuid, required - `role_id` string, uuid, required - `username` string, required - `active` boolean, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `disabled` string, date-time, required - `profile` object - `id` string, uuid, required - `user_id` string, uuid, required - `first_name` string, required - `last_name` string, required - `created` string, date-time, required - `modified` string, date-time, required - `avatar` object, required - `id` string, uuid - `profile_id` string, uuid - `created` string, date-time - `modified` string, date-time - `url` object, required - … - `groups_users` GroupsUsersIndexAndView - `id` string, uuid, required - `group_id` string, uuid, required - `user_id` string, uuid, required - `is_admin` boolean, required - `created` string, date-time, required - `user` UserIndexAndView (recursive) - `gpgkey` Gpgkey - `id` string, uuid, required - `user_id` string, uuid, required - `armored_key` string, required - `bits` integer, required - `uid` string, required - `key_id` string, required - `fingerprint` string, required - `type` 'RSA' | 'ECC', required - `expires` string, date-time, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `role` Role - `id` string, uuid, required - `name` 'admin' | 'guest' | 'user', required - `description` string, required - `created` string, date-time, required - `modified` string, date-time, required - `missing_metadata_key_ids` string[] - `last_logged_in` string, date-time - `group` GroupIndexAndView - `id` string, uuid, required - `name` string, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `created_by` string, uuid, required - `modified_by` string, uuid, required - `my_group_user` GroupsUsersIndexAndView - `id` string, uuid, required - `group_id` string, uuid, required - `user_id` string, uuid, required - `is_admin` boolean, required - `created` string, date-time, required - `user` UserIndexAndView - `is_mfa_enabled` boolean - `id` string, uuid, required - `role_id` string, uuid, required - `username` string, required - `active` boolean, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `disabled` string, date-time, required - `profile` object - … - `groups_users` GroupsUsersIndexAndView (recursive) - `gpgkey` Gpgkey - … - `role` Role - … - `missing_metadata_key_ids` string[] - `last_logged_in` string, date-time - `groups_users` GroupsUsersIndexAndView[] - `id` string, uuid, required - `group_id` string, uuid, required - `user_id` string, uuid, required - `is_admin` boolean, required - `created` string, date-time, required - `user` UserIndexAndView - `is_mfa_enabled` boolean - `id` string, uuid, required - `role_id` string, uuid, required - `username` string, required - `active` boolean, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `disabled` string, date-time, required - `profile` object - … - `groups_users` GroupsUsersIndexAndView (recursive) - `gpgkey` Gpgkey - … - `role` Role - … - `missing_metadata_key_ids` string[] - `last_logged_in` string, date-time - `user_count` integer - `permissions` PermissionIndexAndView[] - `id` string, uuid, required - `aco` 'Resource' | 'Folder', required - `aco_foreign_key` string, uuid, required - `aro` 'User' | 'Group', required - `aro_foreign_key` string, uuid, required - `type` 1 | 7 | 15, required: * `1` - Read * `7` - Update * `15` - Owner - `created` string, date-time, required - `modified` string, date-time, required - `user` UserIndexAndView - `is_mfa_enabled` boolean - `id` string, uuid, required - `role_id` string, uuid, required - `username` string, required - `active` boolean, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `disabled` string, date-time, required - `profile` object - `id` string, uuid, required - `user_id` string, uuid, required - `first_name` string, required - `last_name` string, required - `created` string, date-time, required - `modified` string, date-time, required - `avatar` object, required - `id` string, uuid - `profile_id` string, uuid - `created` string, date-time - `modified` string, date-time - `url` object, required - … - `groups_users` GroupsUsersIndexAndView - `id` string, uuid, required - `group_id` string, uuid, required - `user_id` string, uuid, required - `is_admin` boolean, required - `created` string, date-time, required - `user` UserIndexAndView (recursive) - `gpgkey` Gpgkey - `id` string, uuid, required - `user_id` string, uuid, required - `armored_key` string, required - `bits` integer, required - `uid` string, required - `key_id` string, required - `fingerprint` string, required - `type` 'RSA' | 'ECC', required - `expires` string, date-time, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `role` Role - `id` string, uuid, required - `name` 'admin' | 'guest' | 'user', required - `description` string, required - `created` string, date-time, required - `modified` string, date-time, required - `missing_metadata_key_ids` string[] - `last_logged_in` string, date-time - `group` GroupIndexAndView - `id` string, uuid, required - `name` string, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `created_by` string, uuid, required - `modified_by` string, uuid, required - `my_group_user` GroupsUsersIndexAndView - `id` string, uuid, required - `group_id` string, uuid, required - `user_id` string, uuid, required - `is_admin` boolean, required - `created` string, date-time, required - `user` UserIndexAndView - `is_mfa_enabled` boolean - `id` string, uuid, required - `role_id` string, uuid, required - `username` string, required - `active` boolean, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `disabled` string, date-time, required - `profile` object - … - `groups_users` GroupsUsersIndexAndView (recursive) - `gpgkey` Gpgkey - … - `role` Role - … - `missing_metadata_key_ids` string[] - `last_logged_in` string, date-time - `groups_users` GroupsUsersIndexAndView[] - `id` string, uuid, required - `group_id` string, uuid, required - `user_id` string, uuid, required - `is_admin` boolean, required - `created` string, date-time, required - `user` UserIndexAndView - `is_mfa_enabled` boolean - `id` string, uuid, required - `role_id` string, uuid, required - `username` string, required - `active` boolean, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `disabled` string, date-time, required - `profile` object - … - `groups_users` GroupsUsersIndexAndView (recursive) - `gpgkey` Gpgkey - … - `role` Role - … - `missing_metadata_key_ids` string[] - `last_logged_in` string, date-time - `user_count` integer - `children_resources` union[] - union - ResourceV4IndexAndView - `id` string, uuid, required - `name` string, required - `username` string, required - `uri` string, required - `description` string, required - `deleted` boolean, required - `created` string, date-time, required - `created_by` string, uuid, required - `modified_by` string, uuid, required - `resource_type_id` string, uuid, required - `expired` string, date-time, required - `folder_parent_id` string, uuid, required - `personal` boolean, required - `favorite` Favorite - `id` string, uuid, required - `user_id` string, uuid, required - `foreign_key` string, uuid, required - `foreign_model` 'Resource', required - `created` string, date-time, required - `modified` string, date-time, required - `modifier` UserIndexAndView - `is_mfa_enabled` boolean - `id` string, uuid, required - `role_id` string, uuid, required - `username` string, required - `active` boolean, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `disabled` string, date-time, required - `profile` object - … - `groups_users` GroupsUsersIndexAndView - … - `gpgkey` Gpgkey - … - `role` Role - … - `missing_metadata_key_ids` string[] - `last_logged_in` string, date-time - `creator` UserIndexAndView - `is_mfa_enabled` boolean - `id` string, uuid, required - `role_id` string, uuid, required - `username` string, required - `active` boolean, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `disabled` string, date-time, required - `profile` object - … - `groups_users` GroupsUsersIndexAndView - … - `gpgkey` Gpgkey - … - `role` Role - … - `missing_metadata_key_ids` string[] - `last_logged_in` string, date-time - `secrets` SecretIndex[] - `id` string, uuid, required - `user_id` string, uuid, required - `resource_id` string, uuid, required - `data` string, required - `created` string, date-time, required - `modified` string, date-time, required - `resource_type` ResourceType - `id` string, uuid, required - `slug` 'password-string' | 'password-and-description' | 'totp' | 'password-description-totp' | 'v5-default-with-totp' | 'v5-password-string (Deprecated)' | 'v5-totp-standalone' | 'v5-default', required: * `password-string` - The original passbolt resource type, where the secret is a non empty string. * `password-and-description` - A resource with the password and the description encrypted. * `totp` - A resource with standalone TOTP fields. * `password-description-totp` - A resource with encrypted password, description and TOTP fields. * `v5-default-with-totp` - The new default resource type with a TOTP introduced with v5. * `v5-password-string (Deprecated)` - The original passbolt resource type, kept for backward compatibility reasons. * `v5-totp-standalone` - The new standalone TOTP resource type introduced with v5. * `v5-default` - The new default resource type introduced with v5. - `name` string, required - `description` string, required - `definition` object, required: Schema for the expected data for this kind of resources. - `deleted` string, required - `created` string, date-time, required - `modified` string, date-time, required - `permission` PermissionIndexAndView - `id` string, uuid, required - `aco` 'Resource' | 'Folder', required - `aco_foreign_key` string, uuid, required - `aro` 'User' | 'Group', required - `aro_foreign_key` string, uuid, required - `type` 1 | 7 | 15, required: * `1` - Read * `7` - Update * `15` - Owner - `created` string, date-time, required - `modified` string, date-time, required - `user` UserIndexAndView - … - `group` GroupIndexAndView - … - `permissions` PermissionIndexAndView[] - `id` string, uuid, required - `aco` 'Resource' | 'Folder', required - `aco_foreign_key` string, uuid, required - `aro` 'User' | 'Group', required - `aro_foreign_key` string, uuid, required - `type` 1 | 7 | 15, required: * `1` - Read * `7` - Update * `15` - Owner - `created` string, date-time, required - `modified` string, date-time, required - `user` UserIndexAndView - … - `group` GroupIndexAndView - … - ResourceV5IndexAndView - `metadata` string, required: An armoured OpenPGP message. Its cleartext is a JSON object carrying an `object_type` field that names the payload, `PASSBOLT_RESOURCE_METADATA` for a resource, and the descriptive fields that used to travel in clear in the v4 format. The fields expected for a resource, and the two decryption paths, are described in the guide on working with v5 encrypted metadata. - `metadata_key_id` string, uuid, required - `metadata_key_type` 'user_key' | 'shared_key', required - `id` string, uuid, required - `created` string, date-time, required - `modified` string, date-time, required - `created_by` string, uuid, required - `modified_by` string, uuid, required - `personal` boolean, required - `folder_parent_id` string, uuid, required - `modifier` UserIndexAndView - `is_mfa_enabled` boolean - `id` string, uuid, required - `role_id` string, uuid, required - `username` string, required - `active` boolean, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `disabled` string, date-time, required - `profile` object - … - `groups_users` GroupsUsersIndexAndView - … - `gpgkey` Gpgkey - … - `role` Role - … - `missing_metadata_key_ids` string[] - `last_logged_in` string, date-time - `creator` UserIndexAndView - `is_mfa_enabled` boolean - `id` string, uuid, required - `role_id` string, uuid, required - `username` string, required - `active` boolean, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `disabled` string, date-time, required - `profile` object - … - `groups_users` GroupsUsersIndexAndView - … - `gpgkey` Gpgkey - … - `role` Role - … - `missing_metadata_key_ids` string[] - `last_logged_in` string, date-time - `permission` PermissionIndexAndView - `id` string, uuid, required - `aco` 'Resource' | 'Folder', required - `aco_foreign_key` string, uuid, required - `aro` 'User' | 'Group', required - `aro_foreign_key` string, uuid, required - `type` 1 | 7 | 15, required: * `1` - Read * `7` - Update * `15` - Owner - `created` string, date-time, required - `modified` string, date-time, required - `user` UserIndexAndView - … - `group` GroupIndexAndView - … - `permissions` PermissionIndexAndView[] - `id` string, uuid, required - `aco` 'Resource' | 'Folder', required - `aco_foreign_key` string, uuid, required - `aro` 'User' | 'Group', required - `aro_foreign_key` string, uuid, required - `type` 1 | 7 | 15, required: * `1` - Read * `7` - Update * `15` - Owner - `created` string, date-time, required - `modified` string, date-time, required - `user` UserIndexAndView - … - `group` GroupIndexAndView - … - `resource_type_id` string, uuid, required - `expired` string, date-time, required - `favorite` Favorite - `id` string, uuid, required - `user_id` string, uuid, required - `foreign_key` string, uuid, required - `foreign_model` 'Resource', required - `created` string, date-time, required - `modified` string, date-time, required - `offline` OfflineItem: The mark that makes a resource available offline for one user. It is created when the user marks the item and holds no data of its own beyond the link. - `id` string, uuid, required - `foreign_model` 'Resource', required - `foreign_key` string, uuid, required - `user_id` string, uuid, required - `created` string, date-time, required - `created_by` string, uuid, required - `secrets` SecretIndex[] - `id` string, uuid, required - `user_id` string, uuid, required - `resource_id` string, uuid, required - `data` string, required - `created` string, date-time, required - `modified` string, date-time, required - `resource_type` ResourceType - `id` string, uuid, required - `slug` 'password-string' | 'password-and-description' | 'totp' | 'password-description-totp' | 'v5-default-with-totp' | 'v5-password-string (Deprecated)' | 'v5-totp-standalone' | 'v5-default', required: * `password-string` - The original passbolt resource type, where the secret is a non empty string. * `password-and-description` - A resource with the password and the description encrypted. * `totp` - A resource with standalone TOTP fields. * `password-description-totp` - A resource with encrypted password, description and TOTP fields. * `v5-default-with-totp` - The new default resource type with a TOTP introduced with v5. * `v5-password-string (Deprecated)` - The original passbolt resource type, kept for backward compatibility reasons. * `v5-totp-standalone` - The new standalone TOTP resource type introduced with v5. * `v5-default` - The new default resource type introduced with v5. - `name` string, required - `description` string, required - `definition` object, required: Schema for the expected data for this kind of resources. - `deleted` string, required - `created` string, date-time, required - `modified` string, date-time, required - `children_folders` union[] - union - FolderV4IndexAndView (recursive) - FolderV5IndexAndView - `metadata` string, required: An armoured OpenPGP message. Its cleartext is a JSON object carrying an `object_type` field that names the payload, `PASSBOLT_RESOURCE_METADATA` for a resource, and the descriptive fields that used to travel in clear in the v4 format. The fields expected for a resource, and the two decryption paths, are described in the guide on working with v5 encrypted metadata. - `metadata_key_id` string, uuid, required - `metadata_key_type` 'user_key' | 'shared_key', required - `id` string, uuid, required - `created` string, date-time, required - `modified` string, date-time, required - `created_by` string, uuid, required - `modified_by` string, uuid, required - `personal` boolean, required - `folder_parent_id` string, uuid, required - `modifier` UserIndexAndView - `is_mfa_enabled` boolean - `id` string, uuid, required - `role_id` string, uuid, required - `username` string, required - `active` boolean, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `disabled` string, date-time, required - `profile` object - … - `groups_users` GroupsUsersIndexAndView - … - `gpgkey` Gpgkey - … - `role` Role - … - `missing_metadata_key_ids` string[] - `last_logged_in` string, date-time - `creator` UserIndexAndView - `is_mfa_enabled` boolean - `id` string, uuid, required - `role_id` string, uuid, required - `username` string, required - `active` boolean, required - `deleted` boolean, required - `created` string, date-time, required - `modified` string, date-time, required - `disabled` string, date-time, required - `profile` object - … - `groups_users` GroupsUsersIndexAndView - … - `gpgkey` Gpgkey - … - `role` Role - … - `missing_metadata_key_ids` string[] - `last_logged_in` string, date-time - `permission` PermissionIndexAndView - `id` string, uuid, required - `aco` 'Resource' | 'Folder', required - `aco_foreign_key` string, uuid, required - `aro` 'User' | 'Group', required - `aro_foreign_key` string, uuid, required - `type` 1 | 7 | 15, required: * `1` - Read * `7` - Update * `15` - Owner - `created` string, date-time, required - `modified` string, date-time, required - `user` UserIndexAndView - … - `group` GroupIndexAndView - … - `permissions` PermissionIndexAndView[] - `id` string, uuid, required - `aco` 'Resource' | 'Folder', required - `aco_foreign_key` string, uuid, required - `aro` 'User' | 'Group', required - `aro_foreign_key` string, uuid, required - `type` 1 | 7 | 15, required: * `1` - Read * `7` - Update * `15` - Owner - `created` string, date-time, required - `modified` string, date-time, required - `user` UserIndexAndView - … - `group` GroupIndexAndView - … - `children_resources` union[] - union - … - `children_folders` union[] - union - … ## Other responses - `400`: Bad request - `401`: Authentication required. - `403`: Access restricted - `404`: Not found - `409`: Entity was updated ## Changes - **2026-11-06** `8d72215e2274`: 2 breaking, 14 info - the `body/items/children_folders/items/anyOf[#/components/schemas/folderV5IndexAndView]/allOf[subschema #2]/children_resources/items/anyOf[#/components/schemas/resourceV5IndexAndView]/allOf[subschema #2]/secrets/items/` response's property type changed from `string` to `object` for status `200` - the `body/items/children_resources/items/anyOf[#/components/schemas/resourceV5IndexAndView]/allOf[subschema #2]/secrets/items/` response's property type changed from `string` to `object` for status `200` - added the optional property `body/items/children_folders/items/anyOf[#/components/schemas/folderV5IndexAndView]/allOf[subschema #2]/children_resources/items/anyOf[#/components/schemas/resourceV5IndexAndView]/allOf[subschema #2]/offline` to the response with the `200` status - added the optional property `body/items/children_resources/items/anyOf[#/components/schemas/resourceV5IndexAndView]/allOf[subschema #2]/offline` to the response with the `200` status - …12 more - **2025-06-25** `829cf48ab700`: 1 info - endpoint added [Operation history](https://skmtc.dev/passbolt/apis/passbolt-api/changes/metadata/upgrade/folders.json/post.md) --- [API](https://skmtc.dev/passbolt/apis/passbolt-api.md) - [All operations](https://skmtc.dev/passbolt/apis/passbolt-api/llms.txt) - [OpenAPI document](https://skmtc.dev/passbolt/apis/passbolt-api/revisions/8d72215e2274?raw)