---
url: 'https://dxpr.com/hc/documentation/learn-dxpr-builder/development/api'
title: 'API reference | DXPR'
author:
  name: docs-sync
  url: 'https://dxpr.com/users/docs-sync'
date: '2026-10-23T14:31:17+00:00'
copyright: 'Copyright DXPR. All rights reserved.'
type: article
summary: 'PHP services, JavaScript extension points and HTTP routes'
tags:
  - 'Architecture and APIs'
image: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
published: true
og:
  site_name: DXPR
  updated_time: '2026-10-23T14:31:17+0000'
  'image:alt': 'DXPR, powered by Drupal: AI-powered Drupal for marketers.'
schema:
  '@context': 'https://schema.org'
  '@graph':
    -
      mainEntity: {  }
    -
      '@type': TechArticle
      headline: 'API reference'
      description: 'PHP services, JavaScript extension points and HTTP routes'
      image:
        '@type': ImageObject
        url: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
        width: '1200'
        height: '630'
      datePublished: '2026-10-23T14:31:17+0000'
      dateModified: '2026-10-23T14:31:17+0000'
      author:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
        url: 'https://dxpr.com/'
        logo:
          '@type': ImageObject
          url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg'
          width: '1348'
          height: '501'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
        url: 'https://dxpr.com/'
        logo:
          '@type': ImageObject
          url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg'
          width: '1348'
          height: '501'
      mainEntityOfPage: 'https://dxpr.com/hc/documentation/learn-dxpr-builder/development/api'
      articleSection: 'Architecture and APIs'
    -
      '@type': WebPage
      '@id': 'https://dxpr.com/hc/documentation/learn-dxpr-builder/development/api'
      description: 'PHP services, JavaScript extension points and HTTP routes'
      breadcrumb:
        '@type': BreadcrumbList
        itemListElement:
          -
            '@type': ListItem
            position: 1
            name: Home
            item: 'https://dxpr.com/'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
      inLanguage: en
---
[Help Center](/hc)/[Documentation](/hc/documentation) /[Learn DXPR Builder](/hc/documentation/learn-dxpr-builder) /[Extend](/hc/documentation/learn-dxpr-builder/extend) /[Architecture and APIs](/hc/documentation/learn-dxpr-builder/extend/architecture) # API reference.

PHP services, JavaScript extension points and HTTP routes

 Learn DXPR BuilderExtendArchitecture and APIs

   ## In this guide

The PHP services, JavaScript extension points and routes that DXPR Builder defines. Service IDs come from `dxpr_builder.services.yml`, routes from `dxpr_builder.routing.yml`. For request and response details of each route, see [API endpoints](/hc/documentation/learn-dxpr-builder/reference/api-endpoints).

## PHP services

| Service ID | Class (in `src/`) | Purpose |
|---|---|---|
| `dxpr_builder.service` | `Service\DxprBuilderService` | Prepares builder content for output, handles path tokens, builds the icon set registry |
| `dxpr_builder.license_service` | `Service\DxprBuilderLicenseService` | Licence status, billable users, editor sync with DXPR |
| `dxpr_builder.key_service` | `Service\DxprBuilderKeyService` | Reads and stores the product key |
| `dxpr_builder.jwt_decoder` | `Service\DxprBuilderJWTDecoder` | Decodes the product key payload |
| `dxpr_builder.user_settings` | `Service\UserSettings` | Each editor's own editor settings, kept in user data |
| `dxpr_builder.content_lock` | `Service\ContentLock` | Records which user is editing an entity revision |
| `dxpr_builder.content_migration` | `Service\ContentMigrationService` | Runs content migrations; collects services tagged `dxpr_builder.content_migration` |
| `dxpr_builder.profile_handler` | `Service\Handler\ProfileHandler` | Turns a profile into editor settings |
| `dxpr_builder.handler.block` | `Service\Handler\BlockHandler` | Renders Drupal blocks placed as elements |
| `dxpr_builder.handler.view` | `Service\Handler\ViewHandler` | Renders Views displays placed as elements |
| `dxpr_builder.template_image_validator` | `Service\TemplateImageValidator` | Validates template preview images |
| `dxpr_builder.rl_variant.extractor`, `dxpr_builder.rl_variant.registrar` | `RlIntegration\Service\*` | A/B test variants; inactive without the RL module |
| `dxpr_builder.rl_sort.extractor`, `dxpr_builder.rl_sort.registrar` | `RlIntegration\Service\*` | Smart sort experiments; inactive without the RL module |
| `logger.channel.dxpr_builder` | core logger channel | Log channel `dxpr_builder` |

### DxprBuilderServiceInterface

Implemented by `dxpr_builder.service`. The methods you are most likely to call:

- `insertBaseTokens($content)`: replaces this site's base URL, files directory and module path with tokens. The editor stores content in this form.
- `replaceBaseTokens(&$content): void`: expands the tokens back into URLs for the current environment.
- `stripHtmlElementPersists(string $markup): string`: removes the `data-az-persist` attributes. Run it on markup written outside the editor; the editor rebuilds them on load.
- `getCmsElementNames()`: the blocks and Views displays offered as elements, cached.
- `getIconSets(): array`: the icon set registry after YAML discovery and `hook_dxpr_builder_icon_sets_alter()`.

```php
$markup = \Drupal::service('dxpr_builder.service')->insertBaseTokens($html);

```

