Docs 1
Home GitHub
menu_book Navigation menu
Documentation Advanced Development REST API & Headless

REST API & Headless

Philosophy

Pragma CMS follows a "Data-First" principle. While the core rendering engine is optimized for high-performance server-side delivery, all content is also exposed via a clean REST API. This ensures Data Portability: your content is never trapped inside the CMS and can be consumed by any external system.

Overview

All API endpoints are located in the /api directory. They provide structured access to content and system data through a clean RESTful interface, independent from the HTML rendering layer.

Standard Response Format

All API responses are unified through the sendJsonResponse() helper. While the structure is flexible via the $extra parameter, the CMS follows this professional standard:

JSON 
{
  "success": true,
  "message": null,
  "data": { ... }, 
  "meta": { ... } 
}

Note: success, message, and data are the primary keys. Additional keys like pagination or meta are injected dynamically based on the endpoint context.

Core API Endpoints

1. Public Content API (/api/content)

The primary entry point for headless delivery. It provides read-only access to published content.

Perfect for when you need to build a custom interface (Mobile apps, Digital Signage, or specialized client-side software) while keeping the Pragma Admin as your source of truth.

  • List Content: GET /api/content?action=list&type=blog&limit=10
    Retrieves a paginated list of entries for a specific content type.
  • Single Entry: GET /api/content?action=single&type=page&slug=about
    Fetches the full data of an entry, including its Custom Fields and Builder JSON (automatically decoded).

2. Universal Search API (/api/content/search)

A powerful polymorphic endpoint that searches across all Content Types and Taxonomies simultaneously using high-performance UNION ALL queries.

  • Search Mode: GET /api/search?search=design (Returns a flat list for autocompletes).
  • Navigation Mode: GET /api/search (Returns a grouped structure of recent content).
  • Link Resolution: Use the link_data parameter to resolve internal JSON "recipes" into full titles and URLs.

3. Media API (/api/media)

Handles asset metadata and optimized variants.

  • Fetch Metadata: GET /api/media?media-id=42
    Returns paths, alt texts, dimensions, and available AVIF/WebP variants generated by the engine.

4. Taxonomy API (/api/taxonomies/{type}/terms)

Manage and retrieve categories, tags, or custom hierarchies.

  • Hierarchy: GET /api/taxonomies/categories/terms?hierarchy=true
    Returns a full nested tree structure of terms.
  • Creation: Supports POST requests to create new terms on the fly (requires taxonomy_term_create permission).

5. Pages & Entries API (/api/pages & /api/entries)

Used primarily for internal management and dynamic tree navigation.

  • Tree Navigation: GET /api/pages?action=get-children&parent-id=5
    Retrieves direct children for infinite-nesting UIs.
  • Admin Rendering: Can return fields_html, allowing the admin panel to dynamically inject field editors via AJAX.

6. Forms API (/api/forms)

  • Preview: POST /api/forms?action=render-preview
    Accepts a JSON field definition and returns the rendered HTML of the form for the Admin "Preview" tab.

7. Templates API (/api/templates)

Allows safe inspection of theme and core files.

  • Security: Includes strict anti-traversal checks and directory whitelisting to ensure system files are never exposed.

JavaScript Integration

Pragma CMS includes lightweight wrappers around the Fetch API to simplify data handling in the front-end.

apiRequest(url, options, loader, expectedType)

The universal engine for all AJAX calls.

  • Automatic Error Handling: Triggers UI popups for 4xx/5xx errors.
  • CSRF Ready: Automatically injects security headers.
  • Flexible: Handles json, html fragments, and blob (downloads).

fetchApiResource(resource, searchTerm, langId, extraParams)

High-level sugar for querying CMS resources.

JAVASCRIPT 
// Example: Fetching 5 products with the term "Pro" in English
const products = await fetchApiResource("content?action=list&type=product", "Pro", 1, { limit: 5 });

if (products) {
    console.log(products.data); // Pure array of entry objects
}

Headless Best Practices

  1. CORS: The Content API sends Access-Control-Allow-Origin: * by default, allowing you to build any frontend (web, mobile, embedded systems).
  2. Builder Data: When fetching a page of type "Builder," the content key in the JSON response contains the raw Editor.js JSON. This allows your front-end to map blocks to its own components.
  3. Image Optimization: Always use the generated_variants key from the Media API to serve AVIF or WebP versions to your users instead of the original source files.