Studio Integration

Studio API Endpoints

The Backend Power Tools Bundle provides RESTful APIs for the Pimcore Studio interface, enabling management of Alternative Element Tree configurations and Bookmark Lists. All endpoints are prefixed with /pimcore-studio/api/bundle/backend-power-tools.

Base Paths

• Alternative Element Tree: /pimcore-studio/api/bundle/backend-power-tools/aet
• Bookmark List: /pimcore-studio/api/bundle/backend-power-tools/bl

All endpoints are tagged BackendPowerTools in the OpenAPI documentation.

---

Alternative Element Tree (AET)

Configuration Management

Get Configuration

GET /aet/configuration/{configurationId} Operation ID: bundle_backend_power_tools_aet_get_configuration Permission: AET_CONFIGURATION_PERMISSION

Returns the full configuration data for a specific AET configuration.

Path Parameters:

• configurationId (string, required): Configuration ID (e.g., 019a962e_40b9_7889_ba79_88f5871047a3)

Response: ConfigurationData object Default Error Responses: 500, 404, 401

---

Get Configuration Details

GET /aet/configuration/{configurationId}/details Operation ID: bundle_backend_power_tools_aet_get_configuration_details Permission: DATA_OBJECTS

Returns the resolved tree details for a specific AET configuration, used to render the tree view.

Path Parameters:

• configurationId (string, required): Configuration ID

Response: ConfigurationDetails object Default Error Responses: 500, 404, 401

---

Create Configuration

POST /aet/configuration Operation ID: bundle_backend_power_tools_aet_create_configuration Permission: AET_CONFIGURATION_PERMISSION

Creates a new AET configuration with the given name.

Request Body: CreateConfigurationRequest

{
  "configurationName": "MyCustomTree"
}

Response: ConfigurationId object Default Error Responses: 500, 401

---

Update Configuration

PUT /aet/configuration/{configurationId} Operation ID: bundle_backend_power_tools_aet_update_configuration Permission: AET_CONFIGURATION_PERMISSION

Updates an existing AET configuration's name and data.

Path Parameters:

• configurationId (string, required): Configuration ID

Request Body: UpdateConfigurationRequest

{
  "configurationName": "UpdatedTreeName",
  "data": "{\"general\":{\"name\":\"...\",\"label\":\"...\"},\"dataSource\":{\"classId\":\"CAR\"},\"treeLevels\":[]}"
}

Response: ConfigurationModificationDate object Default Error Responses: 500, 404, 401

---

Delete Configuration

DELETE /aet/configuration/{configurationId} Operation ID: bundle_backend_power_tools_aet_delete_configuration Permission: AET_CONFIGURATION_PERMISSION

Deletes an existing AET configuration.

Path Parameters:

• configurationId (string, required): Configuration ID

Response: HTTP 200 (empty body) Default Error Responses: 500, 401

---

Clone Configuration

POST /aet/configuration/{configurationId}/clone Operation ID: bundle_backend_power_tools_aet_clone_configuration Permission: AET_CONFIGURATION_PERMISSION

Clones an existing AET configuration under a new name.

Path Parameters:

• configurationId (string, required): Configuration ID to clone

Request Body: CloneConfigurationRequest

{
  "configurationName": "ClonedTreeName"
}

Response: HTTP 200 (empty body) Default Error Responses: 500, 404, 401

---

Export Configuration

GET /aet/configuration/{configurationId}/export Operation ID: bundle_backend_power_tools_aet_export_configuration Permission: AET_CONFIGURATION_PERMISSION

Exports an AET configuration as a JSON file download.

Path Parameters:

• configurationId (string, required): Configuration ID

Response: JSON file with Content-Disposition: attachment header and filename derived from the configuration Default Error Responses: 500, 404, 401

---

Import Configuration

POST /aet/configuration/import Operation ID: bundle_backend_power_tools_aet_import_configuration Permission: AET_CONFIGURATION_PERMISSION

Imports an AET configuration from a JSON file upload. This route has priority: 10 to take precedence over the {configurationId} path pattern.

Request Body: multipart/form-data with a file field containing the JSON configuration file.

Response: ConfigurationId object Default Error Responses: 500, 401

---

List Configurations (Admin)

GET /aet/configuration/list Operation ID: bundle_backend_power_tools_aet_list_configuration_admin Permission: AET_CONFIGURATION_PERMISSION

