Search existing knowledge for a passage

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.

Header ParametersExpand Collapse

"Featurebase-Version": optional "2026-08-19.orbit" or "2026-01-01.nova" or "2025-12-12.clover"

One of the following:

"2026-08-19.orbit"

"2026-01-01.nova"

"2025-12-12.clover"

Body ParametersJSONExpand Collapse

query: string

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: optional array of string

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

kinds: optional array of "qna" or "training_file" or "help_center_article"

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: optional number

How many items to return (1–20).

minimum1

maximum20

ReturnsExpand Collapse

KnowledgeSearch object { candidates, object, query, timings }

candidates: array of 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

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

kind: "qna" or "training_file" or "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 of string

Question variants, for Q&A entries

revision: number

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

section: string

Heading breadcrumb of the matching section, for training files

similarity: number

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

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

Public URL of the item when it has one

object: "knowledge_search"

Object type identifier

query: string

The query as searched (trimmed)

timings: object { retrievalMs }

Where the time went

retrievalMs: number

Time spent searching and loading the items

Search existing knowledge for a passage

curl https://do.featurebase.app/v2/training_data/search \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $FEATUREBASE_API_KEY" \
    -d '{
          "query": "Refunds are processed within 14 days of the request.",
          "excludeIds": [
            "67ec1234abcd5678ef901235"
          ],
          "kinds": [
            "help_center_article",
            "qna"
          ],
          "topK": 8
        }'

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