Admin endpoints

These endpoints power the Burst Statistics admin dashboard. They are not intended as a primary integration API — use burst/v1/data/{type} for analytics data instead.

All routes require a valid burst_nonce nonce on write requests. Pass it via the X-WP-Nonce header.

Settings and fields

`GET burst/v1/fields/get`

Returns all field definitions and the full menu configuration in a single response. Menu data is no longer exposed via a dedicated route — consume it through this endpoint.

Permission: manage_burst_statistics

:::caution Breaking change Removed in v3.4.0: the GET burst/v1/menu route. Menu data is no longer exposed directly — read it from the menu field of the GET burst/v1/fields/get response instead. :::

`POST burst/v1/fields/set`

Saves multiple settings fields at once.

Permission: manage_burst_statistics Nonce: required

`POST burst/v1/options/set`

Saves a single option value.

Permission: manage_burst_statistics Nonce: required

Changed in v3.4.0: the post-activation redirect side-effect previously wired to this endpoint has been moved to the frontend admin_init flow. Saving an option no longer triggers the maybe_redirect_to_settings_page hook from this route.

Goals

`GET burst/v1/goals/get`

Returns all configured goals and the list of predefined goals available to add.

Permission: view_burst_statistics

`POST burst/v1/goals/add`

Creates a new goal.

Permission: manage_burst_statistics Nonce: required

`POST burst/v1/goals/set`

Updates an existing goal.

Permission: manage_burst_statistics Nonce: required

`POST burst/v1/goals/delete`

Deletes a goal.

Permission: manage_burst_statistics Nonce: required

`POST burst/v1/goals/add_predefined`

Adds one of the built-in predefined goals.

Permission: manage_burst_statistics Nonce: required

Posts search

`GET burst/v1/posts/`

Searches WordPress posts for use in goal or filter selectors.

Permission: manage_burst_statistics

Query parameters:

Parameter	Type	Required	Description
`search_input`	string	No	Search term. Sanitised with `sanitize_title`

Generic action endpoints

`POST burst/v1/do_action/{action}`

Generic write-action endpoint. The {action} segment selects the operation. Use burst_do_action to register custom write operations.

Permission: manage_burst_statistics Nonce: required Route parameter: {action} — [a-z_-]+

Built-in actions:

`{action}`	Description
`plugin_actions`	Install or activate companion plugins
`fix_task`	Apply an automated fix for a dashboard task
`dismiss_task`	Dismiss a task from the dashboard
`chat`	AJAX fallback for the chat endpoint. Accepts the same `message` and `history` payload as `POST burst/v1/chat` and returns the same response shape. Added in v3.4.2

`GET burst/v1/get_action/{action}`

Generic read-action endpoint. Use burst_get_action to register custom read operations.

Permission: view_burst_statistics Nonce: required Route parameter: {action} — [a-z_-]+

Built-in actions:

`{action}`	Description
`tasks`	Returns the list of plugin tasks
`tracking`	Returns tracking status and last-test timestamp
`get_article_data`	Returns per-article statistics
`get_filter_options`	Returns available filter values (devices, browsers, countries, etc.)
`otherpluginsdata`	Returns data from integrated third-party plugins
`story-report-data`	Returns the report payload for a shared story link. Requires a valid share token. Renamed in v3.4.2 from `report-data`
`chat_status`	Returns the chat availability payload (`enabled`, `abilities_enabled`, `ai_client_loaded`, `has_configured_provider`, `disabled_reason`). Added in v3.4.2

`GET burst/v1/get_action/ecommerce/{action}`

Ecommerce-scoped read-action endpoint. Mirrors GET burst/v1/get_action/{action} but gates access on the sales capability so ecommerce integrations can expose read operations without widening the generic route.

Pro - BusinessAvailable in the Business tier

Ecommerce endpoints require a Business tier license.

Everything in the Business tier is also available in the Agency tier.

Added in v3.4.0.

Permission: view_sales_burst_statistics Nonce: required Route parameter: {action} — [a-z_-]+

Use burst_get_action to register handlers — {action} is passed through to the same filter used by the generic read endpoint, so existing handlers work as-is when the action name is unique.

Show code

add_action( 'burst_get_action', function( array $output, string $action ): array {
    if ( $action === 'my_ecommerce_report' ) {
        $output = [ 'items' => get_my_ecommerce_report() ];
    }
    return $output;
}, 10, 2 );

Extending `do_action` and `get_action`

`burst_do_action`

Fires inside POST burst/v1/do_action/{action}. Use it to handle custom write operations.

