
# Publish content to your site

Your site reads published articles from the content API with a content key (`vck_…`) from **Settings → Publishing → Content API**, which also has a copy-ready Next.js example. The `@volae/content` package described below isn't published; call the API directly:

```bash
# published articles, newest first (?type=faq|article|compare, ?limit=1-100, ?cursor=…)
curl https://api.volae.net/content/v1/items -H "Authorization: Bearer vck_…"

# one article with its body (html, markdown, faq, jsonLd); 404 when it isn't published
curl https://api.volae.net/content/v1/items/export-pdf -H "Authorization: Bearer vck_…"
```

The fields and the publish notification format (`X-Volae-Signature`) are described below.


---

# @volae/content

Read the help articles, FAQs and comparison pages you publish in Volae, and render them on your own site — with
helpers for **Next.js** (App Router) and **Astro**, and a plain client for anything else that has `fetch`
(Node 20+, Bun, Deno, Cloudflare Workers, edge runtimes).

This package isn't published to npm yet. Until it is, call the content API directly: `GET https://api.volae.net/content/v1/items` and `GET https://api.volae.net/content/v1/items/:slug` with `Authorization: Bearer vck_…` return the same JSON this client wraps. The rest of this README describes the package for when it ships.

## Get a content key

In Volae, open the content settings, choose **Publish to your site (headless)**, and create a content key
(`vck_…`). A key belongs to one product and can only read items published to the headless library.

The content is public anyway, so the key is safe in front-end code. Still, keep it in a server-side environment
variable (`VOLAE_CONTENT_KEY`) and fetch on the server — see [SEO](#seo).

## Next.js (App Router)

```sh
# .env
VOLAE_CONTENT_KEY=vck_...
VOLAE_REVALIDATE_SECRET=whsec_...   # see "Publish notifications" below
```

```tsx
// app/help/[slug]/page.tsx
import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { contentMetadata, generateContentParams, getContentItem, VolaeContent } from "@volae/content/next";

type Props = { params: Promise<{ slug: string }> };

export const generateStaticParams = () => generateContentParams();

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const item = await getContentItem((await params).slug);
  return item ? contentMetadata(item, { siteName: "Notely Help" }) : {};
}

export default async function Page({ params }: Props) {
  const item = await getContentItem((await params).slug);
  if (!item) notFound();
  return <VolaeContent item={item} className="prose" />;
}
```

```ts
// app/api/volae-revalidate/route.ts
import { createRevalidateHandler } from "@volae/content/next";

export const POST = createRevalidateHandler({ secret: process.env.VOLAE_REVALIDATE_SECRET! });
```

- `getContentItem(slug, { revalidate? })` — one item, or `null`. Cached with the tags `volae-content` and
  `volae-content:<slug>` until a publish notification arrives (or for `revalidate` seconds).
- `listContentItems({ type?, limit?, cursor?, revalidate? })` — one page, newest first: `{ items, nextCursor }`.
- `generateContentParams({ type? })` — `[{ slug }]` for every published item, for `generateStaticParams`.
- `contentMetadata(item, { siteName? })` — title, description, canonical URL and Open Graph image.
- `<VolaeContent item className? hideTitle? />` — a server component: the title and body in an `<article>`, plus the
  item's JSON-LD (`FAQPage` for FAQs, `Article` for the rest).
- `createRevalidateHandler({ secret })` — the `POST` handler for publish notifications. It checks the signature,
  revalidates the cache tags and answers `{ revalidated: true }`; a bad signature gets 401.

Set `VOLAE_API_URL` only if Volae tells you to use another API address.

## Astro

```sh
# .env
VOLAE_CONTENT_KEY=vck_...
```

```astro
---
// src/pages/help/[slug].astro
import { getContentItem, listAllContentItems } from "@volae/content/astro";
import VolaeContent from "@volae/content/astro/VolaeContent.astro";

export async function getStaticPaths() {
  const items = await listAllContentItems();
  return items.map((item) => ({ params: { slug: item.slug } }));
}

const item = await getContentItem(Astro.params.slug!);
if (!item) return Astro.redirect("/404");
---

<html lang={item.locale}>
  <head>
    <title>{item.title}</title>
    <meta name="description" content={item.description} />
    {item.canonicalUrl && <link rel="canonical" href={item.canonicalUrl} />}
  </head>
  <body>
    <VolaeContent item={item} />
  </body>
</html>
```

- `getContentItem(slug, { apiKey? })`, `listContentItems({ type?, limit?, cursor?, apiKey? })`,
  `listAllContentItems({ type?, apiKey? })` — the key defaults to `import.meta.env.VOLAE_CONTENT_KEY`.
- `jsonLdScript(item)` — the item's JSON-LD as a `<script type="application/ld+json">` tag, for `set:html`.
- `VolaeContent.astro` — the title and body in an `<article>`, plus the JSON-LD.

A static Astro site picks up new content when it's rebuilt: point Volae's publish notification at your host's build
hook, or use server output with `getContentItem` in the page.

## Any other runtime

```ts
import { createContentClient } from "@volae/content";

const volae = createContentClient({ apiKey: process.env.VOLAE_CONTENT_KEY! });

const { items, nextCursor } = await volae.list({ type: "faq", limit: 20 });
for await (const item of volae.listAll()) console.log(item.slug);
const item = await volae.get("export-pdf"); // null when there's no published item with that slug
```

The client sends `If-None-Match` and reuses the previous answer on `304`, waits once on `429` (per `Retry-After`),
and throws `ContentError` with `code` (`unauthorized`, `not_found`, `invalid_input`, `rate_limited`,
`network_error`, `server_error`, …), `status` and `requestId` for everything else.

### Items

Lists return summaries: `slug`, `type` (`faq` | `article` | `compare`), `title`, `description`, `locale`,
`publishedAt`, `updatedAt`, `version`, `cover`, `canonicalUrl`. `get(slug)` adds the body:

- `html` — sanitized by Volae (headings, paragraphs, lists, links, code, quotes, images, tables only), safe to render as
  it is;
- `markdown` — CommonMark with GFM tables, no HTML;
- `faq` — the questions and answers of a FAQ item, or `null`;
- `jsonLd` — schema.org data for search engines.

## Publish notifications

In Volae's content settings, add a notification URL (for example `https://your-site.com/api/volae-revalidate`).
Volae shows a secret (`whsec_…`) once — keep it in `VOLAE_REVALIDATE_SECRET`. When an item is published, updated or
unpublished, Volae POSTs:

```json
{ "type": "content.published", "slug": "export-pdf", "occurredAt": "2026-11-05T08:00:00.000Z" }
```

signed with `X-Volae-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`. Failed deliveries are
retried after 1 minute, 10 minutes and 1 hour.

On Next.js, `createRevalidateHandler` does everything. Anywhere else:

```ts
import { verifyContentWebhook } from "@volae/content";

const event = await verifyContentWebhook({
  secret: process.env.VOLAE_REVALIDATE_SECRET!,
  body: await request.text(),          // the raw body, before any JSON parsing
  signature: request.headers.get("x-volae-signature"),
});
// event: { type, slug, occurredAt }. A bad or old (> 5 minutes) signature throws ContentError("invalid_signature").
```

## SEO

Search engines and AI crawlers need to see the text in the HTML your server sends. Render content on the server or at
build time — server components, `generateStaticParams`, Astro pages — not in the browser after the page loads.
Add the metadata (`contentMetadata` on Next.js; title, description and canonical in your Astro layout) and keep the
JSON-LD that `VolaeContent` renders. If the same content also lives on your Volae help center, `canonicalUrl` tells you
which address search engines should treat as the original.