Returns a flat list of all AET configurations for the admin settings panel. This route has priority: 10 to take precedence over the {configurationId} path pattern.

Response: Array of ConfigurationListItem objects Default Error Responses: 500, 401

---

Default Perspective Configurations

GET /aet/configuration/default-perspective Operation ID: bundle_backend_power_tools_aet_default_perspective_configurations Permission: DATA_OBJECTS

Returns configurations visible in the user's default perspective. This route has priority: 10.

Query Parameters:

• openAlternativeElementTrees (string, optional): Comma-separated list of currently open tree IDs (e.g., 019a962e_40b9_7889_ba79_88f5871047a3)

Response: Array of DefaultPerspectiveConfigurationItem objects Default Error Responses: 500, 401

---

Tree Operations

Get Tree Data

GET /aet/tree Operation ID: bundle_backend_power_tools_aet_get_tree Permission: DATA_OBJECTS

Returns a paginated collection of tree items for an AET configuration. The response uses PaginatedResponseTrait and includes a total count header.

Query Parameters:

• configurationId (string, required): Configuration ID
• path (string, required): Current tree path (e.g., /)
• page (int, optional): Page number
• start (int, optional): Result offset
• limit (int, optional): Number of results to return (default example: 30)
• level (int, optional): Current tree level
• filter (string, optional): Filter term to search items

Response: Paginated AnyOfAlternativeElements collection with total count Default Error Responses: 400, 403, 500, 401, 404

---

Get Tree Calculation Status

GET /aet/tree/{configurationId}/calculation-status Operation ID: bundle_backend_power_tools_aet_get_tree_calculation_status Permission: DATA_OBJECTS

Returns whether a tree calculation is currently in progress for the given configuration.

Path Parameters:

• configurationId (string, required): Configuration ID

Response:

{
  "inProgress": true
}

Default Error Responses: 403, 404, 401

---

Patch Data Object

PATCH /aet/tree/{configurationId}/update/{objectId} Operation ID: bundle_backend_power_tools_aet_patch_data_object Permission: DATA_OBJECTS

Patches one or more fields of a data object within an AET context.

Path Parameters:

• configurationId (string, required): Configuration ID
• objectId (int, required): Data object ID

Request Body: DataParameter — key/value map of fields to update

Response: HTTP 200 (empty body) Default Error Responses: 500, 404, 401

---

Grid Operations

Get Grid Listing

POST /aet/grid/listing Operation ID: bundle_backend_power_tools_aet_grid_listing Permission: DATA_OBJECTS

Returns paginated grid data for an AET configuration.

Request Body: ListRequest (via GridListRequestBody attribute)

Response: GridListing object Default Error Responses: 401, 500

---

Get Export Jobs

POST /aet/grid/export-jobs Operation ID: bundle_backend_power_tools_aet_grid_export_jobs Permission: DATA_OBJECTS

Returns chunked export job arrays for an AET grid.

Request Body: ListRequest (via GridListRequestBody attribute)

Response: GridExportJobs object Default Error Responses: 401, 500

---

Get Batch Edit IDs

POST /aet/grid/batch-edit-ids Operation ID: bundle_backend_power_tools_aet_grid_batch_edit_ids Permission: DATA_OBJECTS

Returns all element IDs matching the given filters for use in batch editing.

Request Body: ListRequest (via GridListRequestBody attribute)

Response: GridBatchEditIds object Default Error Responses: 401, 500

---

Lookup / Utility Operations

List Configurations

GET /aet/configurations Operation ID: bundle_backend_power_tools_aet_list_configurations Permission: DATA_OBJECTS

Returns a list of all AET configurations available to the current user (used for tree selection dropdowns). This route has priority: 10.

Response: { "items": TreeConfigurationItem[] } Default Error Responses: 401, 500

---

List Data Object Classes

GET /aet/data-object-classes Operation ID: bundle_backend_power_tools_aet_list_data_object_classes Permission: AET_CONFIGURATION_PERMISSION

Returns all available data object classes. This route has priority: 10.

Response: { "items": DataObjectClassItem[] } Default Error Responses: 401, 500

---

List Valid Languages

GET /aet/valid-languages Operation ID: bundle_backend_power_tools_aet_list_valid_languages Permission: AET_CONFIGURATION_PERMISSION

Returns all valid languages configured in the Pimcore system. This route has priority: 10.

