How to Integrate Bolt.new with Kentico Xperience

Kentico Xperience's headless content delivery is organized around Channels — logical groupings of content and settings for different delivery endpoints. Before accessing the API, a headless channel must be configured for your Bolt frontend. Log in to Kentico Xperience's admin interface. Navigate to Channel Management in the top navigation. If you are setting up a new headless channel, click 'Create Channel' and select 'Headless channel' as the type. Give it a name that identifies your Bolt frontend (e.g., 'Bolt Frontend' or 'React App'). The channel creates a dedicated API endpoint scoped to the content types and languages you configure for that channel. With the channel created, navigate to its settings to find the Delivery API configuration. Kentico generates a base delivery API URL for your channel in the format: `https://your-project.kontent.ai/` or `https://deliver.kontent.ai/{environment-id}/`. Note your Environment ID — a GUID-format string that identifies your Kentico project environment. For API authentication: Kentico's Delivery API has two access modes. The Preview API (for drafts and unpublished content) requires an API key. The Production API (for published content only) can be configured to not require authentication, or can require an API key for additional security. Generate a Delivery API key from your channel's API Keys section — copy the key immediately after generation as it may not be shown again. For the Management API (content creation and updates), generate a separate Management API key from the API Keys section. Management API keys have broader permissions and must remain strictly server-side. Add to your Bolt .env file: `KENTICO_ENVIRONMENT_ID=your-guid-environment-id`, `KENTICO_DELIVERY_API_KEY=your-delivery-api-key`, and `KENTICO_MANAGEMENT_API_KEY=your-management-api-key`.

1// lib/kentico.ts
2const KENTICO_BASE_URL = 'https://deliver.kontent.ai';
3
4interface KenticoDeliveryFetchOptions {
5  params?: Record<string, string>;
6  preview?: boolean;
7}
8
9export interface KenticoSystemAttributes {
10  id: string;
11  name: string;
12  codename: string;
13  language: string;
14  type: string;
15  collection: string;
16  sitemap_locations: string[];
17  last_modified: string;
18  workflow_step?: string;
19  url_slug?: string;
20}
21
22export interface KenticoContentItem<T = Record<string, unknown>> {
23  system: KenticoSystemAttributes;
24  elements: T;
25}
26
27export interface KenticoDeliveryResponse<T = Record<string, unknown>> {
28  items: KenticoContentItem<T>[];
29  modular_content: Record<string, KenticoContentItem>;
30  pagination: {
31    skip: number;
32    limit: number;
33    count: number;
34    next_page: string;
35  };
36}
37
38export async function kenticoDeliveryFetch<T = Record<string, unknown>>(
39  endpoint: string,
40  options: KenticoDeliveryFetchOptions = {}
41): Promise<T> {
42  const environmentId = process.env.KENTICO_ENVIRONMENT_ID;
43  const apiKey = process.env.KENTICO_DELIVERY_API_KEY;
44
45  if (!environmentId) {
46    throw new Error('KENTICO_ENVIRONMENT_ID is not configured');
47  }
48
49  const baseUrl = options.preview
50    ? `https://preview-deliver.kontent.ai/${environmentId}`
51    : `${KENTICO_BASE_URL}/${environmentId}`;
52
53  const url = new URL(`${baseUrl}/${endpoint}`);
54  if (options.params) {
55    Object.entries(options.params).forEach(([k, v]) => url.searchParams.set(k, v));
56  }
57
58  const headers: Record<string, string> = {
59    'Content-Type': 'application/json',
60  };
61
62  if (apiKey) {
63    headers['Authorization'] = `Bearer ${apiKey}`;
64  }
65
66  const response = await fetch(url.toString(), { headers });
67  const data = await response.json() as { message?: string; request_id?: string } & T;
68
69  if (!response.ok) {
70    throw new Error(
71      `Kentico Delivery API error ${response.status}: ${data.message || response.statusText}`
72    );
73  }
74
75  return data;
76}

