openapi.json

{
  "openapi": "3.0.2",
  "info": {
    "version": "1.0.1-beta",
    "title": "CVE Search API",
    "description": "CVE Search API to retrieve all matching CVE records after applying request inputs as filters.\n\nResponsible Use Guide: [https://cveproject.github.io/search-api-responsible-use](https://cveproject.github.io/search-api-responsible-use \"https://cveproject.github.io/search-api-responsible-use\")",
    "contact": {
      "name": "CVE Overview",
      "url": "https://www.cve.org/"
    }
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "paths": {
    "/search": {
      "post": {
        "tags": [
          "CVE Record"
        ],
        "summary": "Retrieves all matching CVE records after applying the JSON request body as filters",
        "description": "  <h2>Expected Behavior</h2>  <p>Retrieves all matching CVE records after applying the JSON request body as filters</p>  <h2>Result Counts and Pagination</h2>  <p>Direct searches report the exact number of matching records, including totals greater than 10,000, but requested pages must remain within the first 10,000 results.</p>  <p>CVSS vector filters, SSVC filters, date-bounded positive knownExploited searches, cpeName, and virtualMatchString use semantic post-filtering. These searches evaluate at most 10,000 search candidates, so their reported totals and pages include only matches found within that candidate set. A warning is returned when that limit is reached.</p>",
        "operationId": "search",
        "responses": {
          "200": {
            "description": "A list of matching CVE records",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Request correlation ID",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request body, parameter combination, or version range",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "JSON request body exceeds the 100 KiB parser limit (REQUEST_BODY_TOO_LARGE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "415": {
            "description": "A non-empty request body did not use the application/json media type with UTF-8 encoding",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "An unexpected server error; internal details are not returned (INTERNAL_SERVER_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "502": {
            "description": "The search backend returned an invalid or unexpected response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "The search service is temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds before retrying the unavailable search service",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "504": {
            "description": "Search exceeded its processing deadline",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              },
              "examples": {
                "allParameters": {
                  "summary": "All supported request body parameters",
                  "value": {
                    "scope": "FULL",
                    "keywordSearch": "remote code execution",
                    "keywordExactMatch": true,
                    "cveIds": "CVE-2024-1234,CVE-2024-5678",
                    "noRejected": true,
                    "cweId": "CWE-79",
                    "cvssV2Severity": "HIGH",
                    "cvssV3Severity": "CRITICAL",
                    "cvssV3_0Severity": "CRITICAL",
                    "cvssV3_1Severity": "CRITICAL",
                    "cvssV4Severity": "CRITICAL",
                    "cvssV2Metrics": "AV:N/AC:L/Au:N/C:P/I:P/A:P",
                    "cvssV3Metrics": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
                    "cvssV3_0Metrics": "CVSS:3.0/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
                    "cvssV3_1Metrics": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
                    "cvssV4Metrics": "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N",
                    "cpeName": "cpe:2.3:a:freetype:freetype:2.8.1:*:*:*:*:*:*:*",
                    "isVulnerable": false,
                    "lastModStartDate": "2024-01-01T00:00:00.000Z",
                    "lastModEndDate": "2024-12-31T23:59:59.999Z",
                    "pubStartDate": "2024-01-01T00:00:00.000Z",
                    "pubEndDate": "2024-12-31T23:59:59.999Z",
                    "resultsPerPage": 20,
                    "pageNumber": 1,
                    "versionStart": "2.2",
                    "versionStartType": "including",
                    "versionEnd": "2.6",
                    "versionEndType": "excluding",
                    "virtualMatchString": "cpe:2.3:o:linux:linux_kernel",
                    "ssvcExploitation": "ACTIVE",
                    "ssvcAutomatable": "YES",
                    "ssvcTechnicalImpact": "TOTAL",
                    "ssvcRole": "CISA Coordinator",
                    "ssvcTimestampStartDate": "2024-01-01T00:00:00.000Z",
                    "ssvcTimestampEndDate": "2024-12-31T23:59:59.999Z",
                    "knownExploited": true,
                    "kevDateAddedStartDate": "2024-01-01T00:00:00.000Z",
                    "kevDateAddedEndDate": "2024-12-31T23:59:59.999Z",
                    "referenceURL": "vendor.example/security/advisory",
                    "disputed": false
                  }
                },
                "keywordSearch": {
                  "summary": "Keyword search",
                  "value": {
                    "keywordSearch": "remote code execution",
                    "resultsPerPage": 20,
                    "pageNumber": 1
                  }
                },
                "cpeName": {
                  "summary": "Concrete CPE asset search",
                  "value": {
                    "cpeName": "cpe:2.3:a:freetype:freetype:2.8.1:*:*:*:*:*:*:*",
                    "isVulnerable": true
                  }
                },
                "virtualMatchStringRange": {
                  "summary": "CPE Match String version range search",
                  "value": {
                    "virtualMatchString": "cpe:2.3:o:linux:linux_kernel",
                    "versionStart": "2.2",
                    "versionStartType": "including",
                    "versionEnd": "2.6",
                    "versionEndType": "excluding"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/health-check": {
      "get": {
        "summary": "Process liveness check",
        "description": "Returns 200 when the API process is running. This endpoint does not check OpenSearch.",
        "operationId": "healthCheck",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-ID": {
                "description": "Request correlation ID",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/ready-check": {
      "get": {
        "summary": "OpenSearch readiness check",
        "description": "Validates compatible field capabilities for each logical search feature, then sends a minimal zero-result search to the configured CVE index. Alternative CNA, ADP, legacy, and CVSS-version fields may satisfy the same feature. Returns 200 when mappings, index availability, and search permission are valid, or a sanitized 503 response when a readiness check fails.",
        "operationId": "readinessCheck",
        "responses": {
          "200": {
            "description": "API is ready to serve search requests",
            "headers": {
              "X-Request-ID": {
                "description": "Request correlation ID",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "Search service is not ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds before retrying the readiness check",
                "schema": {
                  "type": "integer"
                }
              },
              "X-Request-ID": {
                "description": "Request correlation ID",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/webSearch": {
      "post": {
        "tags": [
          "CVE Record"
        ],
        "summary": "Raw query search",
        "description": "  <h2>Expected Behavior</h2>  <p>Retrieves matching CVE records using the raw query expression supplied in the JSON request body. Service operators can disable this endpoint through runtime configuration.</p>",
        "operationId": "webSearch",
        "responses": {
          "200": {
            "description": "A list of matching CVE records",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebSearchResponse"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Request correlation ID",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, unreadable request body, or invalid raw-query request body, sort, or pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          },
          "410": {
            "description": "The endpoint is disabled by service configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "413": {
            "description": "JSON request body exceeds the 100 KiB parser limit (REQUEST_BODY_TOO_LARGE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported request body encoding (REQUEST_ENCODING_UNSUPPORTED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "An unexpected server error; internal details are not returned (INTERNAL_SERVER_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "502": {
            "description": "The search backend returned an error or invalid response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebSearchResponse"
                }
              }
            }
          },
          "504": {
            "description": "Search exceeded its OpenSearch request deadline",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebSearchResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "additionalProperties": false,
                "properties": {
                  "query": {
                    "type": "string",
                    "minLength": 1
                  },
                  "sort": {
                    "type": "object",
                    "required": [
                      "property"
                    ],
                    "additionalProperties": false,
                    "properties": {
                      "property": {
                        "type": "string",
                        "enum": [
                          "cveId",
                          "relevancy"
                        ]
                      },
                      "order": {
                        "type": "string",
                        "enum": [
                          "asc",
                          "desc"
                        ]
                      }
                    }
                  },
                  "from": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "size": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 500
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ApiErrorResponse": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/ApiError"
          },
          {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        ]
      },
      "SearchWarning": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "cveIds": {
            "type": "array",
            "description": "Requested CVE IDs associated with this warning, when applicable.",
            "items": {
              "type": "string"
            }
          },
          "components": {
            "type": "array",
            "description": "CPE component names associated with this warning, when applicable.",
            "items": {
              "type": "string",
              "enum": [
                "part",
                "vendor",
                "product",
                "version",
                "update",
                "edition",
                "language",
                "sw_edition",
                "target_sw",
                "target_hw",
                "other"
              ]
            }
          }
        }
      },
      "SearchPagination": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "page",
          "pageSize",
          "resultsReturned",
          "totalResults",
          "totalPages",
          "totalIsExact"
        ],
        "properties": {
          "page": {
            "type": "integer",
            "minimum": 0,
            "description": "One-based page number, or 0 when the search has no matches."
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "description": "Maximum number of CVE records requested for this page."
          },
          "resultsReturned": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of CVE records actually returned in this response."
          },
          "totalResults": {
            "type": "integer",
            "minimum": 0,
            "description": "For direct searches, the exact number of matching records, which may be greater than 10,000. For semantic post-filtered searches, the number of matches found within the bounded 10,000-candidate set."
          },
          "totalPages": {
            "type": "integer",
            "minimum": 0,
            "description": "Pages derived from totalResults and pageSize. Semantic post-filtered searches derive this value from matches found within the bounded 10,000-candidate set."
          },
          "totalIsExact": {
            "type": "boolean",
            "description": "True when totalResults represents every match. False when a semantic search reaches the 10,000-candidate limit and additional matches may exist."
          }
        }
      },
      "CveRecord": {
        "type": "object",
        "additionalProperties": true,
        "description": "A complete CVE Record without search-backend transport metadata."
      },
      "SearchResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "apiVersion",
          "status",
          "warnings",
          "pagination",
          "records"
        ],
        "properties": {
          "apiVersion": {
            "type": "string",
            "enum": [
              "1.0"
            ],
            "description": "Version of the public search response contract."
          },
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "warnings": {
            "type": "array",
            "description": "Non-fatal conditions that may affect how the results should be interpreted.",
            "items": {
              "$ref": "#/components/schemas/SearchWarning"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/SearchPagination"
          },
          "records": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CveRecord"
            }
          }
        }
      },
      "WebSearchResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "searchMetadata",
          "resultsTotal",
          "data"
        ],
        "properties": {
          "searchMetadata": {
            "type": "object",
            "additionalProperties": true,
            "required": [
              "searchStatus",
              "version",
              "errors"
            ],
            "properties": {
              "searchStatus": {
                "type": "string"
              },
              "version": {
                "type": "string"
              },
              "errors": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "resultsTotal": {
            "type": "integer",
            "minimum": 0
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "SearchRequest": {
        "type": "object",
        "description": "Optional filters and pagination controls for a CVE record search. Enum-valued fields are accepted case-insensitively and normalized to the documented canonical values. When both boundaries of a date range are supplied, the start must be before or equal to the end. Direct searches report exact totals even when they exceed 10,000, although requested pages must remain inside that window. CVSS vector filters, SSVC filters, date-bounded positive knownExploited searches, cpeName, and virtualMatchString use semantic post-filtering. They evaluate at most 10,000 search candidates, so reported totals and pages include only matches found within that candidate set.",
        "additionalProperties": false,
        "properties": {
          "scope": {
            "type": "string",
            "enum": [
              "FULL",
              "CNA_ONLY",
              "ADP_ONLY"
            ],
            "default": "FULL",
            "description": "Controls which containers participate in filter matching. FULL searches base record fields, CNA data, and all ADP providers. CNA_ONLY searches base record fields and CNA data. ADP_ONLY searches base record fields and all ADP providers. Scope does not remove data from returned records. Values are case-insensitive. CPE applicability filters are not available with ADP_ONLY."
          },
          "keywordSearch": {
            "type": "string",
            "maxLength": 512,
            "example": "remote code execution",
            "description": "Searches description text selected by scope. Unless keywordExactMatch is true, caller query syntax is escaped, each whitespace-delimited term receives a trailing prefix wildcard, and terms are combined with AND using simple_query_string with wildcard analysis enabled. For example, remote code searches for remote* AND code*. With the standard analyzer, use-after-free requires use and after tokens plus a free* prefix, without requiring adjacency or order. Hyphenated CVE and CWE IDs can match description text; use cveIds or cweId for their dedicated fields. Matching follows the selected field's text analyzer. Limited to 512 characters and 64 whitespace-delimited terms."
          },
          "keywordExactMatch": {
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string",
                "enum": [
                  "true",
                  "false"
                ]
              }
            ],
            "default": false,
            "description": "When true, uses an analyzed phrase query instead of keyword prefix matching in the scope-selected description fields. Terms must match in order according to the index text analyzer; this is not a case-sensitive, character-for-character substring comparison. keywordSearch is required when keywordExactMatch is true. JSON booleans and the lowercase strings \"true\" and \"false\" are accepted."
          },
          "cveIds": {
            "type": "string",
            "maxLength": 4096,
            "example": "CVE-2024-1234,CVE-2024-5678",
            "description": "Returns one or more CVE records identified by a comma-separated list of CVE IDs. CVE Records do not exist for years before 1999; those IDs produce no matches and are identified by a non-fatal response warning without preventing other requested IDs from matching. Limited to 100 CVE IDs, 64 characters per ID, and 4096 characters overall."
          },
          "noRejected": {
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string",
                "enum": [
                  "true",
                  "false"
                ]
              }
            ],
            "default": false,
            "description": "When true, excludes CVE records with REJECT, REJECTED, or Rejected status. JSON booleans and the lowercase strings \"true\" and \"false\" are accepted."
          },
          "cweId": {
            "type": "string",
            "maxLength": 32,
            "example": "CWE-79",
            "description": "Returns CVE records whose scope-selected containers include the provided Common Weakness Enumeration ID."
          },
          "cvssV2Severity": {
            "type": "string",
            "enum": [
              "LOW",
              "MEDIUM",
              "HIGH"
            ],
            "description": "Returns CVE records with a scope-selected CVSS v2 base score in the range represented by the provided qualitative severity. Values are case-insensitive."
          },
          "cvssV3Severity": {
            "type": "string",
            "enum": [
              "LOW",
              "MEDIUM",
              "HIGH",
              "CRITICAL"
            ],
            "description": "Returns CVE records with the provided qualitative severity in a scope-selected CVSS v3.0 or v3.1 metric. Values are case-insensitive."
          },
          "cvssV3_0Severity": {
            "type": "string",
            "enum": [
              "LOW",
              "MEDIUM",
              "HIGH",
              "CRITICAL"
            ],
            "description": "Returns CVE records with the provided qualitative severity in a scope-selected CVSS v3.0 metric. Values are case-insensitive."
          },
          "cvssV3_1Severity": {
            "type": "string",
            "enum": [
              "LOW",
              "MEDIUM",
              "HIGH",
              "CRITICAL"
            ],
            "description": "Returns CVE records with the provided qualitative severity in a scope-selected CVSS v3.1 metric. Values are case-insensitive."
          },
          "cvssV4Severity": {
            "type": "string",
            "enum": [
              "LOW",
              "MEDIUM",
              "HIGH",
              "CRITICAL"
            ],
            "description": "Returns CVE records with the provided qualitative severity in a scope-selected CVSS v4.0 metric. Values are case-insensitive."
          },
          "cvssV2Metrics": {
            "type": "string",
            "maxLength": 256,
            "example": "AV:N/AC:L/Au:N/C:P/I:P/A:P",
            "description": "Returns CVE records with a scope-selected CVSS v2 vector containing every supplied slash-delimited metric token. Values are limited to 256 characters, 32 slash-delimited metric tokens, and 32 characters per metric token."
          },
          "cvssV3Metrics": {
            "type": "string",
            "maxLength": 256,
            "example": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
            "description": "Returns CVE records with a scope-selected CVSS v3.0 or v3.1 vector containing every supplied slash-delimited metric token. Values are limited to 256 characters, 32 slash-delimited metric tokens, and 32 characters per metric token."
          },
          "cvssV3_0Metrics": {
            "type": "string",
            "maxLength": 256,
            "example": "CVSS:3.0/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
            "description": "Returns CVE records with a scope-selected CVSS v3.0 vector containing every supplied slash-delimited metric token. Values are limited to 256 characters, 32 slash-delimited metric tokens, and 32 characters per metric token."
          },
          "cvssV3_1Metrics": {
            "type": "string",
            "maxLength": 256,
            "example": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
            "description": "Returns CVE records with a scope-selected CVSS v3.1 vector containing every supplied slash-delimited metric token. Values are limited to 256 characters, 32 slash-delimited metric tokens, and 32 characters per metric token."
          },
          "cvssV4Metrics": {
            "type": "string",
            "maxLength": 256,
            "example": "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N",
            "description": "Returns CVE records with a scope-selected CVSS v4.0 vector containing every supplied slash-delimited metric token. Values are limited to 256 characters, 32 slash-delimited metric tokens, and 32 characters per metric token."
          },
          "cpeName": {
            "type": "string",
            "maxLength": 2048,
            "example": "cpe:2.3:a:freetype:freetype:2.8.1:*:*:*:*:*:*:*",
            "description": "Returns CVE records whose CPE Match Criteria apply to the provided CPE 2.3 asset name. The value must begin with cpe:2.3 and contain concrete part, vendor, product, and version components; part must be a, h, or o. Unescaped * or ? characters anywhere in those required components, including versions such as 2.6.*, return HTTP 400. Backslash-escaped literal characters remain allowed. Empty components, malformed escaping, and unsupported part values return HTTP 400. CPE string literal comparisons are insensitive to lexical case. Every concrete non-version component must be compatible with the same CPE Match Criteria entry that satisfies the version and vulnerability checks; optional * components remain broad matches. The response includes a CPE_COMPONENTS_DEFAULTED warning when omitted trailing components are treated as wildcards. The concrete version can match stored criteria with the same version or criteria with a wildcard version and version range fields. The requested version need not appear literally in a record when it falls within a range. The API does not verify that a software version actually exists; open-ended criteria can match hypothetical versions. Numeric version segments in ranges ignore leading zeros; exact CPE Match Criteria preserve leading zeros. Version qualifiers use Maven-style ordering, with prerelease qualifiers before an unqualified release and sp or unknown qualifiers after it. The version - represents the CPE logical value NA, not an unknown or unrestricted version; numeric range boundaries on wildcard-version criteria do not exclude it under the API matching policy. Use virtualMatchString for partial CPE Match String searches or all versions of a product. For a version interval, omit the virtualMatchString version component and supply versionStart/versionStartType and/or versionEnd/versionEndType. A cpeName version ending in punctuation, such as 2.6., is not a version-prefix search."
          },
          "isVulnerable": {
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string",
                "enum": [
                  "true",
                  "false"
                ]
              }
            ],
            "default": false,
            "description": "When true, returns CVE records where the same CPE Match Criteria entry both matches cpeName and is marked vulnerable. False or omitted does not apply a vulnerability restriction. cpeName is required when isVulnerable is true. virtualMatchString cannot be provided with isVulnerable set to true; false is allowed. JSON booleans and the lowercase strings \"true\" and \"false\" are accepted."
          },
          "lastModStartDate": {
            "type": "string",
            "format": "date-time",
            "example": "2024-01-01T00:00:00.000Z",
            "description": "Returns CVE records with dateUpdated timestamps on or after this value. Use the format yyyy-MM-ddTHH:mm:ss.SSSZ."
          },
          "lastModEndDate": {
            "type": "string",
            "format": "date-time",
            "example": "2024-12-31T23:59:59.999Z",
            "description": "Returns CVE records with dateUpdated timestamps on or before this value. Use the format yyyy-MM-ddTHH:mm:ss.SSSZ."
          },
          "pubStartDate": {
            "type": "string",
            "format": "date-time",
            "example": "2024-01-01T00:00:00.000Z",
            "description": "Returns CVE records with datePublished timestamps on or after this value. Use the format yyyy-MM-ddTHH:mm:ss.SSSZ."
          },
          "pubEndDate": {
            "type": "string",
            "format": "date-time",
            "example": "2024-12-31T23:59:59.999Z",
            "description": "Returns CVE records with datePublished timestamps on or before this value. Use the format yyyy-MM-ddTHH:mm:ss.SSSZ."
          },
          "resultsPerPage": {
            "type": "integer",
            "format": "int32",
            "minimum": 1,
            "maximum": 500,
            "default": 20,
            "description": "Specifies the maximum number of CVE records returned in one response. For every search, the requested page must remain within the first 10,000 results. This pagination window does not cap the exact total reported by a direct search."
          },
          "pageNumber": {
            "type": "integer",
            "format": "int32",
            "minimum": 1,
            "default": 1,
            "description": "Specifies the page to return based on resultsPerPage. For every search, the requested page must remain within the first 10,000 results. This pagination window does not cap the exact total reported by a direct search."
          },
          "versionStart": {
            "type": "string",
            "maxLength": 256,
            "example": "2.2",
            "description": "Sets the starting version bound for a CPE Match String range search. versionStartType and virtualMatchString are required when versionStart is provided. Negative numeric values and the standalone CPE logical NA value (-) are not accepted as ordered range boundaries. When both bounds are provided, versionStart must be less than versionEnd; equal values require both bounds to be including. Numeric version segments in ranges ignore leading zeros; exact CPE Match Criteria preserve leading zeros. Version qualifiers use Maven-style ordering, with prerelease qualifiers before an unqualified release and sp or unknown qualifiers after it. virtualMatchString must not include a version component."
          },
          "versionStartType": {
            "type": "string",
            "enum": [
              "including",
              "excluding"
            ],
            "description": "Controls whether versionStart is inclusive or exclusive. versionStart is required when versionStartType is provided."
          },
          "versionEnd": {
            "type": "string",
            "maxLength": 256,
            "example": "2.6",
            "description": "Sets the ending version bound for a CPE Match String range search. versionEndType and virtualMatchString are required when versionEnd is provided. Negative numeric values and the standalone CPE logical NA value (-) are not accepted as ordered range boundaries. When both bounds are provided, versionStart must be less than versionEnd; equal values require both bounds to be including. Numeric version segments in ranges ignore leading zeros; exact CPE Match Criteria preserve leading zeros. Version qualifiers use Maven-style ordering, with prerelease qualifiers before an unqualified release and sp or unknown qualifiers after it. virtualMatchString must not include a version component."
          },
          "versionEndType": {
            "type": "string",
            "enum": [
              "including",
              "excluding"
            ],
            "description": "Controls whether versionEnd is inclusive or exclusive. versionEnd is required when versionEndType is provided."
          },
          "virtualMatchString": {
            "type": "string",
            "maxLength": 2048,
            "example": "cpe:2.3:o:microsoft:windows_10_1809",
            "description": "Returns CVE records whose CPE Match Criteria are compatible with the provided CPE 2.3 match string. The value must begin with cpe:2.3 and include a valid part component: a, h, o, *, or -. A bare prefix, empty components, malformed escaping, and unsupported part values return HTTP 400. CPE string literal comparisons are insensitive to lexical case. Omitted trailing components and * components act as broad matches; wildcard or omitted leading components produce a BROAD_VIRTUAL_MATCH_STRING response warning. When used with versionStart or versionEnd, provide a partial CPE 2.3 match string without a version component."
          },
          "ssvcExploitation": {
            "type": "string",
            "enum": [
              "NONE",
              "POC",
              "ACTIVE"
            ],
            "description": "Returns records with a scope-selected SSVC metric whose Exploitation decision has this value. Values are case-insensitive and all supplied SSVC filters must match the same SSVC metric entry."
          },
          "ssvcAutomatable": {
            "type": "string",
            "enum": [
              "YES",
              "NO"
            ],
            "description": "Returns records with a scope-selected SSVC metric whose Automatable decision has this value. Values are case-insensitive and all supplied SSVC filters must match the same SSVC metric entry."
          },
          "ssvcTechnicalImpact": {
            "type": "string",
            "enum": [
              "PARTIAL",
              "TOTAL"
            ],
            "description": "Returns records with a scope-selected SSVC metric whose Technical Impact decision has this value. Values are case-insensitive and all supplied SSVC filters must match the same SSVC metric entry."
          },
          "ssvcRole": {
            "type": "string",
            "maxLength": 256,
            "example": "CISA Coordinator",
            "description": "Returns records with a scope-selected SSVC metric whose role exactly matches this case-insensitive value."
          },
          "ssvcTimestampStartDate": {
            "type": "string",
            "format": "date-time",
            "example": "2024-01-01T00:00:00.000Z",
            "description": "Returns records with a scope-selected SSVC metric timestamp on or after this inclusive value. Use the format yyyy-MM-ddTHH:mm:ss.SSSZ."
          },
          "ssvcTimestampEndDate": {
            "type": "string",
            "format": "date-time",
            "example": "2024-12-31T23:59:59.999Z",
            "description": "Returns records with a scope-selected SSVC metric timestamp on or before this inclusive value. Use the format yyyy-MM-ddTHH:mm:ss.SSSZ."
          },
          "knownExploited": {
            "type": "boolean",
            "description": "When true, returns records with a structured KEV metric in a container selected by scope. When false, excludes records with a selected KEV metric. This field must be true when either KEV date boundary is supplied."
          },
          "kevDateAddedStartDate": {
            "type": "string",
            "format": "date-time",
            "example": "2024-01-01T00:00:00.000Z",
            "description": "Returns records whose scope-selected KEV metric has a dateAdded value on or after this inclusive timestamp. knownExploited must be true. Stored date-only values are interpreted as midnight UTC."
          },
          "kevDateAddedEndDate": {
            "type": "string",
            "format": "date-time",
            "example": "2024-12-31T23:59:59.999Z",
            "description": "Returns records whose scope-selected KEV metric has a dateAdded value on or before this inclusive timestamp. knownExploited must be true. Stored date-only values are interpreted as midnight UTC."
          },
          "referenceURL": {
            "type": "string",
            "minLength": 3,
            "maxLength": 2048,
            "example": "vendor.example/security/advisory",
            "description": "Returns records whose scope-selected references contain this case-insensitive literal URL substring. Wildcard syntax is not supported. The substring must contain at least 3 characters."
          },
          "disputed": {
            "type": "boolean",
            "description": "When true, returns records where at least one scope-selected container has the disputed tag. When false, returns records where no selected container has that tag."
          }
        }
      }
    }
  }
}