POST /v2/indices/{index public key}/conversations/{conversation_id}/refine-query
Turn a question asked in an AI Conversation into a search term optimized for keyword search.
Questions in a conversation often depend on earlier messages. For example, “I want them in blue” makes sense after “I’m looking for men’s shoes,” but it may not return useful keyword search results on its own.
The Refine Query endpoint uses the conversation history to make the latest question clear on its own.
For example:
- Earlier question: “I’m looking for men’s shoes”
- Latest question: “I want them in blue”
- Refined query: men’s shoes blue
Use the returned Refine Query with the Search API to show related search results next to the conversational answer.
How it works
- The visitor asks a question.
- The AI Conversations endpoint returns the conversational answer and a
conversation_id. - Send the same question together with that
conversation_idto this endpoint. - The conversation history is looked up on the server and used as context.
- Send the returned
refined-queryvalue to the Search API. - Display the hits as related search results.
The context is built from the questions and answers of the conversation, up to the 20 most recent turns.
The returned value contains only search terms. It does not contain filters or other search parameters.
When starting the conversation, set ai_conversations to true. Otherwise, follow-up requests may fail.
Path parameters
| Parameter | Description | Type | Notes |
|---|---|---|---|
| index public key | The public SITEKEY | string | Identifies your AddSearch account. You can find it in the AddSearch Dashboard. |
| conversation_id | The id of the conversation used as context | string | Returned by the AI Conversations endpoint. It must be exactly 36 characters long. |
Request body parameters
| Parameter | Description | Type | Notes |
|---|---|---|---|
| question | The latest question of the conversation | string | Required. 500 characters or less, and cannot be empty. |
{
"question": "pricing info of addsearch"
}
Sample request
curl --request POST \
'https://api.addsearch.com/v2/indices/YOUR_SITEKEY/conversations/bf9e6055-59f7-42ac-8198-5bbc4e85b57b/refine-query' \
--header 'Content-Type: application/json' \
--data-raw '{
"question": "pricing info of addsearch"
}'
Response
{
"refined_query": "pricing info addsearch",
"errors": [],
"status": 200
}
| Field | Description | Type | Notes |
|---|---|---|---|
| refined_query | The search term derived from the latest question and the conversation history | string | Contains search terms only. Not present when the request fails. |
| errors | The problems found with the request | array | Empty on a successful request |
| status | The HTTP status code of the response | int |
Errors
When a request succeeds, errors is an empty array and status repeats the HTTP status code.
When a request fails, errors lists the problems found and refined-query is not returned.
Error responses do not always use the same format. The status field is also missing from some error responses. Use the HTTP status code as the primary indicator to check whether the request succeeded.
| Status | Meaning | Response body |
|---|---|---|
| 200 OK | The request succeeded | errors is an empty array |
| 400 Bad Request | The request body could not be parsed, or conversation_id is not 36 characters long | {"code": 400, "message": "Unable to process JSON"}, or an errors array describing the path parameter |
| 404 Not Found | No conversation exists for the given conversation_id | {"errors": ["Conversation not found"], "status": 404} |
| 405 Method Not Allowed | A method other than POST was used | {"code": 405, "message": "HTTP 405 Method Not Allowed"} |
| 422 Unprocessable Entity | The question is empty or longer than 500 characters | {"errors": ["question is too long"]} |
| 429 Too Many Requests | The rate limit was exceeded | Empty |
| 500 Internal Server Error | The request could not be processed. For example, a follow-up question sent to a conversation that was not started with ai_conversations set to true. | {"errors": [...], "status": 500} |
Because the refined query only provides an additional set of related results. Treat a failure as non-critical: fall back to the visitor’s original question so that related search results are still shown.
Rate limits
This endpoint is limited to 5 requests per second from one IP address. Requests exceeding the limit return a 429 Too Many Requests response with an empty body. If rejected, throttle concurrent requests in your client and retry after a short delay. See Rate limits for details.