Knowledge Base

The knowledge base stores question-answer pairs that the assistant references when composing replies. Entries are scoped to a workspace and organised by topic. You can manage entries via the API to keep the knowledge base in sync with your documentation, product catalogues, or support articles.

Required scope: kb:read for GET endpoints, kb:write for write endpoints.

List entries

Retrieve all knowledge base entries for a workspace. The response is a bare JSON array.

curl "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/kb-entries" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

[
  {
    "id": "11223344-5566-4788-99aa-bbccddeeff00",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "question": "What are the standard shipping rates?",
    "answer": "Standard shipping is free for orders over EUR 100. For orders under EUR 100, shipping costs EUR 9.95. Express shipping (1-2 business days) is available for EUR 19.95 regardless of order value.",
    "topics": ["shipping", "pricing"],
    "sourceType": "manual",
    "status": "approved",
    "confidence": null,
    "usageCount": 47,
    "lastUsedAt": "2026-03-15T11:20:00.000Z",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-02-20T14:30:00.000Z"
  }
]

Search entries

Search knowledge base entries by semantic similarity to a query string. The response is a bare JSON array.

curl "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/kb-entries/search?q=how%20long%20does%20delivery%20take" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Query parameters:

Parameter	Type	Required	Description
q	string	Yes	Search query. An empty query returns an empty array.

Response:

[
  {
    "id": "11223344-5566-4788-99aa-bbccddeeff00",
    "question": "What are the standard delivery times?",
    "answer": "Standard delivery takes 3-5 business days within Denmark and 5-7 business days for other Nordic countries. Express delivery (1-2 business days) is available at checkout.",
    "topics": ["shipping", "delivery"],
    "status": "approved",
    "usageCount": 32
  }
]

List pending entries

Retrieve entries awaiting human review. These are typically proposed by the learning loop after resolving conversations. The response is a bare JSON array.

curl "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/kb-entries/pending" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

[
  {
    "id": "aabbccdd-eeff-4788-9233-445566778899",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "question": "Can I change the delivery address after placing an order?",
    "answer": "You can change the delivery address up to 2 hours after placing the order by contacting support. After the order enters the packing stage, address changes are no longer possible.",
    "topics": ["shipping", "orders"],
    "sourceType": "extracted",
    "sourceConversationId": "c9f8e7d6-b5a4-3210-fedc-ba9876543210",
    "status": "pending_review",
    "confidence": 0.78,
    "usageCount": 0,
    "lastUsedAt": null,
    "createdAt": "2026-03-14T16:00:00.000Z",
    "updatedAt": "2026-03-14T16:00:00.000Z"
  }
]

Create entry

Create a new knowledge base entry. Entries created via the API are set to approved status by default.

Required scope: kb:write

curl -X POST "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/kb-entries" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is your return policy?",
    "answer": "We accept returns within 30 days of delivery for unused items in original packaging. Contact support to initiate a return. Refunds are processed within 5 business days after we receive the item.",
    "sourceType": "manual",
    "topics": ["returns", "refunds"]
  }'

Request body:

Field	Type	Required	Description
question	string	Yes	The question this entry answers
answer	string	Yes	The answer content
sourceType	string	Yes	Origin of the entry, e.g. "manual"
topics	string[]	No	List of topic tags for categorisation
sourceConversationId	string	No	The conversation this entry was derived from
confidence	number	No	A score between 0.0 and 1.0

Response:

{
  "id": "ffeeddcc-bbaa-4788-9776-554433221100",
  "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "question": "What is your return policy?",
  "answer": "We accept returns within 30 days of delivery for unused items in original packaging. Contact support to initiate a return. Refunds are processed within 5 business days after we receive the item.",
  "topics": ["returns", "refunds"],
  "sourceType": "manual",
  "status": "approved",
  "confidence": null,
  "usageCount": 0,
  "lastUsedAt": null,
  "createdAt": "2026-03-15T15:00:00.000Z",
  "updatedAt": "2026-03-15T15:00:00.000Z"
}

Update entry

Update an existing knowledge base entry. Only question, answer, and topics can be changed, and only the fields you include in the request body are modified.

Required scope: kb:write

curl -X PATCH "https://api.ohallo.eu/api/kb-entries/ffeeddcc-bbaa-4788-7766-554433221100" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "answer": "We accept returns within 30 days of delivery for unused items in original packaging. Extended holiday returns: items purchased between November 15 and December 31 can be returned until January 31. Contact support to initiate a return.",
    "topics": ["returns", "refunds", "holiday-policy"]
  }'

Response: Returns the full updated entry.

Approve entry

Approve a pending entry, making it available to the assistant.

Required scope: kb:write

curl -X POST "https://api.ohallo.eu/api/kb-entries/aabbccdd-eeff-4788-2233-445566778899/approve" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Reject entry

Reject a pending entry. Optionally include a reason that feeds back into the learning loop.

Required scope: kb:write

curl -X POST "https://api.ohallo.eu/api/kb-entries/aabbccdd-eeff-4788-2233-445566778899/reject" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "This information is outdated; our return window changed to 45 days in March 2026."
  }'

Delete entry

Permanently delete a knowledge base entry.

Required scope: kb:write

curl -X DELETE "https://api.ohallo.eu/api/kb-entries/ffeeddcc-bbaa-4788-7766-554433221100" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response: 200 OK with { "ok": true } on success.

Entry statuses

Status	Meaning
approved	Active; the assistant uses this entry when composing replies
pending_review	Proposed by the learning loop or created with low confidence; awaits human review
rejected	Rejected by a human reviewer; not used when composing replies

Source types

Source	Meaning
manual	Created by a human via the dashboard or API
extracted	Proposed by the learning loop from a resolved conversation

Extracted entries include a confidence score (0.0 to 1.0) and a sourceConversationId linking back to the conversation they were derived from.