---
title: "Grep-style code search across a directory"
method: POST
path: "/v1/search/code"
tags: ["Files"]
---

# Grep-style code search across a directory

`POST /v1/search/code`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/search/code`
- Auth: HTTP bearer

Recursive code search rooted at `path` (defaults to `$HOME`). Uses ripgrep
when available, falling back to a native walker. Supports literal or `regex`
patterns, smart-case (override with `case_sensitive`), `glob` filtering,
before/after `context_lines`, and `respect_gitignore`. Results are capped
by `max_results`; the response flags `truncated` when the cap is hit.

## Request body

- SearchCodeRequest
  - `pattern` string, required: Literal string or regular expression (when `regex: true`).
  - `path` string: Absolute root directory. Defaults to `$HOME`.
  - `glob` string: Glob filter (e.g. `**/*.ts`).
  - `regex` boolean: Treat `pattern` as a regular expression. Default false.
  - `case_sensitive` boolean: Tri-state. Omit for smart-case (default), `true`/`false` to force.
  - `context_lines` integer: Lines of context before and after each match. Capped by the service.
  - `max_results` integer: Cap on the number of returned matches. Service-defined default and ceiling.
  - `respect_gitignore` boolean: Respect `.gitignore` entries. Default true.

## Response `200`

Matches with file/line/column and surrounding context

- SearchCodeResponse
  - `matches` object[], required
    - `file` string, required
    - `line` integer, required
    - `column` integer, required
    - `text` string, required
    - `context_before` string[], required
    - `context_after` string[], required
  - `total` integer, required
  - `truncated` boolean, required: True when `max_results` was reached.
  - `engine` string, required: Search backend used (e.g. `ripgrep`, `native`).
  - `elapsedMs` integer, required
  - `errors` string[]: Non-fatal errors encountered while walking. Omitted when empty.

## Other responses

- `400`: Invalid request
- `499`: Client cancelled the request mid-search
- `502`: Search engine failed (ripgrep crash, IO error, etc.)
- `503`: Search service not initialized

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)