Smart Answers API

Updated May 04, 2026 12:52

The Smart Answers API returns answer content for user questions through streaming, JSON, and XML variants.

GET <Smart Answers Endpoint>?q=<question>

Authentication

Use token authentication with a read-only token and send it as Authorization: Token <read-only-token>. For complete token guidance, see Authentication and Authorization.

Note: A missing auth header returns 401 (`Solr Auth Token is required`). Some invalid-token or no-prefix scenarios can return HTTP 200 with payload-level success:false and error_message.

Query Parameters

The query string accepts the following parameters:

Parameter	Description
Authorization required header	Use `Authorization: Token <read-only-token>`.
q required string	User question prompt sent to Smart Answers.
language optional string	Optional language code used for answer retrieval context.
model optional string	Search Profile name used for the Smart Answers request. If you omit this parameter, the request uses `Main Profile`.
ignore_cache optional boolean	Optional boolean flag to bypass cached answers (`true` or `false`).

Note: Both dash and underscore language-code variants are accepted and normalized automatically, so use the language code your integration sends.

Endpoints

The Smart Answers API uses three distinct endpoints depending on your preferred output format.

Smart Answers Endpoint: Returns a data stream for real-time display on your search page. Find this endpoint on the Site Search > App Settings > All APIs > Search & Indexing screen.
JSON Endpoint: Append /json to the Smart Answers Endpoint to get the Smart Answers response as a JSON document.
XML Endpoint: Append /xml to the Smart Answers Endpoint to get the Smart Answers response as an XML document.

The JSON and XML endpoints return the full response at once instead of streaming it. These endpoints are available only through the Smart Answers API.

Streaming Endpoint

The default endpoint returns a streaming response with media type text/event-stream.

Streaming begins within two seconds after the query is sent.

If the query is a question, the stream returns I_AM_A_QUESTION followed by the answer.
If the query isn't a question, the stream returns I_AM_NOT_A_QUESTION.

Example

Here's a cURL example from a Bash or PowerShell command line:

curl -X GET \
  "https://search-ai-us.searchstax.com/api/v1/1234/answer/?q=What%20is%20solr&language=en&ignore_cache=true" \
  -H "authorization: Token <READ_ONLY_TOKEN>" \
  -H "Accept: text/event-stream"

The method returns a stream for real-time display on your search webpage. You'll see something like this in a Bash or PowerShell command window:

Terminal window displaying a curl GET request to the Smart Answers API endpoint with streaming response data showing parsed answer chunks.

JSON Endpoint

Here's a cURL example from a Bash or PowerShell command line:

curl 'https://search-ai-us-east.searchstax.com/api/v1/1234/answer/json/?q=what%20is%20site%20search&model=Main%20Profile&language=en' \
 -H 'accept: text/json' \
 -H 'authorization: Token <READ_ONLY_TOKEN>'

The JSON endpoint returns a structured response with this format:

{
 "success": true,
 "question": "what is site search?",
 "answer": "Site search refers to the functionality integrated into websites...",
 "processing_time": 16.48,
 "error_message": "Optional - only if there is an error"
}

Response Notes

JSON responses can include success, question, answer, processing_time, metadata, and error_message (when success:false).

When the request succeeds, answer contains the generated response text and processing_time shows how long the request took to complete. metadata can include presentation-related values used by UI components.

XML Endpoint

Here's how to call the XML endpoint:

curl 'https://search-ai-us-east.searchstax.com/api/v1/1234/answer/xml/?q=what%20is%20site%20search&model=Main%20Profile&language=en' \
  -H 'accept: text/xml' \
  -H 'authorization: Token <READ_ONLY_TOKEN>'

The XML endpoint returns a structured response with this format:

<SmartAnswer>
  <success>true</success>
  <question>what is site search??</question>
  <answer>**Site search** refers to the functionality integrated into websites...</answer>
  <processing_time>0.0018157958984375</processing_time>
</SmartAnswer>

HTTP Status Codes and Error Handling

HTTP Code	When It Happens	Typical Response Body	What to Do
`200`	Request succeeds. Some payload-level failures also return `200`.	JSON, XML, or stream payload. May include `success:false` and `error_message`.	Inspect payload success and error fields.
`401`	Missing auth header.	`{"detail":"Solr Auth Token is required"}`	Send token auth header.
`429`	Shared rate or plan limit condition.	Too-many-requests response.	Retry with backoff.

Note: Missing or invalid q can be represented as a payload-level error (success:false) at HTTP 200.

Pagination

Not applicable for Smart Answers responses. See Pagination for shared guidance across APIs that support paged result sets.

Rate Limits and Backoff

No Smart Answers-specific per-endpoint rate contract is documented. Follow shared app-level guidance and 429 handling in Service Limits.

Tip: Retry-After can be absent; apply client-side retry delays with backoff.

URL Requirements for Source Links

Smart Answers uses the document URL field stored in your search index; it doesn't generate or rewrite URLs. That means the field should store absolute URLs (protocol + domain), not relative paths (for example, /login).

If the indexed URL is relative, Smart Answers has no domain context. API consumers or widgets display a placeholder domain like https://example.com/login.

Fix: Update your CMS or indexing configuration to store absolute URLs, then reindex your content so the updated URLs are stored. For example, in Drupal, enable "Generate absolute URL" on the URL field and reindex. For more details, see Smart Answers.

Shared API Foundations

Use these shared references for authentication, request and response structure, and pagination behavior used across Site Search APIs:

Articles in this section