Skip to main content
Version: 2026.1

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​

ConstantValueUsed For
AET_CONFIGURATION_PERMISSIONbundle_backend_power_tools_aet_configurationManaging AET configurations, class/brick/language lookups
DATA_OBJECTSobjectsAET tree access, grid operations, configuration listing
BOOKMARK_LIST_PERMISSIONbundle_backend_power_tools_blAll bookmark list CRUD and tree operations
BOOKMARK_LIST_SHARE_PERMISSIONbundle_backend_power_tools_bl_shareReading share recipients and available users

Common Response Codes​

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