> ## 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 files and documentation paths > Browse files and documentation paths in a package, repository, or documentation site. Use this endpoint when you know the target and want to find something to read. Use grep to find text within its contents, or search to discover documentation by topic. ## Start browsing Send a JSON body to `POST /v1/list`. This request lists the root of a package: ```json {"target":"npm:express@5.2.1"} ``` Package targets list files within that package, including local documentation. A repository target such as `github:expressjs/express` lists the whole repository snapshot. To browse hosted documentation, use a `site:` target: ```json {"target":"site:expressjs.com/en","recursive":true,"limit":100} ``` Omit `paths`, or use an empty array, to start at the root. To narrow the selection, pass paths or globs such as `{"target":"github:expressjs/express","paths":["lib/**/*.js"]}`. Entries matching any selector are included. Directories show their immediate children by default; `recursive: true` lists files or pages beneath them. Glob depth is determined by the glob itself. The `file_types`, `languages`, and `intents` filters apply only to source files. For filename extensions, use a path glob. Send all options in the JSON body; query parameters are not accepted. Request bodies can be at most 2 MiB. ## Read a result or open a directory Each entry includes a `read` action, a `browse` action, or both as applicable. Use these actions to make the next request: - For `read`, send its `target` and non-null `path` as URL-encoded query parameters to `GET /v1/read`. Omit `path` when it is null. - For `browse`, send its `target` and non-null `paths` in a new `POST /v1/list` body. Omit `paths` when it is null, and leave out `after`. Copy action values exactly. A displayed path can differ from the path needed to read a file. Preserve the path value, including trailing slashes and any query string, then URL-encode it as one query parameter. Encode literal `+` as `%2B` and `%` as `%25`; do not decode the action before encoding it. For example, `GET /v1/read?target=site%3Aexpressjs.com%2Fen&path=%2F` reads the landing page for that site scope. Use the action returned for your selected entry. ## Get the next page `limit` defaults to 100 and accepts 1–500 entries per page. When `has_more` is true, repeat the same target, paths, filters, recursion, and limit, adding the returned `next_cursor` as `after`. Copy the cursor unchanged. If it is rejected, start again without `after`. Site pages can change between requests. Pagination does not freeze their contents or membership; start without `after` to get a fresh listing. The response does not report a total number of entries. ## Check availability and coverage An empty page does not prove that all content has been indexed. For source files, inspect `code_index_state` and `target_resolution` to check availability, freshness, and the version or commit actually returned. For sites, inspect `inventory_state`, `crawl_status`, `coverage_state`, and `preparation`. Null means unknown or not applicable. A site selection can combine multiple indexed documentation collections. Crawl and coverage fields are null when there is no single collection summary. The `canonical_target` may identify the host root even for a narrower request; keep your original selection and use the returned actions. To wait for source indexing or an empty site's preparation, set `wait_timeout_ms` to a value from 0 to 210000 milliseconds. The default, 0, returns without waiting. At the maximum wait, allow up to 240 seconds for the HTTP request. A wait timeout does not stop preparation. Each site's wait reports an exact `status` and a summary `outcome`; use `status` to distinguish `failed` from `discarded`, or `superseded` from `cancelled`. In `preparation`, `selected` counts documentation collections, `enqueued` counts newly queued preparation, and `active_jobs` lists work already running. A positive `repair_limit_reached` means some collections still need preparation but were not queued. Narrow the site selection to include fewer collections. A zero value does not guarantee complete coverage. For `RESOURCE_LIMIT` errors, choose a target or paths that select fewer documentation collections. If a single collection exceeds the limit, read a known page directly; selecting fewer paths within that collection does not reduce the limit. If a package's source inventory is unavailable (`409 SOURCE_INVENTORY_SCOPE_UNAVAILABLE`), the error can include `repo_url` and `commit_sha`. A repository target at that commit, such as `github:expressjs/express@`, can include files outside the package, so use it only when that broader scope is acceptable. ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json post /v1/list 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 | Browse with list, then follow an exact action through the unified read operation | | Browse known content | List source files, local documentation, or an explicit hosted site | | Find exact text | Grep across ordered packages, repositories and hosted sites, then follow exact read actions | | 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 | | Research 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`; job events use `no-store, no-transform` to preserve streaming. Timeouts do not guarantee that work stopped. Read the documented timeout responses, especially for Research, 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: >- Find exact text across ordered source and hosted-documentation scopes, check coverage, and follow exact reads. name: Grep - description: >- Browse package, repository or hosted-site paths and follow exact read and browse actions. name: List - description: >- Package metadata, release history, vulnerabilities, dependency graphs and upgrade comparisons. Each operation documents its registry, version and evidence scope. name: Packages - 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: Stable exact-tree source comparison. name: Code Diff - description: >- Preview target resolution, cited questions and SBOM generation, plus the deprecated source comparison alias. Use /v1/code/diff for stable source comparison. name: Experimental paths: /v1/list: post: tags: - List summary: List files and documentation paths description: > Browse files and documentation paths in a package, repository, or documentation site. Use this endpoint when you know the target and want to find something to read. Use grep to find text within its contents, or search to discover documentation by topic. ## Start browsing Send a JSON body to `POST /v1/list`. This request lists the root of a package: ```json {"target":"npm:express@5.2.1"} ``` Package targets list files within that package, including local documentation. A repository target such as `github:expressjs/express` lists the whole repository snapshot. To browse hosted documentation, use a `site:` target: ```json {"target":"site:expressjs.com/en","recursive":true,"limit":100} ``` Omit `paths`, or use an empty array, to start at the root. To narrow the selection, pass paths or globs such as `{"target":"github:expressjs/express","paths":["lib/**/*.js"]}`. Entries matching any selector are included. Directories show their immediate children by default; `recursive: true` lists files or pages beneath them. Glob depth is determined by the glob itself. The `file_types`, `languages`, and `intents` filters apply only to source files. For filename extensions, use a path glob. Send all options in the JSON body; query parameters are not accepted. Request bodies can be at most 2 MiB. ## Read a result or open a directory Each entry includes a `read` action, a `browse` action, or both as applicable. Use these actions to make the next request: - For `read`, send its `target` and non-null `path` as URL-encoded query parameters to `GET /v1/read`. Omit `path` when it is null. - For `browse`, send its `target` and non-null `paths` in a new `POST /v1/list` body. Omit `paths` when it is null, and leave out `after`. Copy action values exactly. A displayed path can differ from the path needed to read a file. Preserve the path value, including trailing slashes and any query string, then URL-encode it as one query parameter. Encode literal `+` as `%2B` and `%` as `%25`; do not decode the action before encoding it. For example, `GET /v1/read?target=site%3Aexpressjs.com%2Fen&path=%2F` reads the landing page for that site scope. Use the action returned for your selected entry. ## Get the next page `limit` defaults to 100 and accepts 1–500 entries per page. When `has_more` is true, repeat the same target, paths, filters, recursion, and limit, adding the returned `next_cursor` as `after`. Copy the cursor unchanged. If it is rejected, start again without `after`. Site pages can change between requests. Pagination does not freeze their contents or membership; start without `after` to get a fresh listing. The response does not report a total number of entries. ## Check availability and coverage An empty page does not prove that all content has been indexed. For source files, inspect `code_index_state` and `target_resolution` to check availability, freshness, and the version or commit actually returned. For sites, inspect `inventory_state`, `crawl_status`, `coverage_state`, and `preparation`. Null means unknown or not applicable. A site selection can combine multiple indexed documentation collections. Crawl and coverage fields are null when there is no single collection summary. The `canonical_target` may identify the host root even for a narrower request; keep your original selection and use the returned actions. To wait for source indexing or an empty site's preparation, set `wait_timeout_ms` to a value from 0 to 210000 milliseconds. The default, 0, returns without waiting. At the maximum wait, allow up to 240 seconds for the HTTP request. A wait timeout does not stop preparation. Each site's wait reports an exact `status` and a summary `outcome`; use `status` to distinguish `failed` from `discarded`, or `superseded` from `cancelled`. In `preparation`, `selected` counts documentation collections, `enqueued` counts newly queued preparation, and `active_jobs` lists work already running. A positive `repair_limit_reached` means some collections still need preparation but were not queued. Narrow the site selection to include fewer collections. A zero value does not guarantee complete coverage. For `RESOURCE_LIMIT` errors, choose a target or paths that select fewer documentation collections. If a single collection exceeds the limit, read a known page directly; selecting fewer paths within that collection does not reduce the limit. If a package's source inventory is unavailable (`409 SOURCE_INVENTORY_SCOPE_UNAVAILABLE`), the error can include `repo_url` and `commit_sha`. A repository target at that commit, such as `github:expressjs/express@`, can include files outside the package, so use it only when that broader scope is acceptable. operationId: post_list parameters: - 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 caller-defined session ID: one to 64 ASCII letters, digits, underscores or hyphens, preserved exactly. Supply the header at most once. Invalid supplied IDs return 400 INVALID_SESSION_ID; no session is created. in: header name: X-GitHits-Session-ID required: false schema: maxLength: 64 minLength: 1 pattern: ^[A-Za-z0-9_-]{1,64}$ type: string requestBody: content: application/json: examples: continuation: value: after: opaque-cursor limit: 100 target: npm:express@5.2.1 package: value: target: npm:express@5.2.1 recursive: value: paths: - lib/**/*.js recursive: true target: github:expressjs/express site: value: limit: 100 paths: - / target: site:expressjs.com/en schema: $ref: '#/components/schemas/ListRequest' required: true responses: '200': content: application/json: examples: combined_site: summary: >- Combined documentation collections with limited preparation and unknown overall coverage value: available_versions: null canonical_target: site:expressjs.com code_index_state: null coverage_reason: null coverage_state: null crawl_status: null entries: - browse: null byte_size: null content_hash: null file_type: null intent: null kind: page language: null line_count: null path: / read: path: / target: site:expressjs.com/en title: Express - browse: paths: - 5x/ target: site:expressjs.com/en byte_size: null content_hash: null file_type: null intent: null kind: directory language: null line_count: null path: 5x/ read: null title: null has_more: true indexed_version: null indexing_estimate: null indexing_ref: null indexing_status: null inventory_kind: site inventory_state: available next_cursor: site-cursor +/% preparation: active_jobs: - mode: full state: executing awaited: - mode: full outcome: timeout status: timeout enqueued: 1 repair_limit_reached: 1 selected: 3 requested_target: site:expressjs.com/en resolution: null target_resolution: null preparing: summary: Source indexing in progress; no files available yet value: available_versions: - ref: v5.2.1 version: 5.2.1 canonical_target: null code_index_state: pending coverage_reason: null coverage_state: null crawl_status: null entries: [] has_more: false indexed_version: null indexing_estimate: null indexing_ref: preparation-ref indexing_status: pending inventory_kind: source inventory_state: null next_cursor: null preparation: null requested_target: npm:express resolution: null target_resolution: available_refs: [] available_versions: - ref: v5.2.1 version: 5.2.1 freshness: current freshness_reason: exact_current indexing_ref: null requested: commit_sha: null git_ref: null kind: package_omitted_version package_name: express registry: npm repo_url: https://github.com/expressjs/express version: null resolved_requested: commit_sha: 0123456789abcdef0123456789abcdef01234567 git_ref: v5.2.1 kind: null package_name: express registry: npm repo_url: https://github.com/expressjs/express version: 5.2.1 served: null suggested_refs: [] site: summary: >- Documentation pages with availability and coverage information value: available_versions: null canonical_target: site:expressjs.com code_index_state: null coverage_reason: null coverage_state: complete crawl_status: complete entries: - browse: null byte_size: null content_hash: null file_type: null intent: null kind: page language: null line_count: null path: / read: path: / target: site:expressjs.com/en title: Express - browse: paths: - 5x/ target: site:expressjs.com/en byte_size: null content_hash: null file_type: null intent: null kind: directory language: null line_count: null path: 5x/ read: null title: null has_more: true indexed_version: null indexing_estimate: null indexing_ref: null indexing_status: null inventory_kind: site inventory_state: available next_cursor: site-cursor +/% preparation: active_jobs: [] awaited: [] enqueued: 0 repair_limit_reached: 0 selected: 0 requested_target: site:expressjs.com/en resolution: null target_resolution: null source: summary: Source files with actions to read files and open directories value: available_versions: - ref: v5.2.1 version: 5.2.1 canonical_target: npm:express@5.2.1 code_index_state: current coverage_reason: null coverage_state: null crawl_status: null entries: - browse: null byte_size: 100 content_hash: hash-1 file_type: config intent: production kind: file language: JSON line_count: 10 path: package.json read: path: package.json target: npm:express@5.2.1 title: null - browse: paths: - lib/ target: npm:express@5.2.1 byte_size: null content_hash: null file_type: null intent: null kind: directory language: null line_count: null path: lib/ read: null title: null has_more: false indexed_version: v5.2.1 indexing_estimate: null indexing_ref: null indexing_status: indexed inventory_kind: source inventory_state: null next_cursor: null preparation: null requested_target: npm:express resolution: commit_sha: 0123456789abcdef0123456789abcdef01234567 requested_ref: null requested_version: null resolved_ref: v5.2.1 target_resolution: available_refs: [] available_versions: - ref: v5.2.1 version: 5.2.1 freshness: current freshness_reason: exact_current indexing_ref: null requested: commit_sha: null git_ref: null kind: package_omitted_version package_name: express registry: npm repo_url: https://github.com/expressjs/express version: null resolved_requested: commit_sha: 0123456789abcdef0123456789abcdef01234567 git_ref: v5.2.1 kind: null package_name: express registry: npm repo_url: https://github.com/expressjs/express version: 5.2.1 served: commit_sha: 0123456789abcdef0123456789abcdef01234567 git_ref: v5.2.1 kind: null package_name: express registry: npm repo_url: https://github.com/expressjs/express version: 5.2.1 suggested_refs: [] schema: $ref: '#/components/schemas/ListResponse' description: >- One page of paths with read and browse actions and content availability headers: 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 '400': content: application/problem+json: examples: invalid_session_id: value: code: INVALID_SESSION_ID detail: >- X-GitHits-Session-ID must occur once and match [A-Za-z0-9_-]{1,64}. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Invalid session ID type: about:blank resource_limit: summary: Site selection exceeds the inventory budget value: code: RESOURCE_LIMIT detail: >- This site view exceeds the inventory limit. Choose a target or paths selecting fewer documentation collections. If one collection is too large, read a known page directly. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Site inventory limit exceeded type: about:blank validation: value: code: VALIDATION_ERROR detail: Set limit to an integer from 1 through 500. instance: fixture-request status: 400 title: Validation error type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: >- Check target, paths, filters, limit, wait_timeout_ms, and after. If after is rejected, start without it. If the page or request is too large, narrow paths or lower limit. For RESOURCE_LIMIT, select fewer documentation collections or read a known page directly. INVALID_SESSION_ID: a supplied session header is invalid or duplicated. headers: 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 '401': content: application/problem+json: example: code: AUTHENTICATION_REQUIRED detail: A bearer credential is required. instance: fixture-request status: 401 title: Authentication required type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: Supply a valid bearer credential. headers: Cache-Control: schema: enum: - no-store type: string WWW-Authenticate: schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '403': content: application/problem+json: example: code: FORBIDDEN detail: The caller is not allowed to access this resource. instance: fixture-request status: 403 title: Forbidden type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: Account, capability or terms restrictions prevent this request. headers: 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 '404': content: application/problem+json: example: code: LIST_TARGET_NOT_FOUND detail: >- The requested package, repository, or documentation site was not found. instance: fixture-request status: 404 title: List target not found type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: The list target, source repository, or repository ref was not found. headers: 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 '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 '409': content: application/problem+json: example: code: SOURCE_INVENTORY_SCOPE_UNAVAILABLE detail: >- The package-owned inventory is unavailable. A pinned repository target covers a broader scope; use it only if that scope is acceptable. instance: fixture-request status: 409 title: Package inventory unavailable type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: >- Content is being prepared, or the package inventory is unavailable. Review the preparation reference and repository suggestions when supplied. headers: 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 repository ref is ambiguous. Use an exact commit to select one snapshot. instance: fixture-request status: 422 title: Ambiguous ref type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: >- The repository ref is ambiguous; use an exact commit to select one snapshot. headers: 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 '429': content: application/problem+json: example: code: RATE_LIMITED detail: The request was rate limited. instance: fixture-request status: 429 title: Rate limited type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: Rate limit reached. Respect Retry-After when present. headers: Cache-Control: schema: enum: - no-store type: string Retry-After: schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. 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: LIST_UNSUPPORTED_API detail: >- The listing is unavailable. Include X-Request-ID when reporting the failure. instance: fixture-request status: 502 title: Listing unavailable type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: >- The listing could not be returned. Include X-Request-ID when reporting the failure. headers: 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 '504': content: application/problem+json: example: code: TIMEOUT detail: The upstream request did not complete in time. instance: fixture-request status: 504 title: Upstream timeout type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: The inventory deadline expired. Preparation may continue. headers: 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 security: - bearer_auth: [] x-codeSamples: - label: Browse a package lang: HTTP source: |- POST /v1/list HTTP/1.1 Host: api.githits.dev Authorization: Bearer Content-Type: application/json {"target":"npm:express@5.2.1"} - label: Browse hosted documentation lang: HTTP source: |- POST /v1/list HTTP/1.1 Host: api.githits.dev Authorization: Bearer Content-Type: application/json {"target":"site:expressjs.com/en","recursive":true} components: schemas: ListRequest: additionalProperties: false description: >- Selection for a source or hosted-site inventory page. Unknown and null controls are rejected. properties: after: description: >- Opaque continuation. Blank starts page one; preserve a nonblank cursor unchanged and repeat the same selection. type: string file_types: description: >- File-type labels for source files, such as config. Up to 64 values; surrounding whitespace is removed and case is ignored. Omit or use [] for no filter. For extensions, use a paths glob. items: type: string maxItems: 64 type: array intents: description: >- Include source files with any listed purpose, such as production or test. Up to 64 values; omit or use [] for no filter. items: $ref: '#/components/schemas/ListIntent' maxItems: 64 type: array languages: description: >- Language labels for source files, such as JavaScript. Up to 64 values; surrounding whitespace is removed and case is ignored. Omit or use [] for no filter. items: type: string maxItems: 64 type: array limit: default: 100 description: >- Maximum entries on this page, 1 through 500; default 100. The response does not report a total across pages. format: int32 maximum: 500 minimum: 1 type: integer paths: description: >- Paths or globs relative to the target; entries matching any selector are included. Omit or use [] for the root. Up to 1000 nonblank selectors of 2048 UTF-8 bytes each. On sites, / alone selects the root; a leading / on another selector is optional. items: type: string maxItems: 1000 type: array recursive: default: false description: >- Default false lists immediate directory children. True expands selected directories to leaves; glob depth is independent. type: boolean target: description: >- Package, repository, or documentation site to browse, such as npm:express@5.2.1, github:expressjs/express, or site:expressjs.com/en. Must not be blank. minLength: 1 type: string wait_timeout_ms: default: 0 description: >- Time to wait for source indexing or an empty site to become available, 0 through 210000 milliseconds; default 0. At the maximum wait, allow up to 240 seconds for the HTTP request. Preparation may continue after the wait ends. format: int32 maximum: 210000 minimum: 0 type: integer required: - target type: object ListResponse: description: >- One page of paths, with actions for reading entries or browsing directories and information about content availability. properties: available_versions: description: >- Indexed package versions or repository refs for immediate retry; null for sites. items: $ref: '#/components/schemas/ListAvailableVersion' type: - array - 'null' canonical_target: description: >- Resolved package version, repository commit, or stable site domain root; a sole redirect may retain its scope. Null while unavailable. type: - string - 'null' code_index_state: oneOf: - type: 'null' - $ref: '#/components/schemas/ListCodeState' description: Source freshness or preparation state; null for sites. coverage_reason: description: >- Explanation of site coverage, when available for a single documentation collection; otherwise null. type: - string - 'null' coverage_state: oneOf: - type: 'null' - $ref: '#/components/schemas/ListCoverageState' description: >- Coverage of a single documentation collection; null for combined collections or source files. An empty entries list does not prove complete coverage. crawl_status: oneOf: - type: 'null' - $ref: '#/components/schemas/ListCrawlStatus' description: >- Latest crawl state when the selection has a single documentation collection; null for combined collections or source files. entries: description: Files, pages, and directories on this page, in listing order. items: $ref: '#/components/schemas/ListEntry' type: array has_more: description: Whether another inventory page is available. type: boolean indexed_version: description: Served source ref; null for sites or unprepared source. type: - string - 'null' indexing_estimate: oneOf: - type: 'null' - $ref: '#/components/schemas/ListIndexingEstimate' description: Source preparation estimate, when known. indexing_ref: description: Opaque active source preparation reference, or null. type: - string - 'null' indexing_status: oneOf: - type: 'null' - $ref: '#/components/schemas/ListIndexingStatus' description: >- Source indexing lifecycle; prefer `code_index_state` for freshness. inventory_kind: $ref: '#/components/schemas/ListInventoryKind' description: 'Inventory being browsed: source files or hosted documentation.' inventory_state: oneOf: - type: 'null' - $ref: '#/components/schemas/ListInventoryState' description: >- Whether the hosted site has active pages; null for source inventories. next_cursor: description: >- Opaque continuation; repeat the same request with this value as after. Site entries can change between requests. type: - string - 'null' preparation: oneOf: - type: 'null' - $ref: '#/components/schemas/ListPreparation' description: >- Site preparation counts, active jobs, and wait results; null when not applicable. requested_target: description: >- Target selected for this page. Keep the original request target when continuing. type: string resolution: oneOf: - type: 'null' - $ref: '#/components/schemas/ListResolution' description: Source snapshot resolution; null when not applicable or known. target_resolution: oneOf: - type: 'null' - $ref: '#/components/schemas/ListTargetResolution' description: >- Requested, resolved and served source provenance, including retry candidates. required: - inventory_kind - requested_target - canonical_target - entries - has_more - next_cursor - indexed_version - resolution - target_resolution - code_index_state - indexing_status - indexing_ref - available_versions - indexing_estimate - inventory_state - crawl_status - coverage_state - coverage_reason - preparation type: object ListProblem: allOf: - $ref: '#/components/schemas/ProblemResponse' description: Shared stable problem details and request identity. - properties: commit_sha: description: Exact repository commit for a pinned retry. type: string indexing_ref: description: Opaque active preparation reference, when supplied. type: string repo_url: description: >- Repository URL for a new request at `commit_sha`. This can include files outside the original package. type: string type: object description: >- Listing error with a stable code, explanation, request ID, and preparation or repository suggestions when available. ProblemResponse: description: >- The stable problem document returned for an unsuccessful public API request. properties: acceptance_url: description: Link for accepting the required terms, when provided. 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: Link to the terms that require acceptance, when provided. 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 ListIntent: description: Purpose of a source file; inclusion values form a union. enum: - production - test - benchmark - example - generated - fixture - build - vendor type: string ListAvailableVersion: description: >- An indexed package version or repository ref available for a fresh request. properties: ref: description: Indexed repository ref. A ref-only value is not a package version. type: string version: description: >- Package version to use in a new package request. When null, use an explicit repository target with ref instead. type: - string - 'null' required: - version - ref type: object ListCodeState: description: Source freshness and preparation state. enum: - current - stale - provisional - indexing - pending - failed - not_found - unresolvable type: string ListCoverageState: description: How much of the hosted site the inventory covers. enum: - none - partial - capped - complete type: string ListCrawlStatus: description: State of the most recent hosted-site crawl. enum: - idle - running - complete - failed type: string ListEntry: description: A source file, hosted page, or directory on this page. properties: browse: oneOf: - type: 'null' - $ref: '#/components/schemas/ListBrowseAction' description: >- Exact browse action; pass target and paths to a fresh POST /v1/list request. byte_size: description: Source size in bytes; zero is an empty file, null means unknown. format: int64 minimum: 0 type: - integer - 'null' content_hash: description: Source content identity, or null. type: - string - 'null' file_type: description: Source file-type label, such as config, or null. type: - string - 'null' intent: description: Source file-purpose label, or null. type: - string - 'null' kind: $ref: '#/components/schemas/ListEntryKind' description: File, hosted page, or directory. language: description: Detected source language, or null. type: - string - 'null' line_count: description: Source line count, or null. format: int64 minimum: 0 type: - integer - 'null' path: description: >- Target-relative display path. Follow the exact action instead of reconstructing it. type: string read: oneOf: - type: 'null' - $ref: '#/components/schemas/ListReadAction' description: >- Exact read action; encode its values as query parameters to GET /v1/read. title: description: Hosted page title, or null. type: - string - 'null' required: - kind - path - title - language - file_type - intent - byte_size - line_count - content_hash - read - browse type: object ListIndexingEstimate: description: Estimated source preparation duration, when available. properties: elapsed_seconds: description: Active elapsed duration in seconds, or null. format: int64 minimum: 0 type: - integer - 'null' lower_seconds: description: Estimated lower duration in seconds, or null. format: int64 minimum: 0 type: - integer - 'null' sample_count: description: Number of measurements used for the duration estimate, or null. format: int64 minimum: 0 type: - integer - 'null' source: description: Basis for the duration estimate, or null. type: - string - 'null' upper_seconds: description: Estimated upper duration in seconds, or null. format: int64 minimum: 0 type: - integer - 'null' required: - lower_seconds - upper_seconds - elapsed_seconds - sample_count - source type: object ListIndexingStatus: description: Source indexing lifecycle, independent of freshness. enum: - indexed - indexing - pending - failed - not_found - unresolvable type: string ListInventoryKind: description: Whether this page lists source files or hosted documentation. enum: - source - site type: string ListInventoryState: description: Whether the hosted site has stored pages available to browse. enum: - available - empty type: string ListPreparation: description: Site preparation counts, active jobs, and wait results. properties: active_jobs: description: Active hosted preparation jobs. items: $ref: '#/components/schemas/ListPreparationJob' type: array awaited: description: Outcomes of bounded hosted waits. items: $ref: '#/components/schemas/ListPreparationWait' type: array enqueued: description: >- Number of selected documentation collections with newly queued preparation work. format: int64 minimum: 0 type: integer repair_limit_reached: description: >- Number of selected documentation collections that still need preparation but were not queued because the preparation limit was reached. format: int64 minimum: 0 type: integer selected: description: >- Number of indexed documentation collections selected by the site target. format: int64 minimum: 0 type: integer required: - selected - enqueued - repair_limit_reached - active_jobs - awaited type: object ListResolution: description: The source ref and commit selected for this inventory. properties: commit_sha: description: Served repository commit, or null. type: - string - 'null' requested_ref: description: Repository ref requested, or null. type: - string - 'null' requested_version: description: Package version expression requested, or null. type: - string - 'null' resolved_ref: description: Served indexed ref, or null. type: - string - 'null' required: - requested_version - requested_ref - resolved_ref - commit_sha type: object ListTargetResolution: description: >- The source requested, the version or commit it resolved to, and the snapshot returned. properties: available_refs: description: Indexed repository retry candidates. items: $ref: '#/components/schemas/ListAvailableVersion' type: array available_versions: description: >- Indexed package retry candidates; an empty array means none are known. items: $ref: '#/components/schemas/ListAvailableVersion' type: array freshness: description: >- Whether the returned source matches the requested version or ref; null when unknown. type: - string - 'null' freshness_reason: description: Explanation of source freshness, or null. type: - string - 'null' indexing_ref: description: Reference identifying active source preparation, or null. type: - string - 'null' requested: oneOf: - type: 'null' - $ref: '#/components/schemas/ListIdentity' description: Original source identity requested, or null. resolved_requested: oneOf: - type: 'null' - $ref: '#/components/schemas/ListIdentity' description: Concrete identity resolved for this request, or null. served: oneOf: - type: 'null' - $ref: '#/components/schemas/ListIdentity' description: >- Version or commit actually returned; null when source content is not yet available. suggested_refs: description: Suggested repository refs; these need not be indexed. items: $ref: '#/components/schemas/ListAvailableVersion' type: array required: - requested - resolved_requested - served - freshness - freshness_reason - indexing_ref - available_versions - available_refs - suggested_refs type: object ListBrowseAction: description: An exact action for browsing this directory through POST /v1/list. properties: paths: description: >- Paths to pass unchanged in a new POST /v1/list request. Leave out after; omit paths when null. items: type: string type: - array - 'null' target: description: Complete follow-up browse target. Pass unchanged. type: string required: - target - paths type: object ListEntryKind: description: The kind of path represented by an entry. enum: - file - page - directory type: string ListReadAction: description: An exact action for reading this entry through GET /v1/read. properties: path: description: >- Path to pass to GET /v1/read. Omit it when null. Preserve the value before encoding it as one query parameter: encode literal + as %2B and % as %25, including any query string within the path. type: - string - 'null' target: description: Complete read target. Pass unchanged. type: string required: - target - path type: object ListPreparationJob: description: An active hosted-site preparation job. properties: mode: description: Preparation mode, or null. type: - string - 'null' state: description: Current preparation job state. type: string required: - mode - state type: object ListPreparationWait: description: The result of one bounded hosted-site preparation wait. properties: mode: description: Preparation mode, or null. type: - string - 'null' outcome: $ref: '#/components/schemas/ListWaitOutcome' description: >- Summary wait result. failed and discarded statuses share outcome discarded; superseded and cancelled statuses share outcome cancelled. Use status for the exact result. status: $ref: '#/components/schemas/ListWaitStatus' description: >- Exact wait result: completed, superseded, failed, discarded, cancelled, or timeout. A timeout does not stop preparation. required: - mode - outcome - status type: object ListIdentity: description: >- Package and repository details for a requested or returned source; unknown values are null. properties: commit_sha: description: Exact source commit, or null. type: - string - 'null' git_ref: description: Source Git ref, or null. type: - string - 'null' kind: description: >- Original request kind; normally null on resolved or served identities. type: - string - 'null' package_name: description: Source package name, or null. type: - string - 'null' registry: description: Source package registry, or null. type: - string - 'null' repo_url: description: Source repository URL, or null. type: - string - 'null' version: description: Source package version, or null. type: - string - 'null' required: - kind - registry - package_name - version - repo_url - git_ref - commit_sha type: object ListWaitOutcome: description: Outcome of a bounded hosted-site preparation wait. enum: - completed - discarded - cancelled - timeout type: string ListWaitStatus: description: Exact result of a bounded hosted-site preparation wait. enum: - completed - superseded - failed - discarded - cancelled - timeout type: string securitySchemes: bearer_auth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.