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 grep for exact text across source and hosted docs.

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.

Site inventories use live ordering. Pages can change between requests; restart without after for a fresh traversal. A continuation does not freeze the inventory.

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.

A site view can span several stored site owners on the same host. Crawl and coverage are reported for a single owner; a view spanning several owners leaves crawl_status, coverage_state, and coverage_reason null. canonical_target can be the host’s root even when you requested a narrower path. Keep your requested selection and follow the emitted actions unchanged.

Every non-null preparation includes repair_limit_reached. A positive value means some selected sites were not queued because the preparation limit was reached. Choose a narrower site view to inspect fewer corpora. selected counts the selected owners and enqueued counts newly queued work; fresh sites and active jobs can make these counts differ. A zero repair-limit count is not proof of complete coverage.

Each preparation wait reports nullable mode, the existing outcome, and exact status: completed, superseded, failed, discarded, cancelled or timeout. Failed and discarded waits can share outcome discarded; superseded and cancelled waits can share outcome cancelled. Inspect status for the exact result.

RESOURCE_LIMIT returns HTTP 400 when the selected site view exceeds the inventory budget. Choose a target or paths selecting fewer corpora. If one corpus is too large, read a known page directly; selecting fewer paths inside that same corpus does not reduce its budget.

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

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 stable site domain root; a sole redirect may retain its 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

Producer-reported bounded single-owner coverage reason; null for a multi-owner domain view.

coverage_state

null | enum<string>

required

Single-owner hosted coverage; null for a multi-owner domain view. Empty entries do not establish completion.

Available options:

none,

partial,

capped,

complete

crawl_status

null | enum<string>

required

Latest hosted-site crawl state for one physical owner; null for a multi-owner domain view.

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. Site entries can change between requests.

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

Get started

v1 reference

List files and documentation paths

Start browsing

Read or browse an entry

Continue and assess readiness

Authorizations

Headers

Body

Response