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, follow the read action from POST /v1/list, passing its target and non-null path unchanged. Browse hosted documentation with an explicit site: target; package and repository inventories include local documentation. Documentation results from POST /v1/searches also provide a docs_read_target, which you can pass as target without a path. 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 POST /v1/list, POST /v1/grep, or a code result from POST /v1/searches. Repository refs use @; a literal # is not supported in a code target.

When you have a read action, pass its target and non-null path unchanged. A scoped site target can use / to read its landing page. Preserve trailing slashes, query bytes, and literal percent bytes: they can identify distinct pages. Omit a null path.

Encode both values as query parameters. Encode a literal + as %2B, # as %23, and % as %25; an unencoded + is decoded as a space. For example, GET /v1/read?target=site%3Aexample.org%2Fguide&path=%2F reads that scope’s landing page. For a ready source target, absolute paths, dot segments, or trailing slashes are rejected with 400 VALIDATION_ERROR. Target resolution or indexing errors can occur before the source path is validated.

Interpret the result

Branch on the required kind field:

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.

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.