> ## Documentation Index > Fetch the complete documentation index at: https://docs.githits.com/llms.txt > Use this file to discover all available pages before exploring further. # Find regex or literal matches across source and documentation > Find text in packages, repositories, and hosted documentation. Use this endpoint for exact text or regular-expression matches. Use list to find paths, search to discover topics, and read to retrieve more context for a match. ## Find text Send a JSON body to `POST /v1/grep`. This request searches an Express package and an explicit documentation site for literal text: ```json { "targets":[{"target":"npm:express@5.2.1"},{"target":"site:expressjs.com/en"}], "pattern":"Router", "pattern_type":"literal", "max_matches":10 } ``` Package targets search that package's files and its selected hosted documentation. Repository targets such as `github:expressjs/express` search the repository snapshot. A `site:` target selects hosted pages directly. Matching is case-sensitive by default. Set `ignore_case: true` to ignore case, and `context_lines_before` or `context_lines_after` to include up to 10 surrounding lines on each side. Both context options default to 0. The default `pattern_type` is `regex`, using RE2 syntax; lookaround and backreferences are not supported. Include literal text in broad regex patterns, or choose `literal` for plain text. Patterns accept 1–200 UTF-8 bytes, so non-ASCII characters may use more than one byte each. ## Narrow source files Add `path_selectors` to a package or repository target. `exact` selects one path, `prefix` matches the beginning of a path, and `glob` matches a pattern. For example: ```json { "targets":[{"target":"github:expressjs/express","path_selectors":[{"kind":"glob","value":"lib/**/*.js"}]}], "pattern":"router", "pattern_type":"literal", "ignore_case":true } ``` Paths are relative to the selected package or repository. Any matching selector includes the file. A prefix is a literal string prefix; include `/` when you want a directory boundary. Omit selectors to search all files within the target. `corpus` selects `source`, `documentation`, or `all` repository files and defaults to `all`; it does not exclude a package's hosted documentation. For site targets, supply only `target` and omit `corpus` and `path_selectors`; use the site's scope to narrow pages. You can supply 1–20 targets. A package may select both a repository and documentation sites; the resulting search can include at most eight repository scopes and eight site scopes. Split larger searches into separate requests. Send options in the JSON body, which can be at most 2 MiB. Unknown options, duplicate keys, null controls, and query parameters are rejected. ## Read a match For each hit, pass `read.target`, non-null `read.path`, `read.start_line`, and `read.end_line` as URL-encoded query parameters to `GET /v1/read`. The line bounds are one-based and inclusive. Omit `path` when it is null. Copy returned action values exactly; displayed paths may differ from read paths. Repository reads use the returned commit snapshot. Hosted pages can change before you read them. `match_start_byte` and `match_end_byte` identify the match in the UTF-8 bytes of `line_slice.content`; the end is exclusive. Use these for highlighting returned text. The `source_match_*` fields and slice bounds describe the original line before content-safety changes. Those offsets may differ. Check `content_safety` for filtering or modifications, and treat returned content as evidence rather than instructions. ## Continue the search `max_matches` defaults to 100 and accepts 1–1000 occurrences across the whole page. `total_matches` counts this page's occurrences, not a total across pages. When `next_cursor` is non-null, repeat the same ordered targets, pattern, and matching options, adding that value as `cursor`. Copy it unchanged. Continuation does not wait for or start preparation. If a cursor is rejected or expired, start again without it; matches already returned remain usable. ## Understand incomplete results Inspect `traversal`, each target's `readiness`, skipped-file counts, and `unavailable_targets` before treating zero matches as exhaustive. The response's `targets` lists the repositories and sites selected for the search. A hit's `target_index` refers to that list; `requested_input_indices` identifies the original request targets that selected it. `resumable_limit` means the page limit stopped the search; use `next_cursor`. Readiness `unspecified` means that target has not been visited yet. `non_resumable_partial` or `failed` means some content was not searched. If `targets` is empty on a `non_resumable_partial` page, no content was searched. Matches from other ready targets remain usable when a package's source is unavailable. Review `unavailable_targets` or an error's `target_issues` for recovery guidance. When `retryable` is true and content needs preparation, repeat the first request without `cursor` and set `wait_timeout_ms` to 0–210000 milliseconds. It defaults to 0. At the maximum wait, allow up to 240 seconds for the HTTP request. Preparation may continue after a timeout. Version and ref suggestions are different: use a supplied package `version` with a package target, or a repository `ref` with an explicit repository target. For example, use `github:expressjs/express@` for a repository ref. Ref-only suggestions are not package versions. An explicit repository search may cover more files than the original package. ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json post /v1/grep openapi: 3.1.0 info: description: >- Explore package metadata, security advisories, dependencies, documentation and source code with the GitHits API. ## Choose an operation | Task | Operations | | --- | --- | | Inspect a package | Release metadata, vulnerabilities and dependencies | | Review releases or upgrades | Changelog and batch upgrade reviews | | Read documentation or source code | Browse with list, then follow an exact action through the unified read operation | | Browse known content | List source files, local documentation, or an explicit hosted site | | Find exact text | Grep across ordered packages, repositories and hosted sites, then follow exact read actions | | Compare source trees | Compare files, line statistics and patches between package versions or repository refs | | Discover relevant content | Search across packages, repositories and documentation sites; retrieve a search's status and retained results | | Resolve a target name | Find ranked package, repository and documentation-site targets | | Research a cited question | Generate an answer grounded in a package, repository or documentation site, or continue a conversation | | Generate an example | Generate and save a code example, then submit feedback | | Generate an SBOM | Upload manifests and lockfiles to receive a CycloneDX, SPDX or text inventory | | Find a language identifier | Search supported programming languages | ## Authenticate and send requests The production API origin is `https://api.githits.dev`; development uses `https://api-dev.githits.dev`. Examples target production. Replace `` with your GitHits token. Send the token in `Authorization: Bearer `. JSON request bodies use `Content-Type: application/json`; public JSON field names use `snake_case`. Standard SBOM documents retain their format's field names. Percent-encode path parameters such as package names as one path segment, including any embedded slash. The unified read target is a query value: encode a literal plus sign as `%2B` and a literal fragment marker as `%23`; ordinary form decoding interprets `+` as a space. Each operation documents its accepted parameters and encoding rules. ## Select the data you need Where supported, `fields` is a comma-separated **query parameter**, including on POST requests. Omit it to use the operation's defaults. Supplying it replaces those defaults; required identity and information needed to interpret the result remain present. A **selector** names a supported **group** of response fields. Groups are atomic: their members are selected together. A **wildcard bundle**, such as `vulnerabilities.*`, selects only the groups listed for that bundle. A bare group does not automatically include nested groups. Arbitrary subfields and undeclared wildcards are not supported. Each operation lists its selectors, defaults, dependencies and the data they return. Selection can reduce transferred data without reducing the work needed to produce it; consult its parameter and response field documentation. Small fixed responses do not offer `fields`. ## Interpret responses and errors An omitted optional field can mean unselected or unavailable data, according to the operation's contract. Null has an operation-specific meaning: it can mark unavailable or inapplicable data, or an unselected search result. Empty arrays, zero and false are values, not substitutes for unavailable data. Always retain the result's completeness and freshness information when displaying or processing it. **Requested** identity records caller intent; **resolved** identity records what that intent resolved to; **served** identity identifies the artifact that produced the response. These can differ while indexing or refresh work continues. Use served identity when an exact follow-up read is required, preserving package-relative or repository-relative path scope. Errors normally use `application/problem+json`. Branch on the stable `code`, not the human-readable `detail`. Include `X-Request-ID` when reporting a problem; error `instance` matches that ID. Respect `Retry-After` when present. If request identity cannot be created, the response is an empty HTTP 500 without a request ID. Responses use `Cache-Control: no-store`; job events use `no-store, no-transform` to preserve streaming. Timeouts do not guarantee that work stopped. Read the documented timeout responses, especially for Research, generated examples and append-only feedback. Optional `X-GitHits-*` request headers attribute client, agent and session usage. The OpenAPI extension `x-githits-cost` is provisional operation metadata, not a price or a measure of computation. ## Contract status This API is pre-production. The external v1 contract is not yet frozen. license: name: Proprietary title: GitHits Public API version: 0.1.0 servers: - description: Production url: https://api.githits.dev security: [] tags: - description: >- Find exact text across ordered source and hosted-documentation scopes, check coverage, and follow exact reads. name: Grep - description: >- Browse package, repository or hosted-site paths and follow exact read and browse actions. name: List - description: >- Package metadata, release history, vulnerabilities, dependency graphs and upgrade comparisons. Each operation documents its registry, version and evidence scope. name: Packages - description: >- Read an exact documentation page or source file and retain the page, package-version or repository-commit details needed to cite it. name: Read - description: >- Discover evidence across package, repository and documentation-site targets, then retrieve retained search results and progress. name: Search - description: >- Find supported programming-language names and aliases for example requests. name: Languages - description: >- Generate code examples for programming tasks, with source references and license attribution. name: Examples - description: Rate generated examples or sessions and provide written feedback. name: Feedback - description: Stable exact-tree source comparison. name: Code Diff - description: >- Preview target resolution, cited questions and SBOM generation, plus the deprecated source comparison alias. Use /v1/code/diff for stable source comparison. name: Experimental paths: /v1/grep: post: tags: - Grep summary: Find regex or literal matches across source and documentation description: > Find text in packages, repositories, and hosted documentation. Use this endpoint for exact text or regular-expression matches. Use list to find paths, search to discover topics, and read to retrieve more context for a match. ## Find text Send a JSON body to `POST /v1/grep`. This request searches an Express package and an explicit documentation site for literal text: ```json { "targets":[{"target":"npm:express@5.2.1"},{"target":"site:expressjs.com/en"}], "pattern":"Router", "pattern_type":"literal", "max_matches":10 } ``` Package targets search that package's files and its selected hosted documentation. Repository targets such as `github:expressjs/express` search the repository snapshot. A `site:` target selects hosted pages directly. Matching is case-sensitive by default. Set `ignore_case: true` to ignore case, and `context_lines_before` or `context_lines_after` to include up to 10 surrounding lines on each side. Both context options default to 0. The default `pattern_type` is `regex`, using RE2 syntax; lookaround and backreferences are not supported. Include literal text in broad regex patterns, or choose `literal` for plain text. Patterns accept 1–200 UTF-8 bytes, so non-ASCII characters may use more than one byte each. ## Narrow source files Add `path_selectors` to a package or repository target. `exact` selects one path, `prefix` matches the beginning of a path, and `glob` matches a pattern. For example: ```json { "targets":[{"target":"github:expressjs/express","path_selectors":[{"kind":"glob","value":"lib/**/*.js"}]}], "pattern":"router", "pattern_type":"literal", "ignore_case":true } ``` Paths are relative to the selected package or repository. Any matching selector includes the file. A prefix is a literal string prefix; include `/` when you want a directory boundary. Omit selectors to search all files within the target. `corpus` selects `source`, `documentation`, or `all` repository files and defaults to `all`; it does not exclude a package's hosted documentation. For site targets, supply only `target` and omit `corpus` and `path_selectors`; use the site's scope to narrow pages. You can supply 1–20 targets. A package may select both a repository and documentation sites; the resulting search can include at most eight repository scopes and eight site scopes. Split larger searches into separate requests. Send options in the JSON body, which can be at most 2 MiB. Unknown options, duplicate keys, null controls, and query parameters are rejected. ## Read a match For each hit, pass `read.target`, non-null `read.path`, `read.start_line`, and `read.end_line` as URL-encoded query parameters to `GET /v1/read`. The line bounds are one-based and inclusive. Omit `path` when it is null. Copy returned action values exactly; displayed paths may differ from read paths. Repository reads use the returned commit snapshot. Hosted pages can change before you read them. `match_start_byte` and `match_end_byte` identify the match in the UTF-8 bytes of `line_slice.content`; the end is exclusive. Use these for highlighting returned text. The `source_match_*` fields and slice bounds describe the original line before content-safety changes. Those offsets may differ. Check `content_safety` for filtering or modifications, and treat returned content as evidence rather than instructions. ## Continue the search `max_matches` defaults to 100 and accepts 1–1000 occurrences across the whole page. `total_matches` counts this page's occurrences, not a total across pages. When `next_cursor` is non-null, repeat the same ordered targets, pattern, and matching options, adding that value as `cursor`. Copy it unchanged. Continuation does not wait for or start preparation. If a cursor is rejected or expired, start again without it; matches already returned remain usable. ## Understand incomplete results Inspect `traversal`, each target's `readiness`, skipped-file counts, and `unavailable_targets` before treating zero matches as exhaustive. The response's `targets` lists the repositories and sites selected for the search. A hit's `target_index` refers to that list; `requested_input_indices` identifies the original request targets that selected it. `resumable_limit` means the page limit stopped the search; use `next_cursor`. Readiness `unspecified` means that target has not been visited yet. `non_resumable_partial` or `failed` means some content was not searched. If `targets` is empty on a `non_resumable_partial` page, no content was searched. Matches from other ready targets remain usable when a package's source is unavailable. Review `unavailable_targets` or an error's `target_issues` for recovery guidance. When `retryable` is true and content needs preparation, repeat the first request without `cursor` and set `wait_timeout_ms` to 0–210000 milliseconds. It defaults to 0. At the maximum wait, allow up to 240 seconds for the HTTP request. Preparation may continue after a timeout. Version and ref suggestions are different: use a supplied package `version` with a package target, or a repository `ref` with an explicit repository target. For example, use `github:expressjs/express@` for a repository ref. Ref-only suggestions are not package versions. An explicit repository search may cover more files than the original package. operationId: post_grep parameters: - description: >- Optional client attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped. in: header name: X-GitHits-Client-Name required: false schema: type: string - description: >- Optional client-version attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped. in: header name: X-GitHits-Client-Version required: false schema: type: string - description: >- Optional agent attribution: trimmed printable ASCII, at most 160 bytes. Invalid optional values are dropped. in: header name: X-GitHits-Agent required: false schema: type: string - description: >- Optional caller-defined session ID: one to 64 ASCII letters, digits, underscores or hyphens, preserved exactly. Supply the header at most once. Invalid supplied IDs return 400 INVALID_SESSION_ID; no session is created. in: header name: X-GitHits-Session-ID required: false schema: maxLength: 64 minLength: 1 pattern: ^[A-Za-z0-9_-]{1,64}$ type: string requestBody: content: application/json: examples: continuation: value: cursor: opaque-cursor max_matches: 1 pattern: Router pattern_type: literal targets: - target: site:expressjs.com/en literal_context: value: context_lines_after: 2 context_lines_before: 2 ignore_case: true pattern: router pattern_type: literal targets: - path_selectors: - kind: glob value: lib/**/*.js target: github:expressjs/express mixed: value: pattern: Router targets: - target: npm:express@5.2.1 - target: site:expressjs.com/en schema: $ref: '#/components/schemas/GrepRequest' required: true responses: '200': content: application/json: examples: empty_partial: summary: >- No content searched; retry first-page preparation when appropriate value: hits: [] next_cursor: null targets: [] total_matches: 0 traversal: non_resumable_partial unavailable_targets: - available_refs: null available_versions: null input_index: 0 message: null progress_ref: opaque-progress reason: documentation_publishing repo_url: null requested_version: null retryable: true suggested_refs: null suggested_site_targets: [] target: npm:express@5.2.1 mixed: summary: Repository and site matches linked to the requested targets value: hits: - commit_sha: 0123456789abcdef0123456789abcdef01234567 content_safety: filtered: false modifications: [] context_after_slices: [] context_before_slices: [] file_path: application.js kind: repository line: 16 line_content: var Router = require("router"); line_slice: content: var Router = require("router"); end_byte: 31 original_line_bytes: 31 start_byte: 0 match_end_byte: 10 match_start_byte: 4 read: end_line: 16 path: lib/application.js start_line: 16 target: >- github:expressjs/express@0123456789abcdef0123456789abcdef01234567 repo_url: https://github.com/expressjs/express repository_file_path: lib/application.js source_match_end_byte: 10 source_match_start_byte: 4 target_index: 0 - content_safety: filtered: false modifications: [] context_after_slices: [] context_before_slices: [] kind: site line: 3 line_content: Router handles routes. line_slice: content: Router handles routes. end_byte: 22 original_line_bytes: 22 start_byte: 0 match_end_byte: 6 match_start_byte: 0 page_url: https://expressjs.com/en/guide/routing.html read: end_line: 3 path: null start_line: 3 target: https://expressjs.com/en/guide/routing.html source_match_end_byte: 6 source_match_start_byte: 0 target_index: 1 next_cursor: null targets: - binary_files_skipped: 0 canonical_site: null commit_sha: 0123456789abcdef0123456789abcdef01234567 corpus: all error_code: null file_issues: [] file_issues_omitted: 0 files_in_scope: 1 files_scanned: 1 files_too_large_skipped: 0 kind: repository public_message: null readiness: current repo_url: https://github.com/expressjs/express requested_input_indices: - 0 requested_ref: v5.2.1 retryable: false target: npm:express@5.2.1 target_index: 0 traversal: complete url_prefixes: [] - binary_files_skipped: null canonical_site: https://expressjs.com/en/ commit_sha: null corpus: null error_code: null file_issues: null file_issues_omitted: null files_in_scope: null files_scanned: null files_too_large_skipped: null kind: site public_message: null readiness: current repo_url: null requested_input_indices: - 0 - 1 requested_ref: null retryable: false target: site:expressjs.com/en target_index: 1 traversal: complete url_prefixes: - https://expressjs.com/en/ total_matches: 2 traversal: complete unavailable_targets: [] site: summary: Documentation match with an action to read the page value: hits: - content_safety: filtered: false modifications: [] context_after_slices: [] context_before_slices: [] kind: site line: 3 line_content: Router handles routes. line_slice: content: Router handles routes. end_byte: 22 original_line_bytes: 22 start_byte: 0 match_end_byte: 6 match_start_byte: 0 page_url: https://expressjs.com/en/guide/routing.html read: end_line: 3 path: null start_line: 3 target: https://expressjs.com/en/guide/routing.html source_match_end_byte: 6 source_match_start_byte: 0 target_index: 0 next_cursor: null targets: - binary_files_skipped: null canonical_site: https://expressjs.com/en/ commit_sha: null corpus: null error_code: null file_issues: null file_issues_omitted: null files_in_scope: null files_scanned: null files_too_large_skipped: null kind: site public_message: null readiness: current repo_url: null requested_input_indices: - 0 requested_ref: null retryable: false target: site:expressjs.com/en target_index: 0 traversal: complete url_prefixes: - https://expressjs.com/en/ total_matches: 1 traversal: complete unavailable_targets: [] source: summary: Source match with an action to read the same commit value: hits: - commit_sha: 0123456789abcdef0123456789abcdef01234567 content_safety: filtered: false modifications: [] context_after_slices: [] context_before_slices: [] file_path: application.js kind: repository line: 16 line_content: var Router = require("router"); line_slice: content: var Router = require("router"); end_byte: 31 original_line_bytes: 31 start_byte: 0 match_end_byte: 10 match_start_byte: 4 read: end_line: 16 path: lib/application.js start_line: 16 target: >- github:expressjs/express@0123456789abcdef0123456789abcdef01234567 repo_url: https://github.com/expressjs/express repository_file_path: lib/application.js source_match_end_byte: 10 source_match_start_byte: 4 target_index: 0 next_cursor: null targets: - binary_files_skipped: 0 canonical_site: null commit_sha: 0123456789abcdef0123456789abcdef01234567 corpus: all error_code: null file_issues: [] file_issues_omitted: 0 files_in_scope: 1 files_scanned: 1 files_too_large_skipped: 0 kind: repository public_message: null readiness: current repo_url: https://github.com/expressjs/express requested_input_indices: - 0 requested_ref: v5.2.1 retryable: false target: npm:express@5.2.1 target_index: 0 traversal: complete url_prefixes: [] total_matches: 1 traversal: complete unavailable_targets: [] source_omission: summary: >- Package source unavailable; documentation matches and retry suggestions remain available value: hits: - content_safety: filtered: false modifications: [] context_after_slices: [] context_before_slices: [] kind: site line: 3 line_content: Router handles routes. line_slice: content: Router handles routes. end_byte: 22 original_line_bytes: 22 start_byte: 0 match_end_byte: 6 match_start_byte: 0 page_url: https://expressjs.com/en/guide/routing.html read: end_line: 3 path: null start_line: 3 target: https://expressjs.com/en/guide/routing.html source_match_end_byte: 6 source_match_start_byte: 0 target_index: 0 next_cursor: null targets: - binary_files_skipped: null canonical_site: https://expressjs.com/en/ commit_sha: null corpus: null error_code: null file_issues: null file_issues_omitted: null files_in_scope: null files_scanned: null files_too_large_skipped: null kind: site public_message: null readiness: current repo_url: null requested_input_indices: - 1 requested_ref: null retryable: false target: site:expressjs.com/en target_index: 0 traversal: complete url_prefixes: - https://expressjs.com/en/ total_matches: 1 traversal: non_resumable_partial unavailable_targets: - available_refs: [] available_versions: - ref: v5.2.1 version: 5.2.1 input_index: 0 message: >- This package’s source was not searched. Review its source-resolution guidance; matches from other ready scopes remain usable. progress_ref: null reason: repository_ref_not_found repo_url: https://github.com/expressjs/express requested_version: 5.2.1 retryable: false suggested_refs: - ref: main version: null suggested_site_targets: null target: npm:express@5.2.1 unvisited: summary: Scope not yet visited; continue with identical controls value: hits: - commit_sha: 0123456789abcdef0123456789abcdef01234567 content_safety: filtered: false modifications: [] context_after_slices: [] context_before_slices: [] file_path: application.js kind: repository line: 16 line_content: var Router = require("router"); line_slice: content: var Router = require("router"); end_byte: 31 original_line_bytes: 31 start_byte: 0 match_end_byte: 10 match_start_byte: 4 read: end_line: 16 path: lib/application.js start_line: 16 target: >- github:expressjs/express@0123456789abcdef0123456789abcdef01234567 repo_url: https://github.com/expressjs/express repository_file_path: lib/application.js source_match_end_byte: 10 source_match_start_byte: 4 target_index: 0 next_cursor: opaque-next targets: - binary_files_skipped: 0 canonical_site: null commit_sha: 0123456789abcdef0123456789abcdef01234567 corpus: all error_code: null file_issues: [] file_issues_omitted: 0 files_in_scope: 1 files_scanned: 1 files_too_large_skipped: 0 kind: repository public_message: null readiness: current repo_url: https://github.com/expressjs/express requested_input_indices: - 0 requested_ref: v5.2.1 retryable: false target: npm:express@5.2.1 target_index: 0 traversal: complete url_prefixes: [] - binary_files_skipped: null canonical_site: https://expressjs.com/en/ commit_sha: null corpus: null error_code: null file_issues: null file_issues_omitted: null files_in_scope: null files_scanned: null files_too_large_skipped: null kind: site public_message: null readiness: unspecified repo_url: null requested_input_indices: - 0 - 1 requested_ref: null retryable: false target: site:expressjs.com/en target_index: 1 traversal: resumable_limit url_prefixes: - https://expressjs.com/en/ total_matches: 1 traversal: resumable_limit unavailable_targets: [] zero_matches: summary: Search finished with no matches value: hits: [] next_cursor: null targets: - binary_files_skipped: 0 canonical_site: null commit_sha: 0123456789abcdef0123456789abcdef01234567 corpus: all error_code: null file_issues: [] file_issues_omitted: 0 files_in_scope: 1 files_scanned: 1 files_too_large_skipped: 0 kind: repository public_message: null readiness: current repo_url: https://github.com/expressjs/express requested_input_indices: - 0 requested_ref: v5.2.1 retryable: false target: npm:express@5.2.1 target_index: 0 traversal: complete url_prefixes: [] total_matches: 0 traversal: complete unavailable_targets: [] schema: $ref: '#/components/schemas/GrepResponse' description: One page of text matches with read actions and search progress headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '400': content: application/problem+json: examples: expired_cursor: value: code: MULTI_GREP_CURSOR_EXPIRED detail: >- The cursor expired. Start a new request without it; results already returned remain usable. instance: fixture-request retryable: true status: 400 title: Grep request failed type: about:blank invalid_cursor: value: code: MULTI_GREP_CURSOR_INVALID detail: >- This cursor cannot continue the request. Start a new request without cursor, using the same targets and controls. instance: fixture-request retryable: true status: 400 title: Grep request failed type: about:blank invalid_session_id: value: code: INVALID_SESSION_ID detail: >- X-GitHits-Session-ID must occur once and match [A-Za-z0-9_-]{1,64}. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Invalid session ID type: about:blank validation: value: code: VALIDATION_ERROR detail: >- Set max_matches to an integer from 1 through 1000; it limits the whole page. instance: fixture-request status: 400 title: Validation error type: about:blank schema: $ref: '#/components/schemas/GrepProblem' description: >- Check matching controls. For an invalid or expired cursor, start a new request without it. INVALID_SESSION_ID: a supplied session header is invalid or duplicated. headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '401': content: application/problem+json: example: code: AUTHENTICATION_REQUIRED detail: A bearer credential is required. instance: fixture-request status: 401 title: Authentication required type: about:blank schema: $ref: '#/components/schemas/GrepProblem' description: Supply a valid bearer credential. headers: Cache-Control: schema: enum: - no-store type: string WWW-Authenticate: schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '403': content: application/problem+json: example: code: FORBIDDEN detail: The caller is not allowed to access this resource. instance: fixture-request status: 403 title: Forbidden type: about:blank schema: $ref: '#/components/schemas/GrepProblem' description: Account, capability or terms restrictions prevent this request. headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '405': content: application/problem+json: example: code: METHOD_NOT_ALLOWED detail: The requested method is not supported for this route. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 405 title: Method not allowed type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: 'METHOD_NOT_ALLOWED: the route does not support this HTTP method.' headers: Allow: description: 'Supported methods: POST.' schema: type: string Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '409': content: application/problem+json: example: code: GREP_TARGET_PREPARATION_REQUIRED detail: >- Some requested content cannot be searched. Review target_issues. For retryable preparation, repeat the first request with wait_timeout_ms and omit cursor. For source identity failures, choose a supported target, package version or repository ref. instance: fixture-request retryable: false status: 409 target_issues: - available_refs: null available_versions: null input_index: null message: null progress_ref: null reason: no_grep_scopes repo_url: null requested_version: null retryable: false suggested_refs: null suggested_site_targets: null target: null title: Grep request failed type: about:blank schema: $ref: '#/components/schemas/GrepPreparationProblem' description: >- Review target_issues. For retryable preparation, repeat the first request with wait_timeout_ms and no cursor. For version or ref problems, choose one of the supplied target suggestions. headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '422': content: application/problem+json: example: code: GREP_FILE_TOO_LARGE detail: The selected file exceeds the source 5 MB limit. instance: fixture-request status: 422 title: Grep request failed type: about:blank schema: $ref: '#/components/schemas/GrepProblem' description: The selected source file exceeds the 5 MB size limit. headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '429': content: application/problem+json: example: code: RATE_LIMITED detail: The request was rate limited. instance: fixture-request status: 429 title: Rate limited type: about:blank schema: $ref: '#/components/schemas/GrepProblem' description: Respect Retry-After when present. headers: Cache-Control: schema: enum: - no-store type: string Retry-After: schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '500': description: >- Request identity could not be created. Empty body without X-Request-ID; no problem object is available. headers: Cache-Control: schema: enum: - no-store type: string x-githits-empty-identity-failure: true '502': content: application/problem+json: example: code: UPSTREAM_ERROR detail: The upstream service failed to provide a response. instance: fixture-request status: 502 title: Upstream error type: about:blank schema: $ref: '#/components/schemas/GrepProblem' description: >- The service could not provide a usable response. Include X-Request-ID when reporting the failure. headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '503': content: application/problem+json: example: code: GREP_SERVICE_UNAVAILABLE detail: The grep service is unavailable. Retry when retryable is true. instance: fixture-request retryable: true status: 503 title: Grep request failed type: about:blank schema: $ref: '#/components/schemas/GrepProblem' description: Search is unavailable. Retry when retryable is true. headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '504': content: application/problem+json: example: code: GREP_TIMEOUT detail: >- The grep deadline expired. Narrow the scope or retry; preparation may continue. instance: fixture-request status: 504 title: Grep request failed type: about:blank schema: $ref: '#/components/schemas/GrepProblem' description: The grep deadline expired. Preparation may continue. headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string security: - bearer_auth: [] x-codeSamples: - label: Find literal text in source and hosted docs lang: HTTP source: >- POST /v1/grep HTTP/1.1 Host: api.githits.dev Authorization: Bearer Content-Type: application/json {"targets":[{"target":"npm:express@5.2.1"},{"target":"site:expressjs.com/en"}],"pattern":"Router","pattern_type":"literal","max_matches":10} components: schemas: GrepRequest: additionalProperties: false description: >- One bounded grep page. Unknown, duplicate and null controls are rejected. properties: context_lines_after: default: 0 description: Independent following context count, 0 through 10; default 0. format: int32 maximum: 10 minimum: 0 type: integer context_lines_before: default: 0 description: Independent preceding context count, 0 through 10; default 0. format: int32 maximum: 10 minimum: 0 type: integer cursor: description: >- Opaque continuation; repeat identical targets in the same order and matching controls. Blank starts page one. type: string ignore_case: default: false description: >- Whether to ignore case using Unicode case folding; default false (case-sensitive). type: boolean max_matches: default: 100 description: Page-wide occurrence budget, 1 through 1000, default 100. format: int32 maximum: 1000 minimum: 1 type: integer pattern: description: >- Text or regex to match, 1–200 UTF-8 bytes, without NUL. Whitespace is part of the pattern. Non-ASCII characters may occupy more than one byte. maxLength: 200 minLength: 1 type: string pattern_type: default: regex oneOf: - $ref: '#/components/schemas/GrepPatternType' description: >- Default regex uses RE2 with a literal anchor; set literal for plain text. targets: description: >- Targets to search, in order; 1 through 20. A package can select both repository files and hosted docs. The combined search supports at most eight repository scopes and eight site scopes; split larger searches into separate requests. items: $ref: '#/components/schemas/GrepTarget' maxItems: 20 minItems: 1 type: array wait_timeout_ms: default: 0 description: >- First-page preparation wait, 0 through 210000 ms, default 0. Continuation never waits. Timeout does not stop preparation. format: int32 maximum: 210000 minimum: 0 type: integer required: - targets - pattern type: object GrepResponse: description: >- One page of text matches, with read actions and information about searched or unavailable content. properties: hits: description: Occurrences on this page, tagged as repository or site evidence. items: $ref: '#/components/schemas/GrepHit' type: array next_cursor: description: >- Opaque continuation. Repeat identical ordered targets and matching controls. type: - string - 'null' targets: description: >- Selected repositories and documentation sites, including those not yet visited. Hits refer to this list using `target_index`. items: $ref: '#/components/schemas/GrepTargetStatus' type: array total_matches: description: >- Number of occurrences returned on this page, not a total across pages. format: int64 minimum: 0 type: integer traversal: $ref: '#/components/schemas/GrepTraversal' description: >- Coverage state; inspect readiness and skipped content before concluding no matches. unavailable_targets: description: >- Requested inputs omitted from searched scopes, with recovery guidance. items: $ref: '#/components/schemas/GrepUnavailableTarget' type: array required: - hits - targets - unavailable_targets - traversal - next_cursor - total_matches type: object GrepProblem: allOf: - $ref: '#/components/schemas/ProblemResponse' description: Shared stable problem fields and active request identity. - properties: retryable: description: >- Whether this condition can be retried, when known. An expired cursor requires a fresh request without cursor. type: boolean type: object description: >- Search error with a stable code, explanation, request ID, and retry guidance when available. ProblemResponse: description: >- The stable problem document returned for an unsuccessful public API request. properties: acceptance_url: description: Link for accepting the required terms, when provided. type: string code: description: The stable uppercase API error code. type: string detail: description: A stable, client-safe explanation of the failure. type: string instance: description: The active request trace ID. type: string status: description: The HTTP status returned with this problem. format: int32 minimum: 0 type: integer terms_url: description: Link to the terms that require acceptance, when provided. type: string title: description: A short, stable title for the error. type: string type: description: The generic RFC 9457 problem type. type: string required: - type - title - status - detail - instance - code type: object GrepPreparationProblem: allOf: - $ref: '#/components/schemas/ProblemResponse' description: Shared stable problem fields and active request identity. - properties: retryable: description: Whether the preparation condition can be retried. type: boolean target_issues: description: >- Reasons requested content could not be searched. An issue affecting the whole request has null `input_index` and target. items: $ref: '#/components/schemas/GrepPreparationIssue' maxItems: 20 minItems: 1 type: array required: - retryable - target_issues type: object description: >- Content could not be prepared for search. Review `target_issues` for reasons and next steps. GrepPatternType: description: RE2 regex is the default; literal treats pattern bytes as plain text. enum: - regex - literal type: string GrepTarget: additionalProperties: false description: One ordered package, repository, or explicit site target. properties: corpus: default: all oneOf: - $ref: '#/components/schemas/GrepCorpus' description: Source-only corpus, default all. Omit for site targets. path_selectors: description: >- Source-only selector union; at most 1000. Empty or omitted means no filter. items: $ref: '#/components/schemas/GrepPathSelector' maxItems: 1000 type: array target: description: >- Package, repository, or documentation site, such as npm:express@5.2.1, github:expressjs/express, or site:expressjs.com/en. minLength: 1 type: string required: - target type: object GrepHit: description: >- A text match in repository files (kind repository) or hosted documentation (kind site). oneOf: - allOf: - $ref: '#/components/schemas/GrepRepositoryHit' - properties: kind: enum: - repository type: string required: - kind type: object - allOf: - $ref: '#/components/schemas/GrepSiteHit' - properties: kind: enum: - site type: string required: - kind type: object GrepTargetStatus: description: >- Search progress for a selected repository or site, including which request targets selected it. properties: binary_files_skipped: description: >- Skipped binary repository files; check before treating matches as exhaustive. format: int64 minimum: 0 type: - integer - 'null' canonical_site: description: Canonical hosted-site identity, or null for repository scopes. type: - string - 'null' commit_sha: description: Exact served 40-hex snapshot commit; null when unavailable. type: - string - 'null' corpus: oneOf: - type: 'null' - $ref: '#/components/schemas/GrepCorpus' description: >- Repository file selection only; package-selected hosted docs are unaffected. error_code: description: Scope failure code, or null when no scope error was reported. type: - string - 'null' file_issues: description: >- Selected file-level failure or safety evidence; null is distinct from an empty list. items: $ref: '#/components/schemas/GrepFileIssue' type: - array - 'null' file_issues_omitted: description: >- Number of additional file issues not included in `file_issues`. Zero means none omitted; null means unknown or not applicable. format: int64 minimum: 0 type: - integer - 'null' files_in_scope: description: >- Repository files selected by scope; null when unavailable or inapplicable. format: int64 minimum: 0 type: - integer - 'null' files_scanned: description: >- Repository files scanned on this page; null when unavailable or inapplicable. format: int64 minimum: 0 type: - integer - 'null' files_too_large_skipped: description: >- Repository files skipped for size; null when unavailable or inapplicable. format: int64 minimum: 0 type: - integer - 'null' kind: $ref: '#/components/schemas/GrepTargetKind' description: Repository or hosted-site scope. public_message: description: >- Explanation of this scope's availability or failure, with guidance when available. type: - string - 'null' readiness: $ref: '#/components/schemas/GrepReadiness' description: >- Observed artifact readiness; unspecified means this scope was not visited. repo_url: description: Credential-free supported repository URL; null when inapplicable. type: - string - 'null' requested_input_indices: description: >- Zero-based indices into the request targets array that selected this scope. Several inputs can select the same scope. items: format: int64 minimum: 0 type: integer type: array requested_ref: description: >- Requested repository ref, distinct from the served commit; null on sites. type: - string - 'null' retryable: description: >- Whether this condition can be retried. For content needing preparation, start a new request with `wait_timeout_ms`. type: boolean target: description: >- Target for this content. Copy unchanged when making a follow-up request. type: string target_index: description: >- Zero-based index into the response targets list; not an index into the request targets. format: int64 minimum: 0 type: integer traversal: $ref: '#/components/schemas/GrepTraversal' description: >- Coverage state; inspect readiness and skipped content before concluding no matches. url_prefixes: description: Selected hosted URL prefixes; empty on repository scopes. items: type: string type: array required: - target_index - requested_input_indices - kind - target - traversal - readiness - error_code - retryable - public_message - repo_url - requested_ref - commit_sha - corpus - canonical_site - url_prefixes - files_scanned - files_in_scope - binary_files_skipped - files_too_large_skipped - file_issues - file_issues_omitted type: object GrepTraversal: description: >- Search progress: complete means traversal finished; `resumable_limit` means continue with `next_cursor`; `non_resumable_partial` or failed means some content was not searched; `cursor_expired` requires a fresh request. enum: - complete - resumable_limit - non_resumable_partial - failed - cursor_expired type: string GrepUnavailableTarget: description: >- Requested input omitted from searched scopes with bounded recovery evidence. properties: available_refs: description: >- Available repository ref candidates; ref-only candidates require repository addressing. items: $ref: '#/components/schemas/GrepAvailableVersion' maxItems: 10 type: - array - 'null' available_versions: description: >- Available package-version candidates paired with their repository refs. items: $ref: '#/components/schemas/GrepAvailableVersion' maxItems: 10 type: - array - 'null' input_index: description: Original zero-based requested input index. format: int64 minimum: 0 type: integer message: description: >- Explanation of unavailable content or suggested recovery, when available. type: - string - 'null' progress_ref: description: >- Opaque preparation progress reference, or null when none is available. type: - string - 'null' reason: description: >- Reason the content could not be prepared or its requested version or ref could not be selected. type: string repo_url: description: Credential-free supported repository URL; null when inapplicable. type: - string - 'null' requested_version: description: Selected package release; not a proven repository ref. type: - string - 'null' retryable: description: >- Whether this condition can be retried. For content needing preparation, start a new request with `wait_timeout_ms`. type: boolean suggested_refs: description: >- Suggested repository refs with nullable package versions; never substitute a ref for a version. items: $ref: '#/components/schemas/GrepAvailableVersion' maxItems: 10 type: - array - 'null' suggested_site_targets: description: >- Site targets suggested for a new request. Null means no suggestion information; [] means no known candidates. items: type: string type: - array - 'null' target: description: >- Target for this content. Copy unchanged when making a follow-up request. type: string required: - input_index - target - reason - retryable - progress_ref - suggested_site_targets - message - repo_url - requested_version - suggested_refs - available_refs - available_versions type: object GrepPreparationIssue: description: >- A typed preparation failure; a request-wide issue can have no input index or target. properties: available_refs: description: >- Available repository ref candidates; ref-only candidates require repository addressing. items: $ref: '#/components/schemas/GrepAvailableVersion' maxItems: 10 type: - array - 'null' available_versions: description: >- Available package-version candidates paired with their repository refs. items: $ref: '#/components/schemas/GrepAvailableVersion' maxItems: 10 type: - array - 'null' input_index: description: >- Original zero-based input index; null only for a request-wide preparation issue. format: int64 minimum: 0 type: - integer - 'null' message: description: >- Explanation of unavailable content or suggested recovery, when available. type: - string - 'null' progress_ref: description: >- Opaque preparation progress reference, or null when none is available. type: - string - 'null' reason: description: >- Reason the content could not be prepared or its requested version or ref could not be selected. type: string repo_url: description: Credential-free supported repository URL; null when inapplicable. type: - string - 'null' requested_version: description: Selected package release; not a proven repository ref. type: - string - 'null' retryable: description: >- Whether this condition can be retried. For content needing preparation, start a new request with `wait_timeout_ms`. type: boolean suggested_refs: description: >- Suggested repository refs with nullable package versions; never substitute a ref for a version. items: $ref: '#/components/schemas/GrepAvailableVersion' maxItems: 10 type: - array - 'null' suggested_site_targets: description: >- Site targets suggested for a new request. Null means no suggestion information; [] means no known candidates. items: type: string type: - array - 'null' target: description: >- Target for this content. Copy unchanged when making a follow-up request. type: - string - 'null' required: - input_index - target - reason - retryable - progress_ref - suggested_site_targets - message - repo_url - requested_version - suggested_refs - available_refs - available_versions type: object GrepCorpus: description: >- Repository files to search: source files, local documentation, or both (all). This choice does not exclude hosted documentation selected by a package. enum: - source - documentation - all type: string GrepPathSelector: additionalProperties: false description: One path filter for a package or repository. properties: kind: $ref: '#/components/schemas/GrepSelectorKind' description: >- How to match value. A prefix is a literal string prefix; include / to select a directory boundary. A glob determines its own depth. value: description: >- Path or pattern relative to the package or repository. Must not be blank or contain NUL. minLength: 1 type: string required: - kind - value type: object GrepRepositoryHit: allOf: - $ref: '#/components/schemas/GrepHitEvidence' description: Common match evidence. - properties: commit_sha: description: Exact served 40-hex snapshot commit. type: string file_path: description: Target-relative display path; use read.path for follow-up reads. type: string repo_url: description: Credential-free supported repository URL. type: string repository_file_path: description: >- Repository-root source path, distinct from a package-relative display path. type: string required: - repo_url - commit_sha - file_path - repository_file_path type: object description: >- One source occurrence; display and repository-root paths have distinct roles. GrepSiteHit: allOf: - $ref: '#/components/schemas/GrepHitEvidence' description: Common match evidence. - properties: page_url: description: >- Hosted page URL; use the emitted read action for exact follow-up. type: string required: - page_url type: object description: One occurrence in a live hosted page. GrepFileIssue: description: >- An affected source occurrence or aggregate file issue, including safety evidence. properties: code: description: >- Code identifying a skipped match, file failure, or content-safety issue. type: string content_safety: $ref: '#/components/schemas/GrepSafety' description: Safety filtering and modifications applied to returned evidence. file_path: description: >- Safety-normalized target-relative issue path; not an exact read locator. type: string line: description: Positive one-based source line containing the occurrence. format: int64 minimum: 1 type: integer line_bytes: description: Original line length in bytes; zero denotes an aggregate file issue. format: int64 minimum: 0 type: integer match_end_byte: description: >- Exclusive omitted occurrence end in the original line; null for aggregate issues. format: int64 minimum: 0 type: - integer - 'null' match_start_byte: description: >- Zero-based omitted occurrence start in the original line; null for aggregate issues. format: int64 minimum: 0 type: - integer - 'null' required: - file_path - content_safety - code - line - line_bytes - match_start_byte - match_end_byte type: object GrepTargetKind: description: >- Whether a selected search scope contains repository files or hosted documentation. enum: - repository - site type: string GrepReadiness: description: >- Availability of the selected content. unspecified means the scope has not been visited; current or stale describes the indexed snapshot; other values explain unavailable or incomplete content. enum: - unspecified - current - stale - not_available - missing_ref - reader_open_failed - incomplete - resource_limit - version_unsupported - read_failed type: string GrepAvailableVersion: description: >- An opaque repository ref and optional package version; never substitute one for the other. properties: ref: description: Opaque repository ref, preserved exactly. type: string version: description: >- Package version to use in a new package request. When null, use an explicit repository target with ref instead. type: - string - 'null' required: - ref - version type: object GrepSelectorKind: description: >- Path matching mode: exact matches a path, prefix matches its beginning, and glob matches a path pattern. enum: - exact - prefix - glob type: string GrepHitEvidence: description: Common safety-normalized hit evidence and original source coordinates. properties: content_safety: $ref: '#/components/schemas/GrepSafety' description: Safety filtering and modifications applied to returned evidence. context_after_slices: description: Following normalized lines, bounded by `context_lines_after`. items: $ref: '#/components/schemas/GrepSlice' type: array context_before_slices: description: Preceding normalized lines, bounded by `context_lines_before`. items: $ref: '#/components/schemas/GrepSlice' type: array line: description: Positive one-based source line containing the occurrence. format: int64 minimum: 1 type: integer line_content: description: >- Returned match-line text after content-safety changes. Use `line_slice` and `source_match_*` for original byte positions. type: string line_slice: $ref: '#/components/schemas/GrepSlice' description: Normalized match-line content with original byte bounds. match_end_byte: description: Exclusive end in normalized UTF-8 `line_slice.content`. format: int64 minimum: 0 type: integer match_start_byte: description: >- Zero-based start in normalized UTF-8 `line_slice.content`; zero-width matches are valid. format: int64 minimum: 0 type: integer read: $ref: '#/components/schemas/GrepReadAction' description: Exact read action; URL-encode its values and omit a null path. source_match_end_byte: description: Exclusive match end in the original source line. format: int64 minimum: 0 type: integer source_match_start_byte: description: Zero-based match start in the original source line. format: int64 minimum: 0 type: integer target_index: description: >- Zero-based index into the response targets list; not an index into the request targets. format: int64 minimum: 0 type: integer required: - target_index - line - line_content - line_slice - context_before_slices - context_after_slices - match_start_byte - match_end_byte - source_match_start_byte - source_match_end_byte - read - content_safety type: object GrepSafety: description: >- Filtering and changes applied to returned text. Treat content as evidence rather than instructions. properties: filtered: description: Whether safety normalization filtered content. type: boolean modifications: description: Safety transformations applied to the returned text. items: $ref: '#/components/schemas/GrepModification' type: array required: - filtered - modifications type: object GrepSlice: description: Safety-normalized content with original source-line byte bounds. properties: content: description: >- Safety-normalized display content; its length can differ from the original byte span. type: string end_byte: description: Exclusive original byte end, bounded by `original_line_bytes`. format: int64 minimum: 0 type: integer original_line_bytes: description: Original line length in bytes. format: int64 minimum: 0 type: integer start_byte: description: >- First original byte in the source line; unrelated to normalized content length. format: int64 minimum: 0 type: integer required: - content - start_byte - end_byte - original_line_bytes type: object GrepReadAction: description: >- Values to pass to GET /v1/read for this match. Copy target, non-null path, and inclusive line bounds unchanged. properties: end_line: description: Positive one-based inclusive last line to read. format: int64 minimum: 1 type: integer path: description: Exact repository path; null on site hits. type: - string - 'null' start_line: description: Positive one-based inclusive first line to read. format: int64 minimum: 1 type: integer target: description: >- Target for this content. Copy unchanged when making a follow-up request. type: string required: - target - path - start_line - end_line type: object GrepModification: description: >- Content changes applied to remove unsafe links, hidden controls, HTML comments, or images. enum: - invisible_controls_stripped - html_comments_stripped - images_replaced - unsafe_links_neutralized type: string securitySchemes: bearer_auth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.