{
  "slug": "headless-api",
  "title": "Headless Site API & Chat Embedding",
  "description": "Use CMS Admin as a headless backend inside your own Next.js site. Read content, trigger deploys, and embed the AI chat — all authenticated with a permanent wh_ Access Token.",
  "category": "api-reference",
  "order": 10,
  "locale": "en",
  "translationGroup": "dfab20dd-24ca-4976-9527-7806ef94afb9",
  "helpCardId": null,
  "content": "## Overview\n\nWebHouse CMS Admin is a full headless backend. Any Next.js (or other) site can call its REST API with a permanent `wh_` Access Token — no OAuth redirect, no cookie session. This lets you build custom admin panels, booking management, form inboxes, and even an AI chat inside your own branded UI.\n\n## 1. Create an Access Token\n\nGo to **Account Preferences → Access Tokens → Create custom token**.\n\nChoose only the permissions your site needs:\n\n| Use case | Permissions |\n|---|---|\n| Read content | `content.read` |\n| Full content CRUD | `content.read content.create content.edit content.publish content.delete` |\n| Trigger deploys | `deploy:trigger deploy:read` |\n| Form inbox | `forms.read` |\n\nSet **Site scope** to restrict the token to a specific site. Store it in `.env`:\n\n```\nCMS_API_TOKEN=wh_xxxxxxxxxxxxxxxxxxxx\nCMS_API_URL=https://webhouse.app\n```\n\n**Never expose the token client-side.** Use it in server components, API routes, or `getServerSideProps` only.\n\n## 2. Read Content\n\n```typescript\n// app/posts/page.tsx\nexport default async function PostsPage() {\n  const res = await fetch(\n    `${process.env.CMS_API_URL}/api/cms/posts?status=published`,\n    {\n      headers: { Authorization: `Bearer ${process.env.CMS_API_TOKEN}` },\n      next: { revalidate: 60 },\n    }\n  );\n  const { documents } = await res.json();\n  return <ul>{documents.map((p: any) => <li key={p.slug}>{p.data.title}</li>)}</ul>;\n}\n```\n\n## 3. Content API Reference\n\n```\nGET    /api/cms/{collection}          List documents\nGET    /api/cms/{collection}/{slug}   Get by slug\nPOST   /api/cms/{collection}         Create\nPATCH  /api/cms/{collection}/{slug}  Update\nDELETE /api/cms/{collection}/{id}    Trash\n\nQuery params: status, locale, limit, offset, tags\n```\n\n## 4. Site Admin Building Blocks\n\n### Trigger a deploy\n\n```typescript\nawait fetch(`${process.env.CMS_API_URL}/api/admin/deploy`, {\n  method: 'POST',\n  headers: { Authorization: `Bearer ${process.env.CMS_API_TOKEN}` },\n});\n```\n\n### Read form submissions\n\n```typescript\nconst res = await fetch(\n  `${process.env.CMS_API_URL}/api/admin/forms/contact/submissions`,\n  { headers: { Authorization: `Bearer ${process.env.CMS_API_TOKEN}` } }\n);\nconst { submissions } = await res.json();\n```\n\n## 5. Embed the AI Chat\n\nThe CMS chat runs the same Claude model and tools as CMS Admin. Proxy it through a server route in your site:\n\n```typescript\n// app/api/chat/route.ts\nexport async function POST(request: Request) {\n  const body = await request.text();\n  const upstream = await fetch(`${process.env.CMS_API_URL}/api/cms/chat`, {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      Authorization: `Bearer ${process.env.CMS_API_TOKEN}`,\n    },\n    body,\n  });\n  return new Response(upstream.body, {\n    headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },\n  });\n}\n```\n\nThen consume the stream in a client component with a standard `ReadableStream` parser. The chat streams SSE events with `event: text`, `event: tool_call`, `event: tool_result`, and `event: done`.\n\n**Restrict tools** by granting only the permissions you want on the Access Token — the chat only executes tools matching the token's permission set.\n\n## 6. ICD Revalidation\n\nConfigure the revalidate webhook in Site Settings → Deploy → Revalidate URL to connect Next.js ISR with CMS content publishing:\n\n```typescript\n// app/api/revalidate/route.ts\nimport { revalidatePath } from 'next/cache';\nexport async function POST(req: Request) {\n  const secret = req.headers.get('x-webhouse-secret');\n  if (secret !== process.env.REVALIDATE_SECRET) return new Response('Unauthorized', { status: 401 });\n  const { slug, collection } = await req.json();\n  revalidatePath(`/${collection}/${slug}`);\n  return Response.json({ revalidated: true });\n}\n```\n\n## Further reading\n\n- [Access Tokens](/docs/access-tokens) — creating and scoping tokens\n- [Content API](/docs/api-reference) — full endpoint reference\n- [ICD Deployment](/docs/deployment) — instant content deployment",
  "excerpt": "Overview\n\nWebHouse CMS Admin is a full headless backend. Any Next.js (or other) site can call its REST API with a permanent wh Access Token — no OAuth redirect, no cookie session. This lets you build custom admin panels, booking management, form inboxes, and even an AI chat inside your own branded U",
  "seo": {},
  "createdAt": "2026-04-28T00:00:00.000Z",
  "updatedAt": "2026-04-28T00:00:00.000Z"
}