API endpoints.

This page lists every route that DXPR Builder registers in dxpr_builder.routing.yml, with the HTTP methods, access requirements, request parameters and response shapes as implemented in the controllers. The editor's JavaScript is the intended client for the AJAX endpoints; nothing on this page is a stable public API, and parameter names can change between releases.

Access requirements

Routes use three kinds of requirement. A route can combine them.

What "billable user" means

DxprBuilderBillableUserAccessCheck allows access when DxprBuilderLicenseService::isBillableUser() returns true for the current account. That method returns false for blocked accounts and for accounts whose dxpr_user_is_disavowed field is set (an administrator excludes a user from editing on the User Licenses page). Otherwise it returns true for user 1 and for any account that holds the edit with dxpr builder permission. In short: a billable user is an active, non-excluded account that is allowed to edit with DXPR Builder, and the licence service counts these accounts against your product key.

HTTP methods

Where a route declares methods, only those methods are routed. Where it does not, the route accepts any method (Drupal's MethodFilter only filters routes that declare methods). The tables below state the method the editor's JavaScript actually uses when that is visible in the source.

Editor AJAX endpoints

CSRF token URL

The request must carry the header X-Requested-With: XMLHttpRequest; without it the controller returns HTTP 403 with the JSON body {"error": "Invalid request"}.

Response: a JSON string with the URL of the main AJAX handler and a token query parameter. The URL is a path from the site root (base path included, no host). The JavaScript posts every builder operation to this URL.

Main AJAX handler

The POST body field action selects the operation. Every operation and its parameters are listed under Main AJAX handler operations. When action is missing or unknown, the controller returns an empty Drupal AjaxResponse with no commands. Most operations that re-check the billable user status return the same empty response when that check fails; the tables note the two exceptions.

AI chat

The request body is JSON. The controller proxies the request to the dxpr provider of the Drupal ai module, so no API key reaches the browser. Before the call it merges the domains from the ai_output_allowed_domains setting into the ai module's hostname filter, when that service exists. A value of * sets the filter to full trust instead. The filter is restored afterwards.

Responses:

AI image generation

Responses:

AI image editing

Responses:

File upload

The controller sorts each file by the first part of its client MIME type into <default scheme>://dxpr_builder_images, dxpr_builder_videos or dxpr_builder_files. An image needs an extension of the MIME types image/gif, jpg, jpeg, png, webp, avif or svg. A video needs one of video/webm, ogv, ogg, mp4 or quicktime (for example .mov). The size limit is PHP's upload maximum. A file with the same name and identical SHA-256 content as an existing managed file that the user can view is reused instead of saved again. When the media module is installed and a media type named image, media_image, video or media_video exists, a published media entity is created (or reused) for the file. File usage is recorded under the dxpr_builder module.

Responses:

Media library dialog

The media type offered depends on the media_browser setting: media_library uses the image or video media type directly; media_library_acquia_dam uses acquia_dam_image_asset or acquia_dam_video_asset when that media type exists.

Responses:

Help link validator

Response: a JSON array. [true] when a HEAD request to the link (without following redirects) returns 200; [false] when the HTTP client throws; [] in every other case, including a missing parameter, a non-matching URL or a non-200 status.

Entity link suggestions

Bundles are those with ckeditor5_link_suggestions enabled in their bundle info; when none are configured, all node bundles are searched. Up to 100 entities per entity type are matched with a CONTAINS search through core's entity reference selection plugins.

Response: {"suggestions": [...]} with private cacheability and a max age of 300 seconds. Each suggestion has description, entity_type_id, entity_uuid, group, label and path. When q matches nothing, the array holds a single manual-link suggestion with description, label (the lower-cased input) and path (the input when it is a valid URL, otherwise an empty string). When q is empty, suggestions is an empty array.

User editor settings

The editor sends this request when a user changes their own editor settings, for example under Editor settings. The values are stored with the user account in user.data, module dxpr_builder.

Responses:

Main AJAX handler operations

All operations go to /dxpr_builder/ajax with the token query parameter obtained from /dxpr_builder/csrf. The operation name is sent in the POST body field action; all other parameters are POST body fields unless stated otherwise. The "Re-checks billable" column marks operations that call isBillableUser() again inside the switch. When that check fails they return the empty AjaxResponse described above, unless the row says otherwise.

Session and access

Containers (fields rendered with the DXPR Builder formatter)

dxpr_save_container does the following:

1. Decodes htmlContent: XOR every byte with 7, then URL-decode.
2. Writes the result to the first delta of the named field.
3. Creates a new default revision with the log message Saved with DXPR builder when the entity type is revisionable.
4. Removes any content lock for the entity.
5. Updates block_revision_id in Layout Builder sections that reference the saved inline block.
6. Increments the dxpr_builder.saves_count state value.

The save only happens when the user has update access to the entity. Without it, the operation still returns the empty-string success response.

CMS elements (blocks and views)

In both settings-returning operations, css and js are rendered asset tags not already present in the page, and settings is the decoded drupalSettings object, or an empty string when there are none.

Page templates

User templates

The machine name is derived from name by lower-casing it and replacing every run of characters outside a-z0-9_ with an underscore. type falls back to the data-azb attribute in the markup when a stored template has no type.

Images

Content locks

Admin pages

All of these routes accept any method (no methods key). Paths containing {...} take the config entity ID, or the migration ID for {migration_id}.

What's next?

• Configuration reference for the settings that control the media browser and AI behaviour used by these endpoints.
• PHP API for the services the controllers call.
• Hooks API for the hooks that let other modules alter builder behaviour.