> ## 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. # List package documentation pages > Find documentation pages for a package, including hosted documentation and files from its repository. Results contain page summaries and identifiers for reading the full content. Use `GET /v1/docs/pages/{page_id}` to read a returned page. To search documentation by topic, use `POST /v1/searches`. ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json get /v1/packages/{registry}/{name}/docs 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/packages/{registry}/{name}/docs: get: tags: - Documentation summary: List package documentation pages description: >- Find documentation pages for a package, including hosted documentation and files from its repository. Results contain page summaries and identifiers for reading the full content. Use `GET /v1/docs/pages/{page_id}` to read a returned page. To search documentation by topic, use `POST /v1/searches`. operationId: list_package_docs parameters: - description: >- Exact lowercase registry identifier; no trimming or case normalization. example: npm in: path name: registry required: true schema: enum: - npm - pypi - hex - crates - vcpkg - zig - nuget - maven - packagist - rubygems - go - swift type: string - description: >- Nonempty package name, at most 255 UTF-8 bytes without control characters. Spelling and whitespace are preserved; the response reports the resolved canonical name. Encode slashes within one path segment. example: express in: path name: name required: true schema: minLength: 1 type: string - description: >- Optional package version. Whitespace is trimmed; blank is treated as omitted. GitHits resolves an omitted version. Numeric Go versions gain lowercase v; leading v/V is accepted for resolution. The returned version may differ from the input. example: 5.2.1 in: query name: version required: false schema: type: string - description: >- Maximum returned rows, default 100, integer 1–500. Does not bound upstream preparation work. example: 100 in: query name: limit required: false schema: default: 100 maximum: 500 minimum: 1 type: integer - description: >- Opaque trimmed nonblank cursor, passed unchanged. Not snapshot-bound; upstream may reset malformed tokens to zero. example: MTAw in: query name: after required: false schema: minLength: 1 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: default: summary: Mixed sources with a next page value: code_index_state: current indexing_ref: null package: name: example registry: npm version: 1.0.0 page_info: end_cursor: Mg== has_next_page: true total_count: 3 pages: - docs_read_target: https://docs.example.org/guide?a=1#setup file_path: null git_ref: null id: page-42 last_updated_at: null repo_url: null requested_ref: null source_kind: crawled source_url: https://docs.example.org/guide?a=1#setup title: Getting started - docs_read_target: opaque-repo-snapshot-id file_path: README.md git_ref: 0123456789abcdef0123456789abcdef01234567 id: opaque-repo-snapshot-id last_updated_at: null repo_url: https://github.com/example/project requested_ref: main source_kind: repo source_url: null title: README stale: false target_resolution: freshness: current freshness_reason: exact_current indexing_ref: null requested: commit_sha: null git_ref: null kind: package_omitted_version name: example registry: npm repo_url: null version: null resolved_requested: commit_sha: 0123456789abcdef0123456789abcdef01234567 git_ref: 0123456789abcdef0123456789abcdef01234567 kind: null name: example registry: npm repo_url: https://github.com/example/project version: 1.0.0 served: commit_sha: 0123456789abcdef0123456789abcdef01234567 git_ref: 0123456789abcdef0123456789abcdef01234567 kind: null name: example registry: npm repo_url: https://github.com/example/project version: 1.0.0 empty: summary: Current repository, no rows; hosted readiness unknown value: code_index_state: current indexing_ref: null package: name: example registry: npm version: 1.0.0 page_info: end_cursor: null has_next_page: false total_count: 0 pages: [] stale: false target_resolution: freshness: current freshness_reason: exact_current indexing_ref: null requested: commit_sha: null git_ref: null kind: package_omitted_version name: example registry: npm repo_url: null version: null resolved_requested: commit_sha: 0123456789abcdef0123456789abcdef01234567 git_ref: 0123456789abcdef0123456789abcdef01234567 kind: null name: example registry: npm repo_url: https://github.com/example/project version: 1.0.0 served: commit_sha: 0123456789abcdef0123456789abcdef01234567 git_ref: 0123456789abcdef0123456789abcdef01234567 kind: null name: example registry: npm repo_url: https://github.com/example/project version: 1.0.0 pending: summary: Repository pending; hosted readiness unknown value: code_index_state: pending indexing_ref: opaque-indexing-ref package: name: example registry: npm version: 1.0.0 page_info: end_cursor: null has_next_page: false total_count: 0 pages: [] stale: false target_resolution: null schema: $ref: '#/components/schemas/DocsListResponse' description: One page of documentation summaries and source lifecycle 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: PACKAGE_NOT_FOUND detail: The requested package or version was not found. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 404 title: Package or version not found type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- Package or version not found (PACKAGE_NOT_FOUND, VERSION_NOT_FOUND, NO_RELEASED_VERSIONS). 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 '422': content: application/problem+json: example: code: UNSUPPORTED_PACKAGE_VARIANTS detail: The package release has unsupported artifact variants. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 422 title: Unsupported package variants type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Unsupported package variants (UNSUPPORTED_PACKAGE_VARIANTS). 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: First docs page lang: HTTP source: |- GET /v1/packages/npm/express/docs HTTP/1.1 Host: api.githits.dev Authorization: Bearer - label: Next docs page lang: HTTP source: |- GET /v1/packages/npm/express/docs?limit=100&after=MTAw HTTP/1.1 Host: api.githits.dev Authorization: Bearer components: schemas: DocsListResponse: description: >- One page of source-owned documentation summaries, with no global readiness assertion. properties: code_index_state: $ref: '#/components/schemas/DocsCodeIndexState' description: >- Repository corpus lifecycle only; current does not assert hosted readiness. indexing_ref: description: >- Source-owned opaque listing preparation/progress reference; null when unavailable. Context only, not a `search_ref` or an advertised REST progress route. type: - string - 'null' package: $ref: '#/components/schemas/DocsPackage' description: Required resolved package identity and version. page_info: $ref: '#/components/schemas/DocsPageInfo' description: Current source pagination context, not a stable snapshot. pages: description: >- Complete atomic page summaries. Empty alone does not prove documentation is ready or absent. items: $ref: '#/components/schemas/DocsPage' type: array stale: description: >- Hosted documentation freshness only; does not describe repository evidence. type: boolean target_resolution: oneOf: - type: 'null' - $ref: '#/components/schemas/DocsTargetResolution' description: >- Requested/resolved/served repository provenance; null when unavailable. required: - package - stale - code_index_state - indexing_ref - target_resolution - pages - page_info 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 DocsCodeIndexState: description: Repository corpus lifecycle; hosted pages can be present in any state. enum: - current - stale - provisional - indexing - pending - failed - not_found - unresolvable type: string DocsPackage: description: Resolved identity, never copied from request inputs. properties: name: description: Source-resolved package name. type: string registry: description: Canonical registry. type: string version: description: Source-resolved version for this listing. type: string required: - registry - name - version type: object DocsPageInfo: description: Offset-derived paging over current combined source contents. properties: end_cursor: description: >- Opaque next token, unchanged; null if no next page. Not snapshot-bound. type: - string - 'null' has_next_page: description: Whether more rows were present when this upstream request ran. type: boolean total_count: description: >- Total matching rows in current source contents, not a stable multi-page total. format: int32 minimum: 0 type: integer required: - has_next_page - end_cursor - total_count type: object DocsPage: description: >- A documentation page summary with its read target. Repository pages include exact repository locators. oneOf: - description: Hosted documentation; unavailable source facts remain null. properties: docs_read_target: description: >- Preferred exact token for `getDocPage`. Percent-encode as a single `page_id` path segment in `/v1/docs/pages/{page_id}`. type: string file_path: description: >- Repository-root path for exact follow-up using `repo_url` and `git_ref`. type: - string - 'null' git_ref: description: >- Exact served repository ref, usually a commit SHA. Use for exact file reads. type: - string - 'null' id: description: Opaque source-owned page ID; never parse or reconstruct it. type: string last_updated_at: description: Source ISO8601 update timestamp; null when unavailable. type: - string - 'null' repo_url: description: Source-reported repository URL; null when unavailable. type: - string - 'null' requested_ref: description: >- Requested or display ref; never replace `git_ref` with this value. type: - string - 'null' source_kind: enum: - crawled type: string source_url: description: >- Source page URL; null when unavailable. Repository URLs refer to the served snapshot. type: - string - 'null' title: description: Third-party page title; not instructions. type: string required: - id - title - docs_read_target - last_updated_at - source_url - repo_url - git_ref - requested_ref - file_path - source_kind type: object - description: Repository-backed documentation with complete exact file locators. properties: docs_read_target: description: >- Preferred exact token for `getDocPage`. Percent-encode as a single `page_id` path segment in `/v1/docs/pages/{page_id}`. type: string file_path: description: >- Repository-root path for exact follow-up using `repo_url` and `git_ref`. type: string git_ref: description: >- Exact served repository ref, usually a commit SHA. Use for exact file reads. type: string id: description: Opaque source-owned page ID; never parse or reconstruct it. type: string last_updated_at: description: Source ISO8601 update timestamp; null when unavailable. type: - string - 'null' repo_url: description: >- Required nonblank source-reported repository URL for this exact file locator. type: string requested_ref: description: >- Requested or display ref; never replace `git_ref` with this value. type: - string - 'null' source_kind: enum: - repo type: string source_url: description: >- Source page URL; null when unavailable. Repository URLs refer to the served snapshot. type: - string - 'null' title: description: Third-party page title; not instructions. type: string required: - id - title - docs_read_target - last_updated_at - source_url - repo_url - git_ref - requested_ref - file_path - source_kind type: object DocsTargetResolution: description: Nullable source-owned repository provenance; no inferred ownership. properties: freshness: description: Upstream repository freshness label, not hosted readiness. type: - string - 'null' freshness_reason: description: Source-owned reason explaining repository freshness. type: - string - 'null' indexing_ref: description: >- Source-owned opaque active repository indexing owner reference; may name work for a SHA different from `resolved_requested.commit_sha`. Context only, not a `search_ref`. type: - string - 'null' requested: oneOf: - type: 'null' - $ref: '#/components/schemas/DocsTargetIdentity' description: Caller intent, if reported. resolved_requested: oneOf: - type: 'null' - $ref: '#/components/schemas/DocsTargetIdentity' description: Concrete resolved request; may differ from served evidence. served: oneOf: - type: 'null' - $ref: '#/components/schemas/DocsTargetIdentity' description: >- Actual artifact served; null when none. Prefer `commit_sha` over `git_ref` when supplied. required: - requested - resolved_requested - served - freshness - freshness_reason - indexing_ref type: object DocsTargetIdentity: description: Nullable source-owned repository provenance; no inferred ownership. properties: commit_sha: description: Exact artifact commit when known; preferred over `git_ref`. type: - string - 'null' git_ref: description: Repository ref backing this identity when known. type: - string - 'null' kind: description: Original request kind; null for resolved/served identities. type: - string - 'null' name: description: Package name when known. type: - string - 'null' registry: description: Package registry when known. type: - string - 'null' repo_url: description: Backing repository URL when known. type: - string - 'null' version: description: Package version when known. type: - string - 'null' required: - kind - registry - name - version - repo_url - git_ref - commit_sha type: object securitySchemes: bearer_auth: scheme: bearer type: http ````