Quick start

1. Install the package

Via modstore.pro (provider https://modstore.pro/extras/, email and API key from your account) find and install mxHeadless. Or build the transport:

cd _build
php build.php

In Manager: Packages → Install Package → upload the .transport.zip.

Clear the MODX cache. Details: Installation.

2. Friendly URLs and web server

Enable friendly URLs. Requests to /api/v1/* must reach MODX index.php. Rules: Web server.

Without rewrite:

curl -s 'https://your-site.example/assets/components/mxheadless/api.php?route=/v1/health'

3. Verify the gateway

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

Discovery returns the package version and a capability snapshot. Health checks the database.

4. List resources

curl -s 'https://your-site.example/api/v1/resources?limit=5&filter[published]=1' | jq

Public reads on resources and pages work without a key. Elements, contexts, and most objects require authentication.

5. Swagger and OpenAPI

Open /api/v1/docs in a browser or fetch the spec from /api/v1/meta/openapi.json. Details: Swagger and OpenAPI.

6. Key for protected routes

In Manager: Components → mxHeadless (requires mxheadless_apikeys) or CLI:

php core/components/mxheadless/bin/api-key-create.php --name=ci --scopes=resources.read,chunks.read

The secret is shown once. Then:

curl -s https://your-site.example/api/v1/chunks \
  -H 'Authorization: Bearer mxh_...'

Next steps

• System settings
• Authentication
• Querying
• cURL examples