Integrate Forumulate into your website

For the AI agent doing this integration. Goal — pull an organization's Forumulate content (documentation, blog, forum, changelog, and any other space) from the REST API, render it inside an existing website, and keep it in sync. Everything below is executable with a single token.

The full API reference indexes every resource, and the whole surface is published as a machine-readable OpenAPI spec you can generate a client from — or use the first-party TypeScript SDK.

Facts you'll reuse

• Base URL: https://forumulate.com/api

• Auth header on every request: Authorization: Bearer cft_…

• Org-scoped routes live under /api/orgs/{orgId}/…; public read-only reader routes under /api/public/orgs/{orgId}/…. {orgId} accepts the org's UUID or its slug.

• List routes answer an envelope { <name>: [...], page, sync } and page by cursor — see pagination and the collection envelope.

1. Get a token

Mint a Personal Access Token under Account → API tokens — read scope is enough to pull content. Scope it to the exact spaceIds you will surface, so the token can never read anything else. Keep it server-side; never ship it to the browser. Full model: Authentication.

To build before you have real credentials, use the public read-only token in a sandbox to build against.

2. Discover what to pull

List the spaces and note each one's type (DOCS, BLOG, FORUM, CHANGELOG, FAQ, …):

curl https://forumulate.com/api/orgs/{orgId}/spaces \
  -H "Authorization: Bearer cft_…"
# -> { "spaces": [ { "id", "slug", "name", "type" }, … ] }

For a docs-style space, get its page tree (collections → pages, in reading order):

curl https://forumulate.com/api/public/orgs/{orgId}/spaces/{spaceId}
# -> { "collections": [ { "name", "pages": [ { "id","slug","title","children" } ] } ], "theme", … }

3. Pull the content

A — The item stream (use this for anything you'll keep in sync). Every space exposes its pieces (pages, posts, topics) as items with a stable envelope:

curl "https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/items?limit=100" \
  -H "Authorization: Bearer cft_…" \
  -H "Forumulate-Version: 2026-09-01"
# -> { "items": [ { "id","title","slug","updatedAt", … } ],
#      "page": { "has_more", "next_cursor" },
#      "sync": { "checkpoint" } }

Follow page.next_cursor (pass it back as ?cursor=) until has_more is false. See the item resource and the Items API.

B — Rendered content of one piece. Fetch a page as Markdown (easiest to render) or as structured block JSON:

# Markdown — the same bytes agents read
curl https://forumulate.com/api/public/orgs/{orgId}/spaces/{spaceId}/pages/{pageId}.md

# Structured block JSON — for a custom renderer (callouts, tabs, grids, OpenAPI blocks)
curl https://forumulate.com/api/public/orgs/{orgId}/spaces/{spaceId}/pages/{pageId}

4. Render it on the site

• Markdown → your site's Markdown renderer. Simplest path; start here.

• Block JSON → render the block model yourself when you need full fidelity.

• Preserve each piece's slug for stable URLs on your site, and its updatedAt for cache keys.

5. Keep it in sync (do both)

• Incremental pull. Persist the sync.checkpoint from step 3A. Next run, pass it back to receive only what changed since — never re-pull everything. See incremental sync and the Content Sync Protocol.

• Push (webhooks). Register a webhook so a publish updates the site immediately instead of on a poll. See which event means "this changed" and Webhooks for setup and signature verification.

Always send the Forumulate-Version header you built against, so a later change to a shape never reaches a client that didn't ask for it — see versioning and deprecation.

6. Search (optional)

Power your site's search from Forumulate rather than indexing yourself — see the Search endpoint.

7. If you're an agent, you can skip raw REST

An MCP server exposes the same read (and, with a write token, write) surface as typed tools — discover and pull content without hand-rolling requests.

Alternatives to building a render layer

• Host the reader on your own domain / subfolder — Forumulate serves your docs at your domain, no rendering code at all.

• Embed a space in an iframe.

Both are covered in the guides if you'd rather not build the render layer.

Checklist

1. Token minted (read, scoped to spaceIds) — Account → API tokens

2. Spaces listed; each type noted

3. Items pulled per space (cursor-paged); sync.checkpoint stored

4. Content fetched (.md or block JSON) and rendered with stable slugs + updatedAt cache keys

5. Incremental pull and a webhook wired for freshness

6. Forumulate-Version header pinned on every call

Full reference: API endpoints · OpenAPI spec