Skip to main content
POST
Semantic search

Authorizations

Authorization
string
header
required

API Key authentication using Bearer token. Example: "Authorization: Bearer {apiKey}"

Body

question
null | string
required

Natural-language search question.

output_format
null | enum<string>

Optional success projection. Omit to return both obj and rendered; use json for obj only; use agentic for rendered text only. Repairable errors always return both obj.error and rendered.

Available options:
json,
agentic
data_sources
null | string[]

Repository or workspace names returned by get_data_sources. Omit only when the API key has a single unambiguous scope.

paths
null | string[]

Optional repository-relative path prefixes to include.

extensions
null | string[]

Optional file extensions to include, for example cs, ts, or py.

max_results
null | integer<int32>

Optional maximum number of search results.

exclude_markdown
null | boolean

Exclude Markdown files from search results. Default is false.

Response

Success envelope. obj is the result set: results[] with identifier, kind, dataSource, location.path plus line range, relevance score, and a short description/snippet; rendered is a <semantic_search_results> XML block with a follow-up hint. Repairable failures (missing or invalid arguments, ambiguous or unknown data sources) also return HTTP 200 with obj.error = { code, message, retry, try } and a rendered <tool_error> block; repair the arguments and retry.

obj
any

Arbitrary JSON result for the tool. Present for omitted/json success projections and every repairable error.

rendered
null | string

Agent-facing result text. Present for omitted/agentic success projections and every repairable error.