Training Data

Training data teaches the AI agent about your product beyond your public Help Center: training files (documents, policies, internal notes) and Q&A entries (question variants with the exact answer to give). Use these endpoints to keep that knowledge in sync from your own systems — for example, pushing resolved support conversations, internal runbooks, or SOP documents automatically.

Search existing knowledge for a passage

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

POST/v2/training_data/search

Ask what to do with a Q&A entry

client.trainingData.oracle(, ?): Oracle { action, candidates, checkTruncated, 7 more }

POST/v2/training_data/oracle

ModelsExpand Collapse

KnowledgeMatchCandidate { id, externalId, kind, 8 more }

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

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

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

Oracle { action, candidates, checkTruncated, 7 more }

action: "create" | "update_target" | "update_qna" | 4 more

Suggested next step. create: no overlap found in the checked candidates; verify the source before writing. update_target: an entry already carries one of these questions (existing) and should be updated with this content — use PATCH with expectedRevision from existing to bind the write to this check. update_qna: an existing Q&A entry already answers this with the same facts — merge into it (target) instead of adding a second one. review_qna / review_article / review_file: an existing item (target) contradicts this answer or the judge could not decide — a human should pick the right fact and fix the source. skip: the knowledge already exists (an article or file answers it, or the payload is identical to the entry that already carries the question); nothing to write.

One of the following:

"create"

"update_target"

"update_qna"

"review_qna"

"review_article"

"review_file"

"skip"

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

Retrieved items and the addressed entry (first when present), at most 10. Excerpts are partial evidence.

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

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

checkTruncated: boolean

A candidate or text budget limited verification (including clipped proposed answers or Q&A answers). This yields unclear unless a contradiction was already found. False does not mean the entire workspace was exhaustively checked.

existing: Existing | null

The Q&A entry addressed by externalId or a normalized question, including its checked revision, or null

id: string

Q&A entry ID

question: string

Matching question from your request, or its first question when addressed by externalId

revision: number

Revision of the addressed entry at check time. Use with PATCH expectedRevision.

judged: Array<Judged>

Per-candidate judge verdicts, in the order they were judged. Judging continues after agreement or uncertainty and stops on a contradiction. The addressed entry is always compared when its content changes. Only shortlisted candidates are judged, so this is usually shorter than candidates.

candidateId: string

ID of the judged candidate

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"

reason: string

The judge’s one-line explanation

verdict: "same_topic" | "contradicts" | "different" | "unclear"

The judge’s verdict for this candidate

One of the following:

"same_topic"

"contradicts"

"different"

"unclear"

object: "oracle"

Object type identifier

reason: string

One or two sentences explaining the action, from the judge when it ran

target: Target

The existing item the action refers to, with its excerpt; null for create / update_target. For a different verdict the closest miss is candidates[0].

timings: Timings { judgeCalls, judgeMs, retrievalMs }

Where the time went

judgeCalls: number

Number of judge calls made

judgeMs: number

Time spent in the judge

retrievalMs: number

Time spent searching

verdict: "same_topic" | "contradicts" | "different" | 2 more

How the closest existing item relates to the entry. same_topic: it answers the same customer question (the entry would be a duplicate, rewording, or updated version). contradicts: same question, incompatible facts. different: a different question, even if the wording overlaps. unclear: the judge could not decide. no_match: nothing similar was found.

One of the following:

"same_topic"

"contradicts"

"different"

"unclear"

"no_match"

Training DataFiles

List training files

client.trainingData.files.list(?, ?): CursorPage<TrainingFile { id, characterCount, contentHash, 15 more } >

GET/v2/training_data/files

Add a training file

client.trainingData.files.create(?, ?): TrainingFile { id, characterCount, contentHash, 15 more }

POST/v2/training_data/files

Get a training file

client.trainingData.files.retrieve(, ?, ?): TrainingFile { id, characterCount, contentHash, 15 more }

GET/v2/training_data/files/{id}

Update a training file

client.trainingData.files.update(, , ?): TrainingFile { id, characterCount, contentHash, 15 more }

PATCH/v2/training_data/files/{id}

Delete a training file

client.trainingData.files.delete(, ?, ?): FileDeleteResponse { id, deleted, object }

DELETE/v2/training_data/files/{id}

ModelsExpand Collapse

