Skip to main content
POST
/
search
/
api
/
v1
/
search
/
session
Open a conversational search session
curl --request POST \
  --url https://www.closient.com/search/api/v1/search/session \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "latitude": 0,
  "longitude": 0
}
'
{
  "session_id": "<string>",
  "base_query": "<string>",
  "active_constraints": {},
  "search_history": [
    "<string>"
  ],
  "is_expired": true,
  "latitude": 0,
  "longitude": 0
}

Body

application/json

Payload for opening a new conversational search session.

The initial query seeds the session — its extracted constraints become the starting filter set, and the verbatim text is stored as base_query so follow-up refinements have an anchor. Latitude / longitude fix the geographic origin used for distance-based ranking on every subsequent query in the session.

​
query
string
required

Initial natural-language search query. May contain freeform intent ("birthday gift ideas") or pre-extractable constraints ("red shoes under $50 within 5km"). The refinement extractor parses color, price, distance, availability, and scope on creation.

Required string length: 1 - 500
​
latitude
number
required

User latitude in WGS84 decimal degrees. Used for distance-based ranking and the distance_km constraint. Stored once per session — follow-up queries inherit it.

Required range: -90 <= x <= 90
​
longitude
number
required

User longitude in WGS84 decimal degrees. See latitude.

Required range: -180 <= x <= 180

Response

OK

Response schema for the current state of a search session.

Returned by POST /search/session and DELETE /search/session/{session_id}/constraints/{key}. Reflects the session's full filter state plus the geographic anchor.

​
session_id
string
required

URL-safe session identifier (~32 chars). Use this in the path of every follow-up call (/search/session/{session_id}/...).

​
base_query
string
required

The anchor query for this session. Set on session creation and replaced whenever a follow-up is classified as a new search.

​
active_constraints
Active Constraints · object
required

Current filter state. Keys are members of ConstraintKeyEnum:

Scalar constraints — set replaces:

  • color (string), price_max / price_min (float), distance_km (float), availability (string), scope (string).

Trait-based constraints — list-of-slug, set unions additively across successive refinements (C-2385):

  • exclude_allergens — allergen slugs to drop (peanuts, tree_nuts, dairy, eggs, soy, wheat, gluten, fish, shellfish, sesame, sulfites, mustard).
  • require_certifications — certification slugs that products must carry (vegan, vegetarian, kosher, halal, organic, non_gmo, gluten_free, fair_trade, cruelty_free, rainforest_alliance, usda_organic).
  • avoid_substances — substance slugs to drop (sucralose, aspartame, msg, high_fructose_corn_syrup, red_dye_40, carrageenan, bpa, parabens, phthalates).

Each constraint can be removed individually via DELETE /search/session/{session_id}/constraints/{key}.

​
search_history
string[]
required

Ordered list of every query submitted in this session, oldest first.

​
is_expired
boolean
required

true once the session has passed its 30-minute idle expiry. Expired sessions return 404 from query/constraint endpoints.

​
latitude
number
required

WGS84 latitude captured at session creation.

Required range: -90 <= x <= 90
​
longitude
number
required

WGS84 longitude captured at session creation.

Required range: -180 <= x <= 180