Code

Search package or repository source text

Find literal text or regular-expression matches in a package or public repository. Results identify the matching files and lines, with optional surrounding lines and information about the enclosing function, class, or other symbol.

Use this endpoint to find usages, definitions, or a specific piece of code. For ranked search across multiple packages, repositories, or documentation sites, use POST /v1/searches.

Selector catalogue

Use the following selectors with the fields query parameter to choose which fields the response includes. See Choose what the response includes for details.

Selector	Data	Default
`matches`	Path, 1-based line number, exact line content, byte range and nullable file intent	Yes
`matches.context`	Before/after line arrays; also selects `matches` and retrieves context	No
`matches.symbol`	Nullable enclosing symbol; also selects `matches` and retrieves symbol details	No
`matches.*`	Explicit bundle of all three groups	No

POST

code

grep

curl --request POST \
  --url https://api.githits.dev/v1/code/grep \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "max_matches": 50,
  "name": "express",
  "path": "lib",
  "pattern": "prototype.route",
  "registry": "npm"
}
'

{
  "binary_files_skipped": 1,
  "code_index_state": "current",
  "files_in_scope": 3,
  "files_scanned": 1,
  "files_too_large_skipped": 1,
  "has_more": true,
  "indexing_ref": null,
  "matches": [
    {
      "file_intent": "production",
      "line": 2,
      "line_content": "éclair",
      "match_end_byte": 7,
      "match_start_byte": 2,
      "path": "src/main.rs"
    }
  ],
  "next_cursor": "opaque-source-cursor",
  "target_resolution": {
    "freshness": "current",
    "freshness_reason": "exact_current",
    "requested": {
      "commit_sha": null,
      "git_ref": "main",
      "kind": "repo_branch",
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    },
    "resolved_requested": {
      "commit_sha": "0123456789abcdef0123456789abcdef01234567",
      "git_ref": "0123456789abcdef0123456789abcdef01234567",
      "kind": null,
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    },
    "served": {
      "commit_sha": "0123456789abcdef0123456789abcdef01234567",
      "git_ref": "0123456789abcdef0123456789abcdef01234567",
      "kind": null,
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    }
  },
  "total_matches": 1,
  "truncated_reason": "max_matches",
  "unique_files_matched": 1
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-GitHits-Client-Name

string

Optional trimmed printable ASCII client name, maximum 80 bytes.

X-GitHits-Client-Version

string

Optional trimmed printable ASCII client version, maximum 80 bytes.

X-GitHits-Agent

string

Optional trimmed printable ASCII agent attribution, maximum 160 bytes.

X-GitHits-Session-ID

string

Optional session attribution, maximum 128 printable ASCII bytes; malformed values are dropped.

Query Parameters

fields

string

default:matches

Finite comma-separated matches (default), matches.context, matches.symbol, matches.* union. Context and symbol imply matches. Unknown/empty/duplicate fields parameters and leaf selectors are rejected. At most 2048 decoded bytes.

Use the case-sensitive selectors in the catalogue. Order and duplicate selectors do not affect the result. ASCII whitespace around selectors is ignored. The decoded value is limited to 2048 UTF-8 bytes. Empty or unknown selectors and repeated fields query parameters return 400 VALIDATION_ERROR. A group does not include nested groups unless the catalogue says so; only listed wildcard bundles are supported.

Maximum string length: 2048

Body

application/json

pattern

string

required

Required nonblank pattern, preserved verbatim; maximum 200 UTF-8 bytes, no NUL.

Required string length: 1 - 200

case_sensitive

boolean

default:false

Default false uses ASCII-only case folding; non-ASCII letters remain case-sensitive.

context_lines

integer<int32>

Common context count 0..10, default two when matches.context is selected. Explicit context input requires matches.context selection.

Required range: 0 <= x <= 10

context_lines_after

integer<int32>

0..10 following lines; independently overrides context_lines.

Required range: 0 <= x <= 10

context_lines_before

integer<int32>

0..10 preceding lines; independently overrides context_lines.

Required range: 0 <= x <= 10

cursor

string

Nonblank opaque cursor preserved unchanged. Bound to query parameters and resolved ref.

Minimum string length: 1

exclude_doc_files

boolean

Skip source-classified documentation when true.

exclude_file_intents

enum<string>[]

Exclude intents after inclusion; same finite vocabulary as file_intent.

Source-owned file-intent vocabulary.

Available options:

production,

test,

benchmark,

example,

generated,

fixture,

build,

vendor

exclude_test_files

boolean

Skip source-classified tests when true.

extensions

string[]

Case-insensitive extensions without leading dots, AND with path-selector union.

file_intent

enum<string>

Inclusive intent: production, test, benchmark, example, generated, fixture, build or vendor.

Available options:

production,

test,

benchmark,

example,

generated,

fixture,

build,

vendor

git_ref

string

Repository-only branch, tag or SHA; omission preserves default-branch intent.

globs

string[]

OR-ed glob array; braces/commas remain intact. Maximum 1000 combined path/prefix/glob selectors.

Maximum array length: 1000

include_hidden

boolean

default:false

Default false excludes dotfiles and dot-prefixed segments.

max_matches

integer<int32>

default:50

Per-page match limit 1..1000, default 50.

Required range: 1 <= x <= 1000

max_matches_per_file

integer<int32>

Per-file cap 0..1000 within this page, default equals max_matches; zero disables per-file cap.

Required range: 0 <= x <= 1000

mode

enum<string>

default:literal

Literal substring by default; regex uses source-validated RE2, no lookaround/backreferences, content-index route requires a usable literal anchor.

Available options:

literal,

regex

name

string

Package name, at most 255 UTF-8 bytes.

Minimum string length: 1

path

string

Exact target-relative file or indexed directory; OR with prefix/globs.

Minimum string length: 1

path_prefix

string

Literal prefix OR with path/globs; include trailing slash for directory boundary. Root-only dot is invalid.

Minimum string length: 1

registry

string

Package registry; required with name, exclusive with repository addressing.

repo_url

string

Credential-free public GitHub, GitLab or Codeberg repository root; exclusive with package fields.

Minimum string length: 1

version

string

Package version, at most 100 normalized bytes; omitted or blank means latest release.

wait_timeout_ms

integer<int32>

default:20000

One source indexing wait 0..60000 ms, default 20000; transport budget is added to the deadline.

Required range: 0 <= x <= 60000

Response

Qualified source grep page

binary_files_skipped

integer<int32>

required

Per-page binary files skipped, including invalid UTF-8.

Required range: x >= 0

code_index_state

enum<string>

required

Source freshness; pending evidence is a typed error.

Available options:

current,

stale,

provisional

files_in_scope

integer<int32>

required

Per-page files considered after scope and filters.

Required range: x >= 0

files_scanned

integer<int32>

required

Per-page files actually scanned; content-index pruning can reduce this.

Required range: x >= 0

files_too_large_skipped

integer<int32>

required

Per-page files skipped for exceeding the source 5 MB limit.

Required range: x >= 0

has_more

boolean

required

Exactly whether next_cursor is nonnull; false does not imply completeness.

indexing_ref

string | null

required

Active source work reference; may accompany serveable evidence.

matches

object[]

required

Required page matches in path then line order, including an empty array for zero hits.

Show child attributes

next_cursor

string | null

required

Opaque continuation, null for complete or nonresumable deadline results.

target_resolution

object

required

Mandatory requested/resolved/served provenance.

Show child attributes

total_matches

integer<int32>

required

Matches returned on this page, not a global total.

Required range: x >= 0

truncated_reason

enum<string>

required

Page caps and deadline qualification, retained for every selection.

Available options:

none,

max_matches,

max_matches_per_file,

deadline

unique_files_matched

integer<int32>

required

Distinct files contributing matches on this page.

Required range: x >= 0

⌘I

curl --request POST \
  --url https://api.githits.dev/v1/code/grep \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "max_matches": 50,
  "name": "express",
  "path": "lib",
  "pattern": "prototype.route",
  "registry": "npm"
}
'

