> ## Documentation Index > Fetch the complete documentation index at: https://docs.githits.com/llms.txt > Use this file to discover all available pages before exploring further. # List package or repository code files > Browse the indexed files in a package or public repository. Filter by path, programming language, extension, or file purpose to find the parts of a codebase you need. Use the returned file paths with `GET /v1/code/read` to read their contents, or use `POST /v1/code/grep` to search within them. ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json get /v1/code/files openapi: 3.1.0 info: description: >- Explore package metadata, security advisories, dependencies, documentation and source code with the GitHits API. ## Choose an operation | Task | Operations | | --- | --- | | Inspect a package | Release metadata, vulnerabilities and dependencies | | Review releases or upgrades | Changelog and batch upgrade reviews | | Read documentation | List package documentation, then read a page | | Navigate source code | List files, read a file or search text within a target | | Compare source trees | Compare files, line statistics and patches between package versions or repository refs | | Discover relevant content | Search across packages, repositories and documentation sites; retrieve a search's status and retained results | | Resolve a target name | Find ranked package, repository and documentation-site targets | | Ask a cited question | Generate an answer grounded in a package, repository or documentation site, or continue a conversation | | Generate an example | Generate and save a code example, then submit feedback | | Find a language identifier | Search supported programming languages | ## Authenticate and send requests The production API origin is `https://api.githits.dev`; development uses `https://api-dev.githits.dev`. Examples target production. Replace `` with your GitHits token. Send the token in `Authorization: Bearer `. JSON request bodies use `Content-Type: application/json`; public JSON field names use `snake_case`. Percent-encode a package name or opaque read target as one path segment, including any embedded slash. For query values, encode a literal plus sign as `%2B`; ordinary form decoding interprets `+` as a space. Each operation documents its accepted parameters and encoding rules. ## Select the data you need Where supported, `fields` is a comma-separated **query parameter**, including on POST requests. Omit it to use the operation's defaults. Supplying it replaces those defaults; required identity and information needed to interpret the result remain present. A **selector** names a supported **group** of response fields. Groups are atomic: their members are selected together. A **wildcard bundle**, such as `vulnerabilities.*`, selects only the groups listed for that bundle. A bare group does not automatically include nested groups. Arbitrary subfields and undeclared wildcards are not supported. Each operation lists its selectors, defaults, dependencies and the data they return. Selection can reduce transferred data without reducing the work needed to produce it; consult its parameter and response field documentation. Small fixed responses do not offer `fields`. ## Interpret responses and errors An omitted optional field can mean unselected or unavailable data, according to the operation's contract. Null has an operation-specific meaning: it can mark unavailable or inapplicable data, or an unselected search result. Empty arrays, zero and false are values, not substitutes for unavailable data. Always retain the result's completeness and freshness information when displaying or processing it. **Requested** identity records caller intent; **resolved** identity records what that intent resolved to; **served** identity identifies the artifact that produced the response. These can differ while indexing or refresh work continues. Use served identity when an exact follow-up read is required, preserving package-relative or repository-relative path scope. Errors normally use `application/problem+json`. Branch on the stable `code`, not the human-readable `detail`. Include `X-Request-ID` when reporting a problem; error `instance` matches that ID. Respect `Retry-After` when present. If request identity cannot be created, the response is an empty HTTP 500 without a request ID. Responses use `Cache-Control: no-store`. Timeouts do not guarantee that work stopped. Read the documented timeout responses, especially for Ask, generated examples and append-only feedback. Optional `X-GitHits-*` request headers attribute client, agent and session usage. The OpenAPI extension `x-githits-cost` is provisional operation metadata, not a price or a measure of computation. ## Contract status This API is pre-production. The external v1 contract is not yet frozen. license: name: Proprietary title: GitHits Public API version: 0.1.0 servers: - description: Production url: https://api.githits.dev security: [] tags: - description: >- Package metadata, release history, vulnerabilities, dependency graphs and upgrade comparisons. Each operation documents its registry, version and evidence scope. name: Packages - description: >- Discover existing documentation pages and read their content with exact source locators and availability information. name: Documentation - description: >- Enumerate files, read exact content and grep within a package or repository. Responses retain served identity, indexing state and completeness information. name: Code - description: >- Discover evidence across package, repository and documentation-site targets, then retrieve retained search results and progress. name: Search - description: >- Find supported programming-language names and aliases for example requests. name: Languages - description: >- Generate code examples for programming tasks, with source references and license attribution. name: Examples - description: Rate generated examples or sessions and provide written feedback. name: Feedback - description: >- Preview operations for target resolution, source comparison and cited questions. Routes use /v1/experimental and may later move to permanent v1 locations under a documented migration policy. name: Experimental paths: /v1/code/files: get: tags: - Code summary: List package or repository code files description: > Browse the indexed files in a package or public repository. Filter by path, programming language, extension, or file purpose to find the parts of a codebase you need. Use the returned file paths with `GET /v1/code/read` to read their contents, or use `POST /v1/code/grep` to search within them. operationId: get_code_files parameters: - description: >- Package registry, required with name; mutually exclusive with repo_url. in: query name: registry required: false schema: enum: - npm - pypi - hex - crates - vcpkg - zig - nuget - maven - packagist - rubygems - go - swift type: string - description: >- Package name (max 255 bytes), including encoded scoped names such as %40scope%2Fpackage. in: query name: name required: false schema: minLength: 1 type: string - description: >- Optional package version (max 100 bytes); forbidden with repo_url. Omission retains latest release intent. in: query name: version required: false schema: minLength: 1 type: string - description: >- Public GitHub, GitLab, or Codeberg repository root URL. HTTPS and git+https are supported on all three; GitHub also accepts http, git, ssh, and git+ssh. Use default transport ports and omit credentials, query strings, and fragments. GitLab nested groups are supported. Use HTTPS instead of scp-style shorthand. in: query name: repo_url required: false schema: minLength: 1 type: string - description: >- Repository-only branch, tag or SHA. Omission preserves default-branch intent; no implicit HEAD. in: query name: git_ref required: false schema: minLength: 1 type: string - description: Exact target-relative selector, OR-ed with path_prefix and globs. in: query name: path required: false schema: minLength: 1 type: string - description: >- Literal target-relative prefix, OR-ed with path/globs. Root-only dot means omitted. Trailing slash retains directory boundary. in: query name: path_prefix required: false schema: minLength: 1 type: string - description: Single inclusive intent; forbidden with file_intents. in: query name: file_intent required: false schema: enum: - production - test - benchmark - example - generated - fixture - build - vendor type: string - description: Exclude source-classified documentation after inclusive filtering. in: query name: exclude_doc_files required: false schema: default: false type: boolean - description: Exclude source-classified tests after inclusive filtering. in: query name: exclude_test_files required: false schema: default: false type: boolean - description: >- Include dotfiles and files under dot-prefixed path segments (default false). in: query name: include_hidden required: false schema: default: false type: boolean - description: >- Maximum files per page: 1–1000, default 200. A smaller page does not reduce file enumeration work. in: query name: limit required: false schema: default: 200 maximum: 1000 minimum: 1 type: integer - description: >- Nonnegative offset into all matching paths, default zero. Pin served artifact across pages. in: query name: offset required: false schema: default: 0 maximum: 2147483647 minimum: 0 type: integer - description: >- Time to wait for indexing: 0–60000 milliseconds, default 20000. Zero returns immediately; if files are not ready, the response is 503 PACKAGE_INDEXING. in: query name: wait_timeout_ms required: false schema: default: 20000 maximum: 60000 minimum: 0 type: integer - description: >- Repeatable OR-ed glob selectors; commas and braces remain literal glob text. At most 1000 path + globs selectors. explode: true in: query name: globs required: false schema: items: minLength: 1 type: string minItems: 1 type: array style: form - description: >- Repeat for each case-insensitive extension, without leading dot. AND with inclusion selectors. explode: true in: query name: extensions required: false schema: items: minLength: 1 type: string minItems: 1 type: array style: form - description: >- Repeat for each source file-type filter; values within this family are OR-ed. explode: true in: query name: file_types required: false schema: items: minLength: 1 type: string minItems: 1 type: array style: form - description: >- Repeat for each source language filter; values within this family are OR-ed. explode: true in: query name: languages required: false schema: items: minLength: 1 type: string minItems: 1 type: array style: form - description: Repeat for inclusive intents; forbidden with file_intent. explode: true in: query name: file_intents required: false schema: items: enum: - production - test - benchmark - example - generated - fixture - build - vendor type: string minItems: 1 type: array style: form - description: Repeat for intents excluded after inclusive filtering. explode: true in: query name: exclude_file_intents required: false schema: items: enum: - production - test - benchmark - example - generated - fixture - build - vendor type: string minItems: 1 type: array style: form - description: >- Optional client attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped. in: header name: X-GitHits-Client-Name required: false schema: type: string - description: >- Optional client-version attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped. in: header name: X-GitHits-Client-Version required: false schema: type: string - description: >- Optional agent attribution: trimmed printable ASCII, at most 160 bytes. Invalid optional values are dropped. in: header name: X-GitHits-Agent required: false schema: type: string - description: >- Optional session attribution: trimmed printable ASCII, at most 128 bytes. Invalid optional values are dropped; no session is created. in: header name: X-GitHits-Session-ID required: false schema: type: string responses: '200': content: application/json: example: code_index_state: current files: - byte_size: 0 file_type: source language: rust name: main.rs path: src/main.rs indexing_ref: null limit: 200 offset: 0 returned: 1 target_resolution: freshness: current freshness_reason: exact_current requested: commit_sha: null git_ref: null kind: repo_default_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 total: 1 schema: $ref: '#/components/schemas/CodeFilesResponse' description: Sorted matching file page headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '400': content: application/problem+json: example: code: VALIDATION_ERROR detail: The request is invalid. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Validation error type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: VALIDATION_ERROR headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '401': content: application/problem+json: example: code: AUTHENTICATION_REQUIRED detail: A bearer credential is required. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 401 title: Authentication required type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: AUTHENTICATION_REQUIRED headers: Cache-Control: schema: enum: - no-store type: string WWW-Authenticate: description: Bearer challenge. schema: type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '403': content: application/problem+json: example: code: FORBIDDEN detail: The caller is not allowed to access this resource. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 403 title: Forbidden type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- FORBIDDEN, ACCOUNT_INACTIVE, FEATURE_FLAG_REQUIRED, TERMS_ACCEPTANCE_REQUIRED headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '404': content: application/problem+json: example: code: PACKAGE_NOT_FOUND detail: The requested package was not found. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 404 title: Package not found type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- PACKAGE_NOT_FOUND, NO_RELEASED_VERSIONS, VERSION_NOT_FOUND, REPOSITORY_NOT_FOUND, REF_NOT_FOUND headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '405': content: application/problem+json: example: code: METHOD_NOT_ALLOWED detail: The requested method is not supported for this route. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 405 title: Method not allowed type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: 'METHOD_NOT_ALLOWED: the route does not support this HTTP method.' headers: Allow: description: 'Supported methods: GET, HEAD.' schema: type: string Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '422': content: application/problem+json: example: code: UNSUPPORTED_PACKAGE_VARIANTS detail: The package release has unsupported artifact variants. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 422 title: Unsupported package variants type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: UNSUPPORTED_PACKAGE_VARIANTS, AMBIGUOUS_REF, REF_UNRESOLVABLE headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '429': content: application/problem+json: example: code: RATE_LIMITED detail: The request was rate limited. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 429 title: Rate limited type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: RATE_LIMITED headers: Cache-Control: schema: enum: - no-store type: string Retry-After: description: Optional bounded delta seconds or HTTP date. schema: type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '500': description: >- Request identity could not be created. Empty body without X-Request-ID; no problem object is available. headers: Cache-Control: schema: enum: - no-store type: string x-githits-empty-identity-failure: true '502': content: application/problem+json: example: code: UPSTREAM_ERROR detail: The upstream service failed to provide a response. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 502 title: Upstream error type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: UPSTREAM_ERROR headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '503': content: application/problem+json: example: code: PACKAGE_INDEXING detail: Code evidence is not ready; retry the request later. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 503 title: Code indexing type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: PACKAGE_INDEXING headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '504': content: application/problem+json: example: code: TIMEOUT detail: The upstream request did not complete in time. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 504 title: Upstream timeout type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: TIMEOUT headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string security: - bearer_auth: [] x-codeSamples: - label: Scoped package lang: HTTP source: |- GET /v1/code/files?registry=npm&name=%40scope%2Fpackage HTTP/1.1 Host: api.githits.dev Authorization: Bearer - label: Repository branch lang: HTTP source: >- GET /v1/code/files?repo_url=https%3A%2F%2Fgitlab.com%2Fgroup%2Frepository&git_ref=feature%2Fbranch&limit=1000&offset=1000 HTTP/1.1 Host: api.githits.dev Authorization: Bearer - label: Brace glob lang: HTTP source: >- GET /v1/code/files?registry=npm&name=express&globs=src%2F**%2F*.%7Bjs%2Cts%7D&globs=test%2F**&extensions=js&extensions=ts HTTP/1.1 Host: api.githits.dev Authorization: Bearer components: schemas: CodeFilesResponse: description: One source inventory page and the exact evidence qualification. properties: code_index_state: $ref: '#/components/schemas/CodeIndexState' description: Freshness of the served code inventory. files: description: Atomic rows sorted by target-relative path ascending. items: $ref: '#/components/schemas/CodeFile' type: array indexing_ref: description: >- Opaque active indexing reference, including refresh of stale or provisional evidence; null when absent. type: - string - 'null' limit: description: Effective page cap, 1 through 1000 (default 200). format: int32 type: integer offset: description: Requested nonnegative offset into the sorted filtered inventory. format: int32 type: integer returned: description: Number of rows in this page. minimum: 0 type: integer target_resolution: $ref: '#/components/schemas/CodeTargetResolution' description: >- Canonical requested, resolved and served provenance reported by the source. total: description: All matching files across every page. format: int64 minimum: 0 type: integer required: - target_resolution - code_index_state - indexing_ref - total - offset - limit - returned - files type: object ProblemResponse: description: >- The stable problem document returned for an unsuccessful public API request. properties: acceptance_url: description: An optional acceptance URL supplied by the upstream allow-list. type: string code: description: The stable uppercase API error code. type: string detail: description: A stable, client-safe explanation of the failure. type: string instance: description: The active request trace ID. type: string status: description: The HTTP status returned with this problem. format: int32 minimum: 0 type: integer terms_url: description: An optional terms URL supplied by the upstream allow-list. type: string title: description: A short, stable title for the error. type: string type: description: The generic RFC 9457 problem type. type: string required: - type - title - status - detail - instance - code type: object CodeIndexState: description: >- Serveable code lifecycle states; pending work produces `PACKAGE_INDEXING`. enum: - current - stale - provisional type: string CodeFile: description: >- Metadata for one indexed file. Null means unavailable; empty strings and zero bytes remain explicit values. properties: byte_size: description: Size in bytes; null when unknown, zero for an empty file. format: int64 minimum: 0 type: - integer - 'null' file_type: oneOf: - type: 'null' - $ref: '#/components/schemas/CodeFileType' description: >- Source classification: source, doc, config, other; null when unknown. language: description: Detected language, or null. type: - string - 'null' name: description: File basename. type: string path: description: Target-relative inventory path. type: string required: - path - name - language - file_type - byte_size type: object CodeTargetResolution: description: Source-reported identity; never reconstructed from caller input. properties: freshness: description: 'Source freshness: current, `fallback_recent` or provisional.' type: string freshness_reason: description: Machine-readable source explanation of freshness. type: string requested: $ref: '#/components/schemas/CodeIdentity' description: Original request intent including omitted version or default branch. resolved_requested: $ref: '#/components/schemas/CodeIdentity' description: Current resolved request; may be fresher than the served artifact. served: $ref: '#/components/schemas/CodeIdentity' description: >- Exact served artifact; prefer `commit_sha` over `git_ref` for repository pagination. required: - requested - resolved_requested - served - freshness - freshness_reason type: object CodeFileType: description: Source-reported inventory classification. enum: - source - doc - config - other type: string CodeIdentity: description: >- One side of source target resolution; unknown metadata is explicitly null. properties: commit_sha: description: Exact commit when known; preferred artifact pin. type: - string - 'null' git_ref: description: Requested or served ref according to this identity side. type: - string - 'null' kind: description: >- Original request kind on requested identity; null on concrete identities. type: - string - 'null' name: description: Canonical package name, null for repository targets. type: - string - 'null' registry: description: Canonical package registry, null for repository targets. type: - string - 'null' repo_url: description: Repository backing the target when known. type: - string - 'null' version: description: Concrete package version when resolved; null for repository targets. type: - string - 'null' required: - kind - registry - name - version - repo_url - git_ref - commit_sha type: object securitySchemes: bearer_auth: scheme: bearer type: http ````