Parameters:

Parameter	Type	Description
`$output`	array	Current response array. Modify and return it
`$action`	string	The `{action}` segment from the route
`$data`	array / null	Decoded JSON body of the request

Show code

add_action( 'burst_do_action', function( array $output, string $action, ?array $data ): array {
    if ( $action === 'my_custom_action' ) {
        // Perform write operation.
        $output = [ 'success' => true, 'message' => 'Done.' ];
    }
    return $output;
}, 10, 3 );

`burst_get_action`

Fires inside GET burst/v1/get_action/{action} and GET burst/v1/get_action/ecommerce/{action}. Use it to handle custom read operations.

Parameters:

Parameter	Type	Description
`$output`	array	Current response array. Modify and return it
`$action`	string	The `{action}` segment from the route

Show code

add_action( 'burst_get_action', function( array $output, string $action ): array {
    if ( $action === 'my_custom_data' ) {
        $output = [ 'items' => get_my_custom_data() ];
    }
    return $output;
}, 10, 2 );

Abilities API

Added in v3.4.1.

Burst registers a set of read-only abilities through WordPress's Abilities API (wp_register_ability) so trusted AI agents and automation tools can query analytics without going through the dashboard REST routes. Abilities are opt-in and disabled by default.

Prerequisites

WordPress build that exposes wp_register_ability and wp_register_ability_category
The enable_abilities_api setting must be turned on under Burst → Settings → Advanced
A logged-in user with manage_burst_statistics

When the Abilities API functions are not available, the enable_abilities_api field is hidden from the settings UI.

Registered abilities

All abilities live under the burst-statistics ability category and are flagged readonly, idempotent, and non-destructive.

Ability	Description
`burst/live-visitors`	Current number of live visitors
`burst/live-traffic`	Active visitors and pages from the live traffic feed (accepts `limit`, max 100)
`burst/today-summary`	Summary of key metrics for an optional `date_start`/`date_end` range
`burst/tasks`	Current Burst task list and status
`burst/tracking-status`	Tracking transport status and last test timestamp
`burst/license-notices`	License state and notices for Burst Pro
`burst/data`	Pages overview (`type=insights`) or datatable data (`type=datatable`) with metrics, filters, group-by and limit
`burst/sales-data`	Ecommerce sales metrics (Pro only)
`burst/subscriptions-data`	Ecommerce subscriptions metrics (Pro only)

Pro - BusinessAvailable in the Business tier

The burst/sales-data and burst/subscriptions-data abilities require a Business tier license. They return 503 burst_abilities_pro_required when called on a free install.

Everything in the Business tier is also available in the Agency tier.

Permission and rate limiting

Every ability runs through a single permission callback that requires the current user to hold manage_burst_statistics. Anonymous callers and users without the capability receive 403 burst_abilities_forbidden.

Changed in v3.4.2: the permission callback was tightened from view_burst_statistics to manage_burst_statistics. Update integration users so they hold the manage capability before upgrading.

A per-user, per-ability rate limit caps requests at 30 per 60-second window by default. When the limit is exceeded the ability returns 429 burst_abilities_rate_limited. Both bounds are filterable.

Show code

// Allow 60 requests per 30-second window for the live-visitors ability.
add_filter( 'burst_abilities_rate_limit_max', function( int $max, string $ability ): int {
    return $ability === 'live-visitors' ? 60 : $max;
}, 10, 2 );

add_filter( 'burst_abilities_rate_limit_window', function( int $window, string $ability ): int {
    return $ability === 'live-visitors' ? 30 : $window;
}, 10, 2 );

Filter	Default	Description
`burst_abilities_rate_limit_max`	`30`	Maximum requests per window. Receives the ability slug as the second argument
`burst_abilities_rate_limit_window`	`60`	Window length in seconds. Receives the ability slug as the second argument

Error codes

Code	HTTP status	Cause
`burst_abilities_forbidden`	403	User is not logged in or lacks `manage_burst_statistics`
`burst_abilities_invalid_input`	400	Input failed schema/type validation
`burst_abilities_rate_limited`	429	Per-user rate limit exceeded
`burst_abilities_pro_required`	503	Pro-only ability invoked on a free install
`burst_abilities_unavailable`	503	Burst admin services could not be bootstrapped for the ability call
`burst_abilities_execution_failed`	500	Underlying statistics call threw — check server logs

Chat

Added in v3.4.2.

