> ## 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 a documentation page > Read a documentation page, either in full or as a range of lines. The response includes the page content and information about its source. Use a page identifier returned by `GET /v1/packages/{registry}/{name}/docs` or a documentation search result. This endpoint reads an existing page; it does not start a new crawl. ## 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 | | --- | --- | --- | | `metadata` | Page title, format, navigation breadcrumbs, update time, source label, requested ref, base URL, and available package context. | Yes | | `content` | Original page content or the requested line range, with total line count and returned start and end lines. | Yes | ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json get /v1/docs/pages/{page_id} 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/docs/pages/{page_id}: get: tags: - Documentation summary: Read a documentation page description: > Read a documentation page, either in full or as a range of lines. The response includes the page content and information about its source. Use a page identifier returned by `GET /v1/packages/{registry}/{name}/docs` or a documentation search result. This endpoint reads an existing page; it does not start a new crawl. ## 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 | | --- | --- | --- | | `metadata` | Page title, format, navigation breadcrumbs, update time, source label, requested ref, base URL, and available package context. | Yes | | `content` | Original page content or the requested line range, with total line count and returned start and end lines. | Yes | operationId: get_doc_page parameters: - description: >- Page identifier or `docs_read_target` returned by documentation listing or search. Percent-encode the complete value as one path segment; it is decoded exactly once. For example, a token containing `a%2Fb` must contain `a%252Fb` in the request path. Pass the returned value unchanged before encoding. example: 123-getting-started in: path name: page_id required: true schema: type: string - description: >- Response groups to include: `metadata` and `content`, both selected by default. Explicit selection replaces defaults. No subfields or wildcards are supported. Line ranges require `content`. Selection and line ranges reduce response size, but do not reduce upstream retrieval of the full page. 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. example: metadata in: query name: fields required: false schema: default: metadata,content type: string - description: >- Positive decimal integer, default 1. Requires selected content; start beyond EOF returns empty interval with end=start-1. example: 2 in: query name: start_line required: false schema: default: 1 minimum: 1 type: integer - description: >- Last line to read, inclusive. Must be at least `start_line`; `end_line=0` is invalid. Omit to read through the end of the page. Values beyond the end are clamped. Requires `content` selection. example: 3 in: query name: end_line required: false schema: minimum: 1 type: integer - 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: default: summary: Full original page, both groups value: content: body: | # Guide Hello World end_line: 3 start_line: 1 total_lines: 3 docs_read_target: https://docs.example.org/guide id: 123-guide metadata: base_url: https://docs.example.org/guide breadcrumbs: - Guide content_format: markdown last_updated_at: null owner: name: example registry: npm version: null requested_ref: null source_label: Documentation title: Guide source: kind: crawled url: https://docs.example.org/guide empty: summary: Empty source page value: content: body: '' end_line: 0 start_line: 1 total_lines: 0 docs_read_target: 124-empty id: 124-empty source: kind: crawled url: https://docs.example.org/guide metadata: summary: Metadata-only, without ownership value: docs_read_target: https://docs.example.org/guide id: 123-guide 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 past_eof: summary: Start after EOF, explicit empty interval value: content: body: '' end_line: 9 start_line: 10 total_lines: 3 docs_read_target: 123-guide id: 123-guide source: kind: crawled url: https://docs.example.org/guide ranged: summary: Content-only lines 2 through 3 value: content: body: |- Hello World end_line: 3 start_line: 2 total_lines: 3 docs_read_target: https://docs.example.org/guide id: 123-guide source: kind: crawled url: https://docs.example.org/guide repository: summary: Pinned repository page, no inferred package owner value: content: body: '# Guide' end_line: 1 start_line: 1 total_lines: 1 docs_read_target: repo:opaque-token id: repo:opaque-token metadata: base_url: >- https://github.com/example/repo/blob/0123456789abcdef/docs/guide.md breadcrumbs: [] content_format: markdown last_updated_at: null owner: null requested_ref: main source_label: null title: Guide source: file_path: docs/guide.md git_ref: 0123456789abcdef kind: repo repo_url: https://github.com/example/repo url: >- https://github.com/example/repo/blob/0123456789abcdef/docs/guide.md schema: $ref: '#/components/schemas/DocPageResponse' description: Existing page with selected data groups headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace ID for diagnostics; matches 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 (VALIDATION_ERROR). headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace ID for diagnostics; matches 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 (AUTHENTICATION_REQUIRED). headers: Cache-Control: schema: enum: - no-store type: string WWW-Authenticate: description: Bearer authentication challenge. schema: type: string x-request-id: description: Active trace ID for diagnostics; matches 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 (FORBIDDEN, ACCOUNT_INACTIVE, FEATURE_FLAG_REQUIRED, TERMS_ACCEPTANCE_REQUIRED). TERMS_ACCEPTANCE_REQUIRED may include source-provided HTTPS terms_url and acceptance_url. headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace ID for diagnostics; matches problem.instance. schema: type: string '404': content: application/problem+json: example: code: DOCUMENTATION_PAGE_NOT_FOUND detail: The requested documentation page was not found. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 404 title: Documentation page not found type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Documentation page not found (DOCUMENTATION_PAGE_NOT_FOUND). headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace ID for diagnostics; matches 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 (DOCUMENTATION_PAGE_OWNER_CONFLICT). headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace ID for diagnostics; matches 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 (RATE_LIMITED). headers: Cache-Control: schema: enum: - no-store type: string Retry-After: description: >- Optional bounded delay in seconds or HTTP date; obey before retrying. schema: type: string x-request-id: description: Active trace ID for diagnostics; matches 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 (UPSTREAM_ERROR). headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace ID for diagnostics; matches 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: Upstream timeout (TIMEOUT). headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace ID for diagnostics; matches problem.instance. schema: type: string security: - bearer_auth: [] x-codeSamples: - label: Opaque page ID lang: HTTP source: |- GET /v1/docs/pages/repo%3Aopaque%2Fsnapshot%2Btoken HTTP/1.1 Host: api.githits.dev Authorization: Bearer - label: Emitted URL target lang: HTTP source: >- GET /v1/docs/pages/https%3A%2F%2Fdocs.example.org%2F%40scope%2Fpkg%3Fq%3Da%252Fb?fields=metadata HTTP/1.1 Host: api.githits.dev Authorization: Bearer - label: Content range lang: HTTP source: >- GET /v1/docs/pages/123-getting-started?fields=content&start_line=2&end_line=3 HTTP/1.1 Host: api.githits.dev Authorization: Bearer components: schemas: DocPageResponse: description: >- A page with mandatory exact identity and source; omitted groups are absent. properties: content: $ref: '#/components/schemas/DocPageContent' description: Atomic content and returned range; absent when unselected. docs_read_target: description: >- Exact input token for a subsequent read, encoded as one path segment. type: string id: description: Opaque source-reported page ID; never reconstruct or parse it. type: string metadata: $ref: '#/components/schemas/DocPageMetadata' description: >- Atomic descriptive metadata and best-effort owner; absent when unselected. source: $ref: '#/components/schemas/DocPageSource' description: >- Mandatory source attribution and exact repository locator when applicable. required: - id - docs_read_target - source 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 DocPageContent: description: Full original content or an explicit 1-based inclusive slice. properties: body: description: >- Unmodified full body by default. Explicit slices remove one trailing LF before splitting and join selected lines with LF. No text caps or local sanitization. type: string end_line: description: >- Inclusive returned end; empty ranges use `start_line`-1, including zero for an empty page. May exceed `total_lines` only for a start beyond EOF. minimum: 0 type: integer start_line: description: >- Returned start, default 1. May exceed `total_lines` for an empty slice. minimum: 1 type: integer total_lines: description: >- Lines in the full source after removing one trailing LF for counting; empty body has zero lines. minimum: 0 type: integer required: - body - total_lines - start_line - end_line type: object DocPageMetadata: description: >- All members are returned together, with null representing unavailable metadata. properties: base_url: description: >- Source base URL for resolving relative links, or null when unavailable. type: - string - 'null' breadcrumbs: description: Source navigation trail, possibly empty. items: type: string type: array content_format: description: >- Source format: markdown, html or unknown; preserved without local conversion. type: string last_updated_at: description: Source update timestamp when available, otherwise null. type: - string - 'null' owner: oneOf: - type: 'null' - $ref: '#/components/schemas/DocPageOwner' description: >- Best-effort package context, null when unavailable or ambiguous. No owner is chosen from matched scopes. requested_ref: description: >- Requested/display ref intent, not the actual served ref in `source.git_ref`. type: - string - 'null' source_label: description: >- Source display label when available; URL lives only in mandatory source. type: - string - 'null' title: description: Source title, including an available empty title. type: string required: - title - content_format - breadcrumbs - last_updated_at - source_label - requested_ref - base_url - owner type: object DocPageSource: description: >- Source URL and repository snapshot locator are never hidden by selection. oneOf: - description: A persisted crawl origin; reading never initiates a crawl. 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 file path at `git_ref`. type: string git_ref: description: >- Actual served Git ref, normally a commit SHA; use this for exact follow-up. type: string kind: enum: - repo type: string repo_url: description: Repository URL used for exact file follow-up. type: string url: description: Exact snapshot blob URL. type: string required: - url - repo_url - git_ref - file_path - kind type: object DocPageOwner: description: >- Source-reported package context; each member may independently be unknown. properties: name: description: Public package name, or null when unknown. type: - string - 'null' registry: description: Registry identifier, or null when unknown. type: - string - 'null' version: description: Source-reported package version, or null when unknown. type: - string - 'null' required: - registry - name - version type: object securitySchemes: bearer_auth: scheme: bearer type: http ````