• {uuid}

This parameter returns a specific CPE record identified by a Universal Unique Identifier (UUID). Please note, cpeNameId only checks whether a {uuid} is correctly formatted. Requests for properly formatted {uuid} that have not been assigned to a product in the Official CPE Dictionary will return a successful response without results.

The CPE Match Criteria API response provides valid {uuid} values under the cpeNameId field.

https://services.nvd.nist.gov/rest/json/cpes/2.0?cpeNameId=87316812-5F2C-4286-94FE-CC98B9EAEF53

• {match string}

This parameter returns CPE Names that exist in the Official CPE Dictionary, based on the value of {match string}.

A CPE Name is a string of characters comprised of 13 colon separated values that describe a product. In CPEv2.3 the first two values are always “cpe” and “2.3”. The 11 values that follow are referred to as the CPE components.

A CPE Match string is a single CPE string that correlates to one or many CPE Names in the Official CPE Dictionary. Because the NVD publishes CPE applicability statements for thousands of CVE each year, match strings are made to withstand changes to the Official CPE Dictionary, without requiring consistent maintenance.

https://services.nvd.nist.gov/rest/json/cpes/2.0?cpeMatchString=cpe:2.3:o:microsoft:windows_10

https://services.nvd.nist.gov/rest/json/cpes/2.0?cpeMatchString=cpe:2.3:o:microsoft:windows_10:1511

https://services.nvd.nist.gov/rest/json/cpes/2.0?cpeMatchString=cpe:2.3:*:Microsoft

By default, keywordSearch returns any CPE record where a word or phrase is found in the metadata title or reference links.

If the value of keywordSearch is a phrase, i.e., contains more than one term, including keywordExactMatch returns only the CPE matching the phrase exactly. Otherwise, the results will contain records having any of the terms. If filtering by keywordExactMatch, keywordSearch is required. Please note, this parameter should be provided without a parameter value.

https://services.nvd.nist.gov/rest/json/cpes/2.0?keywordSearch=Microsoft Windows&keywordExactMatch

Please note, the example above would not return a CPE unless the exact phrase "Microsoft Windows" appears in the metadata title or reference links.

• {keyword(s)}

This parameter returns only the CPE records where a word or phrase is found in the metadata title or reference links.

https://services.nvd.nist.gov/rest/json/cpes/2.0?keywordSearch=Red Hat

https://services.nvd.nist.gov/rest/json/cpes/2.0?keywordSearch=Java Oracle 

Please note, multiple {keywords} function like an 'AND' statement. This returns results where all keywords exist somewhere in the metadata title or reference links, though not necessarily together. Keyword search operates as though a wildcard is placed after each keyword provided. For example, providing "circle" will return results such as "circles" but not "encircle".

• {start date}
• {end date}

These parameters return only the CPE records that were last modified during the specified period. If a CPE record has been modified more recently than the specified period, it will not be included in the response. If filtering by the last modified date, both lastModStartDate and lastModEndDate are required. The maximum allowable range when using any date range parameters is 120 consecutive days.

A CPE record is considered "modified" when any of the follow actions occur:

1. A new CPE record is created
2. An existing CPE record is modified
3. An existing CPE is deprecated

Values must be entered in the extended ISO-8601 date/time format:

The "T" is a literal to separate the date from the time. The Z indicates an optional offset-from-UTC. Please note, if a positive Z value is used (such as +01:00 for Central European Time) then the "+" should be encoded in the request as "%2B". The user agent may handle this automatically.

https://services.nvd.nist.gov/rest/json/cpes/2.0/?lastModStartDate=2021-08-04T13:00:00.000%2B01:00&lastModEndDate=2021-10-22T13:36:00.000%2B01:00

• {uuid}

This parameter returns all CPE records associated with a match string identified by its {uuid}. matchCriteriaId will only accept a properly formatted {uuid}.

CPE Match Criteria comes in two forms: CPE Match Strings and CPE Match String Ranges. Both are abstract concepts that are then correlated to CPE URIs in the Official CPE Dictionary. Unlike a CPE Name, match strings and match string ranges do not require a value in the part, vendor, product, or version components. The CVE API returns valid {uuid} within the configurations object. The Match Criteria API returns valid {uuid} within the matchCriteriaId object.

https://services.nvd.nist.gov/rest/json/cpes/2.0?matchCriteriaId=36FBCF0F-8CEE-474C-8A04-5075AF53FAF4

• {page limit}

This parameter specifies the maximum number of CPE records to be returned in a single API response. For network considerations, the default value and maximum allowable limit is 10,000.

• {offset}

