Skip to main content
POST
/
search
/
api
/
v1
/
search
/
session
/
{session_id}
/
query
Submit a follow-up query within a session
curl --request POST \
  --url https://www.closient.com/search/api/v1/search/session/{session_id}/query \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>"
}
'
{
  "session_id": "<string>",
  "is_refinement": true,
  "classification_explanation": "<string>",
  "active_constraints": {},
  "new_constraints": {},
  "base_query": "<string>",
  "query": "<string>",
  "search_history": [
    "<string>"
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.closient.com/llms.txt

Use this file to discover all available pages before exploring further.

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.