Skip to main content
POST
Search

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request body model for the /search endpoint.

query
string
required

Search query string

Minimum string length: 1
content_type
string[] | null

Filter by content type (only supported with focus=general). Supports semantic groups ('documents', 'spreadsheets', 'presentations') and specific formats ('pdf', 'docx', 'xlsx', etc.)

country
string
default:US

Country code for geo-targeted results (e.g., 'US', 'GB', 'IL')

deep_search
boolean | null

Deprecated. Use search_depth instead. true maps to 'deep', false maps to 'lite'.

end_date
string | null

Filter results before this date (format: YYYY-MM-DD or YYYY)

exclude_domains
string[] | null

List of domains to exclude from search results. Maximum 50 domains.

Maximum array length: 50
focus
default:general

Search focus mode (e.g., 'general', 'news', 'shopping') or a list of explicit subagent names (e.g., ['amazon_serp', 'target_serp'])

include_domains
string[] | null

List of domains to include in search results. Maximum 50 domains.

Maximum array length: 50
locale
string
default:en

Language/locale code (e.g., 'en', 'fr', 'de')

max_results
integer
default:10

Maximum number of results to return. Actual count may be lower depending on availability.

Required range: 1 <= x <= 100
max_subagents
integer
default:3

Maximum number of subagents to execute in parallel for WSA focus modes (shopping, social, geo). Ignored for SERP focus modes.

Required range: 1 <= x <= 10
output_format
enum<string>
default:markdown

Output format: plain_text, markdown, or simplified_html

Available options:
plain_text,
markdown,
simplified_html
search_depth
enum<string> | null

Content richness: 'lite' (metadata only), 'fast' (rich content at lower latency), 'deep' (full page scraping).

Available options:
lite,
fast,
deep
start_date
string | null

Filter results after this date (format: YYYY-MM-DD or YYYY)

time_range
enum<string> | null

Filter by recency: hour, day, week, month, or year. Cannot be combined with start_date/end_date.

Available options:
hour,
day,
week,
month,
year

Response

200 - application/json

Successful Response

Response model from SearchService with results.

Note: request_id is always a valid UUID generated internally by the middleware, so no validation is needed.

request_id
string
required

Unique identifier for this request (UUID)

results
ResultModel · object[]
required
total_results
integer
required

Number of results returned

serp_data
Serp Data · object | null

Cleaned SERP entities (e.g. KnowledgeGraph, TopStory, RelatedSearch). Only present for focus='serp'.