Semantic search
Searches indexed code by meaning rather than by exact text. This is the default first tool for behaviour, intent, mechanism, and architecture questions. Phrase question as a full natural-language English sentence — “How does task execution work?”, “Where is retry handling implemented?” — not as bare keywords; keyword strings sharply degrade recall. Keep identifiers and codebase-specific terms verbatim inside the sentence. For acronyms, exact names, error text, routes, or config keys, run grep_search alongside. Results carry stable artifact identifier values — pass them to fetch_artifacts to read the code, or to get_artifact_relationships to map callers and callees, before drawing conclusions from snippets.
Authorizations
API Key authentication using Bearer token. Example: "Authorization: Bearer {apiKey}"
Body
Natural-language search question.
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.
json, agentic Repository or workspace names returned by get_data_sources. Omit only when the API key has a single unambiguous scope.
Optional repository-relative path prefixes to include.
Optional file extensions to include, for example cs, ts, or py.
Optional maximum number of search results.
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.