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.

Headers

X-Session-ID
string

Optional client session identifier.

Body

application/json
query
string
required

The search query, phrased as the user or agent would ask it. Drives ranking and passage selection even when search_queries supplies a rewrite.

Minimum string length: 1
Example:

"linux kernel amd gpu suspend"

client_model
string

Calling model identifier, recorded for analytics and ranking tuning.

filters
object

Structured filters. Keys: country (two-letter code such as 'us' or 'de', scoping results to a market), language (two-letter code such as 'en'), exact_match (boolean; quotes the query so the index matches it verbatim).

freshness_policy
object

Recency requirements. Keys: published_after (RFC 3339 timestamp or YYYY-MM-DD date; only content published after it) and freshness (coarse window code pd, pw, pm, or py for past day, week, month, or year; ignored when published_after is set).

max_results
integer<int64>
default:10

Maximum number of ranked results to return. The response carries fewer when the index has fewer matches.

Required range: 1 <= x <= 50
response
object

Optional response shaping: verbosity preset and serialized-size budget.

scope
object

Which indexes to search. Omit it for the web index. Additive: existing clients are unaffected.

search_queries
string[] | null

Caller-provided query rewrites. The first entry replaces query as the text sent to the search index; query still drives reranking and passage selection. All entries are visible to the server-side query rewriter.

session_id
string<uuid>

Client session identifier (UUID). Groups related search, document, and feedback calls; equivalent to the X-Session-ID header. When omitted, the server generates one and echoes it back as session_id.

source_policy
object

Domain allow/deny policy. Keys: include_domains (array of domains; with require_domain_match true, results outside them are dropped, and a single entry is also sent to the index as a site: operator), exclude_domains (array of domains whose results are always dropped), require_domain_match (boolean). Domains match their subdomains; a leading www. is ignored.

Response

Search results.

request_id
string
required
results
object[] | null
required
search_id
string
required
session_id
string
required
$schema
string<uri>
read-only

A URL to the JSON Schema for this object.

Example:

"https://alpha.api.trycaesar.com/SearchResponse.json"

access
object
integration_results
object
ranking
object
truncated
boolean
usage
object
warnings
object[] | null