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
Ask what to do with a Q&A entry
ModelsExpand Collapse
KnowledgeMatchCandidate object { id, externalId, kind, 8 more }
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.
What kind of knowledge item matched: a Q&A entry, a training file / crawled page, or a live help-center article.
Q&A revision compared by the judge; null for other kinds. Use with PATCH expectedRevision.
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.
KnowledgeSearch object { candidates, object, query, timings }
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.
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.
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.
What kind of knowledge item matched: a Q&A entry, a training file / crawled page, or a live help-center article.
Q&A revision compared by the judge; null for other kinds. Use with PATCH expectedRevision.
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.
Oracle object { action, candidates, checkTruncated, 7 more }
action: "create" or "update_target" or "update_qna" or 4 moreSuggested 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.
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.
Retrieved items and the addressed entry (first when present), at most 10. Excerpts are partial evidence.
Retrieved items and the addressed entry (first when present), at most 10. Excerpts are partial evidence.
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.
What kind of knowledge item matched: a Q&A entry, a training file / crawled page, or a live help-center article.
Q&A revision compared by the judge; null for other kinds. Use with PATCH expectedRevision.
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.
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: object { id, question, revision } The Q&A entry addressed by externalId or a normalized question, including its checked revision, or null
The Q&A entry addressed by externalId or a normalized question, including its checked revision, or null
judged: array of object { candidateId, kind, reason, verdict } 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.
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.
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].
verdict: "same_topic" or "contradicts" or "different" or 2 moreHow 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.
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.
Training DataFiles
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.
List training files
Add a training file
Get a training file
Update a training file
Delete a training file
ModelsExpand Collapse
TrainingFile object { id, characterCount, contentHash, 15 more }
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.
indexStatus: "pending" or "indexed" or "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).
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).
status: "processing" or "completed" or "failed"processing while the file is being converted to text, completed once the content is stored, failed if conversion failed (see processingError).
processing while the file is being converted to text, completed once the content is stored, failed if conversion failed (see processingError).
Training DataQna
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.
List Q&A entries
Create a Q&A entry
Get a Q&A entry
Update a Q&A entry
Delete a Q&A entry
ModelsExpand Collapse
Qna object { id, answer, createdAt, 10 more }
indexStatus: "pending" or "indexed" or "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.
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.
match: optional object { entry, reason, verdict } 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.
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: object { id, kind, section, 3 more } The existing item the verdict is about, or null when nothing was close
The existing item the verdict is about, or null when nothing was close
verdict: "same_topic" or "contradicts" or "different" or 2 moreHow 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.
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.
outcome: optional "created" or "updated" or "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.
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.