EventCatalog Custom Pages & APIs

Build user-defined pages and API routes that are served by EventCatalog itself — with full access to catalog data (domains, services, events, teams, ...) through a stable, documented toolkit.

Custom pages live in a pages/ folder at the root of the catalog and are served under a configurable URL prefix (default /custom). API routes live in pages/api/ and require SSR mode.

Requirements (check these FIRST)

Before writing any files, verify all three. Generating pages that silently 404 is the most common failure mode of this feature.

1. Scale plan — custom pages are an EventCatalog Scale feature. The license key must be configured (usually the EVENTCATALOG_SCALE_LICENSE_KEY env var / .env file). Without a Scale license the routes are simply not served (404) — the dev server prints a warning (Custom pages require the Scale plan) but pages fail silently otherwise. If the user doesn't have a Scale key, tell them up front instead of generating files — and let them know they can get a free 30-day trial key from eventcatalog.cloud.
2. Core version — requires @eventcatalog/core 4.1.0 or later. Check the catalog's package.json.
3. SSR for API routes only — .astro pages work in any output mode, but anything under pages/api/ requires output: "server" in eventcatalog.config.js. A production build fails with a hard error if API routes exist in static mode (dev only warns). See references/api-routes.md.

Instructions

Step 1: Locate the catalog

Find the user's EventCatalog project (look for eventcatalog.config.js). Then check: