Skip to main content
POST

Overview

Generate AI-powered answers to questions with two modes: Search Mode (with namespace) and Direct AI Mode (empty namespace). The API supports context-aware generation using your data or direct AI model calls.
Supports multiple AI models including Claude Sonnet 4.6, Claude Opus 4.6, Llama 4 Maverick, Amazon Nova Pro, DeepSeek, Qwen, and others. Use empty string "" as namespace for direct AI calls.

Authentication

x-api-key
string
required
Your API key for authentication
Content-Type
string
required
Must be application/json

Body Parameters

query
string
required
The user’s question or query to be answered
namespace
string
required
Namespace name for Search Mode, or empty string "" for Direct AI Mode
top_k
number
Number of top relevant chunks for your query across given namespace. Default is 10.
threshold
number
Minimum relevance score threshold (0-1) to filter out chunks below this relevance level. Required when kiosk_mode is true.
temperature
number
AI creativity level (0.0-2.0, default: 0.7). Higher = more creative
type
string
Search type: “text” (default)
ai_model
string
AI model ID (see Available Models table below)
kiosk_mode
boolean
Enable kiosk mode to filter chunks below certain relevance. When kiosk mode is on, threshold is required.
chat_history
array
Previous conversation turns for context (default: [])
header_prompt
string
Custom instruction for AI behavior
Custom instruction to append (default: “Provide a clear and concise answer.”)
structured_response
object
When set with enabled: true, the API returns a JSON object in structured_data matching a schema (default or custom). Optional: schema, tool_name, tool_description. Schemas may use snake_case property names; the service normalizes them for Bedrock. See Structured Output below.
Use snake_case fields in requests and responses only. Legacy camelCase aliases were removed in platform version 1.5.10 (May 2026). If you still send camelCase field names, update your integration to snake_case.

Available Models

Field Restrictions

Empty Namespace Mode: Only these fields are allowed: namespace, query, temperature, chat_history, footer_prompt, header_prompt, ai_model, structured_responseProvided Namespace Mode: All fields are allowed: namespace, query, top_k, threshold, type, kiosk_mode, ai_model, chat_history, header_prompt, footer_prompt, temperature, structured_response

Response Fields

answer
string
The AI-generated answer based on the provided context and query
model
string
The ID of the AI model used to generate the answer
context_count
number
Number of context chunks retrieved and used for generating the answer
query
string
The original query that was submitted
used_context
boolean
When structured output is enabled: whether retrieved context was used (RAG vs Direct AI). Omitted when structured_response is not used.
structured_data
object
When structured_response.enabled is true: the JSON object matching your schema (or the default). Contains e.g. answer, confidence, sources, summary, topics, follow_up_questions. Omitted otherwise. Property names follow your schema; the default schema uses snake_case (e.g. follow_up_questions).

Structured Output

Include structured_response: { enabled: true } in the request to get a type-safe JSON object in structured_data instead of (or in addition to) the plain answer string. Works in both Search Mode and Direct AI Mode. Custom schema objects may use snake_case keys; they are normalized for Bedrock (camelCase) internally.

Enabling

With only enabled: true, the default schema is used.

structured_response fields

Default schema

If schema is omitted or null, the default schema is used:
  • Required: answer, confidence
  • Optional: sources, summary, topics, follow_up_questions

Custom schema

Pass your own JSON Schema in structured_response.schema. Use type, properties, required, items, enum, minimum, maximum, maxLength, etc. Keep required minimal so the model can fill all fields.

Structured output errors

API Modes

Search Mode (with namespace)

When you provide a namespace, the API searches your data for relevant context and uses it to generate contextual answers.

Direct AI Mode (empty namespace)

When you pass an empty string "" as namespace, the API makes a direct call to the AI model without searching your data.

Temperature Guide

  • 0.0-0.5: Conservative, factual responses - best for technical documentation
  • 0.5-1.0: Balanced creativity - good for general Q&A
  • 1.0-2.0: More creative and varied responses - use carefully for factual content

Relevance Score Threshold

Results are scored using Information Theoretic Similarity (ITS), providing nuanced relevance measurements:

Important Notes

  • Search Mode: The namespace must exist and contain indexed data for meaningful results
  • Search Mode: Higher top_k values provide more context but may increase response time
  • Search Mode: The threshold parameter can be used to filter low-relevance results
  • Direct AI Mode: Use empty string "" as namespace for direct AI model calls
  • Field Restrictions: Empty namespace mode only allows basic AI fields, not search-specific fields
  • Field Restrictions: Provided namespace mode allows all fields including search parameters
  • Chat history enables conversational context across multiple queries
  • Custom prompts allow fine-tuning of AI behavior and response format
  • Temperature controls creativity: 0.0 for deterministic, 2.0 for highly creative responses
  • Failed requests still count towards usage limits and are tracked in statistics
  • Some models may have different token limits and capabilities

Use Cases

  • Customer Support: Answer customer questions using your documentation
  • Internal Q&A: Help employees find answers in company knowledge bases
  • Educational Tools: Create AI tutors using educational content
  • Research Assistance: Get insights from research papers and publications
  • Technical Support: Provide technical answers based on documentation
  • Content Creation: Generate content based on existing materials