openapi: 3.0.3
info:
  title: NIST NVD CVE API
  description: >-
    The National Vulnerability Database (NVD) CVE API provides programmatic
    access to CVE records, CVSS metrics, weakness (CWE) data, and configuration
    information for security vulnerabilities.
  version: '2.0'
  contact:
    name: NIST National Vulnerability Database
    url: https://nvd.nist.gov/developers
  license:
    name: Public Domain
servers:
  - url: https://services.nvd.nist.gov/rest/json
    description: NVD production REST endpoint
paths:
  /cves/2.0:
    get:
      summary: Search CVE records
      description: >-
        Returns a paginated list of CVE records that match the supplied filter
        parameters. Supports filters by CVE ID, keyword, CPE, CVSS metrics,
        publication and modification dates.
      operationId: getCves
      parameters:
        - name: cveId
          in: query
          description: Returns a single CVE record by its CVE identifier.
          required: false
          schema:
            type: string
            example: CVE-2023-1234
        - name: cpeName
          in: query
          description: Returns CVE records associated with the supplied CPE 2.3 name.
          required: false
          schema:
            type: string
        - name: cvssV3Severity
          in: query
          description: Filter results by CVSS v3 qualitative severity rating.
          required: false
          schema:
            type: string
            enum: [LOW, MEDIUM, HIGH, CRITICAL]
        - name: keywordSearch
          in: query
          description: Returns CVE records where the description contains the keyword.
          required: false
          schema:
            type: string
        - name: pubStartDate
          in: query
          description: Filter by CVE publish start date (ISO 8601).
          required: false
          schema:
            type: string
            format: date-time
        - name: pubEndDate
          in: query
          description: Filter by CVE publish end date (ISO 8601).
          required: false
          schema:
            type: string
            format: date-time
        - name: lastModStartDate
          in: query
          description: Filter by last modified start date (ISO 8601).
          required: false
          schema:
            type: string
            format: date-time
        - name: lastModEndDate
          in: query
          description: Filter by last modified end date (ISO 8601).
          required: false
          schema:
            type: string
            format: date-time
        - name: resultsPerPage
          in: query
          description: Number of CVE records to return per page (max 2000).
          required: false
          schema:
            type: integer
            default: 2000
            maximum: 2000
        - name: startIndex
          in: query
          description: Zero-based offset into the result set.
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Paginated CVE response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CveResponse'
        '403':
          description: Request denied (rate-limited or invalid parameters).
        '404':
          description: CVE not found.
  /cvehistory/2.0:
    get:
      summary: Retrieve CVE change history
      description: >-
        Returns the change history of CVE records, including modifications to
        descriptions, references, configurations, and CVSS metrics.
      operationId: getCveHistory
      parameters:
        - name: cveId
          in: query
          description: Returns the change history for a single CVE.
          required: false
          schema:
            type: string
        - name: changeStartDate
          in: query
          description: Filter changes that occurred on or after this date (ISO 8601).
          required: false
          schema:
            type: string
            format: date-time
        - name: changeEndDate
          in: query
          description: Filter changes that occurred on or before this date (ISO 8601).
          required: false
          schema:
            type: string
            format: date-time
        - name: resultsPerPage
          in: query
          description: Number of change records to return per page (max 5000).
          required: false
          schema:
            type: integer
            default: 5000
            maximum: 5000
        - name: startIndex
          in: query
          description: Zero-based offset into the result set.
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Paginated CVE change history response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CveHistoryResponse'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: apiKey
      description: >-
        Optional API key obtained from
        https://nvd.nist.gov/developers/request-an-api-key. Increases rate
        limits.
  schemas:
    CveResponse:
      type: object
      properties:
        resultsPerPage:
          type: integer
        startIndex:
          type: integer
        totalResults:
          type: integer
        format:
          type: string
        version:
          type: string
        timestamp:
          type: string
          format: date-time
        vulnerabilities:
          type: array
          items:
            type: object
    CveHistoryResponse:
      type: object
      properties:
        resultsPerPage:
          type: integer
        startIndex:
          type: integer
        totalResults:
          type: integer
        format:
          type: string
        version:
          type: string
        timestamp:
          type: string
          format: date-time
        cveChanges:
          type: array
          items:
            type: object
security:
  - apiKey: []