Skip to main content
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

{
  "ref": "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

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

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