---
title: "POST /v1/origin/repos/{ownerSlug}/{repoName}:grep"
method: POST
path: "/v1/origin/repos/{ownerSlug}/{repoName}:grep"
tags: ["OriginService"]
---

# POST /v1/origin/repos/{ownerSlug}/{repoName}:grep

`POST /v1/origin/repos/{ownerSlug}/{repoName}:grep`

## Request

- Base URL: `https://api.cursor.com`
- URL: `https://api.cursor.com/v1/origin/repos/{ownerSlug}/{repoName}:grep`
- Auth: HTTP bearer

Searches the text of the files in the repository at a ref and returns the
 lines that match, plus any requested surrounding context lines.
 The search is line-oriented: a pattern never matches across a line break,
 and each returned entry is one line. The response is complete only when
 `limit_hit` is false; see `max_results`. An empty repository (no refs)
 returns no matches and `limit_hit` false. Uses POST because the search
 parameters travel in the request body.

## Path parameters

- `ownerSlug` string, required
- `repoName` string, required

## Request body

- object
  - `ref` string: Commit, branch, tag, or symbolic ref (for example `HEAD`) to search. Empty means the repository's default branch.
  - `query` string, required: The pattern to search for. By default it is a regular expression supporting character classes, quantifiers, alternation, groups, and anchors; set `literal` to search for the text exactly instead. Whitespace is significant and is searched for as given. When `literal` is false, case-insensitive matching is a leading `(?i)` in the pattern (for example `(?i)launch`) and whole-word matching is `\b` around it (for example `\blaunch\b`). An empty pattern is rejected with INVALID_ARGUMENT. Maximum UTF-8 size: 4096 bytes.
  - `literal` boolean: Search for `query` as exact text rather than as a regular expression.
  - `caseInsensitive` boolean: Match upper and lower case as equivalent. Applied only when `literal` is true. Ignored for a regular-expression search; write a leading `(?i)` in `query` instead.
  - `wholeWord` boolean: Match only complete words. Applied only when `literal` is true. Ignored for a regular-expression search; write `\b` around the pattern instead.
  - `contextBefore` integer: How many lines immediately before each matching line to return as context. Values above 10 are reduced to 10.
  - `contextAfter` integer: How many lines immediately after each matching line to return as context. Values above 10 are reduced to 10.
  - `filterPath` string: Restrict the search to this file or directory, relative to the repository root. Empty searches the whole repository. Maximum UTF-8 size: 4096 bytes.
  - `includes` string[]: Glob patterns naming the paths to search. Matching is case-insensitive; a pattern containing no `/` matches at any depth, `*` matches within one path segment, and `**` matches across segments. When any include is present, a path matching none of them is not searched. At most 20 entries. Maximum UTF-8 size per pattern: 4096 bytes.
  - `excludes` string[]: Glob patterns naming paths to leave out, in the same syntax as `includes`. An exclude beats an include, and excluding a directory leaves out everything beneath it. At most 20 entries. Maximum UTF-8 size per pattern: 4096 bytes.
  - `maxResults` integer: The most matching occurrences to return. Zero requests the default of 1000, and values above 1000 are reduced to 1000. Context lines do not count toward the cap.

## Response `200`

OK

- GrepContentsResponse
  - `matches` GrepContentsMatch[]: The matching lines and their context lines. The order in which files and lines appear is unspecified and may differ between identical requests.
    - `path` string: Path to the file, relative to the repository root.
    - `lineNumber` integer: One-based line number of this line within the file.
    - `line` string: The line's text, without its trailing line terminator.
    - `kind` 'match' | 'context': Whether this line carries matches or was returned as context.
    - `submatches` GrepContentsSubmatch[]: Where the matches sit inside `line`. Always empty on a context line. When `limit_hit` is true, the last matching line may carry only some of its matches. Ranges that fall entirely past `line` are omitted; ranges that would extend past `line` are reduced to the bytes that remain.
      - `start` integer: Byte offset of the first byte of the match within the line.
      - `end` integer: Byte offset one past the last byte of the match within the line.
  - `limitHit` boolean: Whether the search reached `max_results`. Narrow `query`, `filter_path`, or the glob lists to search a smaller set of files.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: The addressed resource, or its repository, does not exist or is not visible to the caller. Not-found and no-access are deliberately indistinguishable; a 404 never confirms that the resource does not exist.
- `429`: Too Many Requests
- `default`: Default error response

---

[API](https://skmtc.dev/cursor/apis/cursor-origin-api.md) - [All operations](https://skmtc.dev/cursor/apis/cursor-origin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cursor/apis/cursor-origin-api/revisions/cbc1547d6ef7?raw)