Training Data

Create a Q&A entry

Creates or updates question variants and an answer. Optional externalId is a stable, caller-owned key, unique within workspace Q&A. Otherwise a normalized question addresses an existing entry. POST appends variants (maximum 50) and replaces supplied content; PATCH replaces the question list. Questions cannot belong to multiple entries: ambiguous ownership returns 409 question_already_used. New entries return 201; updates and no-ops return 200. Responses include externalId, revision, and indexStatus. Indexing is attempted before returning; verify indexStatus rather than assuming HTTP success means searchable.

POST

/v2/training_data/qna

Create a Q&A entry

curl --request POST \
  --url https://do.featurebase.app/v2/training_data/qna \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "answer": "You can request a refund within 30 days from **Settings → Billing**.",
  "answerFormat": "markdown",
  "externalId": "kb-article-1842",
  "onMatch": "reject",
  "questions": [
    "How do I request a refund?",
    "Can I get my money back?"
  ],
  "source": "resolved-conversations",
  "title": "Refund requests"
}
'

{
  "answer": "You can request a refund within 30 days from **Settings → Billing**.",
  "createdAt": "2026-09-03T10:15:00.000Z",
  "externalId": "resolution-1842",
  "id": "67ec1234abcd5678ef901235",
  "indexStatus": "indexed",
  "match": {
    "entry": {
      "id": "67ec1234abcd5678ef901236",
      "kind": "qna",
      "section": null,
      "similarity": 0.61,
      "title": "Refund requests",
      "url": null
    },
    "reason": "Both answer how to request a refund; the new entry adds the 30-day window.",
    "verdict": "same_topic"
  },
  "object": "qna",
  "outcome": "created",
  "questions": [
    "How do I request a refund?",
    "Can I get my money back?"
  ],
  "revision": 1,
  "source": "resolved-conversations",
  "title": "Refund requests",
  "updatedAt": "2026-09-03T10:15:30.000Z"
}

Writes omit semantic checks by default. Optional onMatch runs a bounded check against the addressed entry and retrieved knowledge: reject refuses overlap; update explicitly permits answer replacement, including contradictions, but refuses unclear results; create explicitly overrides the check. Without an addressed entry, update can merge a matching Q&A, subject to source ownership. Articles and files are never edited. Check failures return 503 before writing. This is not a transaction over the knowledge base: other entries can change concurrently. After a separate oracle call, use PATCH with the checked expectedRevision; stale writes return 409 revision_conflict.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Example: 2026-08-19.orbit

Body

answerstringrequired

The answer the AI agent should give

Required string length: 1 - 100000

Example: You can request a refund within 30 days from **Settings → Billing**.

answerFormatenum<string>default:markdown

Format of answer. markdown (default) is stored as-is; html is converted to markdown.

Available options: markdown, html

Example: markdown

externalIdstring

Your own identifier for this entry (unique per workspace). When provided, the request creates the entry if the ID is new and otherwise updates the existing entry in place — an unchanged payload is a no-op. Use it to keep the AI agent in sync with a system of record without tracking Featurebase IDs.

Required string length: 1 - 255

Example: kb-article-1842

onMatchenum<string>

Optional inline knowledge check. Omit it (the default) and the entry is written immediately without consulting existing knowledge — ask POST /v2/training_data/oracle first when you want a suggestion. Pass it to run the same check as the oracle inside this request and act on the result (this is not a transaction over the knowledge base): reject: respond 409 conflicts_with_existing describing the match and write nothing. update: when an entry already carries one of your questions, write to that entry and report the match; otherwise, if the match is another Q&A entry, merge into it (question variants appended, answer replaced); an article or file is never edited — the entry is written as requested and the match reported. create: write as requested and report the match. unclear is treated as reject for update. With onMatch set, the request fails with 503 knowledge_check_unavailable instead of writing when the check cannot run.

Available options: reject, update, create

Example: reject

questionsstring[]required

Question variants this answer applies to (1–50). Phrase them the way customers ask.

Required array length: 1 - 50

sourcestring

Free-form label for the pipeline or system this entry came from. Filter lists by it to review or sweep everything from one source.

Required string length: 1 - 100

Example: resolved-conversations

titlestring

Short label for the entry. Optional: a new entry defaults to its first question; an existing entry keeps its title when omitted.

Required string length: 1 - 500

Example: Refund requests

Response

Created

answerstringrequired

The answer the AI agent gives (markdown)

Example: You can request a refund within 30 days from **Settings → Billing**.

createdAtstringrequired

ISO timestamp of creation

Example: 2026-09-03T10:15:00.000Z

externalIdstring | nullrequired

Stable identifier supplied by the source system

Example: resolution-1842

idstringrequired

Q&A entry ID

Example: 67ec1234abcd5678ef901235

indexStatusenum<string>required

Whether the entry is searchable by the AI agent. failed entries are stored and indexing is retried hourly up to three times. Re-send the resource to retry after exhaustion.

Available options: pending, indexed, failed

Example: indexed

matchobject | null

Present only when onMatch was passed and the check ran: the verdict and the closest existing item, even when the write went ahead. null otherwise (the default), including when the payload was unchanged.

Show child attributes

objectenum<string>required

Object type identifier

Available options: qna

Example: qna

outcomeenum<string>

What the write did — present on create and update responses. created: a new entry. updated: an entry already carried one of the questions (or was merged into with onMatch: "update") and got new content or an indexing retry. unchanged: everything in the payload was already on that entry; nothing written, nothing re-indexed.

Available options: created, updated, unchanged

Example: created

questionsstring[]required

Question variants the answer applies to

revisionintegerrequired

Q&A revision. Send it as expectedRevision on PATCH to reject stale changes.

Example: 1

sourcestring | nullrequired

Pipeline label, if one was set

Example: resolved-conversations

titlestringrequired

Short label for the entry

Example: Refund requests

updatedAtstringrequired

ISO timestamp of the last change

Example: 2026-09-03T10:15:30.000Z

Still need help? Ask the team