Grep repository content

POST /api/v1/repos/grep

Beta

Search for patterns within repository content with advanced filtering and pagination.

POST /api/v1/repos/grep
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "rev": "main",
  "query": {
    "pattern": "function.*Error",
    "case_sensitive": false
  },
  "file_filters": {
    "include_globs": ["*.js", "*.ts"],
    "exclude_globs": ["node_modules/**", "*.test.js"],
    "extension_filters": [".js", ".ts", ".tsx"]
  },
  "context": {
    "before": 2,
    "after": 2
  },
  "limits": {
    "max_lines": 1000,
    "max_matches_per_file": 50
  },
  "pagination": {
    "limit": 100
  }
}

Request Body

Parameter	Type	Description
rev	Optional	Branch name, tag, or commit SHA to grep in (defaults to repository’s default branch)
query.pattern	Required	Regex pattern to search for
query.case_sensitive	Optional	Whether grep should be case sensitive (default: true)
paths	Optional	Array of specific paths to grep within
file_filters.include_globs	Optional	Glob patterns for files to include in grep
file_filters.exclude_globs	Optional	Glob patterns for files to exclude from grep
file_filters.extension_filters	Optional	File extensions to filter by (e.g., [“.js”, “.py”])
context.before	Optional	Number of lines to include before each match
context.after	Optional	Number of lines to include after each match
limits.max_lines	Optional	Maximum total lines to return (default: 2000, max: 2000)
limits.max_matches_per_file	Optional	Maximum matches per file (default: 200)
pagination.cursor	Optional	Pagination cursor from previous response
pagination.limit	Optional	Maximum number of matches to return (default: 200)

JWT Requirements

• The JWT must include the repository in the repo claim
• Requires git:read scope

Response

{
  "query": {
    "pattern": "function.*Error",
    "case_sensitive": false
  },
  "repo": {
    "ref": "main",
    "commit": "a1b2c3d4e5f6789..."
  },
  "matches": [
    {
      "path": "src/utils/error-handler.js",
      "lines": [
        {
          "line_number": 15,
          "text": "function handleError(message) {",
          "type": "match"
        },
        {
          "line_number": 16,
          "text": "  console.error(message);",
          "type": "context"
        }
      ]
    },
    {
      "path": "src/api/auth.js",
      "lines": [
        {
          "line_number": 42,
          "text": "function validateError() {",
          "type": "match"
        }
      ]
    }
  ],
  "next_cursor": "eyJmaWxlX2luZGV4IjoxMCwibGluZV9udW1iZXIiOjE1fQ==",
  "has_more": true
}

Response Headers

• X-Cache: Indicates cache status (HIT or MISS)

Notes

• Supports full regex patterns in the grep query
• File filtering supports glob patterns (e.g., **/*.js, src/**/*.ts)
• Pagination uses cursor-based navigation for consistent results
• Large files or binary files may be automatically excluded from grep results

Error Responses

Status	Description
400 Bad Request	Invalid regex pattern, missing required fields, or invalid pagination cursor
401 Unauthorized	Missing authorization header
403 Forbidden	Invalid JWT or missing git:read scope
404 Not Found	Repository or reference doesn’t exist
500 Internal Server Error	Git command failures or database errors
503 Service Unavailable	Repository sync in progress or storage unavailable
504 Gateway Timeout	Request timeout