This is the full developer documentation for CitedSEO
# Your articles, in your own stack.
> Show the articles CitedSEO writes on your own site. A static feed with no key, signed webhooks when an article goes live or changes, and a guide for your framework.
# Read the feed
> The CitedSEO feed is static JSON on feeds.citedseo.ai, a small manifest that points at pages of articles and one file per article, with no key.
The feed is how a site that shows its articles itself gets them. It is static JSON, served from `feeds.citedseo.ai` through Cloudflare’s network, so reading it is fast and you can read it as often as you like.
It is not an API you query. It is a snapshot of exactly the articles that are live on your site, written again each time one is published, changed or taken down, and when the site’s article settings or an author change.
## The files
[Section titled “The files”](#the-files)
Everything for one site lives under its [site ID](/site-id):
```txt
feeds.citedseo.ai/{siteId}/
feed/index.json the manifest
b/{buildId}/page-1.json 20 articles a page, newest first
b/{buildId}/page-2.json
b/{buildId}/by-slug/{slug}.json one article
```
There is no key, no header and no query parameter on any of them. Any origin may read them, so they work from the browser too.
## Reading it
[Section titled “Reading it”](#reading-it)
1. **Read the manifest.** It is the only file that changes in place, and it names the current build.
2. **Read from that build.** Its pages for the whole list, or one by-slug file for a single article.
Always start from the manifest. Never keep a `buildId` in your code: it changes with every publish.
## The manifest
[Section titled “The manifest”](#the-manifest)
GET`https://feeds.citedseo.ai/{siteId}/feed/index.json`
* `buildId`string
The current build. Use it in the address of every other file.
* `total`number
How many articles are live.
* `pageCount`number
How many pages the build has. `0` when nothing is live.
* `pageSize`number
How many articles a full page holds: `20`.
* `latestModifiedAt`string | null
When the newest article in the build last changed, as an ISO 8601 time in UTC. `null` when nothing is live.
* `generatedAt`string
When this build was written.
* `removed`true
Present only on the feed of a site that has been removed from CitedSEO: the manifest stays, with `total` 0, and nothing more is published to it.
200 OK
```json
{
"buildId": "01JA2M7Q4K8ZP3",
"total": 42,
"pageCount": 3,
"pageSize": 20,
"latestModifiedAt": "2026-10-11T02:05:00.000Z",
"generatedAt": "2026-10-11T02:05:04.000Z"
}
```
## A page of articles
[Section titled “A page of articles”](#a-page-of-articles)
GET`https://feeds.citedseo.ai/{siteId}/b/{buildId}/page-{n}.json`
Pages are numbered from `1` to the manifest’s `pageCount`. Each holds up to 20 articles, newest first.
* `articles`Article\[]
The page’s [articles](/feed/article), whole: every field, with both bodies.
200 OK
```json
{
"articles": [
{
"id": "0b6f6c1e-3f0a-4a59-9d0e-2f8f4c1f7a31",
"slug": "how-to-brew-green-tea",
"url": "https://example.com/blog/how-to-brew-green-tea",
"title": "How to brew green tea",
"description": "Brew green tea at 80°C for two minutes. Here is why the temp…",
"cover": {
"src": "https://example.com/images/green-tea.webp",
"alt": "A glass teapot of green tea"
},
"author": {
"name": "Sam Lee",
"url": "https://example.com/authors/sam-lee"
},
"publishedAt": "2026-10-09T02:05:00.000Z",
"modifiedAt": "2026-10-11T02:05:00.000Z",
"html": "
Brew green tea at 80°C for two minutes. Hot…",
"markdown": "**Brew green tea at 80°C for two minutes. Hotter water makes…",
"structuredData": {
"@context": "https://schema.org",
"@graph": [
"…"
]
}
}
]
}
```
The long fields are cut short above.
## One article
[Section titled “One article”](#one-article)
GET`https://feeds.citedseo.ai/{siteId}/b/{buildId}/by-slug/{slug}.json`
Put the slug in the address as the article’s `slug` has it. That is already URL-encoded (`caf%C3%A9`, not `café`), so don’t encode it again; encode a slug only when it reached you decoded, as most routers give it. The file answers `404` when no live article has that slug, which is how you tell a page that doesn’t exist.
* `article`Article
The [article](/feed/article), the same object a page holds.
200 OK
```json
{
"article": {
"id": "0b6f6c1e-3f0a-4a59-9d0e-2f8f4c1f7a31",
"slug": "how-to-brew-green-tea",
"url": "https://example.com/blog/how-to-brew-green-tea",
"title": "How to brew green tea",
"description": "Brew green tea at 80°C for two minutes. Here is why the temp…",
"cover": {
"src": "https://example.com/images/green-tea.webp",
"alt": "A glass teapot of green tea"
},
"author": {
"name": "Sam Lee",
"url": "https://example.com/authors/sam-lee"
},
"publishedAt": "2026-10-09T02:05:00.000Z",
"modifiedAt": "2026-10-11T02:05:00.000Z",
"html": "
Brew green tea at 80°C for two minutes. Hot…",
"markdown": "**Brew green tea at 80°C for two minutes. Hotter water makes…",
"structuredData": {
"@context": "https://schema.org",
"@graph": [
"…"
]
}
}
}
```
```js
const feed = 'https://feeds.citedseo.ai/YOUR_SITE_ID';
const manifest = await fetch(`${feed}/feed/index.json`).then((res) => res.json());
// slug as the article has it, already URL-encoded.
const res = await fetch(`${feed}/b/${manifest.buildId}/by-slug/${slug}.json`);
if (!res.ok && res.status !== 404) throw new Error(`The feed answered ${res.status}`);
// 404 is the one answer that means there is no such article.
const article = res.ok ? (await res.json()).article : null;
```
## What is in the feed
[Section titled “What is in the feed”](#what-is-in-the-feed)
* **Only what is live.** An article appears once it has been published, at the version that is live. A newer draft waiting for approval is not in the feed until it ships.
* **Every live article, wherever it publishes.** A site connected to WordPress has the same articles in its feed as on WordPress.
* **Nothing private.** The feed is what your site already shows the public.
When an article is taken down
The feed is rebuilt without it: it is gone from the pages and its by-slug file answers `404` in the new build. There is no “deleted” entry to look for.
## Next
[Section titled “Next”](#next)
[The article](/feed/article)Every field, with a full example.
[Caching and limits](/feed/caching)What is cached for how long, and why builds never change.
# The article
> Every field of an article as the CitedSEO feed serves it and a webhook sends it, with a full example.
An article has one shape. A feed page holds a list of them, a by-slug file holds one, and a webhook sends one, so code that draws one draws them all.
## Fields
[Section titled “Fields”](#fields)
* `id`string
The article’s ID. It never changes, so use it as your key when you store articles.
* `slug`string
The last part of the article’s address, to route by. For `https://example.com/blog/how-to-brew-green-tea` it is `how-to-brew-green-tea`.
* `url`string
The article’s full address on your site. Use it as the canonical address.
* `title`string
The title, as plain text.
* `description`string
The search snippet, for the page’s meta description.
* `cover`object | null
The cover image as `{ src, alt }`, or `null` when the article has none.
* `author`object | null
The byline as `{ name, url }`, where `url` is the author’s page or `null`. The whole field is `null` when the article is by the site itself.
* `publishedAt`string
When the article first went live, as an ISO 8601 time in UTC.
* `modifiedAt`string
When the live version last changed, as an ISO 8601 time in UTC.
* `html`string
The body as HTML, without the title or cover. See [The body as HTML](/feed/html).
* `markdown`string
The same body as Markdown. See [The body as Markdown](/feed/markdown).
* `structuredData`object | null
The article’s schema.org JSON-LD, or `null` when structured data is switched off in the site’s article settings. See [Structured data](/feed/structured-data).
The title and cover are not in the body
`html` and `markdown` start at the first line of the article. Draw `title` and `cover` yourself, where your design wants them.
## TypeScript
[Section titled “TypeScript”](#typescript)
The types come with [the packages](/sdks), so there is nothing to copy:
```ts
import type { FeedArticle, FeedManifest } from '@citedseo/feed';
```
This is the file they are defined in, as it is in the package.
@citedseo/feed
```ts
/** What every read takes. */
export type FeedOptions = {
/** Your site ID. It is the only thing the feed needs. */
siteId: string
/** Another origin to read from, for tests. Defaults to https://feeds.citedseo.ai. */
origin?: string
/** Your own fetch: a framework's caching one, or a test's. Defaults to the global fetch. */
fetch?: typeof fetch
}
/** An article's schema.org JSON-LD: a BlogPosting, an FAQPage when it has an FAQ, and a BreadcrumbList. */
export type StructuredData = {
"@context": string
"@graph": Record[]
}
/** One live article, as a feed page holds it, a by-slug file holds it, and a webhook sends it. */
export type FeedArticle = {
/** The article's ID. It never changes, so use it as your key. */
id: string
/** The last part of its address, to route by. */
slug: string
/** The article's full address on your site. Use it as the canonical address. */
url: string
/** The title, as plain text. */
title: string
/** The search snippet, for the page's meta description. */
description: string
/** The cover image, or null when the article has none. */
cover: { src: string; alt: string } | null
/** The byline, or null when the article is by the site itself. */
author: { name: string; url: string | null } | null
/** When the article first went live, as an ISO 8601 time in UTC. */
publishedAt: string
/** When the live version last changed, as an ISO 8601 time in UTC. */
modifiedAt: string
/** The body as HTML, without the title or cover. Safe to insert: no scripts, no raw HTML. */
html: string
/** The same body as Markdown (CommonMark with GitHub's extras). */
markdown: string
/** The article's JSON-LD, or null when the site has structured data switched off. */
structuredData: StructuredData | null
}
/** `feed/index.json`: the one file that changes in place. It names the current build. */
export type FeedManifest = {
/** The current build. It is part of the address of every other file. */
buildId: string
/** How many articles are live. */
total: number
/** How many pages the build has. 0 when nothing is live. */
pageCount: number
/** How many articles a full page holds. */
pageSize: number
/** When the newest article in the build last changed, or null when nothing is live. */
latestModifiedAt: string | null
/** When this build was written. */
generatedAt: string
/** True once the site is gone from CitedSEO: its feed stays empty for good. */
removed?: true
}
/** `b/{buildId}/page-{n}.json`: one page of articles, newest first. */
export type FeedPage = { articles: FeedArticle[] }
/** `b/{buildId}/by-slug/{slug}.json`: one article. */
export type FeedArticleFile = { article: FeedArticle }
/** The events a webhook sends. */
export const webhookEvents = ["article.published", "article.updated"] as const
export type WebhookEvent = (typeof webhookEvents)[number]
/** The JSON body of a webhook. */
export type WebhookPost = {
event: WebhookEvent
/** The same on every try of the same post, so you can tell one you already took. */
delivery: string
/** The article as it is live now. */
data: FeedArticle
}
```
## A full example
[Section titled “A full example”](#a-full-example)
One article
```json
{
"id": "0b6f6c1e-3f0a-4a59-9d0e-2f8f4c1f7a31",
"slug": "how-to-brew-green-tea",
"url": "https://example.com/blog/how-to-brew-green-tea",
"title": "How to brew green tea",
"description": "Brew green tea at 80°C for two minutes. Here is why the temperature matters and how to get it right without a thermometer.",
"cover": {
"src": "https://example.com/images/green-tea.webp",
"alt": "A glass teapot of green tea"
},
"author": {
"name": "Sam Lee",
"url": "https://example.com/authors/sam-lee"
},
"publishedAt": "2026-10-09T02:05:00.000Z",
"modifiedAt": "2026-10-11T02:05:00.000Z",
"html": "
Brew green tea at 80°C for two minutes. Hotter water makes it bitter.
\n
Why temperature matters
\n
Boiling water pulls out more tannins, which taste bitter. See our tea guide.
\n",
"markdown": "**Brew green tea at 80°C for two minutes. Hotter water makes it bitter.**\n\n## Why temperature matters\n\nBoiling water pulls out more tannins, which taste **bitter**. See our [tea guide](/blog/tea-guide).\n\n> [!TIP]\n> No thermometer? Let boiled water stand for three minutes.\n\n1. Heat the water to 80°C.\n2. Steep for two minutes.\n3. Pour and serve.\n\n| Tea | Temperature |\n| - | - |\n| Green | 80°C |\n| Black | 95°C |\n\n## Frequently asked questions\n\n### Can I use boiling water?\n\nYou can, but the tea will taste bitter.\n\n## Sources\n\n1. [Brewing temperatures](https://example.org/brewing), Example Tea Board",
"structuredData": {
"@context": "https://schema.org",
"@graph": [
{
"@type": "BlogPosting",
"@id": "https://example.com/blog/how-to-brew-green-tea#article",
"headline": "How to brew green tea",
"description": "Brew green tea at 80°C for two minutes. Here is why the temperature matters and how to get it right without a thermometer.",
"url": "https://example.com/blog/how-to-brew-green-tea",
"mainEntityOfPage": "https://example.com/blog/how-to-brew-green-tea",
"inLanguage": "en",
"datePublished": "2026-10-09T02:05:00.000Z",
"dateModified": "2026-10-11T02:05:00.000Z",
"wordCount": 69,
"author": {
"@type": "Person",
"name": "Sam Lee",
"url": "https://example.com/authors/sam-lee"
},
"publisher": {
"@type": "Organization",
"name": "Example Tea",
"url": "https://example.com"
},
"image": "https://example.com/images/green-tea.webp",
"citation": [
"https://example.org/brewing"
]
},
{
"@type": "FAQPage",
"@id": "https://example.com/blog/how-to-brew-green-tea#faq",
"mainEntity": [
{
"@type": "Question",
"name": "Can I use boiling water?",
"acceptedAnswer": {
"@type": "Answer",
"text": "You can, but the tea will taste bitter."
}
}
]
},
{
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Example Tea",
"item": "https://example.com"
},
{
"@type": "ListItem",
"position": 2,
"name": "Blog",
"item": "https://example.com/blog"
},
{
"@type": "ListItem",
"position": 3,
"name": "How to brew green tea",
"item": "https://example.com/blog/how-to-brew-green-tea"
}
]
}
]
}
}
```
# Caching and limits
> How the CitedSEO feed is cached, why a build never changes, and how to cache it on your side.
The feed is built to be cached hard. Only one small file ever changes.
## What is cached, and for how long
[Section titled “What is cached, and for how long”](#what-is-cached-and-for-how-long)
| File | `cache-control` | Why |
| ------------------------------- | ------------------------------------- | ------------------------------------------------------------------------ |
| The manifest, `feed/index.json` | `public, max-age=60` | It points at the current build, so it is kept fresh. |
| Everything under `b/{buildId}/` | `public, max-age=31536000, immutable` | A build is written once and never changes, so it can be cached for good. |
A new article shows in the feed as soon as the manifest you hold is replaced: within a minute, or at once if you re-read it when a [webhook](/webhooks) arrives.
## Why builds never change
[Section titled “Why builds never change”](#why-builds-never-change)
Each publish writes a whole new build beside the old one, then points the manifest at it. So:
* **You never see half a rebuild.** A reader part-way through an old build’s pages still gets a complete, consistent list.
* **Stale reads are safe.** A cached page from an older build is still a true record of that moment.
* **Old builds go away later.** They are kept for a while after a new one lands, then removed. Start from the manifest each time and you will never ask for one that is gone.
## The numbers
[Section titled “The numbers”](#the-numbers)
| | |
| --------------- | ------------------------------------------------------------------- |
| Articles a page | 20 (the manifest’s `pageSize`), newest first |
| Paging | Pages `1` to `pageCount`, from the manifest |
| Cross-origin | Any origin may read every file |
| Key | None |
| Rate limits | None to plan around. They are static files on Cloudflare’s network. |
## Caching it yourself
[Section titled “Caching it yourself”](#caching-it-yourself)
* **A static site** reads the feed at build time. Rebuild when a webhook arrives.
* **A server-rendered site** can read the feed on each request and let `fetch` and the network do the caching, or hold the manifest for a minute and the build’s files for as long as it likes.
* **In the browser**, the same caching applies. Rendering articles in the browser alone means search engines and AI assistants may not see them, so prefer the server.
When the feed can't be reached
Treat a failed fetch as “keep what you have”, not “there are no articles”. Serve your last good copy and try again, so a network blip never empties your blog.
## When a file isn’t there
[Section titled “When a file isn’t there”](#when-a-file-isnt-there)
| You asked for | `404` means |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| The manifest | The site ID is wrong, or the site has no feed. A site with nothing live still has a manifest, with `total` 0. |
| A by-slug file | No live article has that slug. |
| A page or by-slug file from a build you kept | That build is gone. Read the manifest again. |
# The body as HTML
> The elements and class names in an article's HTML body from the CitedSEO feed, and how to style them.
`html` is the article’s body as plain, semantic HTML. It has no inline styles, no scripts and no wrapper element, so it takes on your site’s own typography once you put it inside your article container.
```html
{article.html}
```
## It is safe to insert
[Section titled “It is safe to insert”](#it-is-safe-to-insert)
Text in the body is escaped and raw HTML is never passed through, so the body can’t carry a script. Links are kept only to an `http` or `https` address, a path on your site, or a place in the page.
## What it is made of
[Section titled “What it is made of”](#what-it-is-made-of)
Most of the body is ordinary elements: `p`, `h2` to `h4`, `ul`, `ol`, `table`, `blockquote`, `pre` and `code`, `hr`, `a`, `strong` and `em`. Every `h2` has an `id` made from its words, so you can link to a section or build your own table of contents.
A few parts have a class name, so you can style them:
| Part | Markup | What it is |
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Answer | `p.citedseo-answer` | The short answer at the top of the article, in bold. |
| Key takeaways | `div.citedseo-takeaways` | A “Key takeaways” line, then a list of three to five points. An article has this or the answer. |
| Contents | `nav.citedseo-contents` | A “Contents” line, then a numbered list of links to each `h2`. Only when the site’s article settings have a contents list on, and the article has two or more sections. |
| Callout | `aside.citedseo-callout` | A tip, note or warning set apart from the text. It also has one of `citedseo-note`, `citedseo-tip`, `citedseo-important`, `citedseo-warning` or `citedseo-caution`, and starts with its label in bold. |
| Image | `figure` | An `img`, with a `figcaption` when it has a caption. |
| Video | `figure.citedseo-video` | An `iframe` for a YouTube or Vimeo video. Any other video is a plain link. |
| Quote | `blockquote` | The words quoted, then a line with who said them in a `cite`, when that is known. |
| FAQ | `h2#faq` | “Frequently asked questions”, then an `h3` and a `p` for each question. |
| Sources | `ol.citedseo-sources` | After an `h2#sources`, the pages the article’s facts came from, each a link and its publisher. |
## A starting stylesheet
[Section titled “A starting stylesheet”](#a-starting-stylesheet)
These are the only rules the class names need. Everything else follows your own article styles.
article.css
```css
.citedseo-answer {
font-size: 1.125rem;
}
.citedseo-takeaways,
.citedseo-contents,
.citedseo-callout {
margin-block: 1.5rem;
padding: 1rem 1.25rem;
border: 1px solid #e5e5e5;
border-radius: 6px;
}
.citedseo-callout.citedseo-warning,
.citedseo-callout.citedseo-caution {
border-color: #f59e0b;
}
.citedseo-video iframe {
width: 100%;
aspect-ratio: 16 / 9;
border: 0;
}
.citedseo-sources {
font-size: 0.875rem;
}
```
Want your own components instead?
If you’d rather draw a callout or a table with a component of yours, use [the Markdown body](/feed/markdown) and a Markdown renderer that lets you swap elements.
# The body as Markdown
> The Markdown body of an article from the CitedSEO feed, standard CommonMark with GitHub's extras, for sites that render with their own components.
`markdown` is the same body as `html`, written as standard Markdown: CommonMark with GitHub’s extras (tables, strikethrough and alerts). Any Markdown tool that reads GitHub’s flavour reads it back as the same article.
Use it when you want to draw the article with your own components, for example with MDX, `react-markdown`, `marked` or Astro’s renderer.
## An example
[Section titled “An example”](#an-example)
article.markdown
```md
**Brew green tea at 80°C for two minutes. Hotter water makes it bitter.**
## Why temperature matters
Boiling water pulls out more tannins, which taste **bitter**. See our [tea guide](/blog/tea-guide).
> [!TIP]
> No thermometer? Let boiled water stand for three minutes.
1. Heat the water to 80°C.
2. Steep for two minutes.
3. Pour and serve.
| Tea | Temperature |
| - | - |
| Green | 80°C |
| Black | 95°C |
## Frequently asked questions
### Can I use boiling water?
You can, but the tea will taste bitter.
## Sources
1. [Brewing temperatures](https://example.org/brewing), Example Tea Board
```
## How each part is written
[Section titled “How each part is written”](#how-each-part-is-written)
| Part | Markdown |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| Answer | One bold paragraph at the top. |
| Key takeaways | A bold “Key takeaways” line, then a list. |
| Sections | `##` to `####` headings. |
| Lists | `-` for bullets, `1.` for steps, sub-items indented one level. |
| Tables | GitHub’s pipe tables. |
| Callouts | GitHub’s alerts: a quote that starts `> [!TIP]`, `[!NOTE]`, `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]`. |
| Quotes | A `>` quote, then a line starting with a dash for who said it. |
| Images | ``, the caption as the image’s title. |
| Videos | A link to the video, with its title as the words. |
| Code | A fenced block with its language. The fence is longer than any fence inside it. |
| FAQ | A “Frequently asked questions” `##`, then a `###` for each question. |
| Sources | A “Sources” `##`, then a numbered list of links with their publishers. |
## What is different from the HTML
[Section titled “What is different from the HTML”](#what-is-different-from-the-html)
* **No contents list.** The HTML body can carry one; the Markdown never does, since most renderers make their own.
* **No class names.** Callouts are GitHub’s alerts, so a renderer needs alert support (or a small plugin) to draw them as boxes. Without it they show as ordinary quotes.
* **Videos are links.** There is no player in Markdown.
The title and cover are left out of both, as in the HTML.
# Structured data
> The schema.org JSON-LD that comes with each article in the CitedSEO feed, and how to put it on your page.
Each article comes with its schema.org structured data as JSON-LD, ready to put on the page. It is worked out from the version that is live, so it always says what the page shows.
## What it holds
[Section titled “What it holds”](#what-it-holds)
`structuredData` is one object with an `@graph` of up to three things:
| Type | When | What it says |
| ---------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BlogPosting` | Always | The headline, description, address, language, both dates, the word count, the author (a `Person`, or the site as an `Organization`), the publisher, the cover image and the pages the article cites. |
| `FAQPage` | When the article has an FAQ | Each question and its answer, as plain text. |
| `BreadcrumbList` | Always | The trail from your home page, through your blog, to the article. |
article.structuredData
```json
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "BlogPosting",
"@id": "https://example.com/blog/how-to-brew-green-tea#article",
"headline": "How to brew green tea",
"description": "Brew green tea at 80°C for two minutes. Here is why the temperature matters and how to get it right without a thermometer.",
"url": "https://example.com/blog/how-to-brew-green-tea",
"mainEntityOfPage": "https://example.com/blog/how-to-brew-green-tea",
"inLanguage": "en",
"datePublished": "2026-10-09T02:05:00.000Z",
"dateModified": "2026-10-11T02:05:00.000Z",
"wordCount": 69,
"author": {
"@type": "Person",
"name": "Sam Lee",
"url": "https://example.com/authors/sam-lee"
},
"publisher": {
"@type": "Organization",
"name": "Example Tea",
"url": "https://example.com"
},
"image": "https://example.com/images/green-tea.webp",
"citation": [
"https://example.org/brewing"
]
},
{
"@type": "FAQPage",
"@id": "https://example.com/blog/how-to-brew-green-tea#faq",
"mainEntity": [
{
"@type": "Question",
"name": "Can I use boiling water?",
"acceptedAnswer": {
"@type": "Answer",
"text": "You can, but the tea will taste bitter."
}
}
]
},
{
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Example Tea",
"item": "https://example.com"
},
{
"@type": "ListItem",
"position": 2,
"name": "Blog",
"item": "https://example.com/blog"
},
{
"@type": "ListItem",
"position": 3,
"name": "How to brew green tea",
"item": "https://example.com/blog/how-to-brew-green-tea"
}
]
}
]
}
```
## Put it on the page
[Section titled “Put it on the page”](#put-it-on-the-page)
Write it into a `script` tag of type `application/ld+json` in the page’s `head` or `body`. Escape `<` so nothing in an article can end the script early:
```js
const jsonLd = JSON.stringify(article.structuredData).replaceAll('<', '\\u003c');
```
```html
```
Each [framework guide](/sdks/nextjs) shows where this goes.
It can be null
`structuredData` is `null` when structured data is switched off in the site’s article settings. Check before you write the tag.
## Keep it true
[Section titled “Keep it true”](#keep-it-true)
The addresses in the data are the article’s `url` and your site’s own address. If you show the article at a different address than `url`, the data no longer matches the page. Keep your route and the article’s `url` the same; the [SEO guide](/guides/seo) covers how.
# Update the moment you publish
> Use a CitedSEO webhook to rebuild a static site or clear a cache as soon as an article goes live, with the feed as the fallback.
Without a webhook, your site shows a new article the next time it reads the feed. With one, it can show it within seconds. The pattern is the same everywhere: **verify, then refresh**.
1. **Make an endpoint** that [verifies the signature](/webhooks/verify). `webhookHandler` does it for you.
2. **Refresh** in the way your site needs: start a build, clear a cache, or revalidate a path.
3. **[Add the endpoint](/webhooks)** in the app and keep its secret in `CITEDSEO_WEBHOOK_SECRET`.
## Pick your refresh
[Section titled “Pick your refresh”](#pick-your-refresh)
`webhookHandler` is in [`@citedseo/feed`](/sdks) and every framework package. It checks the signature, so `onPost` only ever runs for a post from us, and it answers `500` when `onPost` throws, so a refresh that failed is tried again.
* Static site
Start a build through your host’s deploy hook. Keep the hook’s address in an environment variable; it is a secret too.
```ts
import { webhookHandler } from '@citedseo/feed';
export const POST = webhookHandler({
secret: process.env.CITEDSEO_WEBHOOK_SECRET!,
onPost: async () => {
const res = await fetch(process.env.DEPLOY_HOOK_URL!, { method: 'POST' });
// Throwing answers 500, so CitedSEO tries the post again.
if (!res.ok) throw new Error(`The deploy hook answered ${res.status}`);
},
});
```
* Next.js
Revalidate the blog. Next.js builds the pages again on the next visit.
app/api/citedseo/route.ts
```ts
import { revalidatePath } from 'next/cache';
import { webhookHandler } from '@citedseo/next';
export const POST = webhookHandler({
secret: process.env.CITEDSEO_WEBHOOK_SECRET!,
onPost: () => revalidatePath('/blog', 'layout'),
});
```
* Your own cache
Clear what you hold, or better, put the article from the post straight into it. The post carries the whole article, so there is nothing more to fetch.
```ts
import { webhookHandler } from '@citedseo/feed';
import { articles } from './store';
export const POST = webhookHandler({
secret: process.env.CITEDSEO_WEBHOOK_SECRET!,
onPost: async ({ data }) => {
// Posts can arrive out of order, so keep whichever version changed last.
const held = await articles.get(data.id);
if (held && held.modifiedAt > data.modifiedAt) return;
await articles.put(data.id, data);
},
});
```
## Keep the feed as the fallback
[Section titled “Keep the feed as the fallback”](#keep-the-feed-as-the-fallback)
A webhook can be missed: your endpoint was down, or a deploy was mid-flight. Don’t let that leave your site stale for good.
* **Still refresh on a timer.** Read the manifest again every few minutes to an hour, so a missed post heals itself. It is one small file.
* **Catch take-downs from the feed.** Nothing is posted when an article is taken down, so a store built only from webhooks keeps it. Compare against the feed now and then and drop what is gone.
One article a day
A site ships one approved change a day unless someone publishes by hand, so a rebuild per webhook is not a lot of builds.
# How publishing works
> What happens when a CitedSEO article is published, when it appears in the feed, and how connected platforms and webhooks fit in.
It helps to know what “published” means before you build on it.
## Publishing is a change of status
[Section titled “Publishing is a change of status”](#publishing-is-a-change-of-status)
An article in CitedSEO is written, checked and then approved, by you or by autopilot. Publishing is the moment an approved version is recorded as **live**. That is all it is: a status, with the version that is live and its address.
Everything a developer sees follows from that one change.
1. **The version is recorded live.** The article now has a live version and an address on your site.
2. **The feed is rebuilt.** A new build of [the feed](/feed) is written with every live article at its live version, and the manifest is pointed at it.
3. **Connected platforms get it.** If the site is connected to a platform such as WordPress, the article is also sent there. This sits on top of the status change. It doesn’t replace the feed.
4. **Your webhooks are told,** after the rebuild. Each endpoint gets `article.published` when the article goes live, and `article.updated` for each change after.
## The feed is always there
[Section titled “The feed is always there”](#the-feed-is-always-there)
Every site has a feed, whatever else it publishes to. It is static files, so reading it never touches CitedSEO’s app or database. A site on WordPress has the same live articles in its feed as on WordPress, so you can use the feed for a second surface (an app, a docs site, a search index) without changing how the site publishes.
## When things publish
[Section titled “When things publish”](#when-things-publish)
A site ships one approved change a day, at its publish time, unless someone presses **Publish now** or picks a time. So expect events to arrive one at a time, not in bursts.
The feed is also rebuilt when the site’s article settings or an author change, since those change what an article’s byline and structured data say. No webhook is sent for that.
## Updates and versions
[Section titled “Updates and versions”](#updates-and-versions)
A live article keeps being improved: refreshed sections, new internal links, a better title. Each is a new version that waits for approval like the first.
* The feed keeps serving the **live** version until the new one ships. A draft never leaks into the feed.
* When the new version ships, `modifiedAt` changes and your webhooks get `article.updated`.
* The article’s `id`, `slug` and `url` stay the same through every update.
## Take-downs and undo
[Section titled “Take-downs and undo”](#take-downs-and-undo)
| In the app | In the feed | Webhook |
| --------------------------------------- | -------------------------------------------------------- | ------------------- |
| A shipped change is undone | A new build, with the article back to how it read before | `article.updated` |
| A new article is taken down | A new build without the article | None |
| A taken-down article is published again | A new build with the article back | `article.published` |
Handle an article leaving
Because nothing is posted for a take-down, a site that stores articles should treat the feed as the record: an article that is no longer in the feed is no longer live.
# SEO for your article pages
> What to put on a page that shows a CitedSEO article so search engines and AI assistants read it properly, from the canonical address to structured data.
The feed gives you everything a well-formed article page needs. This is where each field goes.
## The checklist
[Section titled “The checklist”](#the-checklist)
| On the page | From the article |
| ------------------------------ | ----------------------------------------------------- |
| `` | `title` |
| `<meta name="description">` | `description` |
| `<link rel="canonical">` | `url` |
| `<h1>` | `title`, once |
| Cover image, with its alt text | `cover.src`, `cover.alt` |
| Byline | `author.name`, linked to `author.url` when it has one |
| Published and updated dates | `publishedAt`, `modifiedAt` |
| JSON-LD | `structuredData`, when it isn’t `null` |
| Open Graph tags | `title`, `description`, `url`, `cover.src` |
## Show the article at its `url`
[Section titled “Show the article at its url”](#show-the-article-at-its-url)
Every article has the address CitedSEO expects it to live at: your site, then your blog path, then its slug. The canonical address and the structured data both use it.
So route by `slug` under the same path. If the feed says `https://example.com/blog/how-to-brew-green-tea`, serve the article at `/blog/how-to-brew-green-tea`.
If your articles live somewhere else, say `/guides`, change the site’s **blog path** in the app’s settings so new articles get addresses under it. Don’t rewrite `url` on your side: the structured data would still point at the old address.
An article's address doesn't change
An article keeps the address it first went live at, through every update. Changing the blog path affects new articles only, so add redirects yourself if you move existing ones.
## Render on the server
[Section titled “Render on the server”](#render-on-the-server)
Draw articles on the server or at build time, not in the browser alone. A page that only fills in after JavaScript runs may be read as empty by search engines and by the AI assistants that cite pages. Every [framework guide](/sdks/nextjs) renders on the server.
## Keep the body whole
[Section titled “Keep the body whole”](#keep-the-body-whole)
The body is written to be quoted: an answer at the top, clear sections, an FAQ and a list of sources. Show all of it.
* Keep the **answer** or **key takeaways** at the top, where they are.
* Keep the **sources** list. It is what the article’s facts rest on.
* Don’t drop the **FAQ** if you keep the structured data: the `FAQPage` data describes questions that must be visible on the page.
## One `h1`
[Section titled “One h1”](#one-h1)
The body starts at the first line of the article and uses `h2` and below, so your page’s `h1` is the `title` and there is exactly one.
# Introduction
> What a site's own code can do with CitedSEO, a read feed of your live articles and signed webhooks when one goes live or changes.
CitedSEO writes and updates your site’s articles. These docs are for the developer who wants those articles on a site they build themselves: a Next.js app, an Astro site, anything that can make an HTTP request.
There are two things to use, and neither needs an API key.
## The feed
[Section titled “The feed”](#the-feed)
Every article that is live on your site, as static JSON on `feeds.citedseo.ai`:
```txt
feeds.citedseo.ai/{siteId}/feed/index.json the manifest
feeds.citedseo.ai/{siteId}/b/{buildId}/page-1.json 20 articles a page
feeds.citedseo.ai/{siteId}/b/{buildId}/by-slug/{slug}.json one article
```
They are plain files on Cloudflare’s network, rebuilt each time something publishes, so your site can read them as often as it likes. Each article comes whole: its title, search snippet, cover, byline, dates, the body as both HTML and Markdown, and its schema.org structured data. You fetch it and draw it with your own components.
## Webhooks
[Section titled “Webhooks”](#webhooks)
When an article goes live or changes, CitedSEO can post it to an endpoint of yours, signed so your code can tell the post came from us. Use it to rebuild a static site or clear a cache the moment something publishes, instead of waiting for the next fetch.
## Packages
[Section titled “Packages”](#packages)
For JavaScript and TypeScript there is a package for each: [`@citedseo/feed`](/sdks) reads the feed and checks webhooks anywhere, and `@citedseo/next`, `@citedseo/astro`, `@citedseo/react-router`, `@citedseo/nuxt` and `@citedseo/svelte` fit it to a framework. They are typed end to end. In any other language, the feed is plain JSON over HTTP.
## What is not here
[Section titled “What is not here”](#what-is-not-here)
* **No write API.** Articles are approved, changed and published in the CitedSEO app. The feed is read-only, and there is no API of ours for your site to call.
* **No API keys.** Your site ID is the only thing the feed needs, and the feed holds only what is already public on your site.
## Where to go next
[Section titled “Where to go next”](#where-to-go-next)
[Quickstart](/quickstart)Fetch your articles and show one, in about five minutes.
[The article](/feed/article)Every field the feed and the webhooks give you.
[Verify the signature](/webhooks/verify)Check that a webhook came from CitedSEO.
[Set up with AI](/set-up-with-ai)Hand these docs to your coding agent.
# Quickstart
> Read your live articles from the CitedSEO feed and show one on your own site, with no key, over plain HTTP or with the JavaScript package.
You need your [site ID](/site-id) and anything that can make an HTTP request.
In JavaScript or TypeScript?
[`@citedseo/feed`](/sdks) does these four steps in one call, typed: `await fetchArticles({ siteId })`. The steps below are what it does, and what to write in any other language.
1. **Read the manifest.** It names the current build. There is no key and no header to set.
* curl
```sh
curl https://feeds.citedseo.ai/YOUR_SITE_ID/feed/index.json
```
* JavaScript
```js
const feed = 'https://feeds.citedseo.ai/YOUR_SITE_ID';
const manifest = await fetch(`${feed}/feed/index.json`).then((res) => res.json());
```
* Python
```python
import requests
feed = "https://feeds.citedseo.ai/YOUR_SITE_ID"
manifest = requests.get(f"{feed}/feed/index.json", timeout=10).json()
```
200 OK
```json
{
"buildId": "01JA2M7Q4K8ZP3",
"total": 42,
"pageCount": 3,
"pageSize": 20,
"latestModifiedAt": "2026-10-11T02:05:00.000Z",
"generatedAt": "2026-10-11T02:05:04.000Z"
}
```
2. **Read the pages of articles** from that build. They are numbered from 1 to the manifest’s `pageCount`, which is 0 when nothing is live, and hold 20 articles each, newest first.
* curl
```sh
curl https://feeds.citedseo.ai/YOUR_SITE_ID/b/BUILD_ID/page-1.json
```
* JavaScript
```js
const articles = [];
for (let n = 1; n <= manifest.pageCount; n++) {
const page = await fetch(`${feed}/b/${manifest.buildId}/page-${n}.json`).then((res) => res.json());
articles.push(...page.articles);
}
```
* Python
```python
articles = []
for n in range(1, manifest["pageCount"] + 1):
page = requests.get(f"{feed}/b/{manifest['buildId']}/page-{n}.json", timeout=10).json()
articles.extend(page["articles"])
```
200 OK
```json
{
"articles": [
{
"id": "0b6f6c1e-3f0a-4a59-9d0e-2f8f4c1f7a31",
"slug": "how-to-brew-green-tea",
"url": "https://example.com/blog/how-to-brew-green-tea",
"title": "How to brew green tea",
"description": "Brew green tea at 80°C for two minutes. Here is why the temp…",
"cover": {
"src": "https://example.com/images/green-tea.webp",
"alt": "A glass teapot of green tea"
},
"author": {
"name": "Sam Lee",
"url": "https://example.com/authors/sam-lee"
},
"publishedAt": "2026-10-09T02:05:00.000Z",
"modifiedAt": "2026-10-11T02:05:00.000Z",
"html": "<p class=\"citedseo-answer\"><strong>Brew green tea at 80°C for two minutes. Hot…",
"markdown": "**Brew green tea at 80°C for two minutes. Hotter water makes…",
"structuredData": {
"@context": "https://schema.org",
"@graph": [
"…"
]
}
}
]
}
```
3. **List your articles.** Each has a `slug`, the last part of its address, to route by.
```js
for (const article of articles) {
console.log(`/blog/${article.slug}`, article.title);
}
```
4. **Show one.** Read it by its slug, used as it is: an article’s `slug` is already URL-encoded. The body comes as HTML and as Markdown, without the title or cover, so you place those yourself.
```js
const article = articles[0];
if (!article) throw new Error('Nothing is live yet');
const res = await fetch(`${feed}/b/${manifest.buildId}/by-slug/${article.slug}.json`);
if (res.status === 404) throw new Error('No such article');
if (!res.ok) throw new Error(`The feed answered ${res.status}`);
const { article: whole } = await res.json();
document.querySelector('h1').textContent = whole.title;
document.querySelector('article').innerHTML = whole.html;
```
Always start from the manifest
The build’s name changes with every publish, so never keep one in your code. Read the manifest, then read from the build it names.
## Next
[Section titled “Next”](#next)
[Your framework](/sdks/nextjs)A blog index and article page in Next.js, Astro, React Router, Nuxt or SvelteKit.
[The article](/feed/article)Every field, with a full example.
[Update the moment you publish](/guides/instant-updates)Use a webhook instead of waiting for the next read.
# JavaScript and TypeScript
> The @citedseo/feed package reads your live CitedSEO articles and checks webhooks in any JavaScript runtime, with the feed's types built in.
`@citedseo/feed` is the feed and the webhook check as a package: a few functions over `fetch`, with no dependencies and no key. It runs in Node.js 20+, Cloudflare Workers, Deno, Bun and the browser, and it is what each framework package is built on.
* npm
```sh
npm install @citedseo/feed
```
* pnpm
```sh
pnpm add @citedseo/feed
```
* yarn
```sh
yarn add @citedseo/feed
```
* bun
```sh
bun add @citedseo/feed
```
## Read your articles
[Section titled “Read your articles”](#read-your-articles)
```ts
import { fetchArticle, fetchArticles } from '@citedseo/feed';
const articles = await fetchArticles({ siteId: 'YOUR_SITE_ID' });
const article = await fetchArticle({ siteId: 'YOUR_SITE_ID', slug: 'how-to-brew-green-tea' });
```
| Function | Gives | What it reads |
| ------------------------ | ----------------------------- | ----------------------------------------------------------------------------------------- |
| `fetchArticles(options)` | `FeedArticle[]`, newest first | The manifest, then every page of the build it names. |
| `fetchArticle(options)` | `FeedArticle \| null` | The manifest, then one small file. `null` when no article has that slug. |
| `fetchManifest(options)` | `FeedManifest` | The manifest alone, to see whether anything changed. |
| `jsonLd(article)` | `string \| null` | Nothing. It gives the article’s structured data as text that is safe inside a script tag. |
### Options
[Section titled “Options”](#options)
```ts
/** What every read takes. */
export type FeedOptions = {
/** Your site ID. It is the only thing the feed needs. */
siteId: string
/** Another origin to read from, for tests. Defaults to https://feeds.citedseo.ai. */
origin?: string
/** Your own fetch: a framework's caching one, or a test's. Defaults to the global fetch. */
fetch?: typeof fetch
}
```
Pass `fetch` to read through a cache of your own, such as SvelteKit’s `fetch` in a `load` function.
## Types
[Section titled “Types”](#types)
Every function is typed, and the types are exported. They are the ones CitedSEO’s own engine builds the feed against, so they can’t fall behind it.
```ts
import type { FeedArticle, FeedManifest, WebhookEvent, WebhookPost } from '@citedseo/feed';
```
[The article](/feed/article) prints them in full.
## Check a webhook
[Section titled “Check a webhook”](#check-a-webhook)
```ts
import { webhookHandler } from '@citedseo/feed';
export const POST = webhookHandler({
secret: process.env.CITEDSEO_WEBHOOK_SECRET!,
onPost: async (post) => {
// post.event is "article.published" or "article.updated"; post.data is the article.
},
});
```
| Function | What it does |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `webhookHandler({ secret, onPost })` | A whole route: answers `400` to a post that isn’t ours, runs `onPost` for one that is, answers `204`, or `500` when `onPost` throws so the post is tried again. |
| `readWebhook(request, secret)` | The verified post as a `WebhookPost`, or `null`. |
| `verifyWebhook(secret, body, header)` | Whether a signature header is ours for a raw body. |
See [Verify the signature](/webhooks/verify) for what the check does.
## Errors
[Section titled “Errors”](#errors)
A read that fails throws a `CitedSEOError` with a `code` to branch on:
| `code` | When |
| ------------------ | ------------------------------------------------------- |
| `CONFIG` | The site ID or slug is missing. |
| `NOT_FOUND` | There is no feed for that site ID. |
| `NETWORK_ERROR` | The feed couldn’t be reached. |
| `SERVER_ERROR` | The feed answered with an error; `status` has the code. |
| `INVALID_RESPONSE` | A file wasn’t the shape it should be. |
An article that isn’t there is not an error: `fetchArticle` gives `null`.
## Your framework
[Section titled “Your framework”](#your-framework)
Each of these re-exports everything above, so one import covers a site.
[Next.js](/sdks/nextjs)@citedseo/next: a cached reader and article metadata.
[Astro](/sdks/astro)@citedseo/astro: a content loader.
[React Router](/sdks/react-router)@citedseo/react-router: readers for loaders, and meta.
[Nuxt](/sdks/nuxt)@citedseo/nuxt: readers for server routes, and head tags.
[SvelteKit](/sdks/sveltekit)@citedseo/svelte: readers for load functions, and head tags.
# Astro
> Show your CitedSEO articles in an Astro site with @citedseo/astro, a content loader that fills a collection from the feed, plus a blog index, article pages and JSON-LD.
`@citedseo/astro` is a content loader. Your articles become a collection, typed and queried like any other in your site, and each one renders with `render()`. It needs Astro 6 or later.
Hand this to your coding agent
Copy
```
Read https://developer.citedseo.ai/llms-full.txt.
My CitedSEO site ID is <YOUR_SITE_ID>.
Install @citedseo/astro. Add a content collection that loads my articles, plus a /blog index and /blog/[slug] pages with the article's JSON-LD in this Astro app, reading my articles with that package.
The feed needs no key. Use only the functions and addresses that file lists.
```
## Install
[Section titled “Install”](#install)
* npm
```sh
npm install @citedseo/astro
```
* pnpm
```sh
pnpm add @citedseo/astro
```
* yarn
```sh
yarn add @citedseo/astro
```
* bun
```sh
bun add @citedseo/astro
```
## What you’ll add
[Section titled “What you’ll add”](#what-youll-add)
* .env
* src
* content.config.ts the collection
* pages
* blog
* index.astro the index
* \[slug].astro one article
1. **Set your site ID.**
.env
```sh
CITEDSEO_SITE_ID=YOUR_SITE_ID
```
2. **Load the feed as a collection.** The loader brings its own schema, so there is none to write.
src/content.config.ts
```ts
import { defineCollection } from 'astro:content';
import { citedseoLoader } from '@citedseo/astro';
const articles = defineCollection({
loader: citedseoLoader({ siteId: import.meta.env.CITEDSEO_SITE_ID }),
});
export const collections = { articles };
```
3. **Add the index.**
src/pages/blog/index.astro
```astro
---
import { getCollection } from 'astro:content';
const articles = (await getCollection('articles')).sort(
(a, b) => b.data.publishedAt.valueOf() - a.data.publishedAt.valueOf(),
);
---
<ul>
{
articles.map((article) => (
<li>
<a href={`/blog/${article.id}`}>{article.data.title}</a>
<p>{article.data.description}</p>
</li>
))
}
</ul>
```
4. **Add the article page.** Each entry’s `id` is the article’s slug, and `render()` gives its body.
src/pages/blog/\[slug].astro
```astro
---
import { getCollection, render } from 'astro:content';
import { jsonLd } from '@citedseo/astro';
export async function getStaticPaths() {
const articles = await getCollection('articles');
// An article's slug is URL-encoded; Astro encodes a param itself, so hand it over decoded.
return articles.map((article) => ({
params: { slug: decodeURIComponent(article.id) },
props: { article },
}));
}
const { article } = Astro.props;
const { Content } = await render(article);
const data = jsonLd(article.data);
---
<html lang="en">
<head>
<title>{article.data.title}
{data && }