List

List files and documentation paths

Browse a known package, repository, or documentation site to find the path you want to read. Package targets stay within the package’s own tree; repository targets cover the whole snapshot. Both include local documentation. To browse hosted docs, use an explicit site: target from resolve or a docs search result. Omit paths to start at the root. Directories show immediate children unless recursive is true; glob depth works independently. Follow an entry’s read or browse action unchanged. Use search for topics and code grep for exact source text.

Start browsing

Send JSON such as {"target":"npm:express@5.2.1"}. For hosted docs use {"target":"site:expressjs.com/en"}. Source filters file_types, languages, and intents cannot be used with a site target. Paths form a union of literals and globs; extensions belong in a paths glob such as lib/**/*.js.

This operation returns one fixed JSON projection; it does not accept fields or query parameters. The normal HTTP body limit is 2 MiB, independent of per-array caps. Up to 500 logical entries fit on a page; no total count is implied.

Read or browse an entry

Use read.target and its non-null read.path as URL-encoded query values for GET /v1/read. Omit a null path. A scoped site uses / for its landing page; preserve trailing slashes, query bytes, and literal percent bytes. Display paths can differ from repository-root read paths. Do not construct a read target from a display path.

Use browse.target and browse.paths in a fresh POST /v1/list request. Do not carry the old cursor into a different selection. For example, GET /v1/read?target=site%3Aexpressjs.com%2Fen&path=%2F reads that site’s indexed landing page. Read the emitted action for the actual page you selected.

Continue and assess readiness

When has_more is true, repeat the same target, paths, filters, recursion, and limit with next_cursor as after. The cursor is opaque; a rejected cursor requires a fresh request without it.

An empty page is not proof of complete coverage. Source inventories retain requested, resolved, and served provenance plus indexing state. A source page can be returned while preparation is pending. Hosted inventories separately expose stored-page availability, crawl status, coverage, and preparation jobs. Null means inapplicable or unknown; arrays, zero, and false retain their meanings.

wait_timeout_ms defaults to 0 and accepts 0 through 210000 milliseconds. A positive value waits for source or empty-site preparation; the transport timeout is added. Preparation can continue after a timeout. A package-owned inventory that is unavailable returns recovery guidance rather than silently broadening to its repository. A pinned repository target covers a broader scope; choose it only if that scope is acceptable.

POST

list

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": [
    {
      "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": []
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-GitHits-Client-Name

string

Optional client attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.

X-GitHits-Client-Version

string

Optional client-version attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.

X-GitHits-Agent

string

Optional agent attribution: trimmed printable ASCII, at most 160 bytes. Invalid optional values are dropped.

X-GitHits-Session-ID

string

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.

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9_-]{1,64}$

Body

application/json

Selection for a source or hosted-site inventory page. Unknown and null controls are rejected.

target

string

required

Required nonblank compact package, repository, or explicit site:host[/scope] target. Forwarded unchanged.

Minimum string length: 1

after

string

Opaque continuation. Blank starts page one; preserve a nonblank cursor unchanged and repeat the same selection.

file_types

string[]

Source-only raw file-type labels; at most 64, trimmed and lowercased. Empty means no filter.

Maximum array length: 64

intents

enum<string>[]

Source-only file-purpose inclusion union; at most 64 values. Empty means no filter.

Maximum array length: 64

Purpose of a source file; inclusion values form a union.

Available options:

production,

test,

benchmark,

example,

generated,

fixture,

build,

vendor

languages

string[]

Source-only language labels; at most 64, trimmed and lowercased. Empty means no filter.

Maximum array length: 64

limit

integer<int32>

default:100

Logical entries per page, 1 through 500, default 100. No total count is implied.

Required range: 1 <= x <= 500

paths

string[]

Literal/glob union of at most 1000 selectors, each nonblank and at most 2048 UTF-8 bytes. Omit or use [] for root. Explicit sites remove one leading slash; root alone is allowed.

Maximum array length: 1000

recursive

boolean

default:false

Default false lists immediate directory children. True expands selected directories to leaves; glob depth is independent.

wait_timeout_ms

integer<int32>

default:0

Source or empty-site preparation wait, 0 through 210000 milliseconds, default 0. Transport time is added; timeout does not mean preparation stopped.

Required range: 0 <= x <= 210000

Response

One source or hosted-site inventory page with exact actions and readiness evidence

One bounded inventory page with exact follow-up actions and readiness evidence.

available_versions

object[] | null

required

Indexed package versions or repository refs for immediate retry; null for sites.

Show child attributes

canonical_target

string | null

required

Resolved package version, repository commit, or site scope; null while unavailable.

code_index_state

null | enum<string>

required

Source freshness or preparation state; null for sites.

Available options:

current,

stale,

provisional,

indexing,

pending,

failed,

not_found,

unresolvable

coverage_reason

string | null

required

Hosted coverage explanation, when available.

coverage_state

null | enum<string>

required

Hosted inventory coverage; empty entries alone do not establish completion.

Available options:

none,

partial,

capped,

complete

crawl_status

null | enum<string>

required

Latest hosted-site crawl state, or null.

Available options:

idle,

running,

complete,

failed

entries

object[]

required

Ordered entries on this bounded page; no total count is implied.

Show child attributes

has_more

boolean

required

Whether another inventory page is available.

indexed_version

string | null

required

Served source ref; null for sites or unprepared source.

indexing_estimate

null | object

required

Source preparation estimate, when known.

Show child attributes

indexing_ref

string | null

required

Opaque active source preparation reference, or null.

indexing_status

null | enum<string>

required

Source indexing lifecycle; prefer code_index_state for freshness.

Available options:

indexed,

indexing,

pending,

failed,

not_found,

unresolvable

inventory_kind

enum<string>

required

Inventory being browsed: source files or hosted documentation.

Available options:

source,

site

inventory_state

null | enum<string>

required

Whether the hosted site has active pages; null for source inventories.

Available options:

available,

empty

next_cursor

string | null

required

Opaque continuation; repeat the same request with this value as after.

preparation

null | object

required

Hosted-site admission, active work and bounded wait evidence, or null.

Show child attributes

requested_target

string

required

Normalized target bound to this page and continuation.

resolution

null | object

required

Source snapshot resolution; null when not applicable or known.

Show child attributes

target_resolution

null | object

required

Requested, resolved and served source provenance, including retry candidates.

Show child attributes

⌘I

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": [
    {
      "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": []
  }
}

Get started

v1 reference

List files and documentation paths

Start browsing

Read or browse an entry

Continue and assess readiness

Authorizations

Headers

Body

Response