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 itstargetand non-nullpathas URL-encoded query parameters toGET /v1/read. Omitpathwhen it is null. - For
browse, send itstargetand non-nullpathsin a newPOST /v1/listbody. Omitpathswhen it is null, and leave outafter.
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.
POST /v1/list HTTP/1.1
Host: api.githits.dev
Authorization: Bearer <token>
Content-Type: application/json
{"target":"npm:express@5.2.1"}{
"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
}Authorizations
Headers
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.
1 - 64^[A-Za-z0-9_-]{1,64}$Body
Selection for a source or hosted-site inventory page. Unknown and null controls are rejected.
Include source files with any listed purpose, such as production or test. Up to 64 values; omit or use [] for no filter.
64Purpose of a source file; inclusion values form a union.
production, test, benchmark, example, generated, fixture, build, vendor Response
One page of paths with read and browse actions and content availability
One page of paths, with actions for reading entries or browsing directories and information about content availability.
POST /v1/list HTTP/1.1
Host: api.githits.dev
Authorization: Bearer <token>
Content-Type: application/json
{"target":"npm:express@5.2.1"}{
"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
}