Builder API and Endpoints

Tagixo exposes a headless API consumed by SDK adapters and custom integrations.

The package ships one HTML route (/tagixo/builder/embed — the builder mount) and everything else as JSON. SDK packages (Filament, Primix) and direct consumers all build their admin UI on top of these JSON endpoints; they all point at the same embed route to drop the Vue builder onto a page.

Builder mount (the only HTML route)

GET /tagixo/builder/embed?type={type}&id={id}&back={url} — dispatched by BuilderEmbedController (invokable). Renders the tagixo::builder.embed Blade view, which mounts the Vue SPA against the record resolved by (type, id) via the BuilderTypeRegistry.

Query parameters:

• type (required) — registry key (pages, mails, pdfs, or your own custom key)
• id (required) — primary key of the record to edit
• back (optional) — absolute or relative URL injected as data-back-url; omit to hide the back button

The mount <div> carries data-page-id, data-context, data-layout-variant, data-data-url, data-config-url, and optional data-back-url. The bundled JS wires:

• tagixo:save → POST /tagixo/manage/{type}/{id}/save
• tagixo:save-global-variables → POST /tagixo/builder/global-variables
• tagixo:structure-changed → POST /tagixo/builder/stylesheet

Error responses:

• Unknown type → 404
• Unknown id → 404
• Missing type or id query → 422

Your admin links the user at this URL (anchor, iframe, or redirect). The plugin owns the editor surface; you own the chrome around it.

Bootstrap endpoints

• GET /tagixo/builder/bootstrap
• GET /tagixo/builder/config (alias)

Supported query parameters:

• context (page, form, mail, pdf, partial)
• layout_variant (default, carousel)
• bound_model (optional)
• structure (optional)

Example request:

GET /tagixo/builder/bootstrap?context=page&layout_variant=default

What bootstrap returns

The bootstrap payload is the canonical source of truth for the frontend editor.

Core fields include:

• context
• layoutVariant
• canvas
• structure
• registry.components
• registry.propTypes
• resources.icons
• resources.fonts
• resources.translations
• resources.globalVariables
• resources.dataModels
• compatibility aliases such as availableComponents, propTypeRegistry, availableFonts
• endpoints

The important architectural rule is simple:

• your frontend should render from bootstrap metadata
• your frontend should not ship a hardcoded parallel registry

Render endpoints

• POST /tagixo/builder/render
• POST /tagixo/builder/stylesheet

Typical render payload:

{
  "structure": {
    "body": {},
    "components": []
  },
  "context": "page",
  "layout_variant": "default",
  "entity_type": "page",
  "entity_id": "15"
}

Important request keys:

• structure
• context
• layout_variant
• entity_type and entity_id when the preview flow needs entity awareness

Render behavior:

• context=form uses form preview path.
• context=page + layout_variant=carousel uses carousel preview path.
• default path uses page renderer.

Typical render response:

{
  "html": "<div>...</div>",
  "css": ".vb-section {...}",
  "fonts": "<link ...>"
}

Stylesheet-only endpoint

POST /tagixo/builder/stylesheet returns only regenerated CSS.

Use this when:

• you need style refresh without full HTML render
• your host UI already owns the surrounding markup
• you are debugging CSS generation separately

Preview endpoints

• POST /tagixo/builder/preview-url — issue a short-lived signed URL for the entity
• GET /tagixo/builder/preview-mail/{id} — render a MailTemplate inline (HTML)
• GET /tagixo/builder/preview-pdf/{id} — render a PdfTemplate inline (real PDF if dompdf/dompdf is installed, otherwise print-ready HTML)

Preview flow (page context):

1. The editor calls POST /tagixo/builder/preview-url with {context: "page", entity_id}.
2. The backend returns {preview_url, expires_in} where preview_url points to the page's final public slug, carrying _preview=1 + expires + signature query params.
3. Opening the URL hits your consumer's PublicPageController, which honours the bypass via Page::isAuthorizedPreviewRequest($request) — checking valid signature, _preview=1, and an authenticated session.
4. The page renders through the final renderer pipeline, bypassing the published() gate.

Preview flow (mail / pdf contexts):

1. The editor calls POST /tagixo/builder/preview-url with {context: "mail"|"pdf", entity_id}.
2. The returned URL points at /tagixo/builder/preview-mail/{id} or preview-pdf/{id} (signed the same way).
3. The endpoint renders the template inline.

Important configuration keys:

• tagixo.preview.url_ttl_seconds — signed URL lifetime.

The signed URL is bound to the issuing user or session. Three conditions must all hold for the published gate to be bypassed: valid signature, _preview=1 query param, and authenticated session. If your middleware/auth stack is wrong, preview will fail even while bootstrap works.

Global variables and model metadata

• GET /tagixo/builder/global-variables
• PUT|POST /tagixo/builder/global-variables
• GET /tagixo/builder/models
• GET /tagixo/builder/models/{key}/attributes

Library/template/layout endpoints

• /tagixo/library/*
• /tagixo/templates/*
• /tagixo/layouts/*

Form-specific endpoints

• GET /tagixo/form-builder/config
• GET /tagixo/form-builder/models/{key}/attributes
• POST /tagixo/forms/{formKey}/submit

Adapter implementation rules

• Always consume bootstrap payload as source of truth.
• Do not hardcode component registry on the frontend.
• Keep context and layout_variant explicit in every request.
• Validate payload shape before saving.
• Keep preview and save flows separate.
• Treat body + components as the only accepted structure shape.

Practical adapter checklist

Your custom frontend integration should know how to:

1. request bootstrap
2. render the palette from availableComponents
3. render property panels from propTypeRegistry
4. submit structure to render and stylesheet endpoints
5. issue signed preview URLs
6. save raw structure to your application backend

If any of these are hardcoded outside the payload contract, your adapter will drift from the core package.