## Search existing knowledge for a passage

`client.trainingData.search(TrainingDataSearchParamsparams, RequestOptionsoptions?): KnowledgeSearch`

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

### Parameters

- `params: TrainingDataSearchParams`

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

  - `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).

    - `"qna"`

    - `"training_file"`

    - `"help_center_article"`

  - `topK?: number`

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

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

    - `"2026-08-19.orbit"`

    - `"2026-01-01.nova"`

    - `"2025-12-12.clover"`

### Returns

- `KnowledgeSearch`

  - `candidates: Array<KnowledgeMatchCandidate>`

    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.

      - `"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

    - `"knowledge_search"`

  - `query: string`

    The query as searched (trimmed)

  - `timings: Timings`

    Where the time went

    - `retrievalMs: number`

      Time spent searching and loading the items

### Example

```typescript
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);
```

#### Response

```json
{
  "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
  }
}
```