{
  "binary_files_skipped": 1,
  "code_index_state": "current",
  "files_in_scope": 3,
  "files_scanned": 1,
  "files_too_large_skipped": 1,
  "has_more": true,
  "indexing_ref": null,
  "matches": [
    {
      "file_intent": "production",
      "line": 2,
      "line_content": "éclair",
      "match_end_byte": 7,
      "match_start_byte": 2,
      "path": "src/main.rs"
    }
  ],
  "next_cursor": "opaque-source-cursor",
  "target_resolution": {
    "freshness": "current",
    "freshness_reason": "exact_current",
    "requested": {
      "commit_sha": null,
      "git_ref": "main",
      "kind": "repo_branch",
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    },
    "resolved_requested": {
      "commit_sha": "0123456789abcdef0123456789abcdef01234567",
      "git_ref": "0123456789abcdef0123456789abcdef01234567",
      "kind": null,
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    },
    "served": {
      "commit_sha": "0123456789abcdef0123456789abcdef01234567",
      "git_ref": "0123456789abcdef0123456789abcdef01234567",
      "kind": null,
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    }
  },
  "total_matches": 1,
  "truncated_reason": "max_matches",
  "unique_files_matched": 1
}

Get started

v1 reference

Search package or repository source text

Selector catalogue

Authorizations

Headers

Query Parameters

Body

Response