> ## 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.

# Grep search

> Searches indexed code for exact literal text or a regular expression (set `regex` to `true`). First choice when you already know an exact symbol name, string literal, error message, route, or configuration key, and for exhaustive "find every usage" sweeps. It complements `semantic_search`: embeddings underrepresent rare short tokens such as acronyms (`JWT`, `OIDC`), so run `grep_search` on the exact token alongside a semantic query rather than instead of it.



## OpenAPI

````yaml /openapi-tool-api-v3.json post /api/tools/grep_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/grep_search:
    post:
      tags:
        - ToolApi
      summary: Grep search
      description: >-
        Searches indexed code for exact literal text or a regular expression
        (set `regex` to `true`). First choice when you already know an exact
        symbol name, string literal, error message, route, or configuration key,
        and for exhaustive "find every usage" sweeps. It complements
        `semantic_search`: embeddings underrepresent rare short tokens such as
        acronyms (`JWT`, `OIDC`), so run `grep_search` on the exact token
        alongside a semantic query rather than instead of it.
      operationId: ToolApiGrepSearch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrepSearchToolRequest'
            example:
              query: TaskExecutor
              data_sources:
                - CodeAlive-AI/agent-framework
          text/json:
            schema:
              $ref: '#/components/schemas/GrepSearchToolRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/GrepSearchToolRequest'
      responses:
        '200':
          description: >-
            Success envelope. obj.results[] adds grep specifics: matchCount and
            matches[] with lineNumber, column range, and lineText; rendered is a
            <grep_search_results> XML block. 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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolApiEnvelope'
              example:
                obj:
                  results:
                    - kind: file
                      dataSource:
                        type: Repository
                        id: 665f1c2ab3e77d0c9a1b4d21
                        name: agent-framework
                      identifier: CodeAlive-AI/agent-framework::src/executor.py
                      location:
                        path: src/executor.py
                      score: 1
                      matchCount: 2
                      matches:
                        - lineNumber: 42
                          startColumn: 7
                          endColumn: 19
                          lineText: 'class TaskExecutor:'
                          contextLines: []
                rendered: >-
                  <grep_search_results count="1">
                    <result identifier="CodeAlive-AI/agent-framework::src/executor.py" path="src/executor.py" source="agent-framework" match_count="2" />
                  </grep_search_results>

                  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:
    GrepSearchToolRequest:
      required:
        - query
      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.
        query:
          type:
            - 'null'
            - string
          description: Literal string or regex pattern to search for.
        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.
        regex:
          type:
            - 'null'
            - boolean
          description: Set true to treat query as a regular expression. 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

````