GET STARTED

Mentionwell is a headless content engine with a public read-only API. Your destination site pulls content; Mentionwell never writes to your codebase.

The data model

Five top-level objects live in Mentionwell's database. Most operations move data from one to the next.

  • Site — one destination domain. Has a brand profile, taxonomy, delivery config, and an automation policy.
  • Taxonomy — a tree of content clusters. Headlines get attached to nodes for topical authority + internal linking.
  • Headline — a planned article. Has a target keyword, search intent, schedule, and lifecycle status (proposed → approved → queued → generating → drafted → scheduled → published).
  • Draft — a generated article waiting on review. Includes HTML, Markdown, FAQs, JSON-LD, sources, and a measured cost.
  • Post — a published article. Same shape as a draft plus published: true + publishedAt.

Plus Run (one execution of the planner / writer / critic / publish flow, with cost + duration) and Job (one worker run on the queue: onboarding, draft, publish, autopilot, refresh).

The pipeline

Site profile + taxonomy
        │
        ▼
   Headline ─────► Draft ─────► Post ─────► /api/public/.../posts
   (planner)      (writer +     (publish     (your site fetches)
                   critic)       flow)

Every step writes to the database; the API serves directly off the latest published row.

Two halves: push and pull

Mentionwell supports both delivery directions, and most sites use one or both:

  • Pull (the default): your destination reads the Reader API on its own schedule — every request (SSR), every revalidation (ISR / SWR), or every rebuild (static). Mentionwell doesn't have to do anything on publish — your site fetches when it next needs to render.
  • Push (optional): Mentionwell calls a webhook on your destination the moment a post publishes, so the destination can revalidate cached paths or kick off a rebuild. This is what makes static sites publish in under a minute instead of waiting for the next cron rebuild.

The two halves are independent. A static site usually needs both (push to trigger a rebuild + pull during the rebuild to fetch new posts). An SSR site usually needs only pull. The Connect wizard picks the right combination for your stack and saves it as the site's delivery mode.

Wizard architecture Push half Pull half When articles appear
Static + deploy hook Webhook → deploy hook → rebuild Build-time fetch ~30–90s (rebuild time)
Next.js ISR Webhook → revalidatePath() Request-time fetch with next: { tags } Seconds
Dynamic / api_reader none (intentionally) Request-time or short-TTL fetch Next visit picks it up
GitHub MDX MentionWell commits an MDX file to your repo Your CI/CD picks up the commit 1–3 min (commit + their CI build)
CMS adapter Webhook → adapter → create-draft in your CMS The CMS renders the post itself Depends on CMS

Three reasons the design leans into pull rather than push-only:

  1. No deploy on every post (for SSR sites). You publish in Mentionwell and the next request picks it up. No CI run, no minutes burned.
  2. No coupling. Your destination doesn't need a CMS adapter, plugin, or per-publish webhook unless you choose one — pull works with any framework.
  3. Caching is honest. The Reader API returns ETag + Cache-Control headers tuned for SWR. Your CDN takes care of the rest.

What lives where

Concern Where it lives
Article body (HTML, Markdown, JSON-LD, FAQ, TOC) Mentionwell database, served via /api/public
Site chrome (header, footer, layout) Your destination repo
URL structure (/blog, /blog/[slug]) Your destination repo (typically)
SEO metadata for the article Mentionwell returns it; your destination renders it into <head>
RSS / JSON Feed / sitemap Mentionwell serves them; you link to them from your destination
Auth + roles Mentionwell handles internal auth; your destination only needs the read API key

What Mentionwell is not

  • Not a CMS. There's no rich-text editor for non-technical users; it's an AI editorial pipeline.
  • Not a static site generator. Posts aren't built into your site at deploy time.
  • Not a CDN. The reader API has caching headers; your destination's CDN does the actual edge serving.

Once this model clicks, every weird symptom ("post isn't showing", "it's stale", "preview is fine but prod isn't") collapses to either: env var wrong, cache stale, or post not published yet. Treat those three as your first checks every time.

Read this page as Markdown

66 beta testing now