The chat endpoints expose the Burst Analytics assistant — a WordPress AI Client integration that resolves ability calls (live visitors, today summary, datatables, etc.) into natural-language answers. The same handlers are reachable from REST and from the do_action / get_action fallback channel so the dashboard can call them through both transports.

Prerequisites

Abilities API enabled (enable_abilities_api setting turned on)
WordPress AI Client active and at least one provider configured (Anthropic, OpenAI, or Google)
A logged-in user with manage_burst_statistics

When any prerequisite is missing, the chat endpoints return a structured error and GET burst/v1/chat/status reports the blocking reason in disabled_reason.

`POST burst/v1/chat`

Sends a user message to the assistant, optionally with prior conversation history. The handler primes the configured AI provider, lets the model issue function calls into the registered Burst abilities, and returns the final assistant reply along with the serialized conversation history so the dashboard can persist it client-side.

Permission: manage_burst_statistics Nonce: required Rate limit: 20 requests per 60-second window per user (burst_chat_rate_limit_max / burst_chat_rate_limit_window filters)

Body parameters:

Parameter	Type	Required	Description
`message`	string	Yes	User message. Sanitised with `sanitize_textarea_field` and clamped to 8000 characters (`burst_chat_prompt_max_length` filter)
`history`	array	No	Prior conversation. Each item must be an object with `role` (`user` or `model`) and either `content` or `parts`. Capped at 40 items by default (`burst_chat_history_max_items` filter)

Response on success:

Field	Type	Description
`reply`	string	Assistant reply text
`history`	array	Updated conversation history including the new user and model messages, serialized via the AI Client DTOs

Error codes:

Code	HTTP status	Cause
`burst_chat_forbidden`	403	No logged-in user resolved for rate limiting
`burst_chat_invalid_prompt`	400	`message` was empty after sanitisation
`burst_chat_invalid_history`	400	A history item had an unsupported role or malformed parts
`burst_chat_disabled`	403	Abilities API is disabled in Burst settings
`burst_chat_rate_limited`	429	Per-user chat rate limit exceeded
`burst_ai_client_unavailable`	503	WordPress AI Client classes or functions are missing
`burst_ai_client_empty_response`	502	Provider returned no usable text after tool resolution
`burst_ai_client_exception`	500 / 503	Provider call threw. The `diagnostics` field on the error data lists which providers are loaded and configured. Set the `burst_chat_expose_exception` filter to `true` to include the exception message

Show code

// Allow a higher chat rate for trusted automations.
add_filter( 'burst_chat_rate_limit_max', function( int $max ): int {
    return 60;
} );

add_filter( 'burst_chat_rate_limit_window', function( int $window ): int {
    return 30;
} );

`GET burst/v1/chat/status`

Returns whether the chat feature is currently usable. The dashboard polls this endpoint to decide whether to render the chat UI and to surface configuration hints.

Permission: manage_burst_statistics

Response fields:

Field	Type	Description
`enabled`	bool	True when both `abilities_enabled` and `ai_client_loaded` are true
`abilities_enabled`	bool	Whether the Abilities API setting is on
`ai_client_loaded`	bool	Whether the WordPress AI Client classes are available
`has_configured_provider`	bool	True when at least one registered AI provider reports `isProviderConfigured`
`disabled_reason`	string	Human-readable reason when `enabled` is false. Empty when the chat is ready

The same payload is returned by the chat_status action over the get_action fallback channel and can be extended through the burst_chat_availability filter:

Show code

add_filter( 'burst_chat_availability', function( array $payload ): array {
    $payload['custom_provider'] = defined( 'MY_CUSTOM_AI_KEY' );
    return $payload;
} );

MainWP integration

This endpoint is only available in Burst when the MainWP integration is active.

`GET burst/v1/mainwp-auth`

Added in v3.4.0.

Issues an Application Password token for the MainWP dashboard to authenticate subsequent REST API calls. This is the bootstrap handshake that the dashboard performs once per session before calling any other Burst route with Basic auth.

Method: GET Permission callback: validates a MainWP RSA-signed body or an already logged-in user with manage_burst_statistics. Subscribers and unauthenticated unsigned callers are rejected before the route callback runs.

Changed in v3.4.1: signature verification, capability check, user-switching and dashboard-origin persistence have moved into the permission callback. The route callback now only mints (or reuses) the Application Password.

Response on success:

Field	Type	Description
`token`	string	Base64-encoded Application Password token
`root_url`	string	WordPress REST API root URL
`localization_data`	object	Dashboard localisation strings and settings