TrainingFile { id, characterCount, contentHash, 15 more }

id: string

Training file ID

characterCount: number | null

Characters of extracted text

contentHash: string | null

SHA-256 (hex) of the stored source: for inline text and content edits the trimmed text, for uploads and URLs the original bytes. Compare it with your own hash to detect changes without downloading content.

contentPreview: string | null

First 200 characters of the extracted text

createdAt: string

ISO timestamp of the upload

externalId: string | null

Your own identifier for this file, if one was set

fileSize: number | null

Size of the originally uploaded source in bytes (unchanged by content edits)

indexStatus: "pending" | "indexed" | "failed"

Whether the content is searchable by the AI agent. pending while indexing, indexed when the AI agent can use it, failed if indexing failed (the content is stored and indexing is retried hourly).

One of the following:

"pending"

"indexed"

"failed"

mimeType: string | null

MIME type of the originally uploaded source

name: string

File name shown in the dashboard

object: "training_file"

Object type identifier

processingError: string | null

Conversion error message when status is failed

source: string | null

Pipeline label, if one was set

status: "processing" | "completed" | "failed"

processing while the file is being converted to text, completed once the content is stored, failed if conversion failed (see processingError).

One of the following:

"processing"

"completed"

"failed"

updatedAt: string

ISO timestamp of the last change

wordCount: number | null

Words of extracted text

content?: string | null

Full extracted text (markdown). Returned when retrieving or updating a single file; omitted from list and create responses.

outcome?: "created" | "updated" | "unchanged"

On create and update responses: created, updated (same externalId or same name and bytes, content replaced and re-indexed), or unchanged (identical content, nothing done). Absent on reads.

One of the following:

"created"

"updated"

"unchanged"

FileDeleteResponse { id, deleted, object }

id: string

ID of the deleted training file

deleted: true

Indicates the resource was deleted

object: "training_file"

Object type identifier

Training DataQna

List Q&A entries

client.trainingData.qna.list(?, ?): CursorPage<Qna { id, answer, createdAt, 10 more } >

GET/v2/training_data/qna

Create a Q&A entry

client.trainingData.qna.create(, ?): Qna { id, answer, createdAt, 10 more }

POST/v2/training_data/qna

Get a Q&A entry

client.trainingData.qna.retrieve(, ?, ?): Qna { id, answer, createdAt, 10 more }

GET/v2/training_data/qna/{id}

Update a Q&A entry

client.trainingData.qna.update(, , ?): Qna { id, answer, createdAt, 10 more }

PATCH/v2/training_data/qna/{id}

Delete a Q&A entry

client.trainingData.qna.delete(, ?, ?): QnaDeleteResponse { id, deleted, object }

DELETE/v2/training_data/qna/{id}

ModelsExpand Collapse

Qna { id, answer, createdAt, 10 more }

id: string

Q&A entry ID

answer: string

The answer the AI agent gives (markdown)

createdAt: string

ISO timestamp of creation

externalId: string | null

Stable identifier supplied by the source system

indexStatus: "pending" | "indexed" | "failed"

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.

One of the following:

"pending"

"indexed"

"failed"

object: "qna"

Object type identifier

questions: Array<string>

Question variants the answer applies to

revision: number

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

source: string | null

Pipeline label, if one was set

title: string

Short label for the entry

updatedAt: string

ISO timestamp of the last change

match?: Match | 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.

entry: Entry | null

The existing item the verdict is about, or null when nothing was close

id: string

ID of the item (Q&A entry, training file, or article)

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"

section: string | null

Heading breadcrumb of the matching section, for training files

similarity: number | null

Cosine similarity between your entry and the item (0–1); null for a keyword-only hit

title: string

Title of the item

url: string | null

Public URL of the item when it has one (articles, crawled pages)

reason: string | null

The judge’s one-line explanation of the verdict

verdict: "same_topic" | "contradicts" | "different" | 2 more

One of the following:

"same_topic"

"contradicts"

"different"

"unclear"

"no_match"

outcome?: "created" | "updated" | "unchanged"

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.

One of the following:

"created"

"updated"

"unchanged"

QnaDeleteResponse { id, deleted, object }

id: string

ID of the deleted Q&A entry

deleted: true

Indicates the resource was deleted

object: "qna"

Object type identifier