Create a KB entry

POST

/api/workspaces/{workspaceId}/kb-entries

Production

Creates a new knowledge base entry in the specified workspace. Manually created entries are immediately set to ‘approved’ status and become available to the AI. Provide a clear question-answer pair and relevant topic tags to help the AI match this entry to customer inquiries.

Authorizations

bearerAuth

Parameters

Path Parameters

workspaceId

required

string format: uuid

The workspace to create the entry in.

Request Body

object

question

required

The question or topic this entry addresses.

string

>= 1 characters

Example

What are your delivery times to Germany?

answer

required

The answer to the question.

string

>= 1 characters

Example

Standard delivery to Germany takes 3-5 business days. Express delivery (next business day) is available for EUR 12.50.

sourceType

required

How this entry was created. Use ‘manual’ for human-authored entries, ‘import’ for API-imported entries.

string

>= 1 characters

Example

manual

topics

Tags that categorize this entry. Helps the AI match relevant entries to conversations.

Array<string>

Example

[
  "shipping",
  "delivery",
  "germany"
]

sourceConversationId

Optional reference to the conversation that inspired this entry.

string

Example

c1a2b3c4-5678-9abc-def0-1234567890ab

confidence

Confidence score between 0 and 1. Typically set by the learning loop, not manually.

number

<= 1

Example

Responses

200

The KB entry was created and is immediately available to the AI.

A knowledge base (KB) entry is a question-answer pair that the AI uses to respond to customer inquiries. Entries can be created manually, imported via the API, or proposed automatically by the learning loop after resolved conversations. Proposed entries require human approval before the AI can use them.

object

required

Unique identifier for the KB entry.

string format: uuid

Example

kb1a2b3c-5678-9abc-def0-1234567890ab

tenantId

required

The tenant this entry belongs to.

string format: uuid

Example

a0b1c2d3-4567-89ab-cdef-0123456789ab

workspaceId

required

The workspace this entry is scoped to. The AI only uses entries from the workspace that matches the conversation.

string format: uuid

Example

w1a2b3c4-5678-9abc-def0-1234567890ab

question

required

The question or topic this entry addresses. This is what the AI matches against when a customer asks something.

string

Example

What are your delivery times to Germany?

answer

required

The answer the AI should use when this entry is matched. Can include specific details, links, and instructions.

string

Example

Standard delivery to Germany takes 3-5 business days. Express delivery (next business day) is available for an additional fee of EUR 12.50.

topics

required

Tags that categorize this entry. Used for filtering and to help the AI determine relevance.

Array<string>

Example

[
  "shipping",
  "delivery",
  "germany"
]

sourceType

required

How this entry was created. ‘manual’ means created by a human, ‘learning_loop’ means proposed by the AI after analyzing resolved conversations, ‘import’ means imported via the API.

string

Example

manual

confidence

Confidence score between 0 and 1, set by the learning loop when proposing entries. Higher values indicate the AI is more confident the entry is accurate. Null for manually created entries.

number | null

Example

0.92

status

required

Lifecycle status of the entry. ‘pending_review’ entries are proposed but not yet approved — the AI will not use them. ‘approved’ entries are active and used by the AI. ‘rejected’ entries were reviewed and declined. ‘archived’ entries are no longer active but kept for audit.

string

Allowed values: pending_review approved rejected archived

Example

approved

usageCount

required

Number of times this entry has been referenced by the AI when responding to conversations.

integer

Example

lastUsedAt

Timestamp of the last time the AI referenced this entry. Null if never used.

string | null format: date-time

Example

2026-03-25T14:20:00.000Z

createdAt

required

Timestamp when the entry was created.

string format: date-time

Example

2026-02-01T12:00:00.000Z

updatedAt

required

Timestamp when the entry was last updated.

string format: date-time

Example

2026-03-15T10:30:00.000Z

422

Validation error. One or more required fields are missing or invalid.

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