> ## 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 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 code grep for exact source text. ## 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. 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. `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. ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json post /v1/list 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 or source code | Browse with list, then follow an exact action through the unified read operation | | Browse known content | List source files, local documentation, or an explicit hosted site | | Find exact source text | Grep text within a package or repository | | 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 | | Research 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 | | Generate an SBOM | Upload manifests and lockfiles to receive a CycloneDX, SPDX or text inventory | | 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`. Standard SBOM documents retain their format's field names. Percent-encode path parameters such as package names as one path segment, including any embedded slash. The unified read target is a query value: encode a literal plus sign as `%2B` and a literal fragment marker as `%23`; 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 Research, 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: >- Browse package, repository or hosted-site paths and follow exact read and browse actions. name: List - description: >- Package metadata, release history, vulnerabilities, dependency graphs and upgrade comparisons. Each operation documents its registry, version and evidence scope. name: Packages - description: >- Grep text within a package or repository. Responses retain served identity, indexing state and completeness information. name: Code - description: >- Read an exact documentation page or source file and retain the page, package-version or repository-commit details needed to cite it. name: Read - 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, cited questions and SBOM generation. Routes use /v1/experimental and may later move to permanent v1 locations under a documented migration policy. name: Experimental paths: /v1/list: post: tags: - List summary: List files and documentation paths description: > 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 code grep for exact source text. ## 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. 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. `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. operationId: post_list parameters: - 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 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. in: header name: X-GitHits-Session-ID required: false schema: maxLength: 64 minLength: 1 pattern: ^[A-Za-z0-9_-]{1,64}$ type: string requestBody: content: application/json: examples: continuation: value: after: opaque-cursor limit: 100 target: npm:express@5.2.1 package: value: target: npm:express@5.2.1 recursive: value: paths: - lib/**/*.js recursive: true target: github:expressjs/express site: value: limit: 100 paths: - / target: site:expressjs.com/en schema: $ref: '#/components/schemas/ListRequest' required: true responses: '200': content: application/json: examples: preparing: summary: Unprepared source inventory with no served artifact value: available_versions: - ref: v5.2.1 version: 5.2.1 canonical_target: null code_index_state: pending coverage_reason: null coverage_state: null crawl_status: null entries: [] has_more: false indexed_version: null indexing_estimate: null indexing_ref: preparation-ref indexing_status: pending inventory_kind: source inventory_state: null next_cursor: null preparation: null requested_target: npm:express resolution: null target_resolution: available_refs: [] available_versions: - ref: v5.2.1 version: 5.2.1 freshness: current freshness_reason: exact_current indexing_ref: null requested: commit_sha: null git_ref: null kind: package_omitted_version package_name: express registry: npm repo_url: https://github.com/expressjs/express version: null resolved_requested: commit_sha: 0123456789abcdef0123456789abcdef01234567 git_ref: v5.2.1 kind: null package_name: express registry: npm repo_url: https://github.com/expressjs/express version: 5.2.1 served: null suggested_refs: [] site: summary: Hosted paths with independent crawl and coverage evidence value: available_versions: null canonical_target: site:expressjs.com/en code_index_state: null coverage_reason: null coverage_state: complete crawl_status: complete 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: [] awaited: [] enqueued: 0 selected: 0 requested_target: site:expressjs.com/en resolution: null target_resolution: null source: summary: Source files with exact read and browse actions value: available_versions: - ref: v5.2.1 version: 5.2.1 canonical_target: npm:express@5.2.1 code_index_state: current coverage_reason: null coverage_state: null crawl_status: null entries: - browse: null byte_size: 100 content_hash: hash-1 file_type: config intent: production kind: file language: JSON line_count: 10 path: package.json read: path: package.json target: npm:express@5.2.1 title: null - browse: paths: - lib/ target: npm:express@5.2.1 byte_size: null content_hash: null file_type: null intent: null kind: directory language: null line_count: null path: lib/ read: null title: null has_more: false indexed_version: v5.2.1 indexing_estimate: null indexing_ref: null indexing_status: indexed inventory_kind: source inventory_state: null next_cursor: null preparation: null requested_target: npm:express resolution: commit_sha: 0123456789abcdef0123456789abcdef01234567 requested_ref: null requested_version: null resolved_ref: v5.2.1 target_resolution: available_refs: [] available_versions: - ref: v5.2.1 version: 5.2.1 freshness: current freshness_reason: exact_current indexing_ref: null requested: commit_sha: null git_ref: null kind: package_omitted_version package_name: express registry: npm repo_url: https://github.com/expressjs/express version: null resolved_requested: commit_sha: 0123456789abcdef0123456789abcdef01234567 git_ref: v5.2.1 kind: null package_name: express registry: npm repo_url: https://github.com/expressjs/express version: 5.2.1 served: commit_sha: 0123456789abcdef0123456789abcdef01234567 git_ref: v5.2.1 kind: null package_name: express registry: npm repo_url: https://github.com/expressjs/express version: 5.2.1 suggested_refs: [] schema: $ref: '#/components/schemas/ListResponse' description: >- One source or hosted-site inventory page with exact actions and readiness evidence headers: 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 '400': content: application/problem+json: examples: invalid_session_id: value: code: INVALID_SESSION_ID detail: >- X-GitHits-Session-ID must occur once and match [A-Za-z0-9_-]{1,64}. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Invalid session ID type: about:blank validation: value: code: VALIDATION_ERROR detail: Set limit to an integer from 1 through 500. instance: fixture-request status: 400 title: Validation error type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: >- Correct target, paths, filters, limit, wait_timeout_ms, or cursor; narrow an oversized request or page. INVALID_SESSION_ID: a supplied session header is invalid or duplicated. headers: 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 '401': content: application/problem+json: example: code: AUTHENTICATION_REQUIRED detail: A bearer credential is required. instance: fixture-request status: 401 title: Authentication required type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: Supply a valid bearer credential. headers: Cache-Control: schema: enum: - no-store type: string WWW-Authenticate: schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '403': content: application/problem+json: example: code: FORBIDDEN detail: The caller is not allowed to access this resource. instance: fixture-request status: 403 title: Forbidden type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: Account, capability or terms restrictions prevent this request. headers: 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 '404': content: application/problem+json: example: code: LIST_TARGET_NOT_FOUND detail: >- The requested package, repository, or documentation site was not found. instance: fixture-request status: 404 title: List target not found type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: The list target, source repository, or repository ref was not found. headers: 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 '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: POST.' 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 '409': content: application/problem+json: example: code: SOURCE_INVENTORY_SCOPE_UNAVAILABLE detail: >- The package-owned inventory is unavailable. A pinned repository target covers a broader scope; use it only if that scope is acceptable. instance: fixture-request status: 409 title: Package inventory unavailable type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: >- The target is being prepared, or its package-owned inventory is unavailable. Review the supplied recovery evidence. headers: 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: AMBIGUOUS_REF detail: >- The repository ref is ambiguous. Use an exact commit to select one snapshot. instance: fixture-request status: 422 title: Ambiguous ref type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: >- The repository ref is ambiguous; use an exact commit to select one snapshot. headers: 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 '429': content: application/problem+json: example: code: RATE_LIMITED detail: The request was rate limited. instance: fixture-request status: 429 title: Rate limited type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: Rate limit reached. Respect Retry-After when present. headers: Cache-Control: schema: enum: - no-store type: string Retry-After: schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. 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: LIST_UNSUPPORTED_API detail: >- The inventory service does not support this operation. No fallback query was attempted. instance: fixture-request status: 502 title: Inventory protocol unavailable type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: >- The inventory service returned an unsupported or malformed response. No fallback query was attempted. headers: 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 '504': content: application/problem+json: example: code: TIMEOUT detail: The upstream request did not complete in time. instance: fixture-request status: 504 title: Upstream timeout type: about:blank schema: $ref: '#/components/schemas/ListProblem' description: The inventory deadline expired. Preparation may continue. headers: 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 security: - bearer_auth: [] x-codeSamples: - label: Browse a package lang: HTTP source: |- POST /v1/list HTTP/1.1 Host: api.githits.dev Authorization: Bearer Content-Type: application/json {"target":"npm:express@5.2.1"} - label: Browse hosted documentation lang: HTTP source: |- POST /v1/list HTTP/1.1 Host: api.githits.dev Authorization: Bearer Content-Type: application/json {"target":"site:expressjs.com/en","recursive":true} components: schemas: ListRequest: additionalProperties: false description: >- Selection for a source or hosted-site inventory page. Unknown and null controls are rejected. properties: after: description: >- Opaque continuation. Blank starts page one; preserve a nonblank cursor unchanged and repeat the same selection. type: string file_types: description: >- Source-only raw file-type labels; at most 64, trimmed and lowercased. Empty means no filter. items: type: string maxItems: 64 type: array intents: description: >- Source-only file-purpose inclusion union; at most 64 values. Empty means no filter. items: $ref: '#/components/schemas/ListIntent' maxItems: 64 type: array languages: description: >- Source-only language labels; at most 64, trimmed and lowercased. Empty means no filter. items: type: string maxItems: 64 type: array limit: default: 100 description: >- Logical entries per page, 1 through 500, default 100. No total count is implied. format: int32 maximum: 500 minimum: 1 type: integer paths: description: >- 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. items: type: string maxItems: 1000 type: array recursive: default: false description: >- Default false lists immediate directory children. True expands selected directories to leaves; glob depth is independent. type: boolean target: description: >- Required nonblank compact package, repository, or explicit site:host[/scope] target. Forwarded unchanged. minLength: 1 type: string wait_timeout_ms: default: 0 description: >- Source or empty-site preparation wait, 0 through 210000 milliseconds, default 0. Transport time is added; timeout does not mean preparation stopped. format: int32 maximum: 210000 minimum: 0 type: integer required: - target type: object ListResponse: description: >- One bounded inventory page with exact follow-up actions and readiness evidence. properties: available_versions: description: >- Indexed package versions or repository refs for immediate retry; null for sites. items: $ref: '#/components/schemas/ListAvailableVersion' type: - array - 'null' canonical_target: description: >- Resolved package version, repository commit, or site scope; null while unavailable. type: - string - 'null' code_index_state: oneOf: - type: 'null' - $ref: '#/components/schemas/ListCodeState' description: Source freshness or preparation state; null for sites. coverage_reason: description: Hosted coverage explanation, when available. type: - string - 'null' coverage_state: oneOf: - type: 'null' - $ref: '#/components/schemas/ListCoverageState' description: >- Hosted inventory coverage; empty entries alone do not establish completion. crawl_status: oneOf: - type: 'null' - $ref: '#/components/schemas/ListCrawlStatus' description: Latest hosted-site crawl state, or null. entries: description: Ordered entries on this bounded page; no total count is implied. items: $ref: '#/components/schemas/ListEntry' type: array has_more: description: Whether another inventory page is available. type: boolean indexed_version: description: Served source ref; null for sites or unprepared source. type: - string - 'null' indexing_estimate: oneOf: - type: 'null' - $ref: '#/components/schemas/ListIndexingEstimate' description: Source preparation estimate, when known. indexing_ref: description: Opaque active source preparation reference, or null. type: - string - 'null' indexing_status: oneOf: - type: 'null' - $ref: '#/components/schemas/ListIndexingStatus' description: >- Source indexing lifecycle; prefer `code_index_state` for freshness. inventory_kind: $ref: '#/components/schemas/ListInventoryKind' description: 'Inventory being browsed: source files or hosted documentation.' inventory_state: oneOf: - type: 'null' - $ref: '#/components/schemas/ListInventoryState' description: >- Whether the hosted site has active pages; null for source inventories. next_cursor: description: >- Opaque continuation; repeat the same request with this value as after. type: - string - 'null' preparation: oneOf: - type: 'null' - $ref: '#/components/schemas/ListPreparation' description: >- Hosted-site admission, active work and bounded wait evidence, or null. requested_target: description: Normalized target bound to this page and continuation. type: string resolution: oneOf: - type: 'null' - $ref: '#/components/schemas/ListResolution' description: Source snapshot resolution; null when not applicable or known. target_resolution: oneOf: - type: 'null' - $ref: '#/components/schemas/ListTargetResolution' description: >- Requested, resolved and served source provenance, including retry candidates. required: - inventory_kind - requested_target - canonical_target - entries - has_more - next_cursor - indexed_version - resolution - target_resolution - code_index_state - indexing_status - indexing_ref - available_versions - indexing_estimate - inventory_state - crawl_status - coverage_state - coverage_reason - preparation type: object ListProblem: allOf: - $ref: '#/components/schemas/ProblemResponse' description: Shared stable problem details and request identity. - properties: commit_sha: description: Exact repository commit for a pinned retry. type: string indexing_ref: description: Opaque active preparation reference, when supplied. type: string repo_url: description: Safe repository root for an explicitly broader pinned retry. type: string type: object description: >- List failure with bounded optional recovery evidence; ordinary failures use the shared shape. 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 ListIntent: description: Purpose of a source file; inclusion values form a union. enum: - production - test - benchmark - example - generated - fixture - build - vendor type: string ListAvailableVersion: description: >- An indexed package version or repository ref available for a fresh request. properties: ref: description: Indexed repository ref. A ref-only value is not a package version. type: string version: description: Package-form retry version; when null use repository form with ref. type: - string - 'null' required: - version - ref type: object ListCodeState: description: Source freshness and preparation state. enum: - current - stale - provisional - indexing - pending - failed - not_found - unresolvable type: string ListCoverageState: description: How much of the hosted site the inventory covers. enum: - none - partial - capped - complete type: string ListCrawlStatus: description: State of the most recent hosted-site crawl. enum: - idle - running - complete - failed type: string ListEntry: description: A source file, hosted page, or directory on this page. properties: browse: oneOf: - type: 'null' - $ref: '#/components/schemas/ListBrowseAction' description: >- Exact browse action; pass target and paths to a fresh POST /v1/list request. byte_size: description: Source size in bytes; zero is an empty file, null means unknown. format: int64 minimum: 0 type: - integer - 'null' content_hash: description: Source content identity, or null. type: - string - 'null' file_type: description: Raw source file-type label, or null. type: - string - 'null' intent: description: Source file-purpose label, or null. type: - string - 'null' kind: $ref: '#/components/schemas/ListEntryKind' description: File, hosted page, or directory. language: description: Detected source language, or null. type: - string - 'null' line_count: description: Source line count, or null. format: int64 minimum: 0 type: - integer - 'null' path: description: >- Target-relative display path. Follow the exact action instead of reconstructing it. type: string read: oneOf: - type: 'null' - $ref: '#/components/schemas/ListReadAction' description: >- Exact read action; encode its values as query parameters to GET /v1/read. title: description: Hosted page title, or null. type: - string - 'null' required: - kind - path - title - language - file_type - intent - byte_size - line_count - content_hash - read - browse type: object ListIndexingEstimate: description: Source preparation timing evidence, when available. properties: elapsed_seconds: description: Active elapsed duration in seconds, or null. format: int64 minimum: 0 type: - integer - 'null' lower_seconds: description: Estimated lower duration in seconds, or null. format: int64 minimum: 0 type: - integer - 'null' sample_count: description: Historical duration sample count, or null. format: int64 minimum: 0 type: - integer - 'null' source: description: Producer estimate basis, or null. type: - string - 'null' upper_seconds: description: Estimated upper duration in seconds, or null. format: int64 minimum: 0 type: - integer - 'null' required: - lower_seconds - upper_seconds - elapsed_seconds - sample_count - source type: object ListIndexingStatus: description: Source indexing lifecycle, independent of freshness. enum: - indexed - indexing - pending - failed - not_found - unresolvable type: string ListInventoryKind: description: Whether this page lists source files or hosted documentation. enum: - source - site type: string ListInventoryState: description: Whether the hosted site has stored pages available to browse. enum: - available - empty type: string ListPreparation: description: Hosted-site preparation admission, active jobs, and wait results. properties: active_jobs: description: Active hosted preparation jobs. items: $ref: '#/components/schemas/ListPreparationJob' type: array awaited: description: Outcomes of bounded hosted waits. items: $ref: '#/components/schemas/ListPreparationWait' type: array enqueued: description: Number of newly enqueued hosted preparation jobs. format: int64 minimum: 0 type: integer selected: description: Number of selected hosted preparation jobs. format: int64 minimum: 0 type: integer required: - selected - enqueued - active_jobs - awaited type: object ListResolution: description: The source ref and commit selected for this inventory. properties: commit_sha: description: Served repository commit, or null. type: - string - 'null' requested_ref: description: Repository ref requested, or null. type: - string - 'null' requested_version: description: Package version expression requested, or null. type: - string - 'null' resolved_ref: description: Served indexed ref, or null. type: - string - 'null' required: - requested_version - requested_ref - resolved_ref - commit_sha type: object ListTargetResolution: description: Caller intent, resolved target, and the artifact actually served. properties: available_refs: description: Indexed repository retry candidates. items: $ref: '#/components/schemas/ListAvailableVersion' type: array available_versions: description: >- Indexed package retry candidates; an empty array means none are known. items: $ref: '#/components/schemas/ListAvailableVersion' type: array freshness: description: Producer freshness state, or null. type: - string - 'null' freshness_reason: description: Producer freshness qualification, or null. type: - string - 'null' indexing_ref: description: Active preparation owner reference, or null. type: - string - 'null' requested: oneOf: - type: 'null' - $ref: '#/components/schemas/ListIdentity' description: Original source identity requested, or null. resolved_requested: oneOf: - type: 'null' - $ref: '#/components/schemas/ListIdentity' description: Concrete identity resolved for this request, or null. served: oneOf: - type: 'null' - $ref: '#/components/schemas/ListIdentity' description: >- Identity that produced evidence; null before any artifact is served. suggested_refs: description: Suggested repository refs; these need not be indexed. items: $ref: '#/components/schemas/ListAvailableVersion' type: array required: - requested - resolved_requested - served - freshness - freshness_reason - indexing_ref - available_versions - available_refs - suggested_refs type: object ListBrowseAction: description: An exact action for browsing this directory through POST /v1/list. properties: paths: description: Exact target-relative selectors. Pass unchanged with a fresh cursor. items: type: string type: - array - 'null' target: description: Complete follow-up browse target. Pass unchanged. type: string required: - target - paths type: object ListEntryKind: description: The kind of path represented by an entry. enum: - file - page - directory type: string ListReadAction: description: An exact action for reading this entry through GET /v1/read. properties: path: description: >- Exact read path. Omit null; preserve slash-pair, query and percent bytes. type: - string - 'null' target: description: Complete read target. Pass unchanged. type: string required: - target - path type: object ListPreparationJob: description: An active hosted-site preparation job. properties: mode: description: Preparation mode, or null. type: - string - 'null' state: description: Producer job state. type: string required: - mode - state type: object ListPreparationWait: description: The result of one bounded hosted-site preparation wait. properties: mode: description: Preparation mode, or null. type: - string - 'null' outcome: $ref: '#/components/schemas/ListWaitOutcome' description: Outcome of this preparation wait. required: - mode - outcome type: object ListIdentity: description: Source-reported identity; unavailable facts remain null. properties: commit_sha: description: Exact source commit, or null. type: - string - 'null' git_ref: description: Source Git ref, or null. type: - string - 'null' kind: description: >- Original request kind; normally null on resolved or served identities. type: - string - 'null' package_name: description: Source package name, or null. type: - string - 'null' registry: description: Source package registry, or null. type: - string - 'null' repo_url: description: Source repository URL, or null. type: - string - 'null' version: description: Source package version, or null. type: - string - 'null' required: - kind - registry - package_name - version - repo_url - git_ref - commit_sha type: object ListWaitOutcome: description: Outcome of a bounded hosted-site preparation wait. enum: - completed - discarded - cancelled - timeout type: string securitySchemes: bearer_auth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.