Kentico Xperience's Content Delivery API returns content items filtered by content type, language, and custom element values. Content types are defined in Kentico's Content Type Modeler — they represent the structure of different content (Article, Product, Team Member, Event) with typed elements (text, rich text, date-time, number, asset, linked items, taxonomy). The primary endpoint for content retrieval is `GET /{environmentId}/items` with query parameters. Key parameters: `system.type` (filter by content type codename — the lowercase, underscore-separated name like `article` or `product_page`), `system.language` (filter by language variant, e.g., `en-US`, `es-ES`), `elements.{element_codename}[contains]` (filter by element value), `depth` (how many levels of linked items to include, 0-5), `limit` and `skip` for pagination, and `order` for sorting. Kentico elements are returned as typed objects: text elements have a `value` string, rich text elements have a `value` string containing HTML, asset elements have an `images` array and `links` array, linked items have an `itemCodenames` array of codenames referencing items in `modular_content`, and taxonomy elements have a `taxonomyGroup` string and `value` array of terms. For rich text fields, Kentico inlines linked content (embedded items, linked images) using custom HTML attributes. The `@kontent-ai/delivery-sdk` npm package provides a React SDK for properly resolving these references. For simpler cases where the rich text does not contain inline linked items, the raw HTML in the `value` field can be rendered directly with `dangerouslySetInnerHTML`. A key distinction in Kentico's API: items are returned as flat objects with a `system` property (metadata) and `elements` property (content fields). The element codenames match what was configured in Kentico's Content Type Modeler — ask your Kentico administrator for the exact codenames for your content types if you are integrating with an existing Kentico setup.

1// app/api/kentico/items/route.ts
2import { NextResponse } from 'next/server';
3import { kenticoDeliveryFetch, KenticoDeliveryResponse } from '@/lib/kentico';
4
5export async function GET(request: Request) {
6  const { searchParams } = new URL(request.url);
7  const type = searchParams.get('type');
8  const language = searchParams.get('language') || 'en-US';
9  const limit = parseInt(searchParams.get('limit') || '10', 10);
10  const page = parseInt(searchParams.get('page') || '1', 10);
11  const slug = searchParams.get('slug');
12  const depth = searchParams.get('depth') || '1';
13
14  const skip = (page - 1) * limit;
15
16  const params: Record<string, string> = {
17    'system.language': language,
18    limit: limit.toString(),
19    skip: skip.toString(),
20    depth,
21  };
22
23  if (type) {
24    params['system.type'] = type;
25  }
26
27  if (slug) {
28    // Filter by URL slug element — adjust element codename for your content type
29    params['elements.url_slug'] = slug;
30  }
31
32  try {
33    const data = await kenticoDeliveryFetch<KenticoDeliveryResponse>('items', { params });
34
35    return NextResponse.json({
36      items: data.items,
37      modularContent: data.modular_content,
38      pagination: {
39        total: data.pagination.count,
40        limit: data.pagination.limit,
41        skip: data.pagination.skip,
42        hasNextPage: data.pagination.next_page !== '',
43        currentPage: page,
44        totalPages: Math.ceil(data.pagination.count / limit),
45      },
46    });
47  } catch (err) {
48    const message = err instanceof Error ? err.message : 'Failed to fetch Kentico content';
49    return NextResponse.json({ error: message }, { status: 500 });
50  }
51}

Rendering Kentico content in React requires understanding the element type system. Each element in a Kentico content item has a typed structure depending on how it was configured in the Content Type Modeler. Building TypeScript interfaces that match your specific Kentico content types makes the frontend code more maintainable and catches element access errors at compile time. For text elements, access `elements.title.value` (a plain string). For rich text elements, `elements.body.value` contains HTML that can be rendered with `dangerouslySetInnerHTML`. For date-time elements, `elements.published_date.value` is an ISO 8601 string. For asset elements, `elements.feature_image.value[0].url` gives the first image URL, with `elements.feature_image.value[0].description` for alt text. For taxonomy elements, `elements.categories.value` is an array of term objects with `name` and `codename` properties. Linked items are the most complex element type. The `elements.related_articles.value` contains an array of item codenames. The actual linked item objects are in the `modular_content` object at the top level of the API response, keyed by codename. Your component needs to look up linked items from this separate object and render them recursively. For a production implementation with complex linked content, the `@kontent-ai/delivery-sdk` npm package provides automatic linked item resolution, typed responses, and inline rich text component mapping. For simpler cases with shallow content structures, the direct API approach with manual linked item lookup is sufficient. Langauge-specific content: Kentico stores each language variant as a separate item. When you request content with `system.language=es-ES`, you receive the Spanish translation with the same codename as the default language item. Build language switching by re-fetching the same item with a different language parameter.

