Form Deflect - BeforeQuery

Answer a support request before the ticket is filed. This endpoint runs a non-streaming RAG pass and returns an answer plus a confidence-based deflection decision.

POST https://api.agents.beforequery.com/api/v1/public/knowledge-bases/:knowledgeBaseId/form-deflect

Auth: client key.

Request body

Field	Type	Required	Description
`message`	`string`	Yes	The user’s question / ticket description
`subject`	`string`	No	Ticket subject line (adds context)
`thread_id`	`string`	No	Continue a prior deflection exchange
`deflector_id`	`string`	No	Run on a saved deflector’s settings — see below
`fields`	`{label,value}[]`	No	Other form fields to pass as context (max 12). Fenced into the prompt as material, never as instructions
`group_ids`	`string[]`	No	Scope retrieval to source groups; intersected with the key’s `allowed_groups` (403 if outside the knowledge base or allowed set)
`end_user_id`	`string`	No	An anonymous, browser-scoped reader id, so one person asking on two pages counts once
`end_user_email`	`string`	No	The address on the form, stored on the conversation only — purged with it, and dropped entirely for a zero-retention workspace. See user tracking

With a deflector_id, the request runs on that deflector’s stored confidence threshold, its own origin allowlist, and its configured source groups — none of which the calling page can widen. Without one it falls back to the package default, which is what pre-integration embeds send.

curl https://api.agents.beforequery.com/api/v1/public/knowledge-bases/kb_xxx/form-deflect \
  -H "X-Client-Key: bq_pk_..." \
  -H "Content-Type: application/json" \
  -d '{"subject": "Password reset", "message": "I cannot log in after changing my email"}'

Response

{
  "answer": "If you changed your account email, you need to ... [1]",
  "citations": [{ "index": 1, "url": "https://docs.example.com/account", "title": "Account Settings" }],
  "confidence": 0.82,
  "deflect": true,
  "conversation_id": "conv_uuid",
  "message_id": "msg_uuid",
  "deflection_id": "defl_uuid"
}

Field	Type	Description
`answer`	`string`	LLM-generated answer with `[N]` citation markers
`citations`	`Citation[]`	Same shape as chat citations
`confidence`	`float`	Retrieval-quality score in `[0, 1]`
`deflect`	`bool`	`true` when confidence ≥ threshold (default 0.55)
`conversation_id`	`string`	UUID of the persisted conversation, for analytics and follow-ups
`message_id`	`string`	The answer’s own message row. Present only when `deflect` is `true` — pass it to the feedback endpoint to rate the answer
`deflection_id`	`string`	This interception’s event ID — pass it back to report the outcome
`skip_reason`	`string`	Present when no answer was produced, saying why (for example, the question was shorter than the deflector’s minimum)
`handoff_link`	`string`	Present when the deflector is configured to offer an escalation link

Reporting the outcome

POST /api/v1/public/deflections/:deflection_id/outcome   {"outcome":"submitted"}

Send this when the user submits the ticket anyway. It’s the only signal worth sending: a user who read the answer and closed the tab is a success and reports nothing, so the deflection rate is computed as (answered − submitted) / answered. Answer quality is rated separately, through the same 👍/👎 feedback endpoint as every other surface — a deflection persists a conversation and messages like any other answer.

How confidence is computed

Confidence measures how well the retrieved passages actually answer this question, normalised so that 0.5 is the boundary between answerable and not however your deployment is configured. Three things override it:

An answer that declines (“I don’t have information about…”) drops below the boundary whatever the passages scored. A model saying it does not know is better evidence than any retrieval score.
A verdict that the corpus does not cover the question returns 0 — and the excerpts and citations are withheld from the model entirely, so it cannot assemble a plausible answer out of passages it was never given.
An answer whose claims are not supported by its own sources returns 0. Retrieval scoring cannot catch this: the passages can be right while the answer states a default value or a flag name that appears in none of them.

A check that could not run leaves the confidence alone. Failing every deflection closed on a provider outage trades one failure mode for a worse one.

Recommended client behavior

deflect: true → show the answer with a “That answered my question” dismissal and a “Continue to submit ticket” escape hatch.
deflect: false or request failure → submit the form normally. Never block the user.
Follow-up questions → call the chat endpoint with thread_id set to the returned conversation_id.
Rate the answer → POST /api/v1/public/feedback with the returned message_id. The deflection rate says a ticket was avoided and nothing about whether the answer was right.

Every exchange is logged as a deflection trace and surfaces in analytics. Prefer zero code? Use the drop-in form deflector script.

​Request body

​Response

​Reporting the outcome

​How confidence is computed

​Recommended client behavior

Request body

Response

Reporting the outcome

How confidence is computed

Recommended client behavior