> ## 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. # Read documentation or source code > Read a documentation page or an exact source file. The response identifies which kind was returned and includes the information needed to cite the page, package version, or repository commit. ## Choose a target For documentation, pass a page's `docs_read_target` as `target` and omit `path`. Package documentation from `GET /v1/packages/{registry}/{name}/docs` and documentation results from `POST /v1/searches` provide this value. An HTTP(S) target can include a fragment to select one indexed section. For source code, pass both `target` and the exact target-relative file `path`. Use a package target such as `crates:serde@1.0.0`, or a supported public repository locator such as `https://github.com/serde-rs/serde@master`. Find paths with `GET /v1/code/files`, `POST /v1/code/grep`, or a code result from `POST /v1/searches`. Repository refs use `@`; a literal `#` is not supported in a code target. `target` is a query value. Encode a literal `+` as `%2B` and a documentation fragment marker as `%23`; an unencoded `+` is decoded as a space. ## Interpret the result Branch on the required `kind` field: | `kind` | Result | | --- | --- | | `documentation` | Page identity, reusable `docs_read_target`, and exact crawled or repository source details. | | `code` | Target-relative and repository-root paths, binary status, and the requested, resolved, and served package version or repository commit. | Documentation and source files use 1-based inclusive line ranges. If no bounds are supplied, the complete page or file is returned; for a documentation URL, its fragment selects an indexed section. Explicit bounds override that fragment. An `end_line` past the end is clamped. Empty documentation has null bounds, while an empty text file has bounds `0`–`0`; binary code has null content and bounds. Explicit bounds require the `content` field group. ## Selector catalogue Use these selectors with the `fields` query parameter. Supplying `fields` replaces the defaults; `kind` and the identity and provenance fields for the returned branch remain present. See [Choose what the response includes](https://docs.githits.com/api/requests-and-responses#choose-what-the-response-includes) for the shared selection rules. | Selector | Documentation result | Code result | Default | | --- | --- | --- | --- | | `metadata` | Title, format, breadcrumbs, update and source context, and package ownership when known. | Detected language and total line count. | Yes | | `content` | Body, total lines, returned range, and resolved section anchor. | Body and returned range; values are null for binary files. | Yes | ## Wait for code indexing `wait_timeout_ms` controls how long to wait for code preparation, from `0` to `60000` milliseconds; the default is `20000`. Use `0` when the caller prefers an immediate `503 PACKAGE_INDEXING` response if code is not ready. Documentation reads do not use this budget for indexing. For failures, branch on the problem response's stable `code`. Correct malformed locators, paths, ranges, or selectors after `400 VALIDATION_ERROR`. A `404` means the requested page, file, package, version, repository, or ref was not found. A `409 DOCUMENTATION_PAGE_OWNER_CONFLICT` means the URL belongs to another documentation corpus. A `422` means the target exists but the requested section, file, package variant, or repository ref cannot produce one result. Respect `Retry-After` after `429 RATE_LIMITED`; retry `503 PACKAGE_INDEXING` later or with a positive wait budget. A `504 TIMEOUT` does not guarantee that preparation stopped. ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json get /v1/read openapi: 3.1.0 info: description: >- Explore package metadata, security advisories, dependencies, documentation and source code with the GitHits API. ## Choose an operation | Task | Operations | | --- | --- | | Inspect a package | Release metadata, vulnerabilities and dependencies | | Review releases or upgrades | Changelog and batch upgrade reviews | | Read documentation or source code | Use the unified read operation; package documentation and code inventory operations provide exact targets and paths | | Navigate source code | List files 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 | | Generate an SBOM | Upload manifests and lockfiles to receive a CycloneDX, SPDX or text inventory | | Find a language identifier | Search supported programming languages | ## Authenticate and send requests The production API origin is `https://api.githits.dev`; development uses `https://api-dev.githits.dev`. Examples target production. Replace `` with your GitHits token. Send the token in `Authorization: Bearer `. JSON request bodies use `Content-Type: application/json`; public JSON field names use `snake_case`. Standard SBOM documents retain their format's field names. Percent-encode path parameters such as package names as one path segment, including any embedded slash. The unified read target is a query value: encode a literal plus sign as `%2B` and a literal fragment marker as `%23`; ordinary form decoding interprets `+` as a space. Each operation documents its accepted parameters and encoding rules. ## Select the data you need Where supported, `fields` is a comma-separated **query parameter**, including on POST requests. Omit it to use the operation's defaults. Supplying it replaces those defaults; required identity and information needed to interpret the result remain present. A **selector** names a supported **group** of response fields. Groups are atomic: their members are selected together. A **wildcard bundle**, such as `vulnerabilities.*`, selects only the groups listed for that bundle. A bare group does not automatically include nested groups. Arbitrary subfields and undeclared wildcards are not supported. Each operation lists its selectors, defaults, dependencies and the data they return. Selection can reduce transferred data without reducing the work needed to produce it; consult its parameter and response field documentation. Small fixed responses do not offer `fields`. ## Interpret responses and errors An omitted optional field can mean unselected or unavailable data, according to the operation's contract. Null has an operation-specific meaning: it can mark unavailable or inapplicable data, or an unselected search result. Empty arrays, zero and false are values, not substitutes for unavailable data. Always retain the result's completeness and freshness information when displaying or processing it. **Requested** identity records caller intent; **resolved** identity records what that intent resolved to; **served** identity identifies the artifact that produced the response. These can differ while indexing or refresh work continues. Use served identity when an exact follow-up read is required, preserving package-relative or repository-relative path scope. Errors normally use `application/problem+json`. Branch on the stable `code`, not the human-readable `detail`. Include `X-Request-ID` when reporting a problem; error `instance` matches that ID. Respect `Retry-After` when present. If request identity cannot be created, the response is an empty HTTP 500 without a request ID. Responses use `Cache-Control: no-store`. 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 with exact source locators and availability information. name: Documentation - description: >- Enumerate files and grep within a package or repository. Responses retain served identity, indexing state and completeness information. name: Code - description: >- Read an exact documentation page or source file and retain the page, package-version or repository-commit details needed to cite it. name: Read - description: >- Discover evidence across package, repository and documentation-site targets, then retrieve retained search results and progress. name: Search - description: >- Find supported programming-language names and aliases for example requests. name: Languages - description: >- Generate code examples for programming tasks, with source references and license attribution. name: Examples - description: Rate generated examples or sessions and provide written feedback. name: Feedback - description: >- Preview operations for target resolution, source comparison, cited questions and SBOM generation. Routes use /v1/experimental and may later move to permanent v1 locations under a documented migration policy. name: Experimental paths: /v1/read: get: tags: - Read summary: Read documentation or source code description: > Read a documentation page or an exact source file. The response identifies which kind was returned and includes the information needed to cite the page, package version, or repository commit. ## Choose a target For documentation, pass a page's `docs_read_target` as `target` and omit `path`. Package documentation from `GET /v1/packages/{registry}/{name}/docs` and documentation results from `POST /v1/searches` provide this value. An HTTP(S) target can include a fragment to select one indexed section. For source code, pass both `target` and the exact target-relative file `path`. Use a package target such as `crates:serde@1.0.0`, or a supported public repository locator such as `https://github.com/serde-rs/serde@master`. Find paths with `GET /v1/code/files`, `POST /v1/code/grep`, or a code result from `POST /v1/searches`. Repository refs use `@`; a literal `#` is not supported in a code target. `target` is a query value. Encode a literal `+` as `%2B` and a documentation fragment marker as `%23`; an unencoded `+` is decoded as a space. ## Interpret the result Branch on the required `kind` field: | `kind` | Result | | --- | --- | | `documentation` | Page identity, reusable `docs_read_target`, and exact crawled or repository source details. | | `code` | Target-relative and repository-root paths, binary status, and the requested, resolved, and served package version or repository commit. | Documentation and source files use 1-based inclusive line ranges. If no bounds are supplied, the complete page or file is returned; for a documentation URL, its fragment selects an indexed section. Explicit bounds override that fragment. An `end_line` past the end is clamped. Empty documentation has null bounds, while an empty text file has bounds `0`–`0`; binary code has null content and bounds. Explicit bounds require the `content` field group. ## Selector catalogue Use these selectors with the `fields` query parameter. Supplying `fields` replaces the defaults; `kind` and the identity and provenance fields for the returned branch remain present. See [Choose what the response includes](https://docs.githits.com/api/requests-and-responses#choose-what-the-response-includes) for the shared selection rules. | Selector | Documentation result | Code result | Default | | --- | --- | --- | --- | | `metadata` | Title, format, breadcrumbs, update and source context, and package ownership when known. | Detected language and total line count. | Yes | | `content` | Body, total lines, returned range, and resolved section anchor. | Body and returned range; values are null for binary files. | Yes | ## Wait for code indexing `wait_timeout_ms` controls how long to wait for code preparation, from `0` to `60000` milliseconds; the default is `20000`. Use `0` when the caller prefers an immediate `503 PACKAGE_INDEXING` response if code is not ready. Documentation reads do not use this budget for indexing. For failures, branch on the problem response's stable `code`. Correct malformed locators, paths, ranges, or selectors after `400 VALIDATION_ERROR`. A `404` means the requested page, file, package, version, repository, or ref was not found. A `409 DOCUMENTATION_PAGE_OWNER_CONFLICT` means the URL belongs to another documentation corpus. A `422` means the target exists but the requested section, file, package variant, or repository ref cannot produce one result. Respect `Retry-After` after `429 RATE_LIMITED`; retry `503 PACKAGE_INDEXING` later or with a positive wait budget. A `504 TIMEOUT` does not guarantee that preparation stopped. operationId: read parameters: - description: >- Required nonblank documentation page ID or docs_read_target; when path is present, a code target in :[@] form or a supported public repository locator. Repository refs use @. Encode literal + as %2B and a documentation fragment marker as %23; literal # is not supported in code targets. in: query name: target required: true schema: type: string - description: >- Exact target-relative source-file path. Omit or leave blank for documentation. The UTF-8 value is limited to 500 bytes and must not be absolute, use backslashes, contain . or .. path components, empty slash segments, NUL or control characters, or end in a slash. in: query name: path required: false schema: type: string - description: >- Optional positive inclusive start line. Either bound overrides a documentation URL fragment and requires content. in: query name: start_line required: false schema: maximum: 2147483647 minimum: 1 type: integer - description: >- Optional positive inclusive end line. It must not precede start_line and requires content. in: query name: end_line required: false schema: maximum: 2147483647 minimum: 1 type: integer - description: >- Milliseconds to wait for code indexing, from 0 to 60000; defaults to 20000. Zero returns 503 PACKAGE_INDEXING immediately when code is not ready. Documentation reads do not use this budget for indexing. The overall request deadline includes the selected budget. in: query name: wait_timeout_ms required: false schema: default: 20000 maximum: 60000 minimum: 0 type: integer - description: >- Comma-separated metadata and content response groups; both are selected by default. Supplying fields replaces the defaults. Explicit line bounds require content; kind and branch identity remain present. 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: metadata,content 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 responses: '200': content: application/json: examples: code: summary: Code file with complete citation paths value: code_index_state: current content: body: | fn main() {} end_line: 1 start_line: 1 indexing_ref: null is_binary: false kind: code metadata: language: Rust total_lines: 1 path: src/main.rs repository_file_path: packages/core/src/main.rs 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 documentation: summary: Documentation with both selected groups value: content: anchor: null body: | # Guide end_line: 2 start_line: 1 total_lines: 2 docs_read_target: https://docs.example.org/guide id: guide kind: documentation metadata: base_url: https://docs.example.org/guide breadcrumbs: - Guide content_format: markdown last_updated_at: null owner: null requested_ref: null source_label: Documentation title: Guide source: kind: crawled url: https://docs.example.org/guide documentation_empty: summary: Empty documentation page with nullable coordinates value: content: anchor: null body: '' end_line: null start_line: null total_lines: 0 docs_read_target: empty id: empty kind: documentation source: kind: crawled url: https://docs.example.org/empty schema: $ref: '#/components/schemas/ReadResponse' description: Documentation page or source file 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: Correct the target, path, line bounds, wait budget or fields selection before retrying. 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: Supply a usable bearer token.' 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: Resolve account access, feature availability or terms acceptance before retrying. 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: READ_TARGET_NOT_FOUND detail: The requested read target was not found. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 404 title: Read target not found type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- READ_TARGET_NOT_FOUND, FILE_NOT_FOUND, PACKAGE_NOT_FOUND, NO_RELEASED_VERSIONS, VERSION_NOT_FOUND, REPOSITORY_NOT_FOUND, REF_NOT_FOUND: The requested page, file, package, version, repository or ref was not found. Check the problem code and correct the corresponding target component before retrying. 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: GET, HEAD.' schema: type: string Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '409': content: application/problem+json: example: code: DOCUMENTATION_PAGE_OWNER_CONFLICT detail: The documentation URL belongs to another documentation corpus. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 409 title: Documentation page owner conflict type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- DOCUMENTATION_PAGE_OWNER_CONFLICT: Use the docs_read_target returned for the intended documentation corpus. headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '422': content: application/problem+json: example: code: DOCUMENTATION_SECTION_UNRESOLVED detail: The requested target cannot be returned as one read result. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 422 title: Read target unresolved type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- DOCUMENTATION_SECTION_UNRESOLVED, FILE_PATH_EXCLUDED, SOURCE_FILE_INVENTORY_UNKNOWN, UNSUPPORTED_PACKAGE_VARIANTS, AMBIGUOUS_REF, REF_UNRESOLVABLE: The target exists but the requested section, file, package variant or repository ref cannot produce one result. Check the problem code and choose a more specific or supported target. 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: Respect Retry-After when present before retrying.' 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: A dependency failed or returned unusable data; retry later if appropriate. 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: Code is not ready. Retry later or allow a positive wait_timeout_ms budget. 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: The read did not complete before its deadline. A retry may repeat preparation work. 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: [] x-codeSamples: - label: Documentation target lang: HTTP source: >- GET /v1/read?target=https%3A%2F%2Fdocs.example.org%2Fguide%23install HTTP/1.1 Host: api.githits.dev Authorization: Bearer - label: Package source file lang: HTTP source: >- GET /v1/read?target=crates%3Aserde%401.0.0&path=src%2Flib.rs HTTP/1.1 Host: api.githits.dev Authorization: Bearer - label: Repository range lang: HTTP source: >- GET /v1/read?target=https%3A%2F%2Fgithub.com%2Fexample%2Frepository%40main&path=src%2Fmain.rs&start_line=1&end_line=40&fields=content HTTP/1.1 Host: api.githits.dev Authorization: Bearer components: schemas: ReadResponse: description: A documentation page or source file, selected by `kind`. discriminator: propertyName: kind oneOf: - description: Documentation content with exact source details. properties: content: $ref: '#/components/schemas/DocumentationContent' description: Page body and returned range, absent when unselected. docs_read_target: description: Exact target accepted by a subsequent read. type: string id: description: Opaque documentation page ID. type: string kind: enum: - documentation type: string metadata: $ref: '#/components/schemas/DocumentationMetadata' description: Atomic descriptive metadata, absent when unselected. source: $ref: '#/components/schemas/DocumentationSource' description: >- Mandatory source attribution and repository locator when applicable. required: - id - docs_read_target - source - kind type: object - description: >- Exact source file content and the package version or repository commit served. properties: code_index_state: $ref: '#/components/schemas/CodeIndexState' description: Freshness of the served artifact; pending work is a typed error. content: $ref: '#/components/schemas/CodeContent' description: Atomic source content, absent when unselected. indexing_ref: description: Active indexing reference, null when absent. type: - string - 'null' is_binary: description: True for non-UTF-8 files; selected body and counters are null. type: boolean kind: enum: - code type: string metadata: $ref: '#/components/schemas/CodeMetadata' description: Atomic language and line-count metadata, absent when unselected. path: description: Canonical path relative to the requested target. type: string repository_file_path: description: Canonical repository-root path at the served ref. type: string target_resolution: $ref: '#/components/schemas/CodeTargetResolution' description: Requested target, current resolution and exact artifact served. required: - path - repository_file_path - is_binary - target_resolution - code_index_state - indexing_ref - kind 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 DocumentationContent: description: >- Documentation body and absolute inclusive coordinates within the stored page. properties: anchor: description: Resolved indexed anchor; null for full-page and explicit-line reads. type: - string - 'null' body: description: Full or ranged documentation text, preserving source bytes. type: string end_line: description: Null only for an empty page. format: int32 minimum: 1 type: - integer - 'null' start_line: description: Null only for an empty page. format: int32 minimum: 1 type: - integer - 'null' total_lines: description: >- Total line count of the stored page; a terminal LF adds an empty line. format: int32 minimum: 0 type: integer required: - body - total_lines - start_line - end_line - anchor type: object DocumentationMetadata: description: >- Atomic documentation metadata; null values remain distinct from omission. properties: base_url: description: Base URL for resolving relative links, null when unavailable. type: - string - 'null' breadcrumbs: description: Ordered navigation labels from the documentation root to this page. items: type: string type: array content_format: description: >- Content format reported by the documentation source, such as markdown or HTML. type: string last_updated_at: description: >- Update timestamp reported by the documentation source, null when unknown. type: - string - 'null' owner: oneOf: - type: 'null' - $ref: '#/components/schemas/DocumentationOwner' description: >- Best-effort package owner, null when the page is not package-scoped. requested_ref: description: Requested repository ref, null for crawled pages or when absent. type: - string - 'null' source_label: description: Human-readable source label, null when absent. type: - string - 'null' title: description: Page title reported by the documentation source. type: string required: - title - content_format - breadcrumbs - last_updated_at - source_label - requested_ref - base_url - owner type: object DocumentationSource: description: Exact documentation source locator. oneOf: - description: Persisted crawl origin. properties: kind: enum: - crawled type: string url: description: Exact original page URL. type: string required: - url - kind type: object - description: Snapshot-pinned repository documentation. properties: file_path: description: Repository-root path at the served ref. type: string git_ref: description: Exact served Git ref, normally a commit SHA. type: string kind: enum: - repository type: string repo_url: description: Repository root URL. type: string url: description: Exact snapshot blob URL. type: string required: - url - repo_url - git_ref - file_path - kind type: object CodeIndexState: description: >- Serveable code lifecycle states; pending work produces `PACKAGE_INDEXING`. enum: - current - stale - provisional type: string CodeContent: description: Code body and inclusive returned range. properties: body: description: >- Full or ranged text, empty for empty text files and null for binary files. type: - string - 'null' end_line: description: >- Last returned line clamped to EOF, zero for empty text and null for binary files. format: int32 minimum: 0 type: - integer - 'null' start_line: description: >- First returned 1-based line, zero for empty text and null for binary files. format: int32 minimum: 0 type: - integer - 'null' required: - body - start_line - end_line type: object CodeMetadata: description: Atomic code metadata; binary and unknown values remain null. properties: language: description: Detected source language, null for binary or unknown files. type: - string - 'null' total_lines: description: Total line count of the served file, null for binary files. format: int32 minimum: 0 type: - integer - 'null' required: - language - total_lines type: object CodeTargetResolution: description: Requested, resolved and served identity for a code result. 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 DocumentationOwner: description: Best-effort package ownership reported for the page. properties: name: description: Package name, null when the source cannot report it. type: - string - 'null' registry: description: Package registry, null when the source cannot report it. type: - string - 'null' version: description: Package version, null when the page is not version-pinned. type: - string - 'null' required: - registry - name - version type: object CodeIdentity: description: >- One stage of code-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 ````