1// types/kentico-article.ts
2export interface KenticoTextElement {
3  type: 'text';
4  name: string;
5  value: string;
6}
7
8export interface KenticoRichTextElement {
9  type: 'rich_text';
10  name: string;
11  value: string; // HTML string
12  images: Record<string, { image_id: string; description: string; url: string; width: number; height: number }>;
13  links: Record<string, { codename: string; type: string; url_slug: string }>;
14  modular_content: string[];
15}
16
17export interface KenticoAssetElement {
18  type: 'asset';
19  name: string;
20  value: Array<{
21    name: string;
22    description: string | null;
23    type: string;
24    size: number;
25    url: string;
26    width: number | null;
27    height: number | null;
28  }>;
29}
30
31export interface KenticoDateTimeElement {
32  type: 'date_time';
33  name: string;
34  value: string | null; // ISO 8601
35}
36
37export interface KenticoTaxonomyElement {
38  type: 'taxonomy';
39  name: string;
40  taxonomy_group: string;
41  value: Array<{ name: string; codename: string }>;
42}
43
44export interface KenticoLinkedItemsElement {
45  type: 'modular_content';
46  name: string;
47  value: string[]; // array of item codenames
48}
49
50export interface ArticleElements {
51  title: KenticoTextElement;
52  url_slug: KenticoTextElement;
53  body: KenticoRichTextElement;
54  published_date: KenticoDateTimeElement;
55  feature_image: KenticoAssetElement;
56  categories: KenticoTaxonomyElement;
57  author?: KenticoLinkedItemsElement;
58}
59
60// Utility to strip HTML tags for plain text excerpts:
61export function stripHtml(html: string, maxLength = 200): string {
62  const stripped = html.replace(/<[^>]+>/g, '').replace(/&[^;]+;/g, ' ').trim();
63  return stripped.length > maxLength ? stripped.slice(0, maxLength) + '...' : stripped;
64}

Kentico Xperience's Management API enables creating, updating, and publishing content items programmatically. This is valuable for migrating content from other systems into Kentico, automating content creation from external data sources, or building simplified editorial workflows that write back to Kentico. The Management API uses REST with API key authentication. The base URL format is `https://manage.kontent.ai/v2/projects/{environmentId}/`. Unlike the Delivery API (which is read-only), the Management API requires a separate key with write permissions, generated from Kentico's API Keys section. Creating a content item requires two steps: first create the content item (which establishes its identity, type, and collection), then upsert the language variant (which sets the element values for a specific language). This two-step approach is specific to Kentico's content architecture — each content item can have multiple language variants, and elements are stored per-language-variant rather than on the item itself. Step 1: `POST /items` with body `{ name: 'Article title', type: { codename: 'article' }, collection: { codename: 'default' } }`. This returns the new item's `id`. Step 2: `PUT /items/{item_id}/variants/codename/{language_codename}` with body `{ elements: [{ element: { codename: 'title' }, value: 'Article title' }, { element: { codename: 'body' }, value: '<p>Content</p>' }] }`. This upserts the language variant — creating it if it does not exist, or updating it if it does. After creating and setting elements, change the workflow step to publish the content: `PUT /items/{item_id}/variants/codename/{language_codename}/workflow/{workflow_step_codename}`. The codename for the published state depends on your Kentico workflow configuration — typical values are 'published' or 'live'.

