Skip to content
oHallo Developers

List knowledge base entries

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

Returns the knowledge base entries of a workspace, of every status, in creation order. The assistant draws on the entries with status approved; to read only the entries awaiting review, use the pending endpoint. Without limit and cursor, the answer is every entry, as a JSON array. With either, the answer is one page: at most limit entries, with nextCursor when more entries follow. Pass nextCursor as the cursor parameter to read the next page.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
workspaceId
required
string format: uuid

The workspace to list KB entries for.

Query Parameters

Section titled “Query Parameters ”
limit
integer
>= 1 <= 100

Entries per page, from 1 to 100. Sending it asks for one page; with cursor and no limit, a page holds 50 entries.

Example
50
cursor
string
>= 1 characters <= 512 characters

Opaque cursor from a previous response’s nextCursor. The page starts after the last entry of that response.

Example
eyJjIjoiMjAyNi0wMS0xNVQxMDowMDowMC4wMDAwMDBaIiwiaSI6IjExMjIzMzQ0LTU1NjYtNDc4OC05OWFhLWJiY2NkZGVlZmYwMCJ9

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Without limit and cursor, every KB entry in the workspace, as an array. With either, one page of entries, with nextCursor when more entries follow.

One of:

List of knowledge base entries.

Array<object>

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
id
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 the entry came to be. manual is an entry written by a person, approved when it is created. extracted is a proposal the learning loop drafted from a resolved conversation. The API stores the value sent, and an entry created with a value other than manual starts as pending_review.

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

Where the entry stands. approved: in use, the assistant draws on it. pending_review: created for review, through the API with a sourceType other than manual; it is not used until it is approved. proposed: drafted by oHallo, for example by the learning loop from a resolved conversation; it is not used until it is approved, and a proposal that changes an existing entry is applied to that entry when it is approved. rejected: declined in review. archived: no longer in use, kept for the record.

string
Allowed values: pending_review approved rejected archived proposed
Example
approved
usageCount
required

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

integer
Example
47
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

404

Section titled “404 ”

No workspace exists with the given workspaceId, or it is outside the API key’s brand or workspace restriction.

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
code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string
Example
key_lock
missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>
Example
[
  "mcp:write"
]
entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid
Example
11223344-5566-4788-99aa-bbccddeeff00
connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string
undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>
Example
[
  "get_orders"
]
declaredTools

On the same 422: the tools the connection declares.

Array<string>
Example
[
  "get_order",
  "search_orders"
]

422

Section titled “422 ”

Validation error. limit is not an integer from 1 to 100, or cursor is empty or is not a nextCursor value.

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
code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string
Example
key_lock
missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>
Example
[
  "mcp:write"
]
entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid
Example
11223344-5566-4788-99aa-bbccddeeff00
connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string
undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>
Example
[
  "get_orders"
]
declaredTools

On the same 422: the tools the connection declares.

Array<string>
Example
[
  "get_order",
  "search_orders"
]

Looking for the product? Visit ohallo.ai  ·  Help Centre  ·  Contact

Copyright 2026 oHallo. All rights reserved.