Connect your site
How your website reads the search and AI visibility fixes your team approves in Nagent, your published blog posts and your landing pages, with one server-side key.
Browse documentation
Fixes your team approves, live on your own site
Your team approves search and AI visibility fixes in Nagent: page titles, meta descriptions, main headings and structured data, plus FAQ sections, direct answers and llms.txt lines for the answer engines. This guide shows how your website reads those fixes and puts them on its pages. You wire it in once. After that, every fix your team approves appears on the site, and a fix they withdraw comes off it.
- Issue a key. Your team creates a site key in Nagent and hands it to you.
- Store it on the server. It goes in a server environment variable, never in browser code.
- Read the route. Your server asks Nagent for the live fixes for a page.
- Render the tags. Put the title, description, heading and JSON-LD into the HTML you send.
Want approved blog articles in WordPress? You do not need a site key for that. Connect WordPress on the Integrations settings page with an application password, and Nagent sends each approved article to your WordPress as a draft. See send approved articles to WordPress.
The fixes themselves come from DRIS, the Marketing team's visibility agent, and your team approves them in DRIS's Review tab. See DRIS, AI Visibility for how a fix is proposed and approved.

The examples use promptworld.example as your site and https://nagent.ai as the
Nagent address. Use the address shown on your Site connection card if it
differs.
What your site receives
For each page that has an approved fix, Nagent can supply:
- a page title, for the
<title>tag; - a meta description;
- a main heading, the page's H1;
- one or more JSON-LD blocks for
<script type="application/ld+json">tags; - a list of answer-engine fixes (an FAQ section, a direct answer, a schema block or an llms.txt line), each as a ready-to-paste snippet with where it goes on the page.
A page appears only when at least one fix for it is live, and each field appears only when a fix for that field is live. Everything else on the page stays exactly as you built it.
Get a key
Someone on your team with settings write permission, such as a workspace admin, issues the key in Nagent:
- Open Settings, then Integrations (nagent.ai/admin/settings/integrations), then the Site connection card, marked Beta.
- Click Issue key.
- Copy the key straight away with Copy, then select I have saved it. The key is shown once. Nagent keeps only a fingerprint of it, so nobody at Nagent can read it back.
Once a key exists, the card reads Key issued with the date. Below it, the card shows what your site actually reads with the key: "Your site last read with this key", how long ago, then each feed, Blog posts, Approved fixes, Landing pages and Learning series, marked "read" with how long ago, or "never read". Before the first read it says "Your site has not read with this key yet. Ask your developers to connect it." If the site reads posts but not fixes, the card warns that fixes you approve do not reach it, and points to Export developer handoff (see When your site does not read fixes).
Two more buttons appear once a key exists:
- Rotate key issues a new key and stops the old one at once. The site shows no fixes until the new key is deployed, so rotate when you are ready to deploy it. A lost key is replaced by rotating.
- Revoke key stops the key and issues nothing in its place. Approved fixes are kept and come back as soon as a new key is issued and deployed.
Fixes approved before any key exists are not lost. They go live as soon as a key is issued and your site reads it.
Keep the key secret
Anyone holding the key can read your approved fixes and your workspace's published blog posts and landing pages.
- Store it in a server-side environment variable, for example
NAGENT_SITE_KEY. - Never put it in a variable your framework exposes to the browser, such as one
starting with
NEXT_PUBLIC_orVITE_. - Never call the routes from browser code. Call them from your server, your build or an edge function. The routes send no CORS headers, so browsers block such a call anyway.
- Do not commit the key to your repository.
Read your fixes
GET https://nagent.ai/api/cms/site-fixes
Authorization: Bearer <your site key>
Add ?path= to read one page, for example ?path=/pricing. It accepts a path
(/pricing), the same path with a trailing slash (/pricing/), or an absolute
URL, of which only the path is used. Letter case matters, and a query string is
part of the path: ?path=/pricing does not match a page stored as
/pricing?plan=team. Encode the value with encodeURIComponent when it
contains ? or &. A path with no live fixes returns an empty list, not an
error.
Response
{
"pages": [
{
"path": "/pricing",
"url": "https://www.promptworld.example/pricing",
"title": "Workshops and pricing | Prompt World",
"description": "Two-day workshops and six-week cohorts for marketing and sales teams.",
"h1": "Prompt engineering workshops for your team",
"jsonLd": [
"{\"@context\":\"https://schema.org\",\"@type\":\"Organization\"}"
],
"fixes": [
{
"kind": "add-direct-answer",
"placement": "Place the paragraph directly under the page H1, before any other copy.",
"proposedValue": "Prompt World runs two-day prompt workshops for marketing and sales teams.",
"snippetKind": "html",
"snippet": "<p class=\"direct-answer\">Prompt World runs two-day prompt workshops for marketing and sales teams.</p>",
"approvedAt": "2026-09-29T10:15:00.000Z"
}
],
"updatedAt": "2026-09-29T10:15:00.000Z"
}
]
}
| Field | Meaning |
|---|---|
pages | Every page with at least one live fix, sorted by url. Empty when nothing is live. |
path | The page path, with any query string. No trailing slash, except / for the home page. |
url | The full page address as Nagent audited it: lower-case host, no trailing slash, no #fragment. |
title | The approved page title. Present only when a title fix is live. |
description | The approved meta description. Present only when a description fix is live. |
h1 | The approved main heading. Present only when a heading fix is live. |
jsonLd | An array of strings, each a complete JSON-LD document. Always present, often empty. |
fixes | The answer-engine fixes live on this page, oldest approval first. Always present, often empty. See below. |
updatedAt | When the most recent fix on this page was approved (ISO 8601, UTC). |
- Every field except
path,url,jsonLdandupdatedAtis optional. Keep your own value whenever one is missing. - Each
jsonLdentry is a string, ready to place inside a script tag as it is. Do not parse and re-serialise it, and do not wrap it inJSON.stringifyagain. Any<inside it is already written as\u003c, so a stray</script>in a page title cannot end your tag early. A page may carry several entries, for example an organisation block and a breadcrumb block. - Each entry in
fixeshas akind(add-faq,add-direct-answer,add-schemaoraugment-llms-txt), aplacementsaying where it goes, theproposedValue, acurrentValuewhen there is one, asnippetKind(html,json-ldorllms-txt), thesnippetitself andapprovedAt. Paste the snippet whereplacementsays. An FAQ or schema fix also puts its JSON-LD injsonLd, so a site that already rendersjsonLdgets that part without extra work. - The newest approval wins. If fixes for the same field were approved at different times, the page shows the most recent one.
- Pages are keyed by their full URL. If your site answers on two hosts, such as
promptworld.exampleandwww.promptworld.example, the same path on each is a separate entry and?path=/pricingreturns both. Match onurlto tell them apart.
Status codes
| Status | When | What to do |
|---|---|---|
| 200 | The key is valid. | Use pages, which may be empty. |
| 401 | No Authorization header, a header that is not Bearer <key>, or a key that is wrong, rotated or revoked. Carries WWW-Authenticate: Bearer and is never cached. | Check the key and the environment variable. A rotated key stops working at once. |
| 500 | A fault on Nagent's side. | Not a key problem, so do not rotate. Render the page with your own values and try again on the next request. |
Caching
A successful answer carries Cache-Control: private, max-age=300 and
Vary: Authorization. Fixes change only when someone approves or withdraws
one, so reading the route at most every five minutes is plenty, and a change in
Nagent shows on your site within about five minutes.
Cache the answer on your own server, keyed on your key. Never put it in a shared CDN or proxy cache keyed only on the URL: the answer belongs to one workspace.
Apply fixes automatically
You do not have to write the integration by hand. Three ready-made readers put approved fixes into the HTML your server sends, so crawlers that do not run JavaScript see them. Each one is a single file. Pick the one that matches your site:
| Your site | Use | Download |
|---|---|---|
| A WordPress site | The WordPress plugin | nagent-site-fixes.php |
| Any site behind Cloudflare | The Cloudflare Worker | cloudflare-worker.js |
| A Next.js site (App Router) | The Next.js helper | nextjs-site-fixes.ts |
| Anything else | The feed itself | See Connect your stack |
All three need the same two settings: the Nagent address from your Site connection card (the feed origin) and your site read key. All three keep the key on the server.
What to expect from all three:
- Nothing changes on a page until a fix for that page is approved.
- A fix your team withdraws comes off the page.
- Each reader keeps the feed's answer for ten minutes, so an approval or a withdrawal shows on your site within about ten minutes.
- If Nagent cannot be reached, your pages are served with their own values.
- The FAQ sections and direct answers in
fixesare not placed for you. Where visible content goes on a page needs a person. Their structured data is injsonLd, which is applied.
The WordPress plugin and the Cloudflare Worker are new. Try them on a staging site first, and check a few pages with View source before you use them on your live site.
WordPress plugin
- Download
nagent-site-fixes.phpand upload it towp-content/plugins/on your site, then activate Nagent Site Fixes on the Plugins page. - Open Settings, then Nagent Site Fixes. An administrator can open it.
- Enter the feed origin, for example
https://nagent.ai, and paste your site read key. After saving, the key is shown masked.
The plugin applies the page title, the meta description and the JSON-LD blocks. If Yoast SEO or Rank Math is active, the title and description go through that plugin's own filters, so each page keeps one title and one description. With another SEO plugin you may see two descriptions; check the page source. The main heading is printed by your theme, so the plugin does not change it.
To keep the key out of the database, set it in wp-config.php instead. The
settings page then shows the fields as set there:
define('NAGENT_SITE_KEY', 'your site read key');
define('NAGENT_FEED_ORIGIN', 'https://nagent.ai');
If you already added the hand-written code from the WordPress section below, remove it before you activate the plugin.
Cloudflare Worker
Use this when your site's traffic goes through Cloudflare, whatever the site is built with.
- In Cloudflare, create a Worker and paste in
cloudflare-worker.js. There is no build step. - Under the Worker's settings, add two variables:
NAGENT_FEED_ORIGINas text, for examplehttps://nagent.ai, andNAGENT_SITE_KEYas a secret holding your site read key. - Add a route that sends your site's pages through the Worker, for example
www.promptworld.example/*.
For each HTML page, the Worker reads the fixes for that path and rewrites the
title, the meta description, the JSON-LD blocks and the main heading. It
updates the og: and twitter: title and description tags the page already
has and adds none. The main heading is replaced only on a page with exactly
one h1. The Worker waits at most about a second and a half for Nagent. If
the answer is late or fails, the page from your server is sent unchanged. It
does not store your pages.
Next.js helper
- Copy
nextjs-site-fixes.tsinto your app, for example tolib/nagent-site-fixes.ts. - Set
NAGENT_SITE_KEYin your server environment. SetNAGENT_FEED_ORIGINonly if your Nagent address is nothttps://nagent.ai. - Wrap the metadata of each page, or of a shared layout:
import type { Metadata } from 'next';
import { withSiteFix } from '@/lib/nagent-site-fixes';
export async function generateMetadata(): Promise<Metadata> {
return withSiteFix('/pricing', {
title: 'Pricing',
description: 'Our plans.',
});
}
withSiteFix returns your own metadata with the approved title and
description on top. getSiteFix(path) returns the whole entry, for the main
heading and the JSON-LD blocks. A comment at the top of the file shows a
small server component that prints the JSON-LD.
Connect your stack
Pick the section that matches how your pages are built. Nagent never writes into your CMS; your site reads the fixes and your CMS content stays as it is.
Next.js (App Router)
Read the route on the server, use it in generateMetadata for the title and
description, then render the H1 and JSON-LD in the page. If the route fails or
is slow, the page falls back to its own values and still renders.
// lib/site-fixes.ts
import 'server-only';
export interface SiteFix {
path: string;
url: string;
title?: string;
description?: string;
h1?: string;
jsonLd: string[];
updatedAt: string;
}
const NAGENT = 'https://nagent.ai';
const SITE_ORIGIN = 'https://www.promptworld.example';
export async function siteFix(path: string): Promise<SiteFix | null> {
const key = process.env.NAGENT_SITE_KEY;
if (!key) return null;
try {
const res = await fetch(
`${NAGENT}/api/cms/site-fixes?path=${encodeURIComponent(path)}`,
{
headers: { Authorization: `Bearer ${key}` },
next: { revalidate: 300 },
signal: AbortSignal.timeout(3000),
},
);
if (!res.ok) return null;
const { pages } = (await res.json()) as { pages: SiteFix[] };
const onThisHost = pages.find(p => p.url.startsWith(SITE_ORIGIN));
return onThisHost ?? pages[0] ?? null;
} catch {
return null;
}
}
// app/pricing/page.tsx
import type { Metadata } from 'next';
import { siteFix } from '@/lib/site-fixes';
const DEFAULTS = {
title: 'Pricing',
description: 'Plans and prices.',
h1: 'Pricing',
};
export async function generateMetadata(): Promise<Metadata> {
const fix = await siteFix('/pricing');
return {
title: fix?.title ?? DEFAULTS.title,
description: fix?.description ?? DEFAULTS.description,
};
}
export default async function PricingPage() {
const fix = await siteFix('/pricing');
return (
<>
{fix?.jsonLd.map((ld, i) => (
<script
key={i}
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: ld }}
/>
))}
<h1>{fix?.h1 ?? DEFAULTS.h1}</h1>
{/* the rest of your page */}
</>
);
}
- Next.js shares one fetch between
generateMetadataand the page when the URL and options match, so the route is read once per render. next: { revalidate: 300 }matches the route's five minute cache, held in your own server's data cache.- For many pages, call
siteFixfrom a shared layout or dynamic route with the current path, or read the route once without?path=and look pages up bypath.
WordPress
This section shows how a WordPress site reads your approved fixes. To send approved articles into WordPress as drafts instead, see send approved articles to WordPress.
WordPress runs PHP on every page, so it can read the route on the server. Add
the key to wp-config.php:
define('NAGENT_SITE_KEY', 'your site key');
Then add this to a small plugin or your theme's functions.php:
function nagent_site_fix() {
static $fix = null;
static $done = false;
if ($done) return $fix;
$done = true;
if (!defined('NAGENT_SITE_KEY')) return null;
$path = wp_parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH) ?: '/';
$cache_key = 'nagent_fix_' . md5($path);
$cached = get_transient($cache_key);
if ($cached !== false) return $fix = ($cached ?: null);
$res = wp_remote_get(
'https://nagent.ai/api/cms/site-fixes?path=' . rawurlencode($path),
[
'headers' => ['Authorization' => 'Bearer ' . NAGENT_SITE_KEY],
'timeout' => 3,
]
);
if (is_wp_error($res) || wp_remote_retrieve_response_code($res) !== 200) {
return null;
}
$pages = json_decode(wp_remote_retrieve_body($res), true)['pages'] ?? [];
$origin = untrailingslashit(strtolower(home_url()));
$page = null;
foreach ($pages as $p) {
if (strpos($p['url'], $origin) === 0) { $page = $p; break; }
}
$page = $page ?? ($pages[0] ?? null);
set_transient($cache_key, $page ?: '', 5 * MINUTE_IN_SECONDS);
return $fix = $page;
}
add_filter('pre_get_document_title', function ($title) {
return nagent_site_fix()['title'] ?? $title;
}, 20);
add_action('wp_head', function () {
$fix = nagent_site_fix();
if (!$fix) return;
if (!empty($fix['description'])) {
echo '<meta name="description" content="'
. esc_attr($fix['description']) . '">' . "\n";
}
foreach ($fix['jsonLd'] as $ld) {
echo '<script type="application/ld+json">' . $ld . '</script>' . "\n";
}
}, 1);
- A failed or slow read returns nothing and the page renders with its own values. Only a successful answer is cached, for five minutes, in a transient.
- Print each
jsonLdentry as it arrives. Passing it throughesc_htmlorwp_json_encodebreaks it. - If an SEO plugin such as Yoast or Rank Math writes the title and description,
feed the fix through its filters instead of the two hooks above, so each page
has one title and one description. Yoast uses
wpseo_titleandwpseo_metadesc; Rank Math usesrank_math/frontend/titleandrank_math/frontend/description. - The main heading is printed by your theme's templates. Where the template prints the page heading, print the fix when there is one:
echo esc_html(nagent_site_fix()['h1'] ?? get_the_title());
Headless CMS with your own front end
If your content lives in a headless CMS such as Contentful, Sanity, Strapi or Storyblok and a front end you control renders the pages, wire the route into that front end as the Next.js section shows. The approved fix takes the place of the CMS value when the page renders. Your editors keep working in the CMS as before. While a fix is live it wins; once it is withdrawn, the CMS value shows again.
Single-page apps (for example Vite and React)
Search crawlers, and most AI crawlers in particular, read the HTML your server sends, and many do not run JavaScript. A title or JSON-LD block set in the browser after load is invisible to them, so put the fixes into the HTML your build or server produces:
- At build time. Read the route in a prerender step or a small script that
runs before
vite build, and write the tags into each page's HTML. New fixes then appear after the next build, so rebuild on a schedule if they should appear without a manual deploy. - On the server or at the edge. If your host can run code in front of your static files (server rendering, an edge function or a worker), read the route there, keep the key in that environment, and insert the tags before the HTML is sent.
Reading the route from browser code is not an option: it would hand the key to every visitor, and browsers block the call.
Shopify, Webflow, Wix and Squarespace
These builders do not let you run your own code on the server, so the site cannot read the route with a secret key, and the key must never go into theme JavaScript. For a site like this:
- Do not issue a site key.
- In Nagent, open the fix from DRIS's Queue with Open in its queue, and copy the title, description or JSON-LD from its After values.
- Paste it into the platform's own SEO fields or custom code area.
- Click Mark applied on the finding instead of approving it. Approving puts a fix on the connection, which this site does not read. The next audit checks the change is on the page.
When your site does not read fixes
Some approved fixes have nowhere to go on their own: nothing in Nagent can apply them, or your site does not read the fixes route. On DRIS's AEO proposals page, Export developer handoff downloads them as one Markdown checklist: "Approved fixes nothing can apply, and served fixes your site does not read yet, as one checklist for your developers". Each change is listed under its page with where it goes, the current value, the snippet and an Applied box to tick. Once your site reads the fixes route, served fixes leave the checklist.
Your blog posts
The same key reads the published blog posts in your Nagent workspace.
GET https://nagent.ai/api/cms/blogs
GET https://nagent.ai/api/cms/blogs/<slug>
Authorization: Bearer <your site key>
With a valid key, both routes return only your workspace's published posts,
never drafts and never another workspace's posts, with
Cache-Control: private, max-age=300 and Vary: Authorization. A wrong,
rotated or revoked key returns 401, as on the fixes route.
A missing key behaves differently here. With no Authorization header at
all, the blog routes do not refuse: they answer with the public posts of the
site you called, which on nagent.ai are Nagent's own. So if your site shows
posts you did not write, check that the header is being sent.
The list
| Parameter | Meaning |
|---|---|
page | Page number, from 1. Default 1. |
per_page | Posts per page, 1 to 100. Default 25. |
tag | Only posts with this tag. |
category | Only posts in this category. |
fields=preview | Leave out each post body, for listing pages. |
Posts are newest first. total counts every published post matching the
filters, across all pages.
{
"stories": [ { "slug": "...", "name": "...", "content": { } } ],
"cv": 1790000000000,
"rels": [],
"links": [],
"total": 42,
"page": 1,
"per_page": 25
}
A single post
GET /api/cms/blogs/<slug> returns
{ "story": { ... }, "cv": ..., "rels": [], "links": [] }, or 404 with
{ "error": "Blog not found" } when no published post has that slug. Each read
of a single post counts as one view in Nagent, so cache it on your server
rather than reading it on every visit.
Fields of a post
| Field | Meaning |
|---|---|
name | The post title. |
slug | The post slug; full_slug is blog/<slug>. |
uuid | The post's stable id. |
published_at, created_at, updated_at | ISO 8601 timestamps. |
tag_list | The post tags. |
content.shortDescription | The excerpt. |
content.metaTitle, content.metaDescription | The post's own SEO title and description, when set. The description falls back to the excerpt. |
content.coverImage | The cover image URL, or an empty string. |
content.date, content.readTime | Publication date, and reading time in minutes as a string. |
content.category, content.tags | The category, and the tags as one comma-separated string. |
content.content | The body as rich text (ProseMirror JSON), the same type on the list and single post routes, including for posts written as HTML. With fields=preview it is an empty document. |
A single post also carries content.authorName, content.authorEmail and
content.authors, each author with name, role and avatarUrl. They hold
your workspace's default blog author (see
CREA and the content studio). A post with no author
set returns an empty content.authorName.
Your landing pages
The same key reads the landing pages your team publishes in Nagent, built
with LANDON in Brand Studio, then Landing pages. Your site serves
each page at an address on your own domain, such as
https://www.promptworld.example/offers/spring, so the page has your
domain, not Nagent's. You wire this once. After that, every page your team
publishes appears at its address within about five minutes, and a page they
take offline comes off. How your team builds and publishes the pages is in
Decks and landing pages.
- Your team sets the address. In the page's editor, the Website tab
has Address on your site. They enter the full address, starting with
https://, and save. Two pages cannot share an address. - Your site answers that path. A route on your site reads the page from Nagent by its path and renders it.
- Leads still reach Nagent. The page's form posts to Nagent, from any domain, so every submission lands in your team's Leads.
Once an address is set, Nagent's own copy of the page, and any package downloaded from the Website tab, names your address as canonical. Search engines index the page on your domain, not on Nagent's.
GET https://nagent.ai/api/cms/landing-pages
GET https://nagent.ai/api/cms/landing-pages?path=/offers/spring
Authorization: Bearer <your site key>
| Parameter | Meaning |
|---|---|
path | Only the page whose address on your site has this path. It accepts a path starting with /, or the full address, which must then match host and all. A trailing slash is ignored and letter case matters. A path is unique within your workspace, so one path never names two pages. |
slug | Only the page with this Nagent slug, the last part of its nagent.ai/lp/... address. |
With neither, the route lists every published page in your workspace. Only published pages appear, never drafts or templates and never another workspace's pages. A path with no published page, or a value that is not a path, returns an empty list, not an error. Caching and status codes are as for the fixes route: a five minute private cache, and 401 for a missing, wrong, rotated or revoked key.
Response
{
"pages": [
{
"slug": "spring",
"title": "Spring workshops",
"seo": {
"title": "Spring workshops | Prompt World",
"description": "Two-day prompt engineering workshops this spring.",
"noindex": false
},
"url": "https://nagent.ai/lp/promptworld/spring",
"siteUrl": "https://www.promptworld.example/offers/spring",
"path": "/offers/spring",
"canonicalUrl": "https://www.promptworld.example/offers/spring",
"submitUrl": "https://nagent.ai/api/lp/promptworld/spring/submit",
"fontsHref": "https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700;800&display=swap",
"html": "<style>...</style>\n<div class=\"lp-root\">...</div>\n<script>...</script>",
"publishedAt": "2026-10-11T10:15:00.000Z"
}
]
}
| Field | Meaning |
|---|---|
slug, title | The page's Nagent slug and its title. |
seo | The page's SEO title, description, optional ogImageUrl, and noindex. When noindex is true, add <meta name="robots" content="noindex, nofollow">. |
url | The copy Nagent hosts. |
siteUrl, path | The address your team set, and its path. Both null when none is set. |
canonicalUrl | The address search engines should index: siteUrl when set, otherwise url. Put it in a canonical link. |
submitUrl | Where the page's form posts. It is already inside html. |
fontsHref | A Google Fonts stylesheet for the page's fonts, or null. |
html | The page itself: its styles, markup and form script, ready to place inside your <body>. Every value in it is escaped. |
publishedAt | When the live version was published (ISO 8601, UTC). |
- Place
htmlexactly as received. It carries its own styles, scoped to the page, and a small script that submits the form without leaving the page. Where a CMS strips scripts, the form still works as a plain form post and shows a thank-you page from Nagent. - Images and fonts load from the addresses set in the editor and from Google
Fonts. A strict Content Security Policy must allow them, and allow form
posts to
https://nagent.ai.
Next.js (App Router)
Pick the part of your site the pages live under, here /offers, and add a
dynamic route for it. Your team then gives each page an address under
https://www.promptworld.example/offers/.
// app/offers/[slug]/page.tsx
import 'server-only';
import type { Metadata } from 'next';
import { notFound } from 'next/navigation';
interface LandingPage {
title: string;
seo: { title: string; description: string; noindex: boolean };
canonicalUrl: string;
fontsHref: string | null;
html: string;
}
async function landingPage(path: string): Promise<LandingPage | null> {
const key = process.env.NAGENT_SITE_KEY;
if (!key) return null;
try {
const res = await fetch(
`https://nagent.ai/api/cms/landing-pages?path=${encodeURIComponent(path)}`,
{
headers: { Authorization: `Bearer ${key}` },
next: { revalidate: 300 },
signal: AbortSignal.timeout(3000),
},
);
if (!res.ok) return null;
const { pages } = (await res.json()) as { pages: LandingPage[] };
return pages[0] ?? null;
} catch {
return null;
}
}
type Props = { params: Promise<{ slug: string }> };
export async function generateMetadata({ params }: Props): Promise<Metadata> {
const { slug } = await params;
const page = await landingPage(`/offers/${slug}`);
if (!page) return {};
return {
title: page.seo.title || page.title,
description: page.seo.description,
alternates: { canonical: page.canonicalUrl },
robots: page.seo.noindex ? { index: false, follow: false } : undefined,
};
}
export default async function OfferPage({ params }: Props) {
const { slug } = await params;
const page = await landingPage(`/offers/${slug}`);
if (!page) notFound();
return (
<>
{page.fontsHref && <link rel="stylesheet" href={page.fontsHref} />}
<div dangerouslySetInnerHTML={{ __html: page.html }} />
</>
);
}
- A page taken offline, or a path with no page, gives your own 404.
- To serve pages at any path rather than under one folder, put the same
lookup in a catch-all route,
app/[...path]/page.tsx, and join the segments into the path. Next.js tries your other routes first. - Your site's header and footer wrap the page when the route sits inside your root layout. For a page on its own, put the route in a separate route group with a plain layout.
WordPress
Add this to the plugin or functions.php from the WordPress section above.
It runs only when WordPress has no page of its own at the address, so it
never replaces one of your pages and adds no request to them.
add_action('template_redirect', function () {
if (!is_404() || !defined('NAGENT_SITE_KEY')) return;
$path = wp_parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH) ?: '/';
$path = untrailingslashit($path) ?: '/';
$cache_key = 'nagent_lp_' . md5($path);
$page = get_transient($cache_key);
if ($page === false) {
$res = wp_remote_get(
'https://nagent.ai/api/cms/landing-pages?path=' . rawurlencode($path),
[
'headers' => ['Authorization' => 'Bearer ' . NAGENT_SITE_KEY],
'timeout' => 3,
]
);
if (is_wp_error($res) || wp_remote_retrieve_response_code($res) !== 200) {
return;
}
$pages = json_decode(wp_remote_retrieve_body($res), true)['pages'] ?? [];
$page = $pages[0] ?? '';
set_transient($cache_key, $page, 5 * MINUTE_IN_SECONDS);
}
if (!$page) return;
status_header(200);
nocache_headers();
$title = $page['seo']['title'] ?: $page['title'];
echo "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n";
echo '<meta name="viewport" content="width=device-width, initial-scale=1">' . "\n";
echo '<title>' . esc_html($title) . "</title>\n";
if (!empty($page['seo']['description'])) {
echo '<meta name="description" content="'
. esc_attr($page['seo']['description']) . '">' . "\n";
}
if (!empty($page['seo']['noindex'])) {
echo '<meta name="robots" content="noindex, nofollow">' . "\n";
}
echo '<link rel="canonical" href="' . esc_url($page['canonicalUrl']) . '">' . "\n";
if (!empty($page['fontsHref'])) {
echo '<link rel="stylesheet" href="' . esc_url($page['fontsHref']) . '">' . "\n";
}
echo "<style>body{margin:0}</style>\n</head>\n<body>\n";
echo $page['html'];
echo "\n</body>\n</html>\n";
exit;
});
- Print
htmlas it arrives. Passing it throughwp_ksesoresc_htmlstrips the page's styles and form. - The page is served on its own, without your theme. To show it inside your
theme instead, print
$page['html']from a page template betweenget_header()andget_footer().
Shopify, Webflow, Wix and Squarespace
These builders cannot read the route with a secret key. Download the page from the editor's Website tab instead: the zip holds the page as plain HTML and a fragment to paste into the platform's custom code block. The form in it still sends leads to Nagent. Set the page's address on your site first, so the download names it as canonical, and download again after each change your team publishes.
Check the connection
From a terminal on your server:
curl -i https://nagent.ai/api/cms/site-fixes \
-H "Authorization: Bearer $NAGENT_SITE_KEY"
A working key answers like this:
HTTP/1.1 200 OK
cache-control: private, max-age=300
vary: Authorization
content-type: application/json
{"pages":[]}
{"pages":[]} means the key works and nothing is live yet. Ask your team to
approve a fix, and it appears on the next read. Each read with the key shows
on the Site connection card within a few minutes, feed by feed, so your team
can see the site is connected.
Troubleshooting
| What you see | Likely cause | Fix |
|---|---|---|
| Every read is 401 | The key is missing from the server environment, has a stray space or quote, or was rotated. | Print the length of the variable on the server (never the value). If the key was rotated, deploy the new one. |
pages is empty | Nothing is approved yet, or ?path= does not match the stored path. | Read without ?path= and compare. Case matters, and a query string is part of the path. |
| An approved fix does not show | Your cache or the route's five minute cache still holds the older answer. | Wait five minutes, or clear your own server cache. |
| Two titles or two descriptions on a WordPress page | An SEO plugin writes its own tags as well. | Feed the fix through the plugin's filters, as shown in the WordPress section. |
| The JSON-LD shows as text or breaks the page | The entry was escaped or re-serialised. | Print each jsonLd string exactly as received inside the script tag. |
| The blog shows posts you did not write | The Authorization header is missing, so the route answers with the public posts of the host you called. | Send Authorization: Bearer <key> on every blog read. |
| A landing page's path gives your own 404 | The page is not published, has no address on your site, or its address has a different path. | Read the landing pages route without ?path= and compare each path. Case matters. |
| A landing page shows without styles, or its form does nothing | The html was escaped or filtered, or a Content Security Policy blocks it. | Place html exactly as received, and allow Google Fonts, the page's images and form posts to Nagent. |
Questions about a fix itself, such as why it was suggested or what it changes, go to the person on your team who approves fixes in Nagent.