Response: { "items": ValidLanguageItem[] } Default Error Responses: 401, 500

---

List Precondition Filters

GET /aet/precondition-filters Operation ID: bundle_backend_power_tools_aet_list_precondition_filters Permission: AET_CONFIGURATION_PERMISSION

Returns all available precondition filters for AET configurations. This route has priority: 10.

Response: { "items": PreconditionFilterItem[] } Default Error Responses: 401, 500

---

List Class Definition Fields

GET /aet/class-definition/fields Operation ID: bundle_backend_power_tools_aet_list_class_definition_fields Permission: AET_CONFIGURATION_PERMISSION

Returns the field definitions for a given data object class.

Query Parameters:

• classId (string, required): Class ID (e.g., Car)
• onlySimpleValueFields (bool, optional): When true, returns only simple value fields

Response: { "items": ClassDefinitionField[] } Default Error Responses: 401, 500

---

List Common Relation Fields

GET /aet/class-definition/common-relation-fields Operation ID: bundle_backend_power_tools_aet_list_common_relation_fields Permission: AET_CONFIGURATION_PERMISSION

Returns fields common across all classes referenced by a given relation field.

Query Parameters:

• classId (string, required): Source class ID (e.g., Car)
• relationField (string, required): Relation field name (e.g., manufacturer)

Response: { "items": ClassDefinitionField[] } Default Error Responses: 401, 500

---

List Object Brick Fields

GET /aet/object-brick/fields Operation ID: bundle_backend_power_tools_aet_list_object_brick_fields Permission: AET_CONFIGURATION_PERMISSION

Returns field definitions for a given object brick.

Query Parameters:

• objectBrick (string, required): Object brick key (e.g., MyObjectBrick)

Response: { "items": ClassDefinitionField[] } Default Error Responses: 401, 500

---

Bookmark List (BL)

Main Operations

Get Collection

POST /bl/ Operation ID: bundle_backend_power_tools_bl_get_collection Permission: BOOKMARK_LIST_PERMISSION

Returns a paginated, filterable list of bookmark lists belonging to the current user. Uses CollectionFilterParameter from Studio Backend for consistent pagination and column filter support.

Request Body: CollectionFilterParameter

{
  "page": 1,
  "pageSize": 20,
  "columnFilters": [
    {"type": "search", "filterValue": "search term"},
    {"type": "showAll", "filterValue": true}
  ]
}

Response: Paginated BookmarkList collection with total count Default Error Responses: 401, 500

---

Add Bookmark List

POST /bl/add Operation ID: bundle_backend_power_tools_bl_add Permission: BOOKMARK_LIST_PERMISSION

Creates a new bookmark list for the current user.

Request Body: CreateBookmarkListDto

{
  "name": "My Bookmarks"
}

Response: BookmarkList object Default Error Responses: 500, 401, 404

---

Get Bookmark List by ID

GET /bl/{id} Operation ID: bundle_backend_power_tools_bl_get_by_id Permission: BOOKMARK_LIST_PERMISSION

Retrieves a specific bookmark list by ID. Route requires id to match \d+.

Path Parameters:

• id (int, required): Bookmark list ID

Response: BookmarkList object Default Error Responses: 500, 401, 404

---

Update Bookmark List

PUT /bl/update/{id} Operation ID: bundle_backend_power_tools_bl_update Permission: BOOKMARK_LIST_PERMISSION

Fully updates a specific bookmark list.

Path Parameters:

• id (int, required): Bookmark list ID

Request Body: UpdateBookmarkList (same shape as CreateBookmarkListDto)

Response: BookmarkList object Default Error Responses: 500, 401, 404

---

Delete Bookmark List

DELETE /bl/{id} Operation ID: bundle_backend_power_tools_bl_delete Permission: BOOKMARK_LIST_PERMISSION

Deletes a specific bookmark list by ID.

Path Parameters:

• id (int, required): Bookmark list ID

Response: HTTP 200 (empty body) Default Error Responses: 403, 500, 401, 404

---

Tree Operations

Get Bookmark List Tree

GET /bl/{id}/tree Operation ID: bundle_backend_power_tools_bl_get_tree Permission: BOOKMARK_LIST_PERMISSION

Returns paginated tree nodes for a bookmark list. Response uses PaginatedResponseTrait.

Path Parameters:

• id (int, required): Bookmark list ID

Query Parameters:

