Knowledge Base

The knowledge base stores question-answer pairs that the AI 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.

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

Query parameters:

Parameter	Type	Required	Description
`topics`	string	No	Comma-separated list of topics to filter by
`status`	string	No	Filter by status: `approved`, `pending_review`, `rejected`
`limit`	integer	No	Max items to return (default 50, max 100)
`offset`	integer	No	Number of items to skip (default 0)

Response:

{
  "items": [
    {
      "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"
    }
  ],
  "total": 156
}

Search entries

Search knowledge base entries by semantic similarity to a query string.

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

Response:

{
  "items": [
    {
      "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
    }
  ],
  "total": 3
}

List pending entries

Retrieve entries awaiting human review. These are typically proposed by oHallo’s learning loop after resolving conversations.

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

Response:

{
  "items": [
    {
      "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"
    }
  ],
  "total": 5
}

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.",
    "topics": ["returns", "refunds"]
  }'

Request body:

Field	Type	Required	Description
`question`	string	Yes	The question this entry answers
`answer`	string	Yes	The answer content
`topics`	string[]	Yes	List of topic tags for categorisation

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 the fields you include in the request body are changed.

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 AI.

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: 204 No Content on success.

Entry statuses

Status	Meaning
`approved`	Active — the AI 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 by the AI

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. Entries with confidence >= 0.85 are auto-approved; those below are set to pending_review.