---
title: "Search source files"
method: POST
path: "/websiteSourceCode/files/search"
tags: ["Source code"]
---

# Search source files

`POST /websiteSourceCode/files/search`

## Request

- Base URL: `https://api.cactal.ai/v1`
- URL: `https://api.cactal.ai/v1/websiteSourceCode/files/search`
- Auth: HTTP bearer

Finds text across every source file and returns one entry per matching line with its file name, line, and column. Call this first to locate code, then read only the files it names with websiteSourceCode.files.read. `pattern` is literal text unless `isRegex` is set, and matching is line by line, so a pattern cannot span a newline. Narrow with `nameGlob` and `type`, ask for surrounding lines with `contextLines`, or set `filesOnly` for the cheapest orientation. Results are cursor-paginated over matches.

## Request body

- object
  - `websiteId` string, required
  - `target` 'head' | 'published': Version alias to read: `head` (default) or `published`.
  - `version` integer: Explicit source version. Takes precedence over `target`.
  - `pattern` string, required: Text to find. Literal unless `isRegex` is set. Matched line by line, so `^` and `$` anchor to line boundaries and a pattern cannot span a newline.
  - `isRegex` boolean: Read `pattern` as a regular expression. JavaScript syntax works, including `\b`, `\d`, lookahead, and lazy quantifiers; named capture groups are not supported.
  - `caseSensitive` boolean: Match case exactly. Defaults to `true`.
  - `nameGlob` string: Only search names matching this glob. `*` and `?` stop at a `/`; `**` crosses them, for example `blog/**`.
  - `type` 'page' | 'component' | 'module' | 'server_function' | 'global_css' | 'not_found' | 'website_config' | 'custom_head_start' | 'custom_head_end' | 'custom_body_start' | 'custom_body_end': Only search files of this type.
  - `filesOnly` boolean: Return one entry per matching file, with no line detail.
  - `contextLines` integer: Surrounding lines to return on each side of a match (0 to 3). Defaults to 0.
  - `maxMatchesPerFile` integer: Maximum matches from any one file (up to 50). Defaults to 10.
  - `cursor` string: Opaque cursor from the previous page. Pass the returned `version` too to keep the search pinned.
  - `limit` integer: Maximum matches to return per page. Defaults to 20, maximum 100.

## Response `200`

A page of matches for the requested source version.

- object
  - `items` object[], required
    - `type` 'page' | 'component' | 'module' | 'server_function' | 'global_css' | 'not_found' | 'website_config' | 'custom_head_start' | 'custom_head_end' | 'custom_body_start' | 'custom_body_end', required: File type.
    - `name` string, required: File name to pass to websiteSourceCode.files.read.
    - `line` integer: 1-based number of the matching line. Omitted when `filesOnly` is `true`.
    - `column` integer: 1-based character offset of the first match on the line. Omitted when `filesOnly` is `true`.
    - `match` string: The matching line, cut at 300 characters. Omitted when `filesOnly` is `true`.
    - `before` string[]: Lines immediately before the match. Present only when `contextLines` is set.
    - `after` string[]: Lines immediately after the match. Present only when `contextLines` is set.
  - `nextCursor` string, nullable, required: Opaque cursor for the next page. Pass it as the `cursor` parameter on the next request. `null` when this is the last page.
  - `websiteId` string, required: Id of the website.
  - `version` integer, required: Source version that was searched. Pass it as `version` when continuing.
  - `truncated` boolean: `true` when a file on this page had more matches than `maxMatchesPerFile`. Raise it, or narrow the pattern, to see the rest.

## Other responses

- `400`: Validation failed. The response `message` names the first invalid field.
- `401`: Missing, invalid, expired, or revoked API key.
- `403`: The authenticated principal lacks the required capability.
- `404`: The resource does not exist or is outside the principal’s access scope.
- `429`: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.

---

[API](https://skmtc.dev/cactal/apis/cactal-api.md) · [All operations](https://skmtc.dev/cactal/apis/cactal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cactal/apis/cactal-api/revisions/9cd0fb5eacdd?raw)