Skip to main content
POST
Submit a follow-up query within a session

Path Parameters

session_id
string
required

The session identifier returned from POST /search/session.

Body

application/json

Payload for submitting a query within an existing session.

The classifier decides whether the query refines the current session or resets it as a new search; the body is the same shape either way. Phrasing matters: "but cheaper" reads as refinement, while "instead show me laptops" reads as a fresh search.

query
string
required

Follow-up or replacement query text. The server classifies it as either a refinement (constraints merge into the existing set) or a new search (constraints reset, base_query updates) based on phrasing signals and keyword overlap with the current base_query.

Required string length: 1 - 500

Response

OK

Response for POST /search/session/{session_id}/query.

Reports the classifier's verdict (refinement vs. new search), the constraint delta the extractor pulled out of the new query, and the merged session state. Clients typically render classification_explanation to the user as a chip ("Adding 'under $80' to your search") so the model's behavior is visible.

session_id
string
required

The session this query was applied to (echoed back).

is_refinement
boolean
required

true when the classifier merged new_constraints into the existing filter set; false when it reset the session and replaced base_query.

classification_explanation
string
required

Human-readable rationale for the refinement-vs-new-search verdict. Free-text — produced by the heuristic classifier (e.g. "Refinement language detected.", "Keyword overlap (45%) with base query."). Safe to surface to end users as a UI chip.

active_constraints
Active Constraints · object
required

Updated filter state after applying this query. See SessionOut.active_constraints.

new_constraints
New Constraints · object
required

Just the constraints the extractor pulled out of this query — useful for rendering 'Added X' feedback in the UI. Subset of the keys in active_constraints.

base_query
string
required

The session's current anchor query. Unchanged on refinements; replaced with the new query text on a new-search classification.

query
string
required

The query text just submitted (echoed back).

search_history
string[]
required

Updated history including this query, oldest first.