mxHeadless

REST API gateway for MODX Revolution 3. Exposes resources, pages, elements, contexts, and registered xPDO objects as JSON for Nuxt, Next.js, SvelteKit, mobile apps, and custom clients.

Release 1.0.42. License GPL-2.0-or-later, no feature tiers.

Source: Ibochkarev/mxHeadless.

Features

• /api/v1 prefix via the OnHandleRequest plugin (configurable)
• Only registered objects and fields appear in the API
• PSR-7/15 middleware: CORS, rate limit, CSRF, idempotency, HTTP cache, audit, webhooks
• Live OpenAPI and Swagger UI at /api/v1/docs
• API keys (mxh_*), OAuth (mxt_*), Manager session
• Extension API (OnMxHeadlessRegister) for MiniShop3 and custom extras

Requirements

	Version
MODX Revolution	3.2.3+ (transport declares modx >= 3.0.0, follow the package README)
PHP	8.1+
Database	MySQL / MariaDB (InnoDB), xPDO 3

Details: Requirements.

Installation

Install via modstore.pro in Package Management, or build the transport from source:

cd _build
php build.php

Next: Installation, Web server, Quick start.

Base URL

https://your-site.example/api/v1

curl -s https://your-site.example/api/v1 | jq
curl -s https://your-site.example/api/v1/health | jq

Interactive spec: /api/v1/docs. Details: Swagger and OpenAPI.

Fallback without rewrite: assets/components/mxheadless/api.php?route=/v1/health.

Response format

Success:

{
  "data": {},
  "meta": {
    "total": 100,
    "count": 20,
    "limit": 20,
    "offset": 0,
    "has_more": true
  },
  "links": {
    "self": "/api/v1/resources?limit=20&offset=0",
    "next": "/api/v1/resources?limit=20&offset=20"
  }
}

Errors: RFC 9457 (application/problem+json). See Errors.

How access works

An object appears in the API only after registration in ObjectRegistry with explicit fields, filters, and permissions. The URL name (resources, products) always maps to an ObjectDefinition, not an arbitrary PHP class. QueryParser accepts only fields, filters, and sorts from the definition.

mxHeadless and mxApi

mxApi is a transport and registry for third-party endpoints. mxHeadless ships resources and registered objects with a fixed envelope and live OpenAPI. Both packages can run on different prefixes.

Quick links

Topic	Link
Quick start	quick-start
System settings	settings
Authentication	authentication
Resources	api/resources
Swagger and OpenAPI	api/swagger
MiniShop3	extensions/minishop3
Webhooks	operations/webhooks