Search existing knowledge for a passage

client.trainingData.search(, ?): KnowledgeSearch { candidates, object, query, timings }

POST/v2/training_data/search

Searches one passage or claim across Q&A, training files, and live help-center articles. Returns ranked candidates and query-focused excerpts without judging or writing. Similarity is an embedding score, not factual confidence; calibrate thresholds on representative examples and retain keyword-only results (similarity null). Retrieval and excerpts can miss relevant facts. Fetch full sources for decisions. Split long documents into bounded sections and audit each section before upload. Latency and embedding work depend on query size and service load.

ParametersExpand Collapse

params: TrainingDataSearchParams { query, excludeIds, kinds, 2 more }

query: string

Body param: A passage, claim, or question to find existing knowledge for — for example one section of a document you are about to upload. Compared by meaning and by keywords.

minLength1

maxLength4000

excludeIds?: Array<string>

Body param: Q&A entry / training file IDs to leave out — typically the item you are about to update.

kinds?: Array<"qna" | "training_file" | "help_center_article">

Body param: Restrict to some kinds of knowledge. Default: all three (Q&A entries, training files, live help-center articles).

One of the following:

"qna"

"training_file"

"help_center_article"

topK?: number

Body param: How many items to return (1–20).

minimum1

maximum20

featurebaseVersion?: "2026-08-19.orbit" | "2026-01-01.nova" | "2025-12-12.clover"

Header param: API version for this request. Defaults to your organization’s configured API version if not specified.

One of the following:

"2026-08-19.orbit"

"2026-01-01.nova"

"2025-12-12.clover"

ReturnsExpand Collapse

KnowledgeSearch { candidates, object, query, timings }

candidates: Array<KnowledgeMatchCandidate { id, externalId, kind, 8 more } >

Existing items closest to the query, best first, at most topK. text is an excerpt focused on the query; section is the heading path inside a file when known.

id: string

ID of the existing item

externalId: string | null

The item’s source identity, for training files and Q&A

kind: "qna" | "training_file" | "help_center_article"

What kind of knowledge item matched: a Q&A entry, a training file / crawled page, or a live help-center article.

One of the following:

"qna"

"training_file"

"help_center_article"

questions: Array<string> | null

Question variants, for Q&A entries

revision: number | null

Q&A revision compared by the judge; null for other kinds. Use with PATCH expectedRevision.

section: string | null

Heading breadcrumb of the matching section, for training files

similarity: number | null

Cosine similarity between the query and item. Calibrate any threshold using representative examples; it is not a correctness or contradiction score. null when the item was found by keywords only. Arrays are already ordered closest first.

source: string | null

The item’s source label, for Q&A entries and training files

text: string

Excerpt of the existing content the judge compared against (Q&A answer, matching document section, or article body), up to 1200 characters plus an ellipsis when cut.

title: string

Title of the existing item

url: string | null

Public URL of the item when it has one

object: "knowledge_search"

Object type identifier

query: string

The query as searched (trimmed)

timings: Timings { retrievalMs }

Where the time went

retrievalMs: number

Time spent searching and loading the items

Search existing knowledge for a passage

import Featurebase from 'featurebase-node';

const client = new Featurebase({
  apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted
});

const knowledgeSearch = await client.trainingData.search({
  query: 'Refunds are processed within 14 days of the request.',
});

console.log(knowledgeSearch.candidates);

{
  "candidates": [
    {
      "id": "67ec1234abcd5678ef901236",
      "externalId": null,
      "kind": "qna",
      "questions": [
        "How do I request a refund?"
      ],
      "revision": 1,
      "section": null,
      "similarity": 0.61,
      "source": null,
      "text": "You can request a refund within 30 days from **Settings → Billing**.",
      "title": "Refund requests",
      "url": null
    }
  ],
  "object": "knowledge_search",
  "query": "Refunds are processed within 14 days of the request.",
  "timings": {
    "retrievalMs": 690
  }
}

Returns Examples

{
  "candidates": [
    {
      "id": "67ec1234abcd5678ef901236",
      "externalId": null,
      "kind": "qna",
      "questions": [
        "How do I request a refund?"
      ],
      "revision": 1,
      "section": null,
      "similarity": 0.61,
      "source": null,
      "text": "You can request a refund within 30 days from **Settings → Billing**.",
      "title": "Refund requests",
      "url": null
    }
  ],
  "object": "knowledge_search",
  "query": "Refunds are processed within 14 days of the request.",
  "timings": {
    "retrievalMs": 690
  }
}