### DxprBuilderLicenseServiceInterface

Implemented by `dxpr_builder.license_service`.

- `isBillableUser(?AccountInterface $account = NULL): bool`: TRUE for user 1 and for active accounts with `edit with dxpr builder`that are not excluded from DXPR Builder editing.
- `getLicenseInfo()`: licence status from the DXPR licence server, cached. Without a product key it returns the free tier: one user and 100 content items.
- `syncAllUsersWithCentralStorage(string $operation, string $json_web_token = ''): void`: sends this site's editors to DXPR. `$operation` is one of the interface constants `DXPR_USER_SYNC_OPERATION` (`sync`), `DXPR_USER_ADD_OPERATION` (`add`) or `DXPR_USER_REMOVE_OPERATION`(`remove`).

### DxprBuilderKeyService

- `getApiKey(): ?string`: the product key. When the `api_key_storage`setting is `key`, it reads the Key entity named in `key_provider`; otherwise it reads `json_web_token`.
- `setApiKey(string $key_value, string $storage_type = 'config', ?string $selected_key_id = NULL): void`: stores the key in config or in a Key entity.

### DxprBuilderJWTDecoder

- `decodeJwt(string $access_token)`: returns the `sub`, `scope` and `dxpr_tier` claims of the product key, each NULL when the token cannot be read. The result is cached per token.

## JavaScript extension points

The editor scripts share two arrays on `window.dxprBuilder`. Push your own objects onto them between the script that creates the array and `dxpr_builder.js`, which reads them once when it runs.

| Array | Created by | What `dxpr_builder.js` does with it |
|---|---|---|
| `dxpr_param_types` | `dxpr_param_types.js` | Registers each object as a parameter type with `register_param_type()` |
| `dxpr_elements` | `dxpr_elements.js` | `create_dxpr_elements()` registers each definition with `register_animated_element()` and converts its `params` with `make_param_type()` |

The parameter types the module registers are `boxmodel`, `checkbox`, `checkboxes`, `colorpicker`, `datetime`, `dropdown`, `dxb_slider`, `html`, `icon`, `image`, `images`, `link`, `links`, `numericfield`, `row_layout`, `saved_datetime`, `social_links`, `textarea`, `textfield` and `video`. A parameter with an unknown `type` renders as a plain text input.

[Custom elements](/hc/documentation/learn-dxpr-builder/development/custom-elements) shows a complete element definition and how to load it at the right moment.

## Editor routes

Access legend: **billable** is the `_dxpr_builder_billable_user`check (user 1, or an active account with `edit with dxpr builder`that is not excluded); **CSRF** is `_csrf_token`.

| Path | Route name | Methods | Access |
|---|---|---|---|
| `/dxpr_builder/ajax` | `dxpr_builder.ajax_callback` | any | billable, CSRF |
| `/dxpr_builder/ajax/file_upload` | `dxpr_builder.ajax_file_upload_callback` | POST, DELETE | billable, CSRF |
| `/dxpr_builder/ajax/ai/chat` | `dxpr_builder.ai_chat` | POST | `edit with dxpr builder`, billable, CSRF |
| `/dxpr_builder/ajax/ai/image` | `dxpr_builder.ai_image` | POST | `edit with dxpr builder`, billable, CSRF |
| `/dxpr_builder/ajax/ai/image/edit` | `dxpr_builder.ai_image_edit` | POST | `edit with dxpr builder`, billable, CSRF |
| `/dxpr_builder/csrf` | `dxpr_builder.csrf_refresh` | any | billable |
| `/dxpr_builder/ajax/help_link_validator` | `dxpr_builder.ajax_help_link_validator` | any | billable |
| `/dxpr_builder/media-library` | `dxpr_builder.media_library` | any | `view media` |
| `/dxpr_builder/entity-link-suggestions` | `dxpr_builder.entity_link_suggestions` | GET | `edit with dxpr builder`, CSRF |
| `/dxpr_builder/user-settings` | `dxpr_builder.user_settings` | POST | `edit with dxpr builder`, CSRF |

## Admin routes

All admin pages sit under **DXPR Studio > DXPR Builder**. The tab column shows the label in the admin menu.

| Path | Tab | Permission |
|---|---|---|
| `/admin/dxpr_studio` | DXPR Studio | `administer dxpr builder configuration` |
| `/admin/dxpr_studio/dxpr_builder` | DXPR Builder | `administer dxpr builder configuration` |
| `/admin/dxpr_studio/dxpr_builder/settings` | General Settings | `administer dxpr builder configuration` |
| `/admin/dxpr_studio/dxpr_builder/ai_settings` | AI | `administer dxpr builder configuration` |
| `/admin/dxpr_studio/dxpr_builder/content` | Content Items | `administer dxpr builder configuration` |
| `/admin/dxpr_studio/dxpr_builder/migration-status` | Migrations (under Content Items) | `administer dxpr builder configuration` |
| `/admin/dxpr_studio/dxpr_builder/page_template` | Page Templates | `administer site configuration` |
| `/admin/dxpr_studio/dxpr_builder/user_licenses` | User Licenses | `administer dxpr builder configuration` |
| `/admin/dxpr_studio/dxpr_builder/profile` | User Profiles | `administer dxpr_builder_profile` |
| `/admin/dxpr_studio/dxpr_builder/user_templates` | User Templates | `administer site configuration` |