> ## 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. # Inspect package vulnerabilities > Find known security advisories for a package release, with severity information, affected versions, and recommended upgrade versions. The response includes summary counts and a paginated advisory list. Use this endpoint to check a dependency for known vulnerabilities or investigate which releases address them. ## Selector catalogue Use the following selectors with the `fields` query parameter to choose which fields the response includes. See [Choose what the response includes](https://docs.githits.com/api/requests-and-responses#choose-what-the-response-includes) for details. | Selector | Data | Default | | --- | --- | --- | | `vulnerabilities.summary` | Advisory counts for the selected filters, including counts affecting this release and whether it has known vulnerabilities. | Yes | | `vulnerabilities.advisories` | One page of advisories, with affected version ranges and pagination information. Up to 100 advisories per page. | Yes | | `vulnerabilities.upgrade_paths` | Recommended versions to upgrade to. | Yes | | `vulnerabilities.*` | All vulnerability groups: summary, advisories, and upgrade_paths. | No | ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json get /v1/packages/{registry}/{name}/vulnerabilities openapi: 3.1.0 info: description: >- Explore package metadata, security advisories, dependencies, documentation and source code with the GitHits API. ## Choose an operation | Task | Operations | | --- | --- | | Inspect a package | Release metadata, vulnerabilities and dependencies | | Review releases or upgrades | Changelog and batch upgrade reviews | | Read documentation | List package documentation, then read a page | | Navigate source code | List files, read a file or search text within a target | | Compare source trees | Compare files, line statistics and patches between package versions or repository refs | | Discover relevant content | Search across packages, repositories and documentation sites; retrieve a search's status and retained results | | Resolve a target name | Find ranked package, repository and documentation-site targets | | Ask a cited question | Generate an answer grounded in a package, repository or documentation site, or continue a conversation | | Generate an example | Generate and save a code example, then submit feedback | | Find a language identifier | Search supported programming languages | ## Authenticate and send requests The production API origin is `https://api.githits.dev`; development uses `https://api-dev.githits.dev`. Examples target production. Replace `` with your GitHits token. Send the token in `Authorization: Bearer `. JSON request bodies use `Content-Type: application/json`; public JSON field names use `snake_case`. Percent-encode a package name or opaque read target as one path segment, including any embedded slash. For query values, encode a literal plus sign as `%2B`; ordinary form decoding interprets `+` as a space. Each operation documents its accepted parameters and encoding rules. ## Select the data you need Where supported, `fields` is a comma-separated **query parameter**, including on POST requests. Omit it to use the operation's defaults. Supplying it replaces those defaults; required identity and information needed to interpret the result remain present. A **selector** names a supported **group** of response fields. Groups are atomic: their members are selected together. A **wildcard bundle**, such as `vulnerabilities.*`, selects only the groups listed for that bundle. A bare group does not automatically include nested groups. Arbitrary subfields and undeclared wildcards are not supported. Each operation lists its selectors, defaults, dependencies and the data they return. Selection can reduce transferred data without reducing the work needed to produce it; consult its parameter and response field documentation. Small fixed responses do not offer `fields`. ## Interpret responses and errors An omitted optional field can mean unselected or unavailable data, according to the operation's contract. Null has an operation-specific meaning: it can mark unavailable or inapplicable data, or an unselected search result. Empty arrays, zero and false are values, not substitutes for unavailable data. Always retain the result's completeness and freshness information when displaying or processing it. **Requested** identity records caller intent; **resolved** identity records what that intent resolved to; **served** identity identifies the artifact that produced the response. These can differ while indexing or refresh work continues. Use served identity when an exact follow-up read is required, preserving package-relative or repository-relative path scope. Errors normally use `application/problem+json`. Branch on the stable `code`, not the human-readable `detail`. Include `X-Request-ID` when reporting a problem; error `instance` matches that ID. Respect `Retry-After` when present. If request identity cannot be created, the response is an empty HTTP 500 without a request ID. Responses use `Cache-Control: no-store`. Timeouts do not guarantee that work stopped. Read the documented timeout responses, especially for Ask, generated examples and append-only feedback. Optional `X-GitHits-*` request headers attribute client, agent and session usage. The OpenAPI extension `x-githits-cost` is provisional operation metadata, not a price or a measure of computation. ## Contract status This API is pre-production. The external v1 contract is not yet frozen. license: name: Proprietary title: GitHits Public API version: 0.1.0 servers: - description: Production url: https://api.githits.dev security: [] tags: - description: >- Package metadata, release history, vulnerabilities, dependency graphs and upgrade comparisons. Each operation documents its registry, version and evidence scope. name: Packages - description: >- Discover existing documentation pages and read their content with exact source locators and availability information. name: Documentation - description: >- Enumerate files, read exact content and grep within a package or repository. Responses retain served identity, indexing state and completeness information. name: Code - description: >- Discover evidence across package, repository and documentation-site targets, then retrieve retained search results and progress. name: Search - description: >- Find supported programming-language names and aliases for example requests. name: Languages - description: >- Generate code examples for programming tasks, with source references and license attribution. name: Examples - description: Rate generated examples or sessions and provide written feedback. name: Feedback - description: >- Preview operations for target resolution, source comparison and cited questions. Routes use /v1/experimental and may later move to permanent v1 locations under a documented migration policy. name: Experimental paths: /v1/packages/{registry}/{name}/vulnerabilities: get: tags: - Packages summary: Inspect package vulnerabilities description: > Find known security advisories for a package release, with severity information, affected versions, and recommended upgrade versions. The response includes summary counts and a paginated advisory list. Use this endpoint to check a dependency for known vulnerabilities or investigate which releases address them. ## Selector catalogue Use the following selectors with the `fields` query parameter to choose which fields the response includes. See [Choose what the response includes](https://docs.githits.com/api/requests-and-responses#choose-what-the-response-includes) for details. | Selector | Data | Default | | --- | --- | --- | | `vulnerabilities.summary` | Advisory counts for the selected filters, including counts affecting this release and whether it has known vulnerabilities. | Yes | | `vulnerabilities.advisories` | One page of advisories, with affected version ranges and pagination information. Up to 100 advisories per page. | Yes | | `vulnerabilities.upgrade_paths` | Recommended versions to upgrade to. | Yes | | `vulnerabilities.*` | All vulnerability groups: summary, advisories, and upgrade_paths. | No | operationId: get_package_vulnerabilities parameters: - description: >- Canonical lowercase supported registry. vcpkg and zig are unsupported. example: npm in: path name: registry required: true schema: enum: - npm - pypi - hex - crates - nuget - maven - packagist - rubygems - go - swift type: string - description: >- Package name, 1–255 UTF-8 bytes without control characters; surrounding whitespace is preserved. Encode slash as %2F within one path segment. example: express in: path name: name required: true schema: minLength: 1 type: string - description: >- Optional concrete version or upstream-supported constraint; omission/blank resolves latest. Trimmed; Go numeric versions gain v, Swift permits v tags, other registries reject numeric v/V prefixes. example: 1.0.0 in: query name: version required: false schema: type: string - description: >- Row/page scope, default affected. Explicit value forbidden without advisories selection; default scope metadata remains. Summary retains all three count scopes. example: affected in: query name: advisory_scope required: false schema: default: affected enum: - affected - non_affecting - all type: string - description: >- Optional CVSS minimum: low=0.1, medium=4, high=7, critical=9. Any threshold excludes unknown scores; omission includes them. example: high in: query name: min_severity required: false schema: enum: - low - medium - high - critical type: string - description: >- Include withdrawn advisories; default false. Only exact true/false accepted. example: false in: query name: include_withdrawn required: false schema: default: false type: boolean - description: >- Decimal integer page size 1–100, default 100. Explicit value forbidden without advisories selection. example: 100 in: query name: limit required: false schema: default: 100 maximum: 100 minimum: 1 type: integer - description: >- Opaque nonblank end_cursor from the previous page; preserved unchanged. Pin resolved version and filters; changes can invalidate the cursor. Forbidden without advisories selection. example: opaque-cursor in: query name: after required: false schema: minLength: 1 type: string - description: >- Comma-separated atomic groups from the catalogue. Default all three; explicit replaces defaults. vulnerabilities.* is the explicit bundle of all three. No leaf selectors or security.* alias. Maximum 2048 decoded UTF-8 bytes. Use the case-sensitive selectors in the catalogue. Order and duplicate selectors do not affect the result. ASCII whitespace around selectors is ignored. The decoded value is limited to 2048 UTF-8 bytes. Empty or unknown selectors and repeated `fields` query parameters return `400 VALIDATION_ERROR`. A group does not include nested groups unless the catalogue says so; only listed wildcard bundles are supported. example: vulnerabilities.summary in: query name: fields required: false schema: default: >- vulnerabilities.summary,vulnerabilities.advisories,vulnerabilities.upgrade_paths 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 session attribution: trimmed printable ASCII, at most 128 bytes. Invalid optional values are dropped; no session is created. in: header name: X-GitHits-Session-ID required: false schema: type: string responses: '200': content: application/json: examples: complete: summary: >- Default groups, one advisory page and explicit truncation evidence value: filters: advisory_scope: affected include_withdrawn: false min_severity: null package: name: example registry: npm version: 1.0.0 vulnerabilities: advisories: entries: - affected_version_ranges: - < 2.0.0 affected_version_ranges_count: 1 affected_version_ranges_truncated: false affects_inspected_version: true aliases: - CVE-2026-0001 duplicate_ids: - CVE-2026-0001 fixed_in_versions: - 2.0.0 is_malicious: false matched_affected_version_ranges: - < 2.0.0 modified_at: '2026-02-01T00:00:00Z' osv_id: GHSA-example published_at: '2026-01-01T00:00:00Z' severity_score: 7.5 severity_type: CVSS_V3 summary: Example advisory withdrawn_at: null page_info: end_cursor: null has_next_page: false total_count: 1 summary: affected_vulnerability_count: 1 all_vulnerability_count: 3 current_version_affected: true non_affecting_vulnerability_count: 2 upgrade_paths: - 2.0.0 empty_page: summary: Known empty selected page and upgrade list value: filters: advisory_scope: affected include_withdrawn: false min_severity: null package: name: example registry: npm version: 1.0.0 vulnerabilities: advisories: entries: [] page_info: end_cursor: null has_next_page: false total_count: 0 upgrade_paths: [] summary_only: summary: 'fields=vulnerabilities.summary: no advisory page' value: filters: advisory_scope: affected include_withdrawn: false min_severity: null package: name: example registry: npm version: 1.0.0 vulnerabilities: summary: affected_vulnerability_count: 1 all_vulnerability_count: 3 current_version_affected: true non_affecting_vulnerability_count: 2 unavailable: summary: >- Source security object unavailable; identity and filters remain value: filters: advisory_scope: affected include_withdrawn: false min_severity: null package: name: example registry: npm version: 1.0.0 vulnerabilities: {} schema: $ref: '#/components/schemas/VulnerabilityReport' description: Selected vulnerability evidence for the resolved package version headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace ID for diagnostics; matches problem.instance. schema: type: string '400': content: application/problem+json: example: code: VALIDATION_ERROR detail: The request is invalid. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Validation error type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Validation error (VALIDATION_ERROR). headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace ID for diagnostics; matches problem.instance. schema: type: string '401': content: application/problem+json: example: code: AUTHENTICATION_REQUIRED detail: A bearer credential is required. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 401 title: Authentication required type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Authentication required (AUTHENTICATION_REQUIRED). headers: Cache-Control: schema: enum: - no-store type: string WWW-Authenticate: description: Bearer authentication challenge. schema: type: string x-request-id: description: Active trace ID for diagnostics; matches problem.instance. schema: type: string '403': content: application/problem+json: example: code: FORBIDDEN detail: The caller is not allowed to access this resource. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 403 title: Forbidden type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- Forbidden (FORBIDDEN, ACCOUNT_INACTIVE, FEATURE_FLAG_REQUIRED, TERMS_ACCEPTANCE_REQUIRED). TERMS_ACCEPTANCE_REQUIRED may include source-provided HTTPS terms_url and acceptance_url. headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace ID for diagnostics; matches problem.instance. schema: type: string '404': content: application/problem+json: example: code: PACKAGE_NOT_FOUND detail: The requested package or version was not found. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 404 title: Package or version not found type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- Package or version not found (PACKAGE_NOT_FOUND, VERSION_NOT_FOUND, NO_RELEASED_VERSIONS). headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace ID for diagnostics; matches problem.instance. schema: type: string '405': content: application/problem+json: example: code: METHOD_NOT_ALLOWED detail: The requested method is not supported for this route. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 405 title: Method not allowed type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: 'METHOD_NOT_ALLOWED: the route does not support this HTTP method.' headers: Allow: description: 'Supported methods: GET, HEAD.' schema: type: string Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '422': content: application/problem+json: example: code: UNSUPPORTED_PACKAGE_VARIANTS detail: The package release has unsupported artifact variants. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 422 title: Unsupported package variants type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Unsupported package variants (UNSUPPORTED_PACKAGE_VARIANTS). headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace ID for diagnostics; matches problem.instance. schema: type: string '429': content: application/problem+json: example: code: RATE_LIMITED detail: The request was rate limited. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 429 title: Rate limited type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Rate limited (RATE_LIMITED). headers: Cache-Control: schema: enum: - no-store type: string Retry-After: description: >- Optional bounded delay in seconds or HTTP date; obey before retrying. schema: type: string x-request-id: description: Active trace ID for diagnostics; matches problem.instance. schema: type: string '500': description: >- Request identity could not be created. Empty body without X-Request-ID; no problem object is available. headers: Cache-Control: schema: enum: - no-store type: string x-githits-empty-identity-failure: true '502': content: application/problem+json: example: code: UPSTREAM_ERROR detail: The upstream service failed to provide a response. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 502 title: Upstream error type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Upstream error (UPSTREAM_ERROR). headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace ID for diagnostics; matches problem.instance. schema: type: string '504': content: application/problem+json: example: code: TIMEOUT detail: The upstream request did not complete in time. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 504 title: Upstream timeout type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Upstream timeout (TIMEOUT). headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace ID for diagnostics; matches problem.instance. schema: type: string security: - bearer_auth: [] x-codeSamples: - label: All evidence lang: HTTP source: |- GET /v1/packages/npm/express/vulnerabilities HTTP/1.1 Host: api.githits.dev Authorization: Bearer - label: Counts only lang: HTTP source: >- GET /v1/packages/npm/express/vulnerabilities?fields=vulnerabilities.summary&min_severity=high HTTP/1.1 Host: api.githits.dev Authorization: Bearer - label: Next page lang: HTTP source: >- GET /v1/packages/npm/express/vulnerabilities?version=1.0.0&advisory_scope=all&after=opaque-cursor&limit=100 HTTP/1.1 Host: api.githits.dev Authorization: Bearer components: schemas: VulnerabilityReport: description: Resolved vulnerability report with selected evidence groups. properties: filters: $ref: '#/components/schemas/VulnerabilityFilters' description: Applied row scope, severity threshold and withdrawal policy. package: $ref: '#/components/schemas/VulnerabilityPackage' description: >- Required concrete identity returned by the source, including for sparse projections. vulnerabilities: $ref: '#/components/schemas/VulnerabilityEvidence' description: >- Selected evidence only; no local counts, deduplication or enrichment. required: - package - filters - vulnerabilities type: object ProblemResponse: description: >- The stable problem document returned for an unsuccessful public API request. properties: acceptance_url: description: An optional acceptance URL supplied by the upstream allow-list. type: string code: description: The stable uppercase API error code. type: string detail: description: A stable, client-safe explanation of the failure. type: string instance: description: The active request trace ID. type: string status: description: The HTTP status returned with this problem. format: int32 minimum: 0 type: integer terms_url: description: An optional terms URL supplied by the upstream allow-list. type: string title: description: A short, stable title for the error. type: string type: description: The generic RFC 9457 problem type. type: string required: - type - title - status - detail - instance - code type: object VulnerabilityFilters: description: Applied filters retained with every projection. properties: advisory_scope: $ref: '#/components/schemas/VulnerabilityAdvisoryScope' description: >- Advisory row/page scope, default affected; does not change count scopes. include_withdrawn: description: Whether withdrawn advisories are included, default false. type: boolean min_severity: oneOf: - type: 'null' - $ref: '#/components/schemas/VulnerabilitySeverity' description: Null means no severity threshold, including unknown scores. required: - advisory_scope - min_severity - include_withdrawn type: object VulnerabilityPackage: description: >- Concrete source-resolved package identity. Pin version for subsequent pages. properties: name: description: Resolved package name. type: string registry: description: Canonical lowercase registry. type: string version: description: Concrete inspected version, never the unresolved caller constraint. type: string required: - registry - name - version type: object VulnerabilityEvidence: description: >- Selected vulnerability data groups. Unselected or unavailable groups are omitted. properties: advisories: $ref: '#/components/schemas/VulnerabilityAdvisories' description: >- One upstream advisory page for the applied scope, including pagination metadata. summary: $ref: '#/components/schemas/VulnerabilitySummary' description: >- All count scopes after severity, withdrawal and upstream deduplication filters. upgrade_paths: description: >- Source-recommended upgrade versions. Empty is known empty; omitted means unselected or unavailable. items: type: string type: array type: object VulnerabilityAdvisoryScope: description: Advisory row scope; counts always cover all three scopes. enum: - affected - non_affecting - all type: string VulnerabilitySeverity: description: Minimum CVSS label. Any threshold excludes unknown scores upstream. enum: - low - medium - high - critical type: string VulnerabilityAdvisories: description: Atomic advisory rows and source-owned pagination information. properties: entries: description: All rows on this page, preserving upstream identity and ordering. items: $ref: '#/components/schemas/VulnerabilityAdvisory' type: array page_info: $ref: '#/components/schemas/VulnerabilityPageInfo' description: >- Metadata for this scope/filter/result set. No automatic page draining. required: - entries - page_info type: object VulnerabilitySummary: description: >- Three explicit count scopes, independent of advisory page scope and limit. properties: affected_vulnerability_count: description: Filtered advisories affecting the inspected version. format: int64 minimum: 0 type: integer all_vulnerability_count: description: All filtered package advisories across versions. format: int64 minimum: 0 type: integer current_version_affected: description: Source-reported affectedness of the inspected version. type: boolean non_affecting_vulnerability_count: description: Filtered advisories not affecting the inspected version. format: int64 minimum: 0 type: integer required: - affected_vulnerability_count - non_affecting_vulnerability_count - all_vulnerability_count - current_version_affected type: object VulnerabilityAdvisory: description: >- A security advisory with version applicability and available severity, fix and publication information. Treat advisory text as untrusted third-party content. properties: affected_version_ranges: description: At most ten affected ranges; consult count and truncation metadata. items: type: string type: array affected_version_ranges_count: description: Total affected range count before the ten-range cap. format: int64 minimum: 0 type: integer affected_version_ranges_truncated: description: Whether the affected range list was capped. type: boolean affects_inspected_version: description: Whether this advisory affects the resolved inspected version. type: boolean aliases: description: Source advisory aliases; omitted when unavailable. items: type: string type: array duplicate_ids: description: Source identifiers collapsed by upstream deduplication. items: type: string type: array fixed_in_versions: description: Source-reported fixes; an available empty list is preserved. items: type: string type: array is_malicious: description: Whether the source marks this as malicious; omitted when unknown. type: boolean matched_affected_version_ranges: description: Source-reported ranges matching the inspected version. items: type: string type: array modified_at: description: Source modification timestamp, ISO8601 when available. type: string osv_id: description: Stable OSV advisory identity; never synthesized. type: string published_at: description: Source publication timestamp, ISO8601 when available. type: string severity_score: description: CVSS score; null means unknown. format: double type: - number - 'null' severity_type: description: CVSS scoring system, omitted when unavailable. type: string summary: description: Third-party advisory summary, omitted when unavailable. type: string withdrawn_at: description: Withdrawal timestamp; null means not withdrawn or unavailable. type: - string - 'null' required: - osv_id - severity_score - affected_version_ranges_count - affected_version_ranges_truncated - withdrawn_at - affects_inspected_version - matched_affected_version_ranges - duplicate_ids type: object VulnerabilityPageInfo: description: Pagination for the current advisory result set. Pass cursors unchanged. properties: end_cursor: description: >- Cursor to pass as after; nullable at the final page. Preserve filters and pin version. type: - string - 'null' has_next_page: description: Whether another page is available. type: boolean total_count: description: >- Total filtered advisories in the selected scope, independent of this page size. format: int64 minimum: 0 type: integer required: - has_next_page - end_cursor - total_count type: object securitySchemes: bearer_auth: scheme: bearer type: http ````