> ## 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 documentation, code and symbols > Search documentation, source code, and symbols across packages, public repositories, and documentation sites. Results include matching text and source locations you can use to read the original page or file. Use this endpoint to discover relevant documentation and implementations across projects. Searches can return while indexing or searching is still in progress; use `GET /v1/searches/{search_ref}` to retrieve subsequent results and status. ## 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 | | --- | --- | --- | | `results` | Matching items, their text, relevance scores, source locations, and coverage information. | Yes | | `results.highlights` | Highlight locations within result titles and summaries. Also includes `results`. | No | | `results.*` | Results and highlights together. | No | | `sources` | Source status, applied filters, coverage, and suggested documentation sites. | No | | `progress` | Search request details, readiness counts, and available or suggested versions and refs. | No | ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json post /v1/searches 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/searches: post: tags: - Search summary: Search documentation, code and symbols description: > Search documentation, source code, and symbols across packages, public repositories, and documentation sites. Results include matching text and source locations you can use to read the original page or file. Use this endpoint to discover relevant documentation and implementations across projects. Searches can return while indexing or searching is still in progress; use `GET /v1/searches/{search_ref}` to retrieve subsequent results and status. ## 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 | | --- | --- | --- | | `results` | Matching items, their text, relevance scores, source locations, and coverage information. | Yes | | `results.highlights` | Highlight locations within result titles and summaries. Also includes `results`. | No | | `results.*` | Results and highlights together. | No | | `sources` | Source status, applied filters, coverage, and suggested documentation sites. | No | | `progress` | Search request details, readiness counts, and available or suggested versions and refs. | No | operationId: search parameters: - description: >- Comma-separated results/results.highlights/results.*/sources/progress; default results, 2048 decoded bytes. No arbitrary leaf masks. 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: results maxLength: 2048 type: string - 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 session attribution: trimmed printable ASCII, at most 128 bytes. Invalid optional values are dropped; no session is created. in: header name: X-GitHits-Session-ID required: false schema: type: string requestBody: content: application/json: example: limit: 10 query: name:run sources: - code - symbol targets: - name: serde registry: crates wait_timeout_ms: 20000 schema: $ref: '#/components/schemas/SearchRequest' required: true responses: '200': content: application/json: examples: active: value: completed: false expires_at: null query_warnings: [] result: null search_ref: opaque-search-ref selected_fields: - results status: pending targets: - coverage: null freshness: null indexing_ref: null requested: site:example.org/docs resolved_requested: site:example.org/docs served: null target_resolution: null all_groups: value: completed: false expires_at: null progress: elapsed_ms: 20 filters: category: null file_intent: null kind: null path_prefix: null public_only: null limit: 10 offset: 0 query: install requested_sources: - auto requested_targets: - git_ref: null name: null registry: null repo_url: null site: example.org/docs version: null sources: - docs target_mode: sites targets: - available_refs: [] available_versions: [] coverage: null freshness: stale indexing_ref: null requested: site:example.org/docs requested_ref_kind: null resolved_requested: site:example.org/docs served: site:example.org/docs suggested_refs: [] target_resolution: null targets_ready: 1 targets_total: 1 query_warnings: [] result: evidence_notice: null page: has_more: false limit: 10 offset: 0 returned: 1 partial_results: false query: install query_warnings: [] results: - coverage: null fresh_target_label: null freshness: null highlights: summary: - - 0 - 7 title: - - 0 - 7 id: opaque-page-id locator: commit_sha: null docs_read_target: https://example.org/docs/install end_line: null evidence_range: null file_path: null git_ref: null match_line: null package_name: null page_id: opaque-page-id registry: null repo_url: null repository_file_path: null requested_ref: null source_kind: crawled source_url: https://example.org/docs/install start_line: null symbol_ref: null version: null requested_target_label: site:example.org/docs result_type: documentation_page score: 0.5 served_target_label: site:example.org/docs summary: Install the package. target_label: site:example.org/docs title: Install source_status: - code_index_state: null coverage: null fresh_target_label: null ignored_filters: [] ignored_query_features: [] incompatible_filters: [] incompatible_query_features: [] note: null requested_target_label: site:example.org/docs result_count: 1 served_target_label: site:example.org/docs source: docs target_label: site:example.org/docs target_resolution: null sources: - docs search_ref: opaque-search-ref selected_fields: - results - results.highlights - sources - progress sources: evidence_notice: null partial_results: false source_status: - applied_filters: [] applied_query_features: [] code_index_state: null contributors: - commit_sha: null coverage: null freshness: current kind: docpack repository_url: null result_count: 1 site_key: example.org/docs site_url: https://example.org/docs state: searched coverage: null fresh_target_label: null ignored_filters: [] ignored_query_features: [] incompatible_filters: [] incompatible_query_features: [] note: null requested_target_label: site:example.org/docs result_count: 1 served_target_label: site:example.org/docs source: docs suggested_site_targets: [] suggested_site_targets_truncated: false target_label: site:example.org/docs target_resolution: null sources: - docs status: indexing targets: - coverage: null freshness: stale indexing_ref: null requested: site:example.org/docs resolved_requested: site:example.org/docs served: site:example.org/docs target_resolution: null empty: value: completed: true expires_at: null query_warnings: [] result: evidence_notice: null page: has_more: false limit: 10 offset: 0 returned: 0 partial_results: false query: install query_warnings: [] results: [] source_status: - code_index_state: null coverage: null fresh_target_label: null ignored_filters: [] ignored_query_features: [] incompatible_filters: [] incompatible_query_features: [] note: null requested_target_label: site:example.org/docs result_count: 0 served_target_label: site:example.org/docs source: docs target_label: site:example.org/docs target_resolution: null sources: - docs search_ref: null selected_fields: - results status: null targets: null highlights: value: completed: true expires_at: null query_warnings: [] result: evidence_notice: null page: has_more: false limit: 10 offset: 0 returned: 1 partial_results: false query: install query_warnings: [] results: - coverage: null fresh_target_label: null freshness: null highlights: summary: - - 0 - 7 title: - - 0 - 7 id: opaque-page-id locator: commit_sha: null docs_read_target: https://example.org/docs/install end_line: null evidence_range: null file_path: null git_ref: null match_line: null package_name: null page_id: opaque-page-id registry: null repo_url: null repository_file_path: null requested_ref: null source_kind: crawled source_url: https://example.org/docs/install start_line: null symbol_ref: null version: null requested_target_label: site:example.org/docs result_type: documentation_page score: 0.5 served_target_label: site:example.org/docs summary: Install the package. target_label: site:example.org/docs title: Install source_status: - code_index_state: null coverage: null fresh_target_label: null ignored_filters: [] ignored_query_features: [] incompatible_filters: [] incompatible_query_features: [] note: null requested_target_label: site:example.org/docs result_count: 1 served_target_label: site:example.org/docs source: docs target_label: site:example.org/docs target_resolution: null sources: - docs search_ref: null selected_fields: - results - results.highlights status: null targets: null immediate: value: completed: true expires_at: null query_warnings: [] result: evidence_notice: null page: has_more: false limit: 10 offset: 0 returned: 1 partial_results: false query: install query_warnings: [] results: - coverage: null fresh_target_label: null freshness: null id: opaque-page-id locator: commit_sha: null docs_read_target: https://example.org/docs/install end_line: null evidence_range: null file_path: null git_ref: null match_line: null package_name: null page_id: opaque-page-id registry: null repo_url: null repository_file_path: null requested_ref: null source_kind: crawled source_url: https://example.org/docs/install start_line: null symbol_ref: null version: null requested_target_label: site:example.org/docs result_type: documentation_page score: 0.5 served_target_label: site:example.org/docs summary: Install the package. target_label: site:example.org/docs title: Install source_status: - code_index_state: null coverage: null fresh_target_label: null ignored_filters: [] ignored_query_features: [] incompatible_filters: [] incompatible_query_features: [] note: null requested_target_label: site:example.org/docs result_count: 1 served_target_label: site:example.org/docs source: docs target_label: site:example.org/docs target_resolution: null sources: - docs search_ref: null selected_fields: - results status: null targets: null immediate_progress_absent: value: completed: true expires_at: null progress: null query_warnings: - The source normalized the query. result: null search_ref: null selected_fields: - progress status: null targets: null interim_atomic: value: completed: false expires_at: null query_warnings: [] result: evidence_notice: Refresh is pending; this atomic page may change. page: has_more: false limit: 10 offset: 0 returned: 1 partial_results: false query: install query_warnings: [] results: - coverage: null fresh_target_label: null freshness: null id: opaque-page-id locator: commit_sha: null docs_read_target: https://example.org/docs/install end_line: null evidence_range: null file_path: null git_ref: null match_line: null package_name: null page_id: opaque-page-id registry: null repo_url: null repository_file_path: null requested_ref: null source_kind: crawled source_url: https://example.org/docs/install start_line: null symbol_ref: null version: null requested_target_label: site:example.org/docs result_type: documentation_page score: 0.5 served_target_label: site:example.org/docs summary: Install the package. target_label: site:example.org/docs title: Install source_status: - code_index_state: null coverage: null fresh_target_label: null ignored_filters: [] ignored_query_features: [] incompatible_filters: [] incompatible_query_features: [] note: null requested_target_label: site:example.org/docs result_count: 1 served_target_label: site:example.org/docs source: docs target_label: site:example.org/docs target_resolution: null sources: - docs search_ref: opaque-search-ref selected_fields: - results status: indexing targets: - coverage: null freshness: stale indexing_ref: null requested: site:example.org/docs resolved_requested: site:example.org/docs served: site:example.org/docs target_resolution: null partial: value: completed: false expires_at: null query_warnings: [] result: evidence_notice: Refresh is pending; this atomic page may change. page: has_more: false limit: 10 offset: 0 returned: 1 partial_results: true query: install query_warnings: [] results: - coverage: null fresh_target_label: null freshness: null id: opaque-page-id locator: commit_sha: null docs_read_target: https://example.org/docs/install end_line: null evidence_range: null file_path: null git_ref: null match_line: null package_name: null page_id: opaque-page-id registry: null repo_url: null repository_file_path: null requested_ref: null source_kind: crawled source_url: https://example.org/docs/install start_line: null symbol_ref: null version: null requested_target_label: site:example.org/docs result_type: documentation_page score: 0.5 served_target_label: site:example.org/docs summary: Install the package. target_label: site:example.org/docs title: Install source_status: - code_index_state: null coverage: null fresh_target_label: null ignored_filters: [] ignored_query_features: [] incompatible_filters: [] incompatible_query_features: [] note: null requested_target_label: site:example.org/docs result_count: 1 served_target_label: site:example.org/docs source: docs target_label: site:example.org/docs target_resolution: null sources: - docs search_ref: opaque-search-ref selected_fields: - results status: indexing targets: - coverage: null freshness: stale indexing_ref: null requested: site:example.org/docs resolved_requested: site:example.org/docs served: site:example.org/docs target_resolution: null progress_only: value: completed: false expires_at: null progress: elapsed_ms: 20 filters: category: null file_intent: null kind: null path_prefix: null public_only: null limit: 10 offset: 0 query: install requested_sources: - auto requested_targets: - git_ref: null name: null registry: null repo_url: null site: example.org/docs version: null sources: - docs target_mode: sites targets: - available_refs: [] available_versions: [] coverage: null freshness: null indexing_ref: null requested: site:example.org/docs requested_ref_kind: null resolved_requested: site:example.org/docs served: null suggested_refs: [] target_resolution: null targets_ready: 0 targets_total: 1 query_warnings: [] result: null search_ref: opaque-search-ref selected_fields: - progress status: pending targets: - coverage: null freshness: null indexing_ref: null requested: site:example.org/docs resolved_requested: site:example.org/docs served: null target_resolution: null selected_snapshot_unavailable: value: completed: false expires_at: null query_warnings: [] result: null search_ref: opaque-search-ref selected_fields: - results - sources sources: null status: pending targets: - coverage: null freshness: null indexing_ref: null requested: site:example.org/docs resolved_requested: site:example.org/docs served: null target_resolution: null sources_only: value: completed: true expires_at: null query_warnings: [] result: null search_ref: null selected_fields: - sources sources: evidence_notice: null partial_results: false source_status: - applied_filters: [] applied_query_features: [] code_index_state: null contributors: - commit_sha: null coverage: null freshness: current kind: docpack repository_url: null result_count: 1 site_key: example.org/docs site_url: https://example.org/docs state: searched coverage: null fresh_target_label: null ignored_filters: [] ignored_query_features: [] incompatible_filters: [] incompatible_query_features: [] note: null requested_target_label: site:example.org/docs result_count: 1 served_target_label: site:example.org/docs source: docs suggested_site_targets: [] suggested_site_targets_truncated: false target_label: site:example.org/docs target_resolution: null sources: - docs status: null targets: null terminal_retained: value: completed: false expires_at: null query_warnings: [] result: evidence_notice: Refresh is pending; this atomic page may change. page: has_more: false limit: 10 offset: 0 returned: 1 partial_results: false query: install query_warnings: [] results: - coverage: null fresh_target_label: null freshness: null id: opaque-page-id locator: commit_sha: null docs_read_target: https://example.org/docs/install end_line: null evidence_range: null file_path: null git_ref: null match_line: null package_name: null page_id: opaque-page-id registry: null repo_url: null repository_file_path: null requested_ref: null source_kind: crawled source_url: https://example.org/docs/install start_line: null symbol_ref: null version: null requested_target_label: site:example.org/docs result_type: documentation_page score: 0.5 served_target_label: site:example.org/docs summary: Install the package. target_label: site:example.org/docs title: Install source_status: - code_index_state: null coverage: null fresh_target_label: null ignored_filters: [] ignored_query_features: [] incompatible_filters: [] incompatible_query_features: [] note: null requested_target_label: site:example.org/docs result_count: 1 served_target_label: site:example.org/docs source: docs target_label: site:example.org/docs target_resolution: null sources: - docs search_ref: opaque-search-ref selected_fields: - results status: timeout targets: - coverage: null freshness: stale indexing_ref: null requested: site:example.org/docs resolved_requested: site:example.org/docs served: site:example.org/docs target_resolution: null schema: $ref: '#/components/schemas/SearchResponse' description: Source-qualified immediate, interim or terminal observation headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: 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 headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: 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: 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 or TERMS_ACCEPTANCE_REQUIRED; safe terms/acceptance links may be supplied. headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: Trace identity; also problem.instance. schema: type: string '404': content: application/problem+json: example: code: REF_NOT_FOUND detail: The requested Git reference was not found. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 404 title: Git reference not found type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- REF_NOT_FOUND, REPOSITORY_NOT_FOUND, PACKAGE_NOT_FOUND, VERSION_NOT_FOUND or NO_RELEASED_VERSIONS. headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: 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: AMBIGUOUS_REF detail: The requested Git reference is ambiguous. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 422 title: Ambiguous Git reference type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: AMBIGUOUS_REF or UNSUPPORTED_PACKAGE_VARIANTS. headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: 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: Validated delay seconds or HTTP date. schema: type: string X-Request-ID: description: 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 headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: 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 headers: Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: Trace identity; also problem.instance. schema: type: string security: - bearer_auth: [] components: schemas: SearchRequest: additionalProperties: false description: >- Strict initial search input; selectors are parsed by HTTP before execution. properties: allow_partial_results: default: false description: >- Permit a served subset of runnable pairs; false keeps runnable-pair atomicity even during background refresh. type: boolean filters: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchFilters' description: >- Omission/null means no structured filters. Use upstream : query qualifiers for those capabilities. limit: default: 10 description: >- Result page cap, 1..100. This does not bound all upstream preparation work. format: int32 maximum: 100 minimum: 1 type: integer offset: default: 0 description: Nonnegative offset. A later page requires a fresh initial search. format: int32 maximum: 2147483647 minimum: 0 type: integer query: description: >- Nonblank query, trimmed once. Qualifiers and boolean/phrase syntax are parsed upstream. minLength: 1 type: string sources: description: >- Omission/null means AUTO; explicit docs/code/symbol lists must be nonempty. AUTO is not an explicit selector. items: $ref: '#/components/schemas/SearchInputSource' type: - array - 'null' targets: description: >- One through twenty structured targets. Exact normalized duplicates are removed. items: $ref: '#/components/schemas/SearchTarget' maxItems: 20 minItems: 1 type: array wait_timeout_ms: default: 20000 description: >- One upstream wait, 0..60000 ms; total transport deadline also includes configured request budget. format: int32 maximum: 60000 minimum: 0 type: integer required: - query - targets type: object SearchResponse: description: >- One canonical source observation; a reference does not imply active work. properties: completed: description: >- Source POST completion flag; GET is true exactly for completed status. Other terminal statuses remain false. type: boolean expires_at: description: >- Source expiration timestamp, not a gateway retention guarantee or exact 410 boundary. type: - string - 'null' progress: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchProgressDetails' description: >- Omitted when unselected; null when selected without inline progress. query_warnings: description: >- Parser warnings from the result or inline progress, never inferred from query text. items: type: string type: array result: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchEvidence' description: >- Latest complete page; null when results is unselected or no page is available. Inspect `selected_fields`. search_ref: description: >- Effective-user-owned opaque reference; null for an immediate unreferenced result. type: - string - 'null' selected_fields: description: >- Canonical expanded selected groups in stable order; disambiguates unselected result:null. items: $ref: '#/components/schemas/SearchGroup' type: array sources: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchSources' description: >- Omitted when unselected; null when selected without a source snapshot. status: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchSessionStatus' description: >- Explicit source session state, null when the initial operation supplies none. targets: description: >- Concise readiness/provenance supplied by inline progress; null when absent. items: $ref: '#/components/schemas/SearchTargetProgress' type: - array - 'null' required: - completed - selected_fields - status - search_ref - expires_at - query_warnings - targets - result 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 SearchFilters: additionalProperties: false description: >- Search filters. Check source diagnostics to see which filters were applied or ignored. properties: category: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchCategory' description: Broad symbol category; docs disclose ignored semantics. file_intent: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchFileIntent' description: >- Code/symbol file intent. Non-production intents make docs incompatible. kind: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchKind' description: Symbol kind; docs disclose ignored semantics. path_prefix: description: Code path prefix; docs and symbols disclose ignored semantics. type: - string - 'null' public_only: description: >- True restricts explicit symbols to public definitions; false is equivalent to omission. type: - boolean - 'null' type: object SearchInputSource: description: >- Content sources to search. Omission selects documentation and code for packages or repositories, and documentation for sites. enum: - docs - code - symbol type: string SearchTarget: description: >- Exactly one addressing mode; unrelated keys, including null keys, are rejected. oneOf: - description: >- Package artifact scope; registry/name required, version retains latest intent when absent. properties: name: maxLength: 255 minLength: 1 type: string registry: enum: - npm - pypi - hex - crates - vcpkg - zig - nuget - maven - packagist - rubygems - go - swift type: string version: type: - string - 'null' required: - registry - name type: object - description: Repository scope; omitted ref retains default-branch intent. properties: git_ref: type: - string - 'null' repo_url: minLength: 1 type: string required: - repo_url type: object - description: >- Standalone documentation scope, host[/path-prefix] or site:host[/path-prefix]. properties: site: minLength: 1 type: string required: - site type: object SearchProgressDetails: description: >- Source-owned request context and readiness for the immutable search session. properties: elapsed_ms: description: Source elapsed milliseconds, not a duration estimate. format: int32 type: integer filters: $ref: '#/components/schemas/SearchEffectiveFilters' description: Structured filter context of the original request. limit: description: Original page limit, null on legacy sessions. format: int32 type: - integer - 'null' offset: description: Original page offset, null on legacy sessions; GET cannot change it. format: int32 type: - integer - 'null' query: description: Original validated query; never interpreted by the gateway. type: string requested_sources: description: Original source intent; can include AUTO. items: $ref: '#/components/schemas/SearchSource' type: array requested_targets: description: >- Source-canonical request coordinates; nullable fields distinguish target modes. items: $ref: '#/components/schemas/SearchRequestedTarget' type: array sources: description: Effective source selection. items: $ref: '#/components/schemas/SearchSource' type: array target_mode: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchTargetMode' description: Legacy sessions may lack target mode. targets: description: Qualified readiness plus indexed and suggested alternatives. items: $ref: '#/components/schemas/SearchTargetDetails' type: array targets_ready: description: Ready targets according to source serving policy. format: int32 type: integer targets_total: description: Source target count, not a gateway job count. format: int32 type: integer required: - targets_total - targets_ready - elapsed_ms - query - sources - requested_sources - target_mode - requested_targets - filters - limit - offset - targets type: object SearchEvidence: description: >- Source-reported `DiscoverySearchResult` evidence; nullable facts remain explicitly null. properties: evidence_notice: description: >- Notice when pending or required work means disclosed snapshots may change; callers may follow searchRef while the session is nonterminal or retry with a later fresh search after a terminal readiness outcome type: - string - 'null' page: $ref: '#/components/schemas/SearchPage' description: Pagination metadata for the merged result set partial_results: description: >- True only when allowPartialResults was set and this payload serves some runnable target/source pairs while omitting others. This is not a progress signal; use the enclosing AsyncDiscoverySearchResult.completed or DiscoverySearchProgress.status together with sourceStatus. type: boolean query: description: >- The original validated query string submitted for this discovery search type: string query_warnings: description: >- Parser warnings recorded while normalizing malformed or lossy query input items: type: string type: array results: description: Merged, typed discovery hits for the requested page items: $ref: '#/components/schemas/SearchHit' type: array source_status: description: >- Per-target, per-source status explaining readiness and partial results items: $ref: '#/components/schemas/SearchSourceStatus' type: array sources: description: The effective sources searched after AUTO expansion items: $ref: '#/components/schemas/SearchSource' type: array required: - query - query_warnings - sources - results - page - partial_results - source_status - evidence_notice type: object SearchGroup: description: Atomic evidence groups, independent of the transport protocol. enum: - results - results.highlights - sources - progress type: string SearchSources: description: >- Snapshot diagnostics independently useful without transferring hit bodies. properties: evidence_notice: description: Source uncertainty notice; null when absent. type: - string - 'null' partial_results: description: True means omitted runnable pairs, not background work alone. type: boolean source_status: description: >- Qualified source/target pairs, including incompatible and unavailable pairs. items: $ref: '#/components/schemas/SearchSourceDetails' type: array sources: description: Effective sources after AUTO expansion. items: $ref: '#/components/schemas/SearchSource' type: array required: - sources - source_status - partial_results - evidence_notice type: object SearchSessionStatus: description: Canonical `SearchSessionStatus` values, serialized as `snake_case`. enum: - pending - indexing - searching - completed - deferred - timeout - failed type: string SearchTargetProgress: description: >- Source-reported `DiscoveryTargetProgress` evidence; nullable facts remain explicitly null. properties: coverage: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchCoverage' description: >- Advisory coverage for selected package documentation targets when latest progress has docs metadata freshness: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchState' description: >- Freshness-aware code target lifecycle. `PROVISIONAL` means exact-SHA evidence is queryable while indexing continues; prefer this over legacy indexing status for code progress. indexing_ref: description: >- Git ref queued or running for fresher code evidence when indexing is active, including provisional exact-SHA serving type: - string - 'null' requested: description: >- Original target label requested by the caller, e.g. `npm:lodash@4.17.21` or `owner/repo@main` type: string resolved_requested: description: Resolved requested package version or repository ref when known type: - string - 'null' served: description: >- Exact target that has served evidence so far. Provisional exact-SHA evidence may be served while indexing continues; null while indexing if no evidence has served. type: - string - 'null' target_resolution: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchResolution' description: >- Requested/resolved/served provenance for this target. Null for legacy or terminal entries where resolution details were not available. required: - requested - resolved_requested - served - freshness - indexing_ref - target_resolution - coverage type: object SearchCategory: description: Canonical `SymbolCategory` values, serialized as `snake_case`. enum: - callable - type - module - data - documentation type: string SearchFileIntent: description: Canonical `FileIntent` values, serialized as `snake_case`. enum: - production - test - benchmark - example - generated - fixture - build - vendor type: string SearchKind: description: Canonical `SymbolKind` values, serialized as `snake_case`. enum: - function - method - constructor - getter - setter - operator - class - interface - trait - struct - enum - record - protocol - extension - delegate - mixin - actor - annotation - type - module - namespace - package - object - field - property - event - constant - doc_section type: string SearchEffectiveFilters: description: >- Complete source filter context; all members are present, with null for omission. properties: category: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchCategory' description: Symbol category. file_intent: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchFileIntent' description: Source file intent. kind: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchKind' description: Symbol kind. path_prefix: description: Source path restriction. type: - string - 'null' public_only: description: Public-symbol restriction. type: - boolean - 'null' required: - kind - category - path_prefix - file_intent - public_only type: object SearchSource: description: Canonical `DiscoverySearchSource` values, serialized as `snake_case`. enum: - auto - docs - code - symbol type: string SearchRequestedTarget: description: >- Original source-normalized structured target; do not rewrite it to caller spelling. properties: git_ref: description: Requested repository ref intent. type: - string - 'null' name: description: Canonical package name. type: - string - 'null' registry: description: Canonical registry; null for repository and site targets. enum: - npm - pypi - hex - crates - vcpkg - zig - nuget - maven - packagist - rubygems - go - swift - null type: - string - 'null' repo_url: description: Requested repository URL. type: - string - 'null' site: description: Standalone documentation scope. type: - string - 'null' version: description: Requested package version intent. type: - string - 'null' required: - registry - name - version - repo_url - git_ref - site type: object SearchTargetMode: description: Canonical `DiscoveryTargetMode` values. enum: - packages - repo - mixed - sites type: string SearchTargetDetails: allOf: - $ref: '#/components/schemas/SearchTargetProgress' - properties: available_refs: description: Immediately indexed repository-ref alternatives, possibly empty. items: $ref: '#/components/schemas/SearchAvailableVersion' type: array available_versions: description: >- Immediately indexed package-version alternatives, possibly empty. items: $ref: '#/components/schemas/SearchAvailableVersion' type: array requested_ref_kind: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchRequestedRefKind' description: >- Original ref intent; null for sites or unavailable legacy context. suggested_refs: description: >- Suggestions may still require indexing; an empty list is not an exhaustive claim. items: $ref: '#/components/schemas/SearchAvailableVersion' type: array required: - requested_ref_kind - available_versions - available_refs - suggested_refs type: object description: >- Readiness details, with the same mandatory provenance as concise target progress. SearchPage: description: >- Source-reported `DiscoveryPageInfo` evidence; nullable facts remain explicitly null. properties: has_more: description: hasMore reported by the source. type: boolean limit: description: limit reported by the source. format: int32 type: integer offset: description: offset reported by the source. format: int32 type: integer returned: description: returned reported by the source. format: int32 type: integer required: - offset - limit - returned - has_more type: object SearchHit: description: >- Source-reported `DiscoverySearchHit` evidence; nullable facts remain explicitly null. properties: coverage: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchCoverage' description: >- Coverage for the crawled documentation site that served this hit. Null for repo-backed docs and code hits. fresh_target_label: description: Fresh exact target label currently searched or being indexed type: - string - 'null' freshness: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchState' description: >- Freshness state of the served evidence for this hit; `PROVISIONAL` means exact-SHA evidence is queryable while indexing continues highlights: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchHighlights' description: >- Highlight spans for display fields so clients can emphasize matches without reparsing the query id: description: id reported by the source. type: string locator: $ref: '#/components/schemas/SearchLocator' description: Locator data used for follow-up open/read/trace actions requested_target_label: description: Original requested target label before backend resolution type: - string - 'null' result_type: $ref: '#/components/schemas/SearchResultType' description: resultType reported by the source. score: description: >- Monotonic display score for this fused result page. Not comparable across queries, raw backend scores, or raw RRF values. format: double type: - number - 'null' served_target_label: description: Exact target label that served this hit type: - string - 'null' summary: description: >- Short display summary for the hit. Repository code/doc previews and locator ranges use aigrep focus metadata when available; otherwise both use the same bounded 11-line fallback. If hydration returns no content, the summary is empty and the locator keeps the declared range for follow-up reads. Previews are capped at 16 KiB and keep visible evidence when truncated. type: - string - 'null' target_label: description: >- Human-readable target label, e.g. npm:lodash@4.17.21 or owner/repo@main type: string title: description: Primary display title for the hit type: - string - 'null' required: - id - result_type - target_label - requested_target_label - fresh_target_label - served_target_label - freshness - title - summary - score - coverage - locator type: object SearchSourceStatus: description: >- Source-reported `DiscoverySourceStatus` evidence; nullable facts remain explicitly null. properties: code_index_state: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchState' description: >- Code freshness state for repo-backed sources when applicable; `PROVISIONAL` means exact-SHA evidence is queryable while indexing continues coverage: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchCoverage' description: >- Coverage for the selected docs target/source. May describe withheld transient partial data. fresh_target_label: description: Fresh exact target label currently searched or being indexed type: - string - 'null' ignored_filters: description: >- Filters ignored for this source because they are orthogonal or unsupported items: type: string type: array ignored_query_features: description: >- Parsed query features this source ignored because they were orthogonal or unsupported items: type: string type: array incompatible_filters: description: Filters that make this source incompatible with the current request items: type: string type: array incompatible_query_features: description: >- Parsed query features that make this source incompatible with the current request items: type: string type: array note: description: Explanatory note for incompatible, unsupported, or partial states type: - string - 'null' requested_target_label: description: Original requested target label before backend resolution type: - string - 'null' result_count: description: >- Number of returned hits from this source for the target on the current page format: int32 type: - integer - 'null' served_target_label: description: >- Exact target label that served returned evidence for this source/target type: - string - 'null' source: $ref: '#/components/schemas/SearchSource' description: source reported by the source. target_label: description: >- Human-readable target label, e.g. npm:lodash@4.17.21 or owner/repo@main type: string target_resolution: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchResolution' description: >- Requested/resolved/served provenance for this source target, when target resolution was available required: - source - target_label - requested_target_label - fresh_target_label - served_target_label - code_index_state - coverage - result_count - ignored_filters - incompatible_filters - ignored_query_features - incompatible_query_features - note - target_resolution type: object SearchSourceDetails: allOf: - $ref: '#/components/schemas/SearchSourceStatus' - properties: applied_filters: description: Structured filters this source actually applied. items: type: string type: array applied_query_features: description: Parsed query features this source actually applied. items: type: string type: array contributors: description: Bounded documentation contributors; empty for non-docs sources. items: $ref: '#/components/schemas/SearchContributor' type: array suggested_site_targets: description: >- Bounded documentation scopes suggested by the source, possibly empty. items: type: string type: array suggested_site_targets_truncated: description: True means the suggestions are not exhaustive. type: boolean required: - applied_filters - applied_query_features - suggested_site_targets - suggested_site_targets_truncated - contributors type: object description: >- Atomic diagnostics; qualification deliberately repeats the result group's facts when both are selected. SearchCoverage: description: >- Source-reported `DocCoverage` evidence; nullable facts remain explicitly null. properties: artifact_overflow_page_count: description: >- Exportable crawled pages omitted from the served docpack by its artifact-size bound format: int32 type: - integer - 'null' coverage_reason: description: Machine-readable reason for capped coverage, when applicable type: - string - 'null' coverage_state: $ref: '#/components/schemas/SearchCoverageState' description: Normalized coverage state from `PkgSeer`'s database estimated_total_pages: description: >- Estimated total pages, when known from future sitemap-based discovery format: int32 type: - integer - 'null' frontier_remaining: description: >- Discovered-but-unserved URL count; may be null when a live frontier count is not part of the selected published snapshot. format: int32 type: - integer - 'null' note: description: Backend-owned note suitable for CLI/MCP rendering type: - string - 'null' pages_crawled: description: Number of pages indexed for the site crawl generation format: int32 type: integer required: - coverage_state - coverage_reason - pages_crawled - frontier_remaining - artifact_overflow_page_count - estimated_total_pages - note type: object SearchState: description: Canonical `CodeIndexState` values, serialized as `snake_case`. enum: - current - stale - provisional - indexing - pending - failed - not_found - unresolvable type: string SearchResolution: description: >- Source-reported `TargetResolution` evidence; nullable facts remain explicitly null. properties: freshness: description: >- Machine-readable freshness state: `current`, `fallback_recent`, `provisional`, `indexing`, or `unavailable`. `provisional` means exact-SHA evidence is queryable while indexing continues and final evidence may replace or enrich it. type: - string - 'null' freshness_reason: description: >- Machine-readable reason for the freshness state, for example `exact_current`, `exact_provisional`, `latest_version_indexing`, `no_current_fallback`, `ref_resolution_deferred`, `same_ref_refresh_coalesced`, or `ref_unresolvable`. type: - string - 'null' indexing_ref: description: >- Opaque ref for the active indexing job or progress owner. It may be present with `indexing`, `provisional`, or `fallback_recent` freshness; a same-ref coalesced job may name work whose SHA differs from `resolvedRequested.commitSha`. type: - string - 'null' requested: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchIdentity' description: Original package or repository target requested by the caller. resolved_requested: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchIdentity' description: >- Concrete target provenance `PkgSeer` resolved for the request. This may differ from `requested`, and may name a fresher SHA that was not admitted because an active same-ref job owns the work. served: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchIdentity' description: >- Exact artifact that served returned evidence. Provisional exact-SHA evidence may be served while indexing continues; null when no evidence was served yet, such as active indexing without fallback. required: - requested - resolved_requested - served - freshness - freshness_reason - indexing_ref type: object SearchAvailableVersion: description: >- A source-advertised alternative; a ref-only row must not become an invented package version. properties: ref: description: Exact source ref spelling. type: string version: description: >- Package version when known; otherwise use repository addressing for the ref. type: - string - 'null' required: - version - ref type: object SearchRequestedRefKind: description: Canonical `DiscoveryRequestedRefKind` values. enum: - omitted_version - latest_version - exact_version - default_branch - head - branch - sha type: string SearchHighlights: description: >- Source-reported `DiscoveryHitHighlights` evidence; nullable facts remain explicitly null. properties: summary: description: >- Compact `[start, end)` character-offset spans within the summary field items: items: format: int32 type: integer type: array type: - array - 'null' title: description: Compact `[start, end)` character-offset spans within the title field items: items: format: int32 type: integer type: array type: - array - 'null' required: - title - summary type: object SearchLocator: description: >- Source-reported `DiscoveryLocator` evidence; nullable facts remain explicitly null. properties: commit_sha: description: >- Resolved commit SHA for the served repo-backed result when available. Use this for drift-free session replay and exact code hydration. type: - string - 'null' docs_read_target: description: >- Optional emitted docs-read target, populated for documentation page and repository doc hits; null for repository code and symbol hits type: - string - 'null' end_line: description: 1-indexed end line for repository or documentation source evidence format: int32 type: - integer - 'null' evidence_range: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchEvidenceRange' description: >- Explicit focused source evidence for repository hits. Legacy startLine/endLine retain the same coordinates. file_path: description: >- File path relative to the declared target. Package hits exclude the package repository subpath; repository hits are repository-root relative. Pass this path unchanged to target-scoped exact file reads. type: - string - 'null' git_ref: description: >- Exact Git ref used to serve the repo-backed result. This is the follow-up ref for exact file reads and is usually a commit SHA. type: - string - 'null' match_line: description: >- 1-indexed source line selected by the search backend for the visible snippet when available format: int32 type: - integer - 'null' package_name: description: >- Package name for package-backed hits or resolved repo-backed package attribution type: - string - 'null' page_id: description: >- Opaque documentation page identifier for doc-read follow-up. Repo-backed page IDs are snapshot-pinned. type: - string - 'null' registry: description: >- Package registry for package-backed hits or resolved repo-backed package attribution type: - string - 'null' repo_url: description: Repository URL for repo-backed hits type: - string - 'null' repository_file_path: description: >- Repository-root-relative file path for repo-backed file hits. Pair this with repoUrl and commitSha or gitRef for exact repository reads. type: - string - 'null' requested_ref: description: >- Requested or display Git ref that produced the repo-backed result. This preserves user-facing provenance separately from gitRef. type: - string - 'null' source_kind: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchSourceKind' description: Typed documentation source kind for documentation hits source_url: description: >- Source URL for documentation hits. Repo-backed hits use an exact snapshot blob URL; crawled hits use the crawl origin URL. type: - string - 'null' start_line: description: 1-indexed start line for repository or documentation source evidence format: int32 type: - integer - 'null' symbol_ref: description: Stable symbol reference when the hit resolves to a known symbol type: - string - 'null' version: description: >- Package version or resolved indexed ref when package attribution exists type: - string - 'null' required: - registry - package_name - version - page_id - docs_read_target - source_kind - source_url - repo_url - git_ref - commit_sha - requested_ref - file_path - repository_file_path - start_line - end_line - evidence_range - match_line - symbol_ref type: object SearchResultType: description: Canonical `DiscoveryResultType` values, serialized as `snake_case`. enum: - documentation_page - repository_symbol - repository_code - repository_doc type: string SearchContributor: description: >- A bounded contributor identity and its readiness; no local crawl or enrichment is performed. properties: commit_sha: description: Exact served commit when known. type: - string - 'null' coverage: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchCoverage' description: Coverage/caps; null does not mean complete. freshness: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchContributorFreshness' description: Unknown freshness is null. kind: $ref: '#/components/schemas/SearchContributorKind' description: Repository documentation or a published documentation pack. repository_url: description: >- Repository identity, null for an unavailable/non-repository contributor. type: - string - 'null' result_count: description: Source-reported contribution count. format: int32 type: integer site_key: description: Opaque documentation scope key when known. type: - string - 'null' site_url: description: Source documentation URL when known. type: - string - 'null' state: $ref: '#/components/schemas/SearchContributorState' description: Source observation; ready does not claim searched. required: - kind - state - freshness - result_count - repository_url - commit_sha - site_key - site_url - coverage type: object SearchCoverageState: description: Canonical `DocCoverageState` values, serialized as `snake_case`. enum: - none - partial - capped - complete type: string SearchIdentity: description: >- Source-reported `TargetResolutionIdentity` evidence; nullable facts remain explicitly null. properties: commit_sha: description: >- Commit SHA for this identity when known. Clients should prefer this over `gitRef` for exact artifact identity when present. type: - string - 'null' git_ref: description: >- Git ref resolved, indexed, or served for this identity. For package targets this is the repo ref backing the package version. type: - string - 'null' kind: description: >- Original request kind for `TargetResolution.requested`, such as `package_exact_version`, `package_omitted_version`, `repo_branch`, `repo_default_branch`, `repo_head`, or `repo_sha`. Null on resolved/served identities. type: - string - 'null' package_name: description: Package name for package-scoped identities. type: - string - 'null' registry: description: Package registry for package-scoped identities. type: - string - 'null' repo_url: description: Repository URL backing this identity, when known. type: - string - 'null' version: description: Package version for package-scoped identities, when known. type: - string - 'null' required: - kind - registry - package_name - version - repo_url - git_ref - commit_sha type: object SearchEvidenceRange: description: >- Source-reported `DiscoveryEvidenceRange` evidence; nullable facts remain explicitly null. properties: end_line: description: Inclusive 1-indexed end line format: int32 type: integer match_line: description: >- 1-indexed source line selected by the search backend for the visible snippet format: int32 type: - integer - 'null' match_spans_truncated: description: >- Whether the authoritative match-span set was capped by the search backend type: boolean range_kind: description: Backend classification of the focused evidence range type: - string - 'null' start_line: description: Inclusive 1-indexed start line format: int32 type: integer required: - start_line - end_line - match_line - range_kind - match_spans_truncated type: object SearchSourceKind: description: Canonical `DocSourceKind` values, serialized as `snake_case`. enum: - crawled - repository type: string SearchContributorFreshness: description: Canonical `DiscoveryEvidenceFreshness` values. enum: - current - stale - provisional type: string SearchContributorKind: description: Canonical `DiscoveryDocumentationContributorKind` values. enum: - repository_docs - docpack type: string SearchContributorState: description: Canonical `DiscoveryDocumentationContributorState` values. enum: - searched - ready - pending - unavailable type: string securitySchemes: bearer_auth: scheme: bearer type: http ````