Connect your website

The CMS API lets your website fetch and render published content from Profound CMS. You can use it to power documentation pages, marketing pages, blogs, help centers, or any other content-driven experience.

The typical integration has three parts:

1. Configure your CMS connection
2. Fetch published content
3. Render the content in your application

Configuration

To connect your application to the CMS, provide your CMS API URL, website ID, and API key.

const cmsConfig = {
  cmsUrl: 'https://cms.dev.tryprofoun.com',
  websiteId: 'your-website-id',
  apiKey: process.env.PROFOUND_API_KEY,
};

Use environment variables for values that change between environments:

NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_WEBSITE_ID=your-website-id
PROFOUND_API_KEY=your-api-key

Do not expose private API keys in client-side code. API keys should be used on your server, in your build process, or in your backend routes.

Fetch Content

Content in the CMS is organized by schema. For example, your project may have schemas such as post, category, page, or section.

Use the schema name to fetch content:

const posts = await cms.schema('post').fetchAll();

To fetch a single document by ID:

const post = await cms.schema('post').fetchSingleById('document-id');

To fetch localized content, request the translated version of the schema:

const frenchPost = await cms
  .schema('post')
  .translation('fr')
  .fetchSingleById('document-id');

Render Routes

For websites that use CMS-managed pages, you can fetch content based on the current URL path.

const route = await cms.route.getByPath({
  websiteId: 'your-website-id',
  path: '/docs/getting-started',
});

The route response identifies the page and the blocks to render. Your application can then fetch the blocks and render them with your own components.

const blocks = await cms.block.getByIds({
  websiteId: 'your-website-id',
  ids: route.blockIds,
});

Example: Render a Documentation Page

async function getDocsPage(path: string) {
  const route = await cms.route.getByPath({
    websiteId: process.env.WEBSITE_ID,
    path,
  });

  const blocks = await cms.block.getByIds({
    websiteId: process.env.WEBSITE_ID,
    ids: route.blockIds,
  });

  return {
    title: route.label,
    path: route.path,
    blocks,
  };
}

You can use the returned blocks to render the page using your application’s component system.

Caching

Published CMS content is safe to cache. For most websites, cache API responses for a short period and revalidate them when content changes.

A common setup is:

const content = await cache(
  () => cms.schema('post').fetchAll(),
  {
    revalidate: 60,
    tags: ['cms-posts'],
  }
);

Recommended cache behavior:

• Cache published reads.
• Use shorter cache windows for frequently updated content.
• Use cache tags if your framework supports on-demand invalidation.
• Avoid caching preview or draft content.

Preview Mode

Preview mode lets editors see unpublished changes before they are published.

A common pattern is to use a separate preview route, for example:

/docs/getting-started
/cms-preview/docs/getting-started

Production pages should fetch only published content. Preview pages can accept preview parameters, such as:

?edit_mode=true

Preview routes should usually be dynamic and should not be statically cached.

Error Handling

CMS content may be unavailable during a build or request. Your application should handle this gracefully.

Recommended behavior:

• Return 404 when a route does not exist.
• Return an empty list when optional navigation content cannot be loaded.
• Log server-side fetch errors.
• Avoid exposing internal API errors to visitors.

Example:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Failed to fetch CMS post', error);
    return null;
  }
}

Security

Keep API keys private and use them only on the server. Do not include private credentials in browser bundles or public JavaScript.

Use public environment variables only for non-sensitive values such as:

• CMS public URL
• Website ID
• Locale configuration

Use private environment variables for:

• API keys
• preview tokens
• admin credentials
• deployment secrets

Summary

Use the CMS API when your website needs to fetch structured content, render CMS-managed routes, or support editor preview workflows.

A standard integration should:

• Configure the CMS URL, website ID, and API key.
• Fetch documents by schema.
• Fetch pages by route path.
• Render CMS blocks with your own components.
• Cache published content.
• Keep the preview content dynamic.
• Keep private credentials on the server.