Read a package or repository code file
Read a source file from a package or public repository, either in full or as a range of lines. The response includes file information and identifies the version or commit the content came from.
Find file paths with GET /v1/code/files, or follow a code search result to inspect its surrounding implementation.
Selector catalogue
Use the following selectors with the fields query parameter to choose which fields the response includes. See Choose what the response includes for details.
fields selector | Returned group | Default |
|---|---|---|
metadata | metadata { language, total_lines } | Yes |
content | content { body, start_line, end_line } | Yes |
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Optional client attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.
Optional client-version attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.
Optional agent attribution: trimmed printable ASCII, at most 160 bytes. Invalid optional values are dropped.
Optional session attribution: trimmed printable ASCII, at most 128 bytes. Invalid optional values are dropped; no session is created.
Query Parameters
Package registry, required with name; mutually exclusive with repo_url.
npm, pypi, hex, crates, vcpkg, zig, nuget, maven, packagist, rubygems, go, swift Package name, up to 255 UTF-8 bytes; encode scoped names as %40scope%2Fpackage.
Optional package version, up to 100 normalized bytes; omitted or blank retains latest-release intent. Forbidden with repo_url.
Public GitHub, GitLab, or Codeberg repository root URL; cannot be combined with package parameters. HTTPS and git+https are supported on all three; GitHub also accepts http, git, ssh, and git+ssh. Use default ports and omit credentials, query strings, and fragments. Use HTTPS instead of scp-style shorthand.
Repository-only branch, tag or SHA, omission preserves default-branch intent.
Required exact target-relative file path. No absolute, parent, NUL or trailing directory boundary.
Positive inclusive source start. Omitted means 1. Explicit ranges require content; starts past EOF and ranges on empty text are source validation errors.
1 <= x <= 2147483647Last line to read, inclusive; must be positive and not precede start_line. Omission reads to the end of the file. Values past the end are clamped. Requires the content group.
1 <= x <= 2147483647Time to wait for indexing: 0–60000 milliseconds, default 20000. The request deadline also includes the configured transport timeout.
0 <= x <= 60000Comma-separated atomic metadata/content groups; both default. No empty values, leaf paths or wildcard. Range arguments require content; at most 2048 decoded bytes.
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
Qualified source file
One exact file with mandatory source provenance and atomic selected groups.
Freshness of the served artifact; pending work is a typed error.
current, stale, provisional Active source indexing reference, null when absent; may accompany serveable evidence.
True for non-UTF-8 files; selected body and line counters are null.
Canonical target-relative source file path.
Requested intent, current resolution and actually served artifact.
Atomic source content group; omitted only when not selected.
Atomic metadata group; omitted only when not selected.