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:

{"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:

{"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@<commit_sha>, can include files outside the package, so use it only when that broader scope is acceptable.