Update a KB widget

PATCH

/api/widgets/kb/{widgetId}

• Production

Updates the configuration of a knowledge base widget. Only the fields you include in the request body are updated. Changes take effect immediately for new page loads on the embedded site.

Authorizations

• bearerAuth

Parameters

Path Parameters

widgetId

required

string format: uuid

The unique identifier of the widget to update.

Request Body

object

name

Updated display name.

string

>= 1 characters

primaryColor

Updated primary color.

string

fontFamily

Updated font family.

string

customCss

Updated custom CSS.

string

allowedOrigins

Updated allowed origins. Replaces the existing list.

Array<string>

enabled

Enable or disable the widget.

boolean

theme

Updated color theme.

string

Allowed values: light dark auto

inlineView

Updated layout mode.

string

Allowed values: grid list

Responses

200

The widget was updated.

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

404

No widget exists with the given ID in the authenticated tenant.

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

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