> ## Documentation Index > Fetch the complete documentation index at: https://docs.codealive.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi-tool-api-v3.json post /api/tools/semantic_search openapi: 3.1.1 info: title: CodeAlive Tool API description: >- Tool-only OpenAPI 3.1 contract for MCP and agent integrations. Every operation is read-only and returns a Tool API envelope. contact: name: CodeAlive Team url: https://codealive.ai email: support@codealive.ai license: name: Terms of Service url: https://app.codealive.ai/terms version: 3.0.0 servers: - url: https://app.codealive.ai security: - ApiKeyScheme: [] tags: - name: ToolApi description: CodeAlive Tool API v3 paths: /api/tools/semantic_search: post: tags: - ToolApi summary: Semantic search description: >- 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. operationId: ToolApiSemanticSearch requestBody: content: application/json: schema: $ref: '#/components/schemas/SemanticSearchToolRequest' example: question: How does task execution work? data_sources: - CodeAlive-AI/agent-framework text/json: schema: $ref: '#/components/schemas/SemanticSearchToolRequest' application/*+json: schema: $ref: '#/components/schemas/SemanticSearchToolRequest' responses: '200': description: >- 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 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 block; repair the arguments and retry. content: application/json: schema: $ref: '#/components/schemas/ToolApiEnvelope' example: obj: results: - kind: method dataSource: type: Repository id: 665f1c2ab3e77d0c9a1b4d21 name: agent-framework identifier: >- CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run location: path: src/executor.py range: start: line: 42 character: 0 end: line: 88 character: 0 score: 0.91 description: >- Executes a queued task through retry and telemetry wrappers. contentByteSize: 2048 rendered: >- Executes a queued task through retry and telemetry wrappers. Fetch relevant identifiers with fetch_artifacts or read local files before drawing conclusions. text/json: schema: $ref: '#/components/schemas/ToolApiEnvelope' '400': description: >- Bad request, including malformed JSON, unknown output_format, or invalid transport-level input. '401': description: Authentication failed or API key is missing. '403': description: >- The caller is not authorized for the requested data source or plan feature. '429': description: Rate limit, quota, or plan limit exceeded. '500': description: Unexpected server failure. components: schemas: SemanticSearchToolRequest: required: - question type: object properties: output_format: enum: - json - agentic type: - 'null' - string description: >- 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. question: type: - 'null' - string description: Natural-language search question. data_sources: type: - 'null' - array items: type: string description: >- Repository or workspace names returned by get_data_sources. Omit only when the API key has a single unambiguous scope. paths: type: - 'null' - array items: type: string description: Optional repository-relative path prefixes to include. extensions: type: - 'null' - array items: type: string description: Optional file extensions to include, for example cs, ts, or py. max_results: type: - 'null' - integer description: Optional maximum number of search results. format: int32 exclude_markdown: type: - 'null' - boolean description: Exclude Markdown files from search results. Default is false. additionalProperties: false ToolApiEnvelope: type: object properties: obj: description: >- Arbitrary JSON result for the tool. Present for omitted/json success projections and every repairable error. rendered: type: - 'null' - string description: >- Agent-facing result text. Present for omitted/agentic success projections and every repairable error. additionalProperties: false securitySchemes: ApiKeyScheme: type: http description: >- API Key authentication using Bearer token. Example: "Authorization: Bearer {apiKey}" scheme: bearer bearerFormat: API Key ````