This parameter specifies the index of the first CPE to be returned in the response data. The index is zero-based, meaning the first CPE is at index zero.

The CPE API returns four primary objects in the response body that are used for pagination: resultsPerPage, startIndex, totalResults, and products. totalResults indicates the total number of CPE records that match the request parameters. If the value of totalResults is greater than the value of resultsPerPage there are more records than could be returned by a single API response and additional requests must update the startIndex to get the remaining records.

The best, most efficient, practice for keeping up to date with the NVD is to use the date range parameters to request only the CPE that have been modified since your last request.

https://services.nvd.nist.gov/rest/json/cpes/2.0/?resultsPerPage=20&startIndex=0

https://services.nvd.nist.gov/rest/json/cpes/2.0/?resultsPerPage=20&startIndex=20

• {CVE ID}

This parameter returns all non-deprecated CPE match strings in the availability statement of a specific vulnerability identified by its Common Vulnerabilities and Exposures identifier (the CVE ID).

https://services.nvd.nist.gov/rest/json/cpematch/2.0?cveId=CVE-2022-32223

• {start date}
• {end date}

These parameters return only the CPE records that were last modified during the specified period. If a CPE record has been modified more recently than the specified period, it will not be included in the response. If filtering by the last modified date, both lastModStartDate and lastModEndDate are required. The maximum allowable range when using any date range parameters is 120 consecutive days.

When a user populates the lastModStartDate and lastModEndDate parameters, the API will compare these dates with the most recent lastModified or cpeLastModified dates of the CPE Match Criteria. If this date is within the time frame provided, the match criteria will be included in the response. This ensures that data consumers are always aware of changes to the CPE Match Criteria itself or the CPE Names that match.
cpeLastModified changes when a CPE Name relevant to the CPE Match Criteria is created, modified, or deprecated.
lastModified changes when the CPE Match Criteria is created or its status changes.

Values must be entered in the extended ISO-8601 date/time format:

The "T" is a literal to separate the date from the time. The Z indicates an optional offset-from-UTC. Please note, if a positive Z value is used (such as +01:00 for Central European Time) then the "+" should be encoded in the request as "%2B". The user agent may handle this automatically.

https://services.nvd.nist.gov/rest/json/cpematch/2.0?lastModStartDate=2021-08-04T13:00:00.000%2B01:00&lastModEndDate=2021-10-22T13:36:00.000%2B01:00

• {uuid}

This parameter returns all CPE records associated with a match string identified by its {uuid}. matchCriteriaId will only accept a properly formatted {uuid}.

CPE Match Criteria comes in two forms: CPE Match Strings and CPE Match String Ranges. Both are abstract concepts that are then correlated to CPE URIs in the Official CPE Dictionary. Unlike a CPE Name, match strings and match string ranges do not require a value in the part, vendor, product, or version components. The CVE API returns valid {uuid} within the configurations object. The Match Criteria API returns valid {uuid} within the matchCriteriaId object.

https://services.nvd.nist.gov/rest/json/cpematch/2.0?matchCriteriaId=36FBCF0F-8CEE-474C-8A04-5075AF53FAF4

• {cpe match string}

This parameter returns all CPE Match Strings that conform to the pattern of the {cpe match string}. If a match string includes any CPE Names they will be listed in the response under matches.

CPE Match Criteria comes in two forms: CPE Match Strings and CPE Match String Ranges. Both are abstract concepts that are then correlated to CPE URIs in the Official CPE Dictionary. Unlike a CPE Name, CPE Match Strings and CPE Match String Ranges do not require a value in the part, vendor, product, or version components.

This parameter does not support CPE Match String Ranges.

matchCriteriaId is a simpler alternative for many use cases.

https://services.nvd.nist.gov/rest/json/cpematch/2.0?matchStringSearch=cpe:2.3:*:cisco:adaptive_security_appliance:*

• {page limit}

This parameter specifies the maximum number of match records to be returned in a single API response. For network considerations, the default value and maximum allowable limit is 500.

Note: Per the /cpematch/ resultsPerPage update this value will be reduced to 500 after April 15th, 2024.

• {offset}

This parameter specifies the index of the first match string to be returned in the response data. The index is zero-based, meaning the first record is at index zero.

The CPE Match API returns four primary objects in the response body that are used for pagination: resultsPerPage, startIndex, totalResults, and matchStrings. totalResults indicates the total number of CPE records that match the request parameters. If the value of totalResults is greater than the value of resultsPerPage there are more records than could be returned by a single API response and additional requests must update the startIndex to get the remaining records.

The best, most efficient, practice for keeping up to date with the NVD is to use the date range parameters to request only the CPE Match Strings that have been modified since your last request.