Read

Read documentation or source code

Read a documentation page or an exact source file. The response identifies which kind was returned and includes the information needed to cite the page, package version, or repository commit.

Choose a target

For documentation, pass a page’s docs_read_target as target and omit path. Package documentation from GET /v1/packages/{registry}/{name}/docs and documentation results from POST /v1/searches provide this value. An HTTP(S) target can include a fragment to select one indexed section.

For source code, pass both target and the exact target-relative file path. Use a package target such as crates:serde@1.0.0, or a supported public repository locator such as https://github.com/serde-rs/serde@master. Find paths with GET /v1/code/files, POST /v1/code/grep, or a code result from POST /v1/searches. Repository refs use @; a literal # is not supported in a code target.

target is a query value. Encode a literal + as %2B and a documentation fragment marker as %23; an unencoded + is decoded as a space.

Interpret the result

Branch on the required kind field:

`kind`	Result
`documentation`	Page identity, reusable `docs_read_target`, and exact crawled or repository source details.
`code`	Target-relative and repository-root paths, binary status, and the requested, resolved, and served package version or repository commit.

Documentation and source files use 1-based inclusive line ranges. If no bounds are supplied, the complete page or file is returned; for a documentation URL, its fragment selects an indexed section. Explicit bounds override that fragment. An end_line past the end is clamped. Empty documentation has null bounds, while an empty text file has bounds 0–0; binary code has null content and bounds. Explicit bounds require the content field group.

Selector catalogue

Use these selectors with the fields query parameter. Supplying fields replaces the defaults; kind and the identity and provenance fields for the returned branch remain present. See Choose what the response includes for the shared selection rules.

Selector	Documentation result	Code result	Default
`metadata`	Title, format, breadcrumbs, update and source context, and package ownership when known.	Detected language and total line count.	Yes
`content`	Body, total lines, returned range, and resolved section anchor.	Body and returned range; values are null for binary files.	Yes

Wait for code indexing

wait_timeout_ms controls how long to wait for code preparation, from 0 to 60000 milliseconds; the default is 20000. Use 0 when the caller prefers an immediate 503 PACKAGE_INDEXING response if code is not ready. Documentation reads do not use this budget for indexing.

For failures, branch on the problem response’s stable code. Correct malformed locators, paths, ranges, or selectors after 400 VALIDATION_ERROR. A 404 means the requested page, file, package, version, repository, or ref was not found. A 409 DOCUMENTATION_PAGE_OWNER_CONFLICT means the URL belongs to another documentation corpus. A 422 means the target exists but the requested section, file, package variant, or repository ref cannot produce one result. Respect Retry-After after 429 RATE_LIMITED; retry 503 PACKAGE_INDEXING later or with a positive wait budget. A 504 TIMEOUT does not guarantee that preparation stopped.

GET

read

GET /v1/read?target=https%3A%2F%2Fdocs.example.org%2Fguide%23install HTTP/1.1
Host: api.githits.dev
Authorization: Bearer <token>

{
  "code_index_state": "current",
  "content": {
    "body": "fn main() {}\n",
    "end_line": 1,
    "start_line": 1
  },
  "indexing_ref": null,
  "is_binary": false,
  "kind": "code",
  "metadata": {
    "language": "Rust",
    "total_lines": 1
  },
  "path": "src/main.rs",
  "repository_file_path": "packages/core/src/main.rs",
  "target_resolution": {
    "freshness": "current",
    "freshness_reason": "exact_current",
    "requested": {
      "commit_sha": null,
      "git_ref": "main",
      "kind": "repo_branch",
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    },
    "resolved_requested": {
      "commit_sha": "0123456789abcdef0123456789abcdef01234567",
      "git_ref": "0123456789abcdef0123456789abcdef01234567",
      "kind": null,
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    },
    "served": {
      "commit_sha": "0123456789abcdef0123456789abcdef01234567",
      "git_ref": "0123456789abcdef0123456789abcdef01234567",
      "kind": null,
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": 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 session attribution: trimmed printable ASCII, at most 128 bytes. Invalid optional values are dropped; no session is created.

Query Parameters

target

string

required

Required nonblank documentation page ID or docs_read_target; when path is present, a code target in :[@] form or a supported public repository locator. Repository refs use @. Encode literal + as %2B and a documentation fragment marker as %23; literal # is not supported in code targets.

path

string

Exact target-relative source-file path. Omit or leave blank for documentation. The UTF-8 value is limited to 500 bytes and must not be absolute, use backslashes, contain . or .. path components, empty slash segments, NUL or control characters, or end in a slash.

start_line

integer

Optional positive inclusive start line. Either bound overrides a documentation URL fragment and requires content.

Required range: 1 <= x <= 2147483647

end_line

integer

Optional positive inclusive end line. It must not precede start_line and requires content.

Required range: 1 <= x <= 2147483647

wait_timeout_ms

integer

default:20000

Milliseconds to wait for code indexing, from 0 to 60000; defaults to 20000. Zero returns 503 PACKAGE_INDEXING immediately when code is not ready. Documentation reads do not use this budget for indexing. The overall request deadline includes the selected budget.

Required range: 0 <= x <= 60000

fields

string

default:metadata,content

Comma-separated metadata and content response groups; both are selected by default. Supplying fields replaces the defaults. Explicit line bounds require content; kind and branch identity remain present.

Use the case-sensitive selectors in the catalogue. Order and duplicate selectors do not affect the result. ASCII whitespace around selectors is ignored. The decoded value is limited to 2048 UTF-8 bytes. Empty or unknown selectors and repeated fields query parameters return 400 VALIDATION_ERROR. A group does not include nested groups unless the catalogue says so; only listed wildcard bundles are supported.

Response

Documentation page or source file

Option 1
Option 2

A documentation page or source file, selected by kind.

docs_read_target

string

required

Exact target accepted by a subsequent read.

string

required

Opaque documentation page ID.

kind

enum<string>

required

Available options:

documentation

source

object

required

Mandatory source attribution and repository locator when applicable.

Option 1
Option 2

Show child attributes

content

object

Page body and returned range, absent when unselected.

Show child attributes

metadata

object

Atomic descriptive metadata, absent when unselected.

Show child attributes

⌘I

GET /v1/read?target=https%3A%2F%2Fdocs.example.org%2Fguide%23install HTTP/1.1
Host: api.githits.dev
Authorization: Bearer <token>

{
  "code_index_state": "current",
  "content": {
    "body": "fn main() {}\n",
    "end_line": 1,
    "start_line": 1
  },
  "indexing_ref": null,
  "is_binary": false,
  "kind": "code",
  "metadata": {
    "language": "Rust",
    "total_lines": 1
  },
  "path": "src/main.rs",
  "repository_file_path": "packages/core/src/main.rs",
  "target_resolution": {
    "freshness": "current",
    "freshness_reason": "exact_current",
    "requested": {
      "commit_sha": null,
      "git_ref": "main",
      "kind": "repo_branch",
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    },
    "resolved_requested": {
      "commit_sha": "0123456789abcdef0123456789abcdef01234567",
      "git_ref": "0123456789abcdef0123456789abcdef01234567",
      "kind": null,
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    },
    "served": {
      "commit_sha": "0123456789abcdef0123456789abcdef01234567",
      "git_ref": "0123456789abcdef0123456789abcdef01234567",
      "kind": null,
      "name": null,
      "registry": null,
      "repo_url": "https://github.com/example/repository",
      "version": null
    }
  }
}

Get started

v1 reference

Read documentation or source code

Choose a target

Interpret the result

Selector catalogue

Wait for code indexing

Authorizations

Headers

Query Parameters

Response