Create a KB widget

POST

/api/workspaces/{workspaceId}/widgets/kb

• Production

Creates a new knowledge base widget for embedding on external websites. Configure the visual appearance (colors, fonts, CSS), security (allowed origins), and display mode (grid or list). The widget renders approved KB entries from the workspace and provides a search interface for visitors.

Authorizations

• bearerAuth

Parameters

Path Parameters

workspaceId

required

string format: uuid

The workspace to create the widget in.

Request Body

object

name

required

Display name for the widget.

string

>= 1 characters

Example

Help Center Widget

primaryColor

Primary color as a hex code.

string

Example

#0166A3

fontFamily

Font family for widget text.

string

Example

Inter, sans-serif

customCss

Custom CSS injected into the widget iframe.

string

allowedOrigins

Domains allowed to embed this widget.

Array<string>

Example

[
  "https://www.example.com"
]

enabled

Whether the widget should be active immediately.

boolean

Example

true

theme

Color theme for the widget.

string

Allowed values: light dark auto

Example

auto

inlineView

Layout mode for displaying entries.

string

Allowed values: grid list

Example

grid

Responses

201

The widget was created.

A knowledge base widget that can be embedded on external websites. The widget renders a searchable, branded interface showing approved KB entries from the associated workspace. Widgets are secured by allowed origins and can be customized with your brand colors, fonts, and CSS.

object

id

required

Unique identifier for the widget.

string format: uuid

Example

kw1a2b3c-5678-9abc-def0-1234567890ab

tenantId

required

The tenant this widget belongs to.

string format: uuid

Example

a0b1c2d3-4567-89ab-cdef-0123456789ab

workspaceId

required

The workspace whose KB entries are displayed in this widget.

string format: uuid

Example

w1a2b3c4-5678-9abc-def0-1234567890ab

name

required

Display name for the widget, used in the dashboard to identify it.

string

Example

Help Center Widget

primaryColor

Primary color for the widget UI as a hex code.

string | null

Example

#0166A3

fontFamily

Font family for the widget text. Must be a web-safe font or one loaded on the host page.

string | null

Example

Inter, sans-serif

customCss

Custom CSS injected into the widget iframe for advanced styling.

string | null

Example

.widget-header { border-bottom: 2px solid #0166A3; }

allowedOrigins

List of domains allowed to embed this widget. The widget will refuse to load on unlisted origins. Use ’*’ to allow all origins (not recommended for production).

Array<string>

Example

[
  "https://www.example.com",
  "https://help.example.com"
]

enabled

required

Whether the widget is currently active. Disabled widgets return an error when loaded.

boolean

Example

true

theme

Color theme for the widget. ‘auto’ follows the user’s system preference.

string

Allowed values: light dark auto

Example

auto

inlineView

Layout mode for displaying KB entries. ‘grid’ shows entries as cards, ‘list’ shows them in a vertical list.

string

Allowed values: grid list

Example

grid

publicKey

Public key used to authenticate the widget when loaded on an external page.

string | null

Example

pk_wgt_a1b2c3d4e5f6

createdAt

required

Timestamp when the widget was created.

string format: date-time

Example

2026-03-01T10:00:00.000Z

updatedAt

required

Timestamp when the widget was last updated.

string format: date-time

Example

2026-03-20T15:30:00.000Z

422

Validation error.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found