Search Result Summaries

This reference covers the AI-related search endpoints available on a Searchcraft index.

API Endpoint Reference

GET /index/:index/capabilities Returns AI capability flags for an index.
POST /index/:index/search/summary Streams an AI-generated summary of search results using server-sent events.

Capabilities Endpoint

Use the capabilities endpoint to determine whether an index has AI enabled and whether summary generation is configured.

The enabled flag reflects the index’s stored ai_enabled master switch. An index may still report searchSummaryConfigured: true while enabled: false if AI configuration has been saved but the master switch is currently turned off.

Authenticated requests to this endpoint require the READ permission.

Example capabilities request

curl -H "Authorization: read-key-value" https://searchcraft-cluster-url/index/data_test/capabilities

Example capabilities response

{
  "status": 200,
  "data": {
    "ai": {
      "enabled": true,
      "searchSummaryConfigured": true,
      "llmProviderConfigured": true,
      "llmModelConfigured": true
    }
  }
}

Search Summary Endpoint

The summary endpoint accepts the same request body shape as POST /index/:index/search. The payload is a standard Searchcraft query payload.

Authenticated requests to this endpoint require the LLM_RAG_SUMMARIES permission.

Summary responses are streamed as text/event-stream; charset=utf-8.

400 conditions

The endpoint returns 400 in the following situations. Use GET /index/:index/capabilities to check availability before calling the summary endpoint. See Optional AI configuration for how to configure these settings.

Condition	Message
`ai_enabled` is `false`	`AI features are disabled for this index`
No `ai` block configured	`AI features not configured for this index`
`ai` exists but no `search_summary` block	`Search summary not configured for this index`
Invalid `llm_provider` value	`Invalid LLM provider`

Example summary request

curl -N -H "Content-Type: application/json" -H "Authorization: read-key-value" --data '{"query":"wireless headphones","limit":5}' https://searchcraft-cluster-url/index/data_test/search/summary

Example event stream

event: metadata
data: {"results_count":3,"cached":false}

event: delta
data: {"content":"Top options include..."}

event: done
data: {"results_count":3}

Event types

Event	Payload	Description
`metadata`	`{"results_count": number, "cached": boolean}`	Always the first event. `results_count` is the number of search hits found. `cached` is `true` when both the search results and the generated summary were served from cache.
`delta`	`{"content": string}`	One or more delta events containing the streamed summary text. When there are zero results, a single delta is emitted with the configured `empty_state_message` instead of calling the LLM.
`done`	`{"results_count": number}`	Final event indicating the stream has completed.
`error`	`{"message": string}`	Emitted if a streaming error occurs.

Zero results behaviour

When a search query returns no hits, the LLM is not called. Instead, the endpoint immediately emits a delta event containing the empty_state_message configured on the index, with the ${searchTopic} placeholder substituted for the matched search term. If a matching keyword rule provides its own empty_state_message, that takes precedence over the index-level default.

Structured Query Support

The summary endpoint supports the same structured queries as the standard search endpoint.

curl -N -H "Content-Type: application/json" -H "Authorization: read-key-value" --data '{"query":[{"dynamic":{"ctx":"gaming laptop"}},{"term":{"ctx":"Asus","fields":"brand"}}],"limit":5}' https://searchcraft-cluster-url/index/data_test/search/summary

When keyword rules are configured, Searchcraft derives human-readable match text from supported query fragments including fuzzy, exact, dynamic queries.

Keyword Rules

Keyword rules are configured on the index declaration under ai.search_summary.keyword_rules. See Optional AI configuration for the full rule schema.

Rules are sorted by order and evaluated in that order. The first matching rule wins and no further rules are evaluated.

Matching behaviour

A rule matches when any keyword in its detect_keywords array is found in the search term. Matching is case-insensitive and substring-based, so a keyword of "nutrition" would also match a query like "malnutrition".

Rule fields

Field	Description
`replacement_term`	When set, replaces the search term submitted to the search engine and used as the topic in the LLM prompt. The original search term is preserved only for display purposes.
`custom_instruction`	Appended to the index-level `additional_prompt_instructions` when the rule matches.
`empty_state_message`	Overrides the index-level `empty_state_message` when the rule matches and the search returns no results. Supports `${searchTopic}` placeholder replacement.

Supported LLM Providers

The summary endpoint works with any LLM provider configured on the index. Supported providers are:

Provider	`llm_provider` value	Credential
AWS Bedrock	`bedrock`	AWS SDK credential chain (`llm_region` required)
llama.cpp	`llamacpp`	None (`llm_base_url` required)
Ollama	`ollama`	None
OpenAI	`openai`	`llm_api_key`
Anthropic	`anthropic`	`llm_api_key`
Google Gemini	`google`	`llm_api_key`
xAI (Grok)	`xai`	`llm_api_key`
Mistral AI	`mistral`	`llm_api_key`

See Optional AI configuration for full configuration examples and field descriptions.