> ## 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. # 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](https://docs.githits.com/api/requests-and-responses#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 | ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json post /v1/code/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 | List package documentation, then read a page | | Navigate source code | List files, read a file or search text within a target | | 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 | | Ask 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 | | 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`. Percent-encode a package name or opaque read target as one path segment, including any embedded slash. For query values, encode a literal plus sign as `%2B`; 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`. Timeouts do not guarantee that work stopped. Read the documented timeout responses, especially for Ask, 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: >- Package metadata, release history, vulnerabilities, dependency graphs and upgrade comparisons. Each operation documents its registry, version and evidence scope. name: Packages - description: >- Discover existing documentation pages and read their content with exact source locators and availability information. name: Documentation - description: >- Enumerate files, read exact content and grep within a package or repository. Responses retain served identity, indexing state and completeness information. name: Code - 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: >- Preview operations for target resolution, source comparison and cited questions. Routes use /v1/experimental and may later move to permanent v1 locations under a documented migration policy. name: Experimental paths: /v1/code/grep: post: tags: - Code summary: Search package or repository source text description: > 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](https://docs.githits.com/api/requests-and-responses#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 | operationId: post_code_grep parameters: - description: >- 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. in: query name: fields required: false schema: default: matches maxLength: 2048 type: string - description: Optional trimmed printable ASCII client name, maximum 80 bytes. in: header name: X-GitHits-Client-Name required: false schema: type: string - description: Optional trimmed printable ASCII client version, maximum 80 bytes. in: header name: X-GitHits-Client-Version required: false schema: type: string - description: >- Optional trimmed printable ASCII agent attribution, maximum 160 bytes. in: header name: X-GitHits-Agent required: false schema: type: string - description: >- Optional session attribution, maximum 128 printable ASCII bytes; malformed values are dropped. in: header name: X-GitHits-Session-ID required: false schema: type: string requestBody: content: application/json: examples: package: value: max_matches: 50 name: express path: lib pattern: prototype.route registry: npm repository: value: git_ref: 0123456789abcdef0123456789abcdef01234567 globs: - src/**/*.{rs,ts} pattern: clair repo_url: https://github.com/example/repository schema: $ref: '#/components/schemas/CodeGrepRequest' required: true responses: '200': content: application/json: examples: capped: value: 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 context: value: binary_files_skipped: 1 code_index_state: current files_in_scope: 3 files_scanned: 1 files_too_large_skipped: 1 has_more: false indexing_ref: null matches: - context: after: [] before: - // food file_intent: production line: 2 line_content: éclair match_end_byte: 7 match_start_byte: 2 path: src/main.rs next_cursor: null 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: none unique_files_matched: 1 deadline: value: binary_files_skipped: 1 code_index_state: current files_in_scope: 3 files_scanned: 1 files_too_large_skipped: 1 has_more: false 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: null 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: deadline unique_files_matched: 1 default: value: binary_files_skipped: 1 code_index_state: current files_in_scope: 3 files_scanned: 1 files_too_large_skipped: 1 has_more: false 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: null 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: none unique_files_matched: 1 empty: value: binary_files_skipped: 1 code_index_state: current files_in_scope: 3 files_scanned: 1 files_too_large_skipped: 1 has_more: false indexing_ref: null matches: [] next_cursor: null 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: 0 truncated_reason: none unique_files_matched: 0 full: value: binary_files_skipped: 1 code_index_state: current files_in_scope: 3 files_scanned: 1 files_too_large_skipped: 1 has_more: false indexing_ref: null matches: - context: after: [] before: - // food file_intent: production line: 2 line_content: éclair match_end_byte: 7 match_start_byte: 2 path: src/main.rs symbol: arity: 0 category: callable end_line: 3 file_path: src/main.rs is_public: false kind: function name: main parent_path: null qualified_path: null start_line: 1 symbol_ref: crates:example:1.0.0:a1 next_cursor: null 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: none unique_files_matched: 1 symbol: value: binary_files_skipped: 1 code_index_state: current files_in_scope: 3 files_scanned: 1 files_too_large_skipped: 1 has_more: false indexing_ref: null matches: - file_intent: production line: 2 line_content: éclair match_end_byte: 7 match_start_byte: 2 path: src/main.rs symbol: arity: 0 category: callable end_line: 3 file_path: src/main.rs is_public: false kind: function name: main parent_path: null qualified_path: null start_line: 1 symbol_ref: crates:example:1.0.0:a1 next_cursor: null 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: none unique_files_matched: 1 symbol_unavailable: value: binary_files_skipped: 1 code_index_state: current files_in_scope: 3 files_scanned: 1 files_too_large_skipped: 1 has_more: false indexing_ref: null matches: - file_intent: production line: 2 line_content: éclair match_end_byte: 7 match_start_byte: 2 path: src/main.rs symbol: null next_cursor: null 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: none unique_files_matched: 1 schema: $ref: '#/components/schemas/CodeGrepResponse' description: Qualified source grep page headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '400': content: application/problem+json: example: code: VALIDATION_ERROR detail: The request is invalid. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Validation error type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- VALIDATION_ERROR, GREP_PATTERN_TOO_SHORT, GREP_PATTERN_TOO_LONG, GREP_PATTERN_INVALID, GREP_INVALID_REGEX, GREP_UNSUPPORTED_PATTERN, GREP_PATTERN_TOO_UNSELECTIVE, GREP_SCOPE_REQUIRED, GREP_SELECTOR_INVALID, GREP_CURSOR_INVALID, GREP_CONTEXT_TOO_LARGE, GREP_CONTEXT_NEGATIVE, GREP_MAX_MATCHES_TOO_LARGE, GREP_MAX_MATCHES_INVALID headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '401': content: application/problem+json: example: code: AUTHENTICATION_REQUIRED detail: A bearer credential is required. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 401 title: Authentication required type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: AUTHENTICATION_REQUIRED headers: Cache-Control: schema: enum: - no-store type: string WWW-Authenticate: description: Bearer challenge. schema: type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '403': content: application/problem+json: example: code: FORBIDDEN detail: The caller is not allowed to access this resource. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 403 title: Forbidden type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- FORBIDDEN, ACCOUNT_INACTIVE, FEATURE_FLAG_REQUIRED, TERMS_ACCEPTANCE_REQUIRED headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '404': content: application/problem+json: example: code: FILE_NOT_FOUND detail: The requested file is absent from the indexed target. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 404 title: File not found type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- FILE_NOT_FOUND, PACKAGE_NOT_FOUND, NO_RELEASED_VERSIONS, VERSION_NOT_FOUND, REPOSITORY_NOT_FOUND, REF_NOT_FOUND headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. 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 '422': content: application/problem+json: example: code: FILE_PATH_EXCLUDED detail: The source excludes this path from the indexed target. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 422 title: File path excluded type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- FILE_PATH_EXCLUDED, UNSUPPORTED_PACKAGE_VARIANTS, AMBIGUOUS_REF, REF_UNRESOLVABLE headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '429': content: application/problem+json: example: code: RATE_LIMITED detail: The request was rate limited. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 429 title: Rate limited type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: RATE_LIMITED headers: Cache-Control: schema: enum: - no-store type: string Retry-After: description: Optional bounded delta seconds or HTTP date. schema: type: string x-request-id: description: Active trace identity, also problem.instance. 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: 4bf92f3577b34da6a3ce929d0e0e4736 status: 502 title: Upstream error type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: UPSTREAM_ERROR, GREP_FAILED headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '503': content: application/problem+json: example: code: PACKAGE_INDEXING detail: Code evidence is not ready; retry the request later. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 503 title: Code indexing type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- PACKAGE_INDEXING, GREP_INDEX_ABSENT, GREP_INDEX_STALE, GREP_INDEX_INCOMPLETE, GREP_CAS_REQUIRED, GREP_SERVICE_UNAVAILABLE headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '504': content: application/problem+json: example: code: TIMEOUT detail: The upstream request did not complete in time. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 504 title: Upstream timeout type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: TIMEOUT, GREP_TIMEOUT headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string security: - bearer_auth: [] components: schemas: CodeGrepRequest: additionalProperties: false properties: case_sensitive: default: false description: >- Default false uses ASCII-only case folding; non-ASCII letters remain case-sensitive. type: boolean context_lines: description: >- Common context count 0..10, default two when matches.context is selected. Explicit context input requires matches.context selection. format: int32 maximum: 10 minimum: 0 type: integer context_lines_after: description: 0..10 following lines; independently overrides `context_lines`. format: int32 maximum: 10 minimum: 0 type: integer context_lines_before: description: 0..10 preceding lines; independently overrides `context_lines`. format: int32 maximum: 10 minimum: 0 type: integer cursor: description: >- Nonblank opaque cursor preserved unchanged. Bound to query parameters and resolved ref. minLength: 1 type: string exclude_doc_files: description: Skip source-classified documentation when true. type: boolean exclude_file_intents: description: >- Exclude intents after inclusion; same finite vocabulary as `file_intent`. items: $ref: '#/components/schemas/CodeFileIntent' type: array exclude_test_files: description: Skip source-classified tests when true. type: boolean extensions: description: >- Case-insensitive extensions without leading dots, AND with path-selector union. items: type: string type: array file_intent: $ref: '#/components/schemas/CodeFileIntent' description: >- Inclusive intent: production, test, benchmark, example, generated, fixture, build or vendor. git_ref: description: >- Repository-only branch, tag or SHA; omission preserves default-branch intent. type: string globs: description: >- OR-ed glob array; braces/commas remain intact. Maximum 1000 combined path/prefix/glob selectors. items: type: string maxItems: 1000 type: array include_hidden: default: false description: Default false excludes dotfiles and dot-prefixed segments. type: boolean max_matches: default: 50 description: Per-page match limit 1..1000, default 50. format: int32 maximum: 1000 minimum: 1 type: integer max_matches_per_file: description: >- Per-file cap 0..1000 within this page, default equals `max_matches`; zero disables per-file cap. format: int32 maximum: 1000 minimum: 0 type: integer mode: default: literal oneOf: - $ref: '#/components/schemas/CodeGrepMode' description: >- Literal substring by default; regex uses source-validated RE2, no lookaround/backreferences, content-index route requires a usable literal anchor. name: description: Package name, at most 255 UTF-8 bytes. minLength: 1 type: string path: description: >- Exact target-relative file or indexed directory; OR with prefix/globs. minLength: 1 type: string path_prefix: description: >- Literal prefix OR with path/globs; include trailing slash for directory boundary. Root-only dot is invalid. minLength: 1 type: string pattern: description: >- Required nonblank pattern, preserved verbatim; maximum 200 UTF-8 bytes, no NUL. maxLength: 200 minLength: 1 type: string registry: description: >- Package registry; required with name, exclusive with repository addressing. type: string repo_url: description: >- Credential-free public GitHub, GitLab or Codeberg repository root; exclusive with package fields. minLength: 1 type: string version: description: >- Package version, at most 100 normalized bytes; omitted or blank means latest release. type: string wait_timeout_ms: default: 20000 description: >- One source indexing wait 0..60000 ms, default 20000; transport budget is added to the deadline. format: int32 maximum: 60000 minimum: 0 type: integer required: - pattern type: object CodeGrepResponse: properties: binary_files_skipped: description: Per-page binary files skipped, including invalid UTF-8. format: int32 minimum: 0 type: integer code_index_state: $ref: '#/components/schemas/CodeIndexState' description: Source freshness; pending evidence is a typed error. files_in_scope: description: Per-page files considered after scope and filters. format: int32 minimum: 0 type: integer files_scanned: description: >- Per-page files actually scanned; content-index pruning can reduce this. format: int32 minimum: 0 type: integer files_too_large_skipped: description: Per-page files skipped for exceeding the source 5 MB limit. format: int32 minimum: 0 type: integer has_more: description: >- Exactly whether `next_cursor` is nonnull; false does not imply completeness. type: boolean indexing_ref: description: Active source work reference; may accompany serveable evidence. type: - string - 'null' matches: description: >- Required page matches in path then line order, including an empty array for zero hits. items: $ref: '#/components/schemas/CodeGrepMatch' type: array next_cursor: description: >- Opaque continuation, null for complete or nonresumable deadline results. type: - string - 'null' target_resolution: $ref: '#/components/schemas/CodeTargetResolution' description: Mandatory requested/resolved/served provenance. total_matches: description: Matches returned on this page, not a global total. format: int32 minimum: 0 type: integer truncated_reason: $ref: '#/components/schemas/CodeGrepTruncation' description: Page caps and deadline qualification, retained for every selection. unique_files_matched: description: Distinct files contributing matches on this page. format: int32 minimum: 0 type: integer required: - target_resolution - code_index_state - indexing_ref - total_matches - unique_files_matched - files_in_scope - files_scanned - binary_files_skipped - files_too_large_skipped - has_more - next_cursor - truncated_reason - matches type: object ProblemResponse: description: >- The stable problem document returned for an unsuccessful public API request. properties: acceptance_url: description: An optional acceptance URL supplied by the upstream allow-list. 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: An optional terms URL supplied by the upstream allow-list. 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 CodeFileIntent: description: Source-owned file-intent vocabulary. enum: - production - test - benchmark - example - generated - fixture - build - vendor type: string CodeGrepMode: enum: - literal - regex type: string CodeIndexState: description: >- Serveable code lifecycle states; pending work produces `PACKAGE_INDEXING`. enum: - current - stale - provisional type: string CodeGrepMatch: properties: context: $ref: '#/components/schemas/CodeGrepContext' description: Atomic context group, omitted when unselected. file_intent: description: Source classification, null when unavailable. type: - string - 'null' line: description: 1-based line number. format: int32 minimum: 1 type: integer line_content: description: Exact matching line without trailing newline. type: string match_end_byte: description: 0-based exclusive UTF-8 byte end; in éclair, clair occupies [2,7). format: int32 minimum: 0 type: integer match_start_byte: description: 0-based first UTF-8 byte within `line_content`. format: int32 minimum: 0 type: integer path: description: Canonical target-relative source path. type: string symbol: oneOf: - type: 'null' - $ref: '#/components/schemas/CodeGrepSymbol' description: >- Atomic enclosing symbol, omitted when unselected, null when no symbol is available. required: - path - line - line_content - match_start_byte - match_end_byte - file_intent type: object CodeTargetResolution: description: Source-reported identity; never reconstructed from caller input. properties: freshness: description: 'Source freshness: current, `fallback_recent` or provisional.' type: string freshness_reason: description: Machine-readable source explanation of freshness. type: string requested: $ref: '#/components/schemas/CodeIdentity' description: Original request intent including omitted version or default branch. resolved_requested: $ref: '#/components/schemas/CodeIdentity' description: Current resolved request; may be fresher than the served artifact. served: $ref: '#/components/schemas/CodeIdentity' description: >- Exact served artifact; prefer `commit_sha` over `git_ref` for repository pagination. required: - requested - resolved_requested - served - freshness - freshness_reason type: object CodeGrepTruncation: enum: - none - max_matches - max_matches_per_file - deadline type: string CodeGrepContext: properties: after: description: Following lines in order, bounded by effective after count. items: type: string type: array before: description: Preceding lines, oldest first, bounded by effective before count. items: type: string type: array required: - before - after type: object CodeGrepSymbol: properties: arity: description: Parameter count when available. format: int32 minimum: 0 type: - integer - 'null' category: description: Broad source category, null when unknown. type: - string - 'null' end_line: description: Inclusive 1-based end when available. format: int32 minimum: 1 type: - integer - 'null' file_path: description: Target-relative symbol file when available. type: - string - 'null' is_public: description: Source public/exported visibility when available. type: - boolean - 'null' kind: description: Source kind, null when unknown. type: - string - 'null' name: description: Short name. type: string parent_path: description: Qualified parent path when available. type: - string - 'null' qualified_path: description: Qualified name with native language separators. type: - string - 'null' start_line: description: Inclusive 1-based start when available. format: int32 minimum: 1 type: - integer - 'null' symbol_ref: description: Opaque source symbol identity; retain unchanged. type: string required: - symbol_ref - name - qualified_path - kind - category - arity - is_public - file_path - start_line - end_line - parent_path type: object CodeIdentity: description: >- One side of source target resolution; unknown metadata is explicitly null. properties: commit_sha: description: Exact commit when known; preferred artifact pin. type: - string - 'null' git_ref: description: Requested or served ref according to this identity side. type: - string - 'null' kind: description: >- Original request kind on requested identity; null on concrete identities. type: - string - 'null' name: description: Canonical package name, null for repository targets. type: - string - 'null' registry: description: Canonical package registry, null for repository targets. type: - string - 'null' repo_url: description: Repository backing the target when known. type: - string - 'null' version: description: Concrete package version when resolved; null for repository targets. type: - string - 'null' required: - kind - registry - name - version - repo_url - git_ref - commit_sha type: object securitySchemes: bearer_auth: scheme: bearer type: http ````