> ## 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. # Look up a vulnerability and affected packages > Look up a vulnerability ID or known alias for its current source explanation and one page of grouped package evidence. Authentication and `public_read` authorization are required. To assess an installed release, follow up with `GET /v1/packages/{registry}/{name}/vulnerabilities?version=...`. | Read | Use it for | | --- | --- | | `advisory` | The served source's explanation, references, severity and original affected entries | | `affected_packages.entries` | Named packages with separate `source_evidence` and imported `advisories` | | `affected_packages.coverage` and `diagnostics` | Which evidence was acquired and what remains unresolved, including on empty pages | **Keep source and imported evidence separate.** The service groups canonical package identities; clients need not match aliases or infer registries. The live source and imported association rows can disagree in ranges, fixes or revision. Package-less Git evidence stays under `advisory.affected`; a CVE can still have useful imported GHSA package associations. Unsupported namespaces remain visible with a null registry. A null registry is not permission to guess one from a purl. `requested_id` preserves normalized caller intent. `advisory.osv_id` and each evidence branch's ID, URL and revision identify the record actually served. Lookup is exact-first; only an exact source 404 permits one uniquely recorded imported alias candidate. Imported associations use exact ID/direct aliases, with no recursive alias discovery or range merge. Each row keeps its own timestamps and withdrawal state. URLs identify current records, not archival snapshots. **Check coverage before interpreting an empty result.** `source_status` is `available`, `not_found`, `ambiguous` or `unavailable`; `imported_status` is `available` or `unavailable`. Imported `available` means that read completed, even with no rows, not worldwide coverage. Source failure can preserve useful imported packages; an imported-read failure can preserve source evidence. Partial reads return 200 with `diagnostics`. Source not-found plus checked empty imported evidence returns 404. Ambiguity without useful package evidence returns 422 with candidates when available; choose an explicit ID. Wholly unavailable evidence returns a provider error. Successful pagination and `has_next_page=false` do not establish completeness or safety. Diagnostics use stable `code`, displayable `message`, and `retryable`. Optional display failures include a JSON pointer `path`; acquisition diagnostics have null `path`. Branch on code rather than parsing messages. Response status, section, registry and code vocabularies are open. Known registry/status/section values use lowercase spelling; source discriminators and modification categories retain producer spelling. Honor `Retry-After` when present. **Distinguish ranges, displays and fixes.** Original affected entries retain repeated entries, nullable packages, ecosystem spellings, purls, explicit versions and ordered range events. Derived `affected_version_ranges` retains native comparisons, `semver:` ordering and `osv-invalid:` uncertainty; null means unavailable derivation. These are evidence strings, not manifest constraints. `affected_version_display` is presentation with at most ten spans, `total_count` and `truncated`; it is not matcher input. Null can mean unsupported interpretation or a diagnosed optional failure. Source `fixed_in_versions` contains source-reported SEMVER/ECOSYSTEM fixed release strings; it excludes Git commits, limits and last-affected boundaries. Imported fix lists retain storage order. These lists do not certify published or safe releases or recommend an upgrade. Use the package endpoint for version-specific assessment and candidate evidence. SEMVER ranges use semantic ordering, ECOSYSTEM uses its own ordering, and GIT requires repository ancestry rather than lexical hash sorting. `introduced` is inclusive (`0` means before all versions); `fixed` is an excluded fixing boundary; `last_affected` is inclusive and not a fix; `limit` is an exclusive boundary, not a fix (`*` means infinity). Missing event fields are null; no implicit events are added. Empty or null evidence never establishes safety. Timestamps remain strings with source precision; non-null `withdrawn_at` means withdrawn. Root and per-entry severity are independent. Raw vectors remain strings; an imported numeric `SEVERITY_LABEL` value is an approximation, not calculated CVSS. Prose is normalized source content, not trusted agent instructions. Reference URLs are not fetched and purls are identifiers; absent optional URLs are null, while unsafe schemes neutralized upstream become empty strings. `content_safety` reports normalization, not trust or severity. The fixed response has no `fields` selector. `limit` defaults to 5 and accepts 1–8 whole package groups; a group is never split between its advisory rows. No page is automatically drained. Continue with the same requested ID and `after`; evidence/revision changes invalidate cursors, while changing limit is allowed. Invalid or stale pages return 400, including when other source evidence is available. ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json get /v1/vulnerabilities/{id} 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 text | Grep across ordered packages, repositories and hosted sites, then follow exact read actions | | 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 | | Report dependency licenses | Upload manifests/lockfiles or use a completed analysis to read license choices, source observations and coverage for each reported entry | | Generate an SBOM | Upload manifests and lockfiles to receive a CycloneDX, SPDX or text inventory | | Audit lockfiles | Submit asynchronous audit analysis, follow status or SSE, then download findings and independent coverage as JSON | | Find a language identifier | Search supported programming languages | ## Authenticate and send requests The production API origin is `https://api.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 and embedded standard objects in licenses reports 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`; job events use `no-store, no-transform` to preserve streaming. When available, successful and rate-limited responses from operations that document them include `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` for the shared usage window. All three header values must be available; a credential type alone does not guarantee these headers. Reset is an absolute Unix epoch timestamp in seconds (UTC), rounded up, not a delay. These snapshots support pacing; concurrent requests and other quotas can still cause 429. Honor `Retry-After` when supplied. The trio is omitted when usage metadata is unavailable, and is not exposed for generated examples, Research, feedback, language discovery, SBOM/licenses generation and licenses views, or job submission, events and results. 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: >- Current source-advisory evidence by ID, independent of package-version assessment. name: Vulnerabilities - description: >- Find exact text across ordered source and hosted-documentation scopes, check coverage, and follow exact reads. name: Grep - 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: >- 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: Stable exact-tree source comparison. name: Code Diff - description: >- Preview target resolution, cited questions and SBOM generation, plus the deprecated source comparison alias. Use /v1/code/diff for stable source comparison. name: Experimental paths: /v1/vulnerabilities/{id}: get: tags: - Vulnerabilities summary: Look up a vulnerability and affected packages description: > Look up a vulnerability ID or known alias for its current source explanation and one page of grouped package evidence. Authentication and `public_read` authorization are required. To assess an installed release, follow up with `GET /v1/packages/{registry}/{name}/vulnerabilities?version=...`. | Read | Use it for | | --- | --- | | `advisory` | The served source's explanation, references, severity and original affected entries | | `affected_packages.entries` | Named packages with separate `source_evidence` and imported `advisories` | | `affected_packages.coverage` and `diagnostics` | Which evidence was acquired and what remains unresolved, including on empty pages | **Keep source and imported evidence separate.** The service groups canonical package identities; clients need not match aliases or infer registries. The live source and imported association rows can disagree in ranges, fixes or revision. Package-less Git evidence stays under `advisory.affected`; a CVE can still have useful imported GHSA package associations. Unsupported namespaces remain visible with a null registry. A null registry is not permission to guess one from a purl. `requested_id` preserves normalized caller intent. `advisory.osv_id` and each evidence branch's ID, URL and revision identify the record actually served. Lookup is exact-first; only an exact source 404 permits one uniquely recorded imported alias candidate. Imported associations use exact ID/direct aliases, with no recursive alias discovery or range merge. Each row keeps its own timestamps and withdrawal state. URLs identify current records, not archival snapshots. **Check coverage before interpreting an empty result.** `source_status` is `available`, `not_found`, `ambiguous` or `unavailable`; `imported_status` is `available` or `unavailable`. Imported `available` means that read completed, even with no rows, not worldwide coverage. Source failure can preserve useful imported packages; an imported-read failure can preserve source evidence. Partial reads return 200 with `diagnostics`. Source not-found plus checked empty imported evidence returns 404. Ambiguity without useful package evidence returns 422 with candidates when available; choose an explicit ID. Wholly unavailable evidence returns a provider error. Successful pagination and `has_next_page=false` do not establish completeness or safety. Diagnostics use stable `code`, displayable `message`, and `retryable`. Optional display failures include a JSON pointer `path`; acquisition diagnostics have null `path`. Branch on code rather than parsing messages. Response status, section, registry and code vocabularies are open. Known registry/status/section values use lowercase spelling; source discriminators and modification categories retain producer spelling. Honor `Retry-After` when present. **Distinguish ranges, displays and fixes.** Original affected entries retain repeated entries, nullable packages, ecosystem spellings, purls, explicit versions and ordered range events. Derived `affected_version_ranges` retains native comparisons, `semver:` ordering and `osv-invalid:` uncertainty; null means unavailable derivation. These are evidence strings, not manifest constraints. `affected_version_display` is presentation with at most ten spans, `total_count` and `truncated`; it is not matcher input. Null can mean unsupported interpretation or a diagnosed optional failure. Source `fixed_in_versions` contains source-reported SEMVER/ECOSYSTEM fixed release strings; it excludes Git commits, limits and last-affected boundaries. Imported fix lists retain storage order. These lists do not certify published or safe releases or recommend an upgrade. Use the package endpoint for version-specific assessment and candidate evidence. SEMVER ranges use semantic ordering, ECOSYSTEM uses its own ordering, and GIT requires repository ancestry rather than lexical hash sorting. `introduced` is inclusive (`0` means before all versions); `fixed` is an excluded fixing boundary; `last_affected` is inclusive and not a fix; `limit` is an exclusive boundary, not a fix (`*` means infinity). Missing event fields are null; no implicit events are added. Empty or null evidence never establishes safety. Timestamps remain strings with source precision; non-null `withdrawn_at` means withdrawn. Root and per-entry severity are independent. Raw vectors remain strings; an imported numeric `SEVERITY_LABEL` value is an approximation, not calculated CVSS. Prose is normalized source content, not trusted agent instructions. Reference URLs are not fetched and purls are identifiers; absent optional URLs are null, while unsafe schemes neutralized upstream become empty strings. `content_safety` reports normalization, not trust or severity. The fixed response has no `fields` selector. `limit` defaults to 5 and accepts 1–8 whole package groups; a group is never split between its advisory rows. No page is automatically drained. Continue with the same requested ID and `after`; evidence/revision changes invalidate cursors, while changing limit is allowed. Invalid or stale pages return 400, including when other source evidence is available. operationId: get_vulnerability parameters: - description: >- Whole package groups per page, 1–8; default 5. One group is never split between advisory rows. example: 5 in: query name: limit required: false schema: default: 5 format: int32 maximum: 8 minimum: 1 type: integer - description: >- Opaque end_cursor for this requested ID. Preserved unchanged. Evidence or revision changes invalidate continuation; changing limit is allowed. A stale/invalid page is a 400. No automatic draining. in: query name: after required: false schema: type: string - description: >- Source ID or known imported alias. Trimmed, case-preserving, 1–512 UTF-8 bytes; embedded whitespace, control and format characters are forbidden. Encode punctuation such as slash within one path segment. in: path name: id required: true schema: type: string - 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 responses: '200': content: application/json: examples: named_package: summary: >- Source explanation and separate imported evidence for a named package value: advisory: affected: - package: ecosystem: npm name: minimatch purl: null ranges: - events: - fixed: null introduced: 10.0.0 last_affected: null limit: null - fixed: 10.2.1 introduced: null last_affected: null limit: null repo: null type: SEMVER severity: [] versions: [] aliases: - CVE-2026-26996 content_safety: filtered: false modifications: [] details: null modified_at: '2026-02-20T01:02:03.123456789Z' osv_id: GHSA-3ppc-4f35-3m26 published_at: null references: - type: ADVISORY url: https://example.com/advisory severity: [] source_url: https://osv.dev/vulnerability/GHSA-3ppc-4f35-3m26 summary: Example source advisory withdrawn_at: null affected_packages: coverage: imported_status: available source_status: available entries: - advisories: - affected_version_display: ranges: - 10.0.0 – 10.2.0 total_count: 1 truncated: false affected_version_ranges: - '>=10.0.0 <10.2.1' aliases: - CVE-2026-26996 content_safety: filtered: false modifications: [] fixed_in_versions: - 10.2.1 is_malicious: false modified_at: '2026-02-21T00:00:00Z' osv_id: GHSA-3ppc-4f35-3m26 package_name: minimatch published_at: null registry: npm severity_score: 7.5 severity_type: CVSS_V3 source_url: >- https://osv.dev/vulnerability/GHSA-3ppc-4f35-3m26 summary: Imported advisory evidence withdrawn_at: null package: ecosystem: npm name: minimatch registry: npm source_evidence: affected: - package: ecosystem: npm name: minimatch purl: null ranges: - events: - fixed: null introduced: 10.0.0 last_affected: null limit: null - fixed: 10.2.1 introduced: null last_affected: null limit: null repo: null type: SEMVER severity: [] versions: [] affected_version_display: ranges: - 10.0.0 – 10.2.0 total_count: 1 truncated: false affected_version_ranges: - '>=10.0.0 <10.2.1' content_safety: filtered: false modifications: [] fixed_in_versions: - 10.2.1 modified_at: '2026-02-20T01:02:03.123456789Z' osv_id: GHSA-3ppc-4f35-3m26 source_url: https://osv.dev/vulnerability/GHSA-3ppc-4f35-3m26 withdrawn_at: null page_info: end_cursor: null has_next_page: false total_count: 1 diagnostics: [] requested_id: GHSA-3ppc-4f35-3m26 package_less_git: summary: >- Package-less Git evidence with an imported package association value: advisory: affected: - package: null ranges: - events: - fixed: null introduced: '0' last_affected: null limit: null - fixed: null introduced: null last_affected: abc limit: null - fixed: null introduced: null last_affected: null limit: '*' repo: https://example.com/repo type: GIT severity: [] versions: [] aliases: - GHSA-3ppc-4f35-3m26 content_safety: filtered: false modifications: [] details: null modified_at: '2026-02-20T01:02:03.123456789Z' osv_id: CVE-2026-26996 published_at: null references: - type: ADVISORY url: https://example.com/advisory severity: - score: CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H source: null type: CVSS_V3 source_url: https://osv.dev/vulnerability/CVE-2026-26996 summary: Example source advisory withdrawn_at: null affected_packages: coverage: imported_status: available source_status: available entries: - advisories: - affected_version_display: ranges: - 10.0.0 – 10.2.0 - 9.0.0 – 9.0.5 total_count: 2 truncated: false affected_version_ranges: - '>=10.0.0 <10.2.1' - '>=9.0.0 <9.0.6' aliases: - CVE-2026-26996 content_safety: filtered: false modifications: [] fixed_in_versions: - 10.2.1 - 9.0.6 is_malicious: false modified_at: '2026-02-21T00:00:00Z' osv_id: GHSA-3ppc-4f35-3m26 package_name: minimatch published_at: null registry: npm severity_score: 7.5 severity_type: CVSS_V3 source_url: >- https://osv.dev/vulnerability/GHSA-3ppc-4f35-3m26 summary: Imported advisory evidence withdrawn_at: null package: ecosystem: npm name: minimatch registry: npm source_evidence: null page_info: end_cursor: null has_next_page: false total_count: 1 diagnostics: [] requested_id: CVE-2026-26996 source_unavailable: summary: Usable imported evidence when source acquisition fails value: advisory: null affected_packages: coverage: imported_status: available source_status: unavailable entries: - advisories: - affected_version_display: ranges: - 10.0.0 – 10.2.0 total_count: 1 truncated: false affected_version_ranges: - '>=10.0.0 <10.2.1' aliases: - CVE-2026-26996 content_safety: filtered: false modifications: [] fixed_in_versions: - 10.2.1 is_malicious: false modified_at: '2026-02-21T00:00:00Z' osv_id: GHSA-3ppc-4f35-3m26 package_name: minimatch published_at: null registry: npm severity_score: 7.5 severity_type: CVSS_V3 source_url: >- https://osv.dev/vulnerability/GHSA-3ppc-4f35-3m26 summary: Imported advisory evidence withdrawn_at: null package: ecosystem: npm name: minimatch registry: npm source_evidence: null page_info: end_cursor: null has_next_page: false total_count: 1 diagnostics: - candidate_ids: null candidate_ids_truncated: null code: UPSTREAM_ERROR message: The source could not be read. path: null retryable: true section: advisory requested_id: GHSA-3ppc-4f35-3m26 schema: $ref: '#/components/schemas/AdvisoryReport' description: >- Attributed source and one whole-group package page, with explicit evidence coverage and diagnostics headers: Cache-Control: schema: enum: - no-store type: string X-RateLimit-Limit: description: >- Maximum requests in the authenticated usage window shared across operations. Optional: supplied only when usage metadata is available. schema: pattern: ^[0-9]+$ type: string X-RateLimit-Remaining: description: >- Requests remaining in that usage window after admission. Advisory snapshot; concurrent requests can consume quota. Optional when usage metadata is unavailable. schema: pattern: ^[0-9]+$ type: string X-RateLimit-Reset: description: >- Usage window reset time as Unix epoch seconds (UTC), rounded up to the next whole second. This is an absolute timestamp, not a delay. Optional when usage metadata is unavailable. Honor Retry-After on 429 when present; other quotas can also reject requests. schema: pattern: ^[0-9]+$ 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: The source ID or request is invalid. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Validation error type: about:blank schema: $ref: '#/components/schemas/AdvisoryProblem' description: >- VALIDATION_ERROR: The source ID or request is invalid. INVALID_SESSION_ID: a supplied session header is invalid or duplicated. VALIDATION_ERROR details identify the first invalid field and a reason when available. Array indices are zero-based; submitted values and unknown keys are not echoed. 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: 4bf92f3577b34da6a3ce929d0e0e4736 status: 401 title: Authentication required type: about:blank schema: $ref: '#/components/schemas/AdvisoryProblem' description: 'AUTHENTICATION_REQUIRED: A bearer credential is required.' 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 '403': content: application/problem+json: example: code: FORBIDDEN detail: >- The caller is not allowed to access this resource. ACCOUNT_INACTIVE, FEATURE_FLAG_REQUIRED or TERMS_ACCEPTANCE_REQUIRED may also be returned. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 403 title: Forbidden type: about:blank schema: $ref: '#/components/schemas/AdvisoryProblem' description: >- FORBIDDEN: The caller is not allowed to access this resource. ACCOUNT_INACTIVE, FEATURE_FLAG_REQUIRED or TERMS_ACCEPTANCE_REQUIRED may also be returned. 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: NOT_FOUND detail: >- The source was not found and the imported association read completed with no package evidence. diagnostics: - candidate_ids: null candidate_ids_truncated: null code: NOT_FOUND message: >- The source was not found and the imported association read completed with no package evidence. path: null retryable: false section: advisory instance: 4bf92f3577b34da6a3ce929d0e0e4736 retryable: false status: 404 title: Vulnerability lookup failed type: about:blank schema: $ref: '#/components/schemas/AdvisoryProblem' description: >- NOT_FOUND: The source was not found and the imported association read completed with no package 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 '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: candidate_ids: - GHSA-example-a - GHSA-example-b candidate_ids_truncated: false code: AMBIGUOUS_VULNERABILITY_ID detail: >- Multiple source advisories match this alias. Read an explicit candidate ID. diagnostics: - candidate_ids: - GHSA-example-a - GHSA-example-b candidate_ids_truncated: false code: AMBIGUOUS_VULNERABILITY_ID message: >- Multiple source advisories match this alias. Read an explicit candidate ID. path: null retryable: false section: advisory instance: 4bf92f3577b34da6a3ce929d0e0e4736 retryable: false status: 422 title: Vulnerability lookup failed type: about:blank schema: $ref: '#/components/schemas/AdvisoryProblem' description: >- AMBIGUOUS_VULNERABILITY_ID: Multiple source advisories match this alias. Read an explicit candidate ID. 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: 4bf92f3577b34da6a3ce929d0e0e4736 retryable: true status: 429 title: Rate limited type: about:blank schema: $ref: '#/components/schemas/AdvisoryProblem' description: >- RATE_LIMITED: The request was rate limited. RATE_LIMITED can also mean your shared daily allowance is exhausted. When Retry-After is supplied, wait until that delay or HTTP date before trying again. headers: Cache-Control: schema: enum: - no-store type: string X-RateLimit-Limit: description: >- Maximum requests in the authenticated usage window shared across operations. Optional: supplied only when usage metadata is available. schema: pattern: ^[0-9]+$ type: string X-RateLimit-Remaining: description: >- Requests remaining in that usage window after admission. Advisory snapshot; concurrent requests can consume quota. Optional when usage metadata is unavailable. schema: pattern: ^[0-9]+$ type: string X-RateLimit-Reset: description: >- Usage window reset time as Unix epoch seconds (UTC), rounded up to the next whole second. This is an absolute timestamp, not a delay. Optional when usage metadata is unavailable. Honor Retry-After on 429 when present; other quotas can also reject requests. schema: pattern: ^[0-9]+$ type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '500': description: >- A request ID could not be assigned. The response has an empty body and no X-Request-ID or problem object; try again later. 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 retryable: false status: 502 title: Upstream error type: about:blank schema: $ref: '#/components/schemas/AdvisoryProblem' description: 'UPSTREAM_ERROR: The upstream service failed to provide a response.' 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 '503': content: application/problem+json: example: code: QUOTA_UNAVAILABLE detail: >- Daily usage authorization is temporarily unavailable. Retry this request. instance: 4bf92f3577b34da6a3ce929d0e0e4736 retryable: true status: 503 title: Quota authorization unavailable type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- Service unavailable QUOTA_UNAVAILABLE: your daily allowance could not be checked. This is temporary; retry the same request later (retryable=true). 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: 4bf92f3577b34da6a3ce929d0e0e4736 retryable: true status: 504 title: Upstream timeout type: about:blank schema: $ref: '#/components/schemas/AdvisoryProblem' description: 'TIMEOUT: The upstream request did not complete in time.' 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: [] components: schemas: AdvisoryReport: description: >- One advisory lookup with independently usable source and grouped package evidence. properties: advisory: oneOf: - type: 'null' - $ref: '#/components/schemas/AdvisorySource' description: >- Current exact-first OSV source explanation. Its `osv_id` identifies the served record. Null on source lookup failure; inspect `diagnostics` with section `advisory`. Related source records are never merged. affected_packages: oneOf: - type: 'null' - $ref: '#/components/schemas/AdvisoryConnection' description: >- Known named packages grouped by the existing registry identity rules, combining one served source record with exact-ID/direct-alias associations in the imported corpus. Package-less Git evidence remains under advisory.affected. A source failure preserves imported groups; an imported read failure preserves named source groups. Null means neither branch established package evidence; inspect `diagnostics`. An invalid or stale selected page returns 400 rather than a successful null page. The REST page defaults to limit 5 and accepts 1–8 complete groups; whole groups are never cut between their advisory rows. This endpoint returns one page without automatic draining. diagnostics: description: >- Public outcomes from source/imported acquisition and optional displays. Shared acquisition outcomes occur once, ordered source then imported. Optional display diagnostics follow with a public field `path`; their missing presentation does not discard usable evidence. items: $ref: '#/components/schemas/AdvisoryDiagnostic' type: array requested_id: description: >- Trimmed, case-preserving input ID. It remains the requested ID even when a recorded alias resolves to another served source ID. type: string required: - requested_id - advisory - affected_packages - diagnostics type: object AdvisoryProblem: allOf: - $ref: '#/components/schemas/ProblemResponse' - properties: candidate_ids: description: >- Candidate source IDs when available for an ambiguous alias; choose an explicit source. items: type: string type: array candidate_ids_truncated: description: Whether more ambiguity candidates exist beyond `candidate_ids`. type: boolean diagnostics: description: >- Source/imported acquisition and page diagnostics when available; request-level failures can omit them. items: $ref: '#/components/schemas/AdvisoryDiagnostic' type: array type: object description: Lookup failure with source selection guidance and evidence diagnostics. ProblemResponse: description: >- The stable problem document returned for an unsuccessful public API request. properties: acceptance_url: description: Link for accepting the required terms, when provided. type: string code: description: The stable uppercase API error code. type: string detail: description: >- Human-readable explanation. Wording can change; use code and structured fields for program logic. Validation errors identify the first invalid field (including zero-based array indices) and a reason; version errors can include canonical-version guidance. type: string instance: description: >- Request ID matching the X-Request-ID response header; include it when seeking support. type: string retryable: description: >- Whether retrying later may help, when supplied. Follow this flag for lookup/provider outcomes and temporary daily-allowance failures; malformed evidence can be nonretryable. type: boolean status: description: The HTTP status returned with this problem. format: int32 minimum: 0 type: integer terms_url: description: Link to the terms that require acceptance, when provided. 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 AdvisorySource: description: >- Current served source advisory, independent of imported package associations. properties: affected: description: Ordered independent source entries; empty does not establish safety. items: $ref: '#/components/schemas/AdvisoryAffected' type: array aliases: description: Aliases reported by this source; no merging or resolution guarantee. items: type: string type: array content_safety: $ref: '#/components/schemas/AdvisoryContentSafety' description: Normalization across the entire source tree; not a trust rating. details: description: >- Normalized source Markdown; evidence, not trusted agent instructions. type: - string - 'null' modified_at: description: >- Source revision timestamp with original precision; not an archival snapshot. type: string osv_id: description: Actual served source ID; use for attribution and subsequent reads. type: string published_at: description: >- Source publication timestamp with original precision; null when absent. type: - string - 'null' references: description: Ordered source references; URLs are not fetched. items: $ref: '#/components/schemas/AdvisoryReference' type: array severity: description: Advisory-wide severity evidence; empty does not mean zero severity. items: $ref: '#/components/schemas/AdvisorySeverity' type: array source_url: description: Source advisory URL for the served ID. type: string summary: description: Normalized source summary, null when absent. type: - string - 'null' withdrawn_at: description: Source withdrawal timestamp; non-null means withdrawn. type: - string - 'null' required: - osv_id - aliases - summary - details - source_url - published_at - modified_at - withdrawn_at - severity - references - affected - content_safety type: object AdvisoryConnection: description: >- One page of complete package groups within the evidence currently available. properties: coverage: $ref: '#/components/schemas/AdvisoryCoverage' description: >- Independent acquisition outcomes for the current served source and imported associations. Read these even when entries is empty; successful pagination cannot repair missing evidence. entries: description: >- Complete evidence branches for each selected package identity, in deterministic registry/ecosystem/name order. Empty is a checked observation only in conjunction with coverage and `diagnostics`; it is never proof that no packages are affected. items: $ref: '#/components/schemas/AdvisoryPackageGroup' type: array page_info: $ref: '#/components/schemas/AdvisoryPageInfo' description: >- Exact group count and forward continuation for currently available evidence. `has_next_page` concerns pagination only, not missing acquisition or global corpus completeness. `end_cursor` is null on the final page. required: - entries - page_info - coverage type: object AdvisoryDiagnostic: description: >- An explicit unresolved acquisition or optional-presentation outcome. Lookup errors can also carry page diagnostics. properties: candidate_ids: description: >- Source advisory candidates for `AMBIGUOUS_VULNERABILITY_ID` when provided; null when unavailable or inapplicable. The producer currently supplies at most 20 sorted distinct IDs. Missing guidance or future bounds never discard usable evidence. Choose an explicit candidate rather than retrying the alias. items: type: string type: - array - 'null' candidate_ids_truncated: description: >- Whether more ambiguity candidates were omitted, when supplied. Null means unavailable or inapplicable; missing guidance does not discard usable evidence. type: - boolean - 'null' code: description: >- Stable public error code, such as `NOT_FOUND`, `AMBIGUOUS_VULNERABILITY_ID`, `RATE_LIMITED`, TIMEOUT, `UPSTREAM_ERROR` or `VALIDATION_ERROR`. Branch on this field rather than parsing message text. type: string message: description: >- Neutral public explanation suitable for display. It contains no raw provider body, transport exception or credential. type: string path: description: >- Sanitized JSON pointer for an optional supporting-field failure; null for backend acquisition outcomes. type: - string - 'null' retryable: description: >- Whether retrying this failed operation can be useful. Invalid input, missing sources and unresolved aliases are non-retryable; a partial response does not make every diagnostic retryable. type: boolean section: description: >- Evidence section with an unresolved outcome: `advisory` or `affected_packages`. Unfamiliar producer sections remain explicit. type: string required: - section - code - message - retryable - candidate_ids - candidate_ids_truncated - path type: object AdvisoryAffected: description: Typed `VulnerabilityAffected` source evidence. properties: package: oneOf: - type: 'null' - $ref: '#/components/schemas/AdvisoryPackage' description: Source package coordinates; null for package-less Git evidence. ranges: description: Source ranges in order; empty is missing evidence, not safety. items: $ref: '#/components/schemas/AdvisoryRange' type: array severity: description: Per-entry source severity; no inheritance from root severity. items: $ref: '#/components/schemas/AdvisorySeverity' type: array versions: description: Explicit source versions in order; not expanded ranges. items: type: string type: array required: - package - severity - ranges - versions type: object AdvisoryContentSafety: description: Typed `ContentSafety` source evidence. properties: filtered: description: Whether normalization changed source content. type: boolean modifications: description: Open source normalization categories, including unfamiliar values. items: type: string type: array required: - filtered - modifications type: object AdvisoryReference: description: Typed `VulnerabilityReference` source evidence. properties: type: description: Open source reference category; preserve unfamiliar values. type: string url: description: Source URL; null when absent, empty when neutralized. type: - string - 'null' required: - type - url type: object AdvisorySeverity: description: Typed `VulnerabilitySeverity` source evidence. properties: score: description: Raw source score or CVSS vector; never converted to numeric CVSS. type: string source: description: Attribution URL; null when absent, empty when neutralized. type: - string - 'null' type: description: Open source severity discriminator; preserve unfamiliar values. type: string required: - type - score - source type: object AdvisoryCoverage: description: >- Independent source/imported acquisition states, never a global safety rating. properties: imported_status: description: >- `available` means the exact/direct-alias read completed against the imported corpus, even with zero rows; `unavailable` means it failed. Corpus absence is not a global safety claim. Unfamiliar producer states remain explicit. type: string source_status: description: >- Acquisition of the one current exact-first source record: `available`, `not_found`, `ambiguous` or `unavailable`. Availability does not mean every linked advisory was fetched. Missing outcomes are explained in `diagnostics`; unfamiliar producer states remain explicit. type: string required: - source_status - imported_status type: object AdvisoryPackageGroup: description: >- One proven package identity with separate live-source and imported-advisory evidence. properties: advisories: description: >- All stored advisory association rows qualifying through the requested/served ID or its recorded direct aliases for this package, including withdrawn records. Source IDs, revisions and spellings remain attributable; no advisory or range merge is performed. Empty means no matching imported association was found, not that the source package is unaffected. Bounded displays remain separate from original source ranges and reported fixes. items: $ref: '#/components/schemas/AdvisoryLocalAdvisory' type: array package: $ref: '#/components/schemas/AdvisoryIdentity' description: >- Backend-grouped identity. Clients need not correlate source spellings, ecosystems or registry aliases. Original spellings and purls remain in `source_evidence`.affected. source_evidence: oneOf: - type: 'null' - $ref: '#/components/schemas/AdvisorySourceEvidence' description: >- This group's evidence from the actual served source record. Null when that record supplies no named entry for this identity or could not be read. A CVE may have no package coordinates while an imported GHSA association still supplies useful ranges. This branch never adopts another advisory's evidence. required: - package - source_evidence - advisories type: object AdvisoryPageInfo: description: >- Whole-group pagination within current evidence, separate from acquisition coverage. properties: end_cursor: description: Cursor to use for fetching the next page. Null if no more pages. type: - string - 'null' has_next_page: description: Whether there are more results after this page type: boolean total_count: description: Total number of items available format: int32 minimum: 0 type: integer required: - total_count - has_next_page - end_cursor type: object AdvisoryPackage: description: Typed `VulnerabilityPackage` source evidence. properties: ecosystem: description: Open OSV ecosystem string, including suffixes; not a registry enum. type: string name: description: Source package name. type: string purl: description: Source package identifier, not a browser URL; null when absent. type: - string - 'null' required: - name - ecosystem - purl type: object AdvisoryRange: description: Typed `VulnerabilityRange` source evidence. properties: events: description: Events in source order, without implicit events or evaluation. items: $ref: '#/components/schemas/AdvisoryRangeEvent' type: array repo: description: Source repository URL; null when absent, empty when neutralized. type: - string - 'null' type: description: >- Open range type: SEMVER, ECOSYSTEM or GIT; commit ancestry is not lexical order. type: string required: - type - repo - events type: object AdvisoryLocalAdvisory: description: >- A real imported advisory association, with its own source attribution and revision. properties: affected_version_display: oneOf: - type: 'null' - $ref: '#/components/schemas/AdvisoryDisplay' description: >- Optional compact presentation of affected-version evidence using package release catalogs. Release catalog data is acquired when ordering affects presentation; display strings are not matcher input. affected_version_ranges: description: >- Raw advisory evidence strings: space-separated native comparisons or literal ==version entries. * means all valid versions; semver: preserves source `SemVer` ordering where native ordering differs; osv-invalid: marks an unevaluable source timeline, not a confirmed match. These ranges are advisory-wide, not an installed-version assessment. Follow up through the package vulnerabilities endpoint with an installed version. Preserve these strings; they are not manifest constraints. items: type: string type: - array - 'null' aliases: description: Alternative advisory IDs. items: type: string type: array content_safety: $ref: '#/components/schemas/AdvisoryContentSafety' description: >- Content-safety report for advisory display prose. Content is normalized regardless of field selection; the report may include transformations in unselected fields. fixed_in_versions: description: >- Source-reported fixed-version evidence for this advisory, in storage order and not sorted for a specific resolved version. These strings do not certify releases or safe upgrades; follow up through the package vulnerabilities endpoint with an installed version. items: type: string type: - array - 'null' is_malicious: description: Whether this advisory identifies malicious package behavior. type: - boolean - 'null' modified_at: description: Last modification timestamp in ISO8601 format. type: - string - 'null' osv_id: description: OSV advisory identifier. type: - string - 'null' package_name: description: Affected package name. type: - string - 'null' published_at: description: Publication timestamp in ISO8601 format. type: - string - 'null' registry: description: Affected package registry. type: - string - 'null' severity_score: description: >- Numeric severity value (0.0-10.0). When `severity_type` is `SEVERITY_LABEL`, this is an approximation derived from the source label, not a calculated CVSS score. format: double type: - number - 'null' severity_type: description: >- How `severity_score` was derived. `SEVERITY_LABEL` means `severity_score` is an approximation derived from the source label, not a calculated CVSS score. type: - string - 'null' source_url: description: >- OSV advisory page URL derived from this source advisory ID. It identifies the stored advisory record, not a package-version assessment or a historical source snapshot. type: string summary: description: One-line vulnerability description. type: - string - 'null' withdrawn_at: description: >- Withdrawal timestamp in ISO8601 format, or null when the advisory is active. type: - string - 'null' required: - osv_id - source_url - registry - package_name - summary - severity_score - severity_type - affected_version_ranges - fixed_in_versions - published_at - modified_at - withdrawn_at - aliases - is_malicious - affected_version_display - content_safety type: object AdvisoryIdentity: description: >- A canonical registry-proven package identity, or an explicitly unmapped source namespace. properties: ecosystem: description: >- Established base OSV ecosystem for a proven registry, or the original unmapped source namespace. Supported suffixes such as Maven repository qualifiers remain in original affected evidence, while registry identity follows ingestion rules. Null only for an imported registry without an established OSV ecosystem label. type: - string - 'null' name: description: >- Canonical package name under the proven registry identity rules; otherwise the source package name. `RubyGems` case and unresolved source names retain their normal identity semantics. type: string registry: description: >- Supported registry when package identity is proven; null for unknown ecosystems or unresolved source coordinates. Null is not permission to assume a default registry. type: - string - 'null' required: - name - registry - ecosystem type: object AdvisorySourceEvidence: description: >- The served source record's original and derived evidence for one package group. properties: affected: description: >- All original affected entries belonging to this package, in source order, including repeated entries, explicit versions, source ecosystem spellings and purls. GIT ranges retain commit events and require repository ancestry; they never become package release constraints. items: $ref: '#/components/schemas/AdvisoryAffected' type: array affected_version_display: oneOf: - type: 'null' - $ref: '#/components/schemas/AdvisoryDisplay' description: >- Optional compact presentation of this package's source-derived version evidence, using the same observed-release interpretation as imported advisories. Null means unsupported interpretation or a nullable enrichment failure; original ranges remain authoritative. Display strings are not matcher input. Count and truncation refer only to displayable version evidence, not Git commit ranges. affected_version_ranges: description: >- Derived advisory constraint evidence using the same parser as ingestion, only when this package identity and source range kinds are supported. Null means derivation is unavailable; original affected evidence is still present. Strings retain native comparisons, semver: ordering and osv-invalid: uncertainty markers. Empty is absence of derived version evidence, not proof of non-affecting. Do not treat these as manifest constraints. items: type: string type: - array - 'null' content_safety: $ref: '#/components/schemas/AdvisoryContentSafety' description: >- Normalization report shared with the complete served source record, plus derived constraint/fix presentation. It can describe transformations outside this package group or outside selected fields. It is neither a severity nor a source-trust rating. fixed_in_versions: description: >- Distinct source-reported fixed release strings from only this group's SEMVER/ECOSYSTEM fixed events, in source order. GIT fixing commits, `last_affected` and limit are excluded. These strings are evidence, not verified releases or safe upgrade recommendations. items: type: string type: array modified_at: description: >- Source modification timestamp with its original subsecond precision. It identifies the current observation, not an archived or replayable historical document. type: string osv_id: description: >- Actual served advisory ID for every affected entry in this branch. It can differ from `requested_id` after unique recorded-alias resolution. type: string source_url: description: >- OSV advisory page URL derived from the served source ID, suitable for attribution and a current source follow-up. type: string withdrawn_at: description: >- Source withdrawal timestamp, or null when withdrawal is not reported. Withdrawn evidence remains visible and must be marked accordingly. type: - string - 'null' required: - osv_id - source_url - modified_at - withdrawn_at - affected - affected_version_ranges - fixed_in_versions - affected_version_display - content_safety type: object AdvisoryRangeEvent: description: Typed `VulnerabilityRangeEvent` source evidence. properties: fixed: description: >- Exclusive fixing version or commit; source evidence, not upgrade advice. type: - string - 'null' introduced: description: Inclusive start; 0 means before all versions. Null when absent. type: - string - 'null' last_affected: description: Inclusive last affected boundary; not a fix. Null when absent. type: - string - 'null' limit: description: >- Exclusive upper bound, not a fix; * means infinity. Null when absent. type: - string - 'null' required: - introduced - fixed - last_affected - limit type: object AdvisoryDisplay: description: Bounded presentation of release-version ranges; never matcher input. properties: ranges: description: Compact affected-version display strings. items: type: string type: array total_count: description: Number of compact display ranges before truncation. format: int32 minimum: 0 type: integer truncated: description: Whether the compact display range list was truncated. type: boolean required: - ranges - total_count - truncated type: object securitySchemes: bearer_auth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.