• page (int, optional): Page number
• pageSize (int, optional, default: 30): Page size
• parentId (int, optional): Parent folder ID (default: 0 = root)
• elementType (string, optional): Element type to load from default trees (asset, object, document)
• searchTerm (string, optional): Filter term

Response: Paginated AnyOfBookmarkListNodes collection with total count Default Error Responses: 400, 403, 500, 401, 404

---

Add/Update Tree Items

POST /bl/{id}/tree/items Operation ID: bundle_backend_power_tools_bl_tree_add_update_items Permission: BOOKMARK_LIST_PERMISSION

Adds new items or updates existing items in the bookmark list tree.

Path Parameters:

• id (int, required): Bookmark list ID

Request Body: AddTreeItem

Response: HTTP 200 (empty body) Default Error Responses: 403, 500, 401

---

Add Folder

POST /bl/{id}/tree/folder Operation ID: bundle_backend_power_tools_bl_tree_add_folder Permission: BOOKMARK_LIST_PERMISSION

Creates a new folder in the bookmark list tree.

Path Parameters:

• id (int, required): Bookmark list ID

Request Body: AddTreeFolder

Response: HTTP 200 (empty body) Default Error Responses: 409 (conflict/exists), 403, 500, 401

---

Remove Tree Items

DELETE /bl/{id}/tree/items Operation ID: bundle_backend_power_tools_bl_tree_remove_items Permission: BOOKMARK_LIST_PERMISSION

Removes items from the bookmark list tree.

Path Parameters:

• id (int, required): Bookmark list ID

Request Body: RemoveTreeItem

Response: HTTP 200 (empty body) Default Error Responses: 403, 500, 404, 401

---

Rename Folder

PUT /bl/{id}/tree/folder Operation ID: bundle_backend_power_tools_bl_tree_rename_folder Permission: BOOKMARK_LIST_PERMISSION

Renames a folder in the bookmark list tree.

Path Parameters:

• id (int, required): Bookmark list ID

Request Body: RenameTreeFolder

Response: HTTP 200 (empty body) Default Error Responses: 409 (conflict/exists), 403, 500, 401, 404

---

Share Operations

Get Share Recipients

GET /bl/{id}/share/recipients Operation ID: bundle_backend_power_tools_bl_get_share_collection Permission: BOOKMARK_LIST_SHARE_PERMISSION

Returns a paginated collection of users the bookmark list is currently shared with.

Path Parameters:

• id (int, required): Bookmark list ID

Response: Paginated ShareRecipient collection with total count Default Error Responses: 403, 500, 404, 401

---

Get Shareable Users

GET /bl/{id}/share/users Operation ID: bundle_backend_power_tools_bl_get_user_collection Permission: BOOKMARK_LIST_SHARE_PERMISSION

Returns a paginated collection of users the bookmark list can be shared with.

Path Parameters:

• id (int, required): Bookmark list ID

Query Parameters:

• searchTerm (string, optional): Filter users by name (e.g., admin)

Response: Paginated ShareUser collection with total count Default Error Responses: 403, 500, 404, 401

---

Patch Share Recipients

PATCH /bl/{id}/share/recipients Operation ID: bundle_backend_power_tools_bl_patch_share_list Permission: BOOKMARK_LIST_PERMISSION

Adds and/or removes share recipients for a bookmark list. Returns the updated list of recipients.

Path Parameters:

• id (int, required): Bookmark list ID

Request Body: PatchShares

Response: Paginated ShareRecipient collection (updated state) Default Error Responses: 403, 500, 404, 401

---

Permissions

Constant	Value	Used For
AET_CONFIGURATION_PERMISSION	bundle_backend_power_tools_aet_configuration	Managing AET configurations, class/brick/language lookups
DATA_OBJECTS	objects	AET tree access, grid operations, configuration listing
BOOKMARK_LIST_PERMISSION	bundle_backend_power_tools_bl	All bookmark list CRUD and tree operations
BOOKMARK_LIST_SHARE_PERMISSION	bundle_backend_power_tools_bl_share	Reading share recipients and available users

---

Common Response Codes

Code	Meaning
200	Successful request
400	Bad request (invalid query/body parameters)
401	Missing or invalid authentication
403	Forbidden — user lacks required permission or ownership
404	Resource not found
409	Conflict — resource already exists (e.g., duplicate folder name)
500	Internal server error