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/projects/:projectId/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
`group_ids`	`string[]`	No	Scope retrieval to source groups; intersected with the key’s `allowed_groups` (403 if outside the project or allowed set)

curl https://api.agents.beforequery.com/api/v1/public/projects/proj_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"
}

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

How confidence is computed

Confidence derives from the top-3 RRF retrieval scores (normalised to [0, 1]), with a bonus for a strong single-chunk signal and a penalty when the LLM signals it could not find an answer in the documentation.

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.

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