1// app/api/kentico/manage/articles/route.ts
2import { NextResponse } from 'next/server';
3
4const KENTICO_MANAGE_BASE = 'https://manage.kontent.ai/v2/projects';
5
6async function kenticoManageFetch<T>(
7  endpoint: string,
8  options: { method: string; body?: Record<string, unknown> }
9): Promise<T> {
10  const environmentId = process.env.KENTICO_ENVIRONMENT_ID;
11  const apiKey = process.env.KENTICO_MANAGEMENT_API_KEY;
12
13  if (!environmentId || !apiKey) {
14    throw new Error('KENTICO_ENVIRONMENT_ID and KENTICO_MANAGEMENT_API_KEY must be configured');
15  }
16
17  const response = await fetch(
18    `${KENTICO_MANAGE_BASE}/${environmentId}/${endpoint}`,
19    {
20      method: options.method,
21      headers: {
22        Authorization: `Bearer ${apiKey}`,
23        'Content-Type': 'application/json',
24      },
25      body: options.body ? JSON.stringify(options.body) : undefined,
26    }
27  );
28
29  const data = await response.json() as { message?: string; validation_errors?: Array<{message: string}> } & T;
30
31  if (!response.ok) {
32    const message = data.message ||
33      data.validation_errors?.[0]?.message ||
34      `Kentico Management API error: ${response.status}`;
35    throw new Error(message);
36  }
37
38  return data;
39}
40
41export async function POST(request: Request) {
42  const { name, body_html, published_date, categories } = await request.json() as {
43    name: string;
44    body_html?: string;
45    published_date?: string;
46    categories?: string[]; // taxonomy term codenames
47  };
48
49  if (!name) {
50    return NextResponse.json({ error: 'name is required' }, { status: 400 });
51  }
52
53  try {
54    // Step 1: Create the content item
55    const item = await kenticoManageFetch<{ id: string; codename: string }>('items', {
56      method: 'POST',
57      body: {
58        name,
59        type: { codename: 'article' },
60        collection: { codename: 'default' },
61      },
62    });
63
64    // Step 2: Set language variant elements
65    const elements = [
66      { element: { codename: 'title' }, value: name },
67    ];
68
69    if (body_html) {
70      elements.push({ element: { codename: 'body' }, value: body_html });
71    }
72
73    if (published_date) {
74      elements.push({ element: { codename: 'published_date' }, value: published_date });
75    }
76
77    if (categories && categories.length > 0) {
78      (elements as unknown[]).push({
79        element: { codename: 'categories' },
80        value: categories.map((c) => ({ codename: c })),
81      });
82    }
83
84    await kenticoManageFetch(`items/${item.id}/variants/codename/en-US`, {
85      method: 'PUT',
86      body: { elements },
87    });
88
89    return NextResponse.json({
90      id: item.id,
91      codename: item.codename,
92      previewUrl: `${process.env.KENTICO_DELIVERY_URL}/preview/${item.codename}`,
93      message: `Article '${name}' created as draft in Kentico`,
94    }, { status: 201 });
95  } catch (err) {
96    const message = err instanceof Error ? err.message : 'Failed to create Kentico article';
97    return NextResponse.json({ error: message }, { status: 500 });
98  }
99}

Kentico's Content Delivery API calls work in Bolt's WebContainer preview since they are outbound HTTPS requests to Kentico's cloud infrastructure. The Management API also works in the WebContainer — both are server-side API routes making outbound calls, unaffected by the WebContainer's incoming connection limitation. Deploy to Netlify via Settings → Applications → Connect Netlify or click Publish to deploy to Bolt Cloud. Add server-side environment variables: `KENTICO_ENVIRONMENT_ID`, `KENTICO_DELIVERY_API_KEY`, and `KENTICO_MANAGEMENT_API_KEY` — all without NEXT_PUBLIC_ prefix to keep them server-side. For production content delivery performance, implement Next.js ISR using Kentico's webhook notifications. Kentico Xperience supports webhooks that fire when content is published or updated. Configure a webhook in Kentico's admin (Settings → Webhooks) pointing to your deployed `/api/kentico/revalidate` endpoint. When editors publish content in Kentico, the webhook triggers ISR revalidation, serving fresh content without a full redeploy. Kentico's webhooks send a POST request with a payload identifying the changed content item by codename and type. Parse this payload in your revalidation route to determine which pages to revalidate — rather than revalidating all pages, revalidate only the specific article or product page that changed. This targeted revalidation keeps your cached pages fresh while minimizing unnecessary regeneration. For multi-language deployments, ensure each language has a corresponding route structure in Next.js (`/en/articles/[slug]`, `/es/articles/[slug]`) and that your revalidation logic covers all active language variants when content is updated.

1# Production environment variables — Netlify or Bolt Cloud
2# Server-side only — never add NEXT_PUBLIC_ prefix
3
4KENTICO_ENVIRONMENT_ID=your-project-environment-guid
5KENTICO_DELIVERY_API_KEY=your-delivery-api-key
6KENTICO_MANAGEMENT_API_KEY=your-management-api-key
7KENTICO_WEBHOOK_SECRET=your-webhook-verification-secret
8
9# Kentico delivery base URLs (for reference, used in lib/kentico.ts):
10# Live API: https://deliver.kontent.ai/{KENTICO_ENVIRONMENT_ID}/
11# Preview API: https://preview-deliver.kontent.ai/{KENTICO_ENVIRONMENT_ID}/
12# Management API: https://manage.kontent.ai/v2/projects/{KENTICO_ENVIRONMENT_ID}/