When the MainWP integration is active, permissive CORS headers are added to all burst/v1 routes. The Origin header is reflected, credentials are allowed, and the Authorization, X-WP-Nonce, X-Burst-Share-Token and X-BurstMainWP request headers are permitted.

Changed in v3.4.1: during the unpaired bootstrap call to burst/v1/mainwp-auth, CORS responses no longer set Access-Control-Allow-Credentials: true. Credentials are only echoed back once the request origin matches the persisted dashboard origin, so the very first signed handshake cannot ride on a logged-in cookie.

Public proxy pattern

Burst's data endpoints are intentionally protected. If you need public access to analytics data (for example, for a public-facing dashboard widget), implement a minimal proxy rather than loosening Burst's own permissions.

Show code

add_action( 'rest_api_init', function() {
    register_rest_route(
        'burst-public/v1',
        '/data/(?P<type>[a-z_\-]+)',
        [
            'methods'             => 'GET',
            'permission_callback' => '__return_true',
            'callback'            => function( WP_REST_Request $request ) {
                // Validate a custom API key before proxying.
                $api_key = $request->get_param( 'key' );
                if ( ! hash_equals( BURST_PUBLIC_API_KEY, (string) $api_key ) ) {
                    return new WP_REST_Response( [ 'success' => false, 'message' => 'Invalid key' ], 403 );
                }

                // Only allow a strict subset of data types.
                $allowed_types = [ 'today', 'insights', 'datatable' ];
                $type          = sanitize_key( $request->get_param( 'type' ) );
                if ( ! in_array( $type, $allowed_types, true ) ) {
                    return new WP_REST_Response( [ 'success' => false, 'message' => 'Type not allowed' ], 400 );
                }

                $url = add_query_arg(
                    [
                        'date_start' => $request->get_param( 'date_start' ),
                        'date_end'   => $request->get_param( 'date_end' ),
                    ],
                    rest_url( 'burst/v1/data/' . $type )
                );

                $response = wp_remote_get(
                    $url,
                    [
                        'headers' => [
                            'Authorization' => 'Basic ' . base64_encode( BURST_REST_USER . ':' . BURST_REST_APP_PASSWORD ),
                        ],
                        'timeout' => 15,
                    ]
                );

                if ( is_wp_error( $response ) ) {
                    return new WP_REST_Response( [ 'success' => false, 'message' => $response->get_error_message() ], 500 );
                }

                return new WP_REST_Response(
                    json_decode( wp_remote_retrieve_body( $response ), true ),
                    wp_remote_retrieve_response_code( $response )
                );
            },
        ]
    );
} );

caution

Do not expose all Burst routes publicly. Restrict endpoint types, require a key or signature, and keep responses read-only.

Settings and fields​

GET burst/v1/fields/get​

POST burst/v1/fields/set​

POST burst/v1/options/set​

Goals​

GET burst/v1/goals/get​

POST burst/v1/goals/add​

POST burst/v1/goals/set​

POST burst/v1/goals/delete​

POST burst/v1/goals/add_predefined​

Posts search​

GET burst/v1/posts/​

Generic action endpoints​

POST burst/v1/do_action/{action}​

GET burst/v1/get_action/{action}​

GET burst/v1/get_action/ecommerce/{action}​

Pro - BusinessAvailable in the Business tier

Extending do_action and get_action​

burst_do_action​

burst_get_action​

Abilities API​

Prerequisites​

Registered abilities​

Pro - BusinessAvailable in the Business tier

Permission and rate limiting​

Error codes​

Chat​

Prerequisites​

POST burst/v1/chat​

GET burst/v1/chat/status​

MainWP integration​

GET burst/v1/mainwp-auth​

Public proxy pattern​

Settings and fields

`GET burst/v1/fields/get`

`POST burst/v1/fields/set`

`POST burst/v1/options/set`

Goals

`GET burst/v1/goals/get`

`POST burst/v1/goals/add`

`POST burst/v1/goals/set`

`POST burst/v1/goals/delete`

`POST burst/v1/goals/add_predefined`

Posts search

`GET burst/v1/posts/`

Generic action endpoints

`POST burst/v1/do_action/{action}`

`GET burst/v1/get_action/{action}`

`GET burst/v1/get_action/ecommerce/{action}`

Extending `do_action` and `get_action`

`burst_do_action`

`burst_get_action`

Abilities API

Prerequisites

Registered abilities

Permission and rate limiting

Error codes

Chat

Prerequisites

`POST burst/v1/chat`

`GET burst/v1/chat/status`

MainWP integration

`GET burst/v1/mainwp-auth`

Public proxy pattern