NVD

Your guide to moving from API 1.0 to API 2.0

The following information is intended to assist users of the existing 1.0 APIs transition over to the 2.0 APIs. In September 2022 the 2.0 APIs were released in an open beta. During the open beta the APIs could contain some bugs and changes to the schema did not affect versioning. In January 2023, the 2.0 APIs exited the open beta period. Future changes to the structure of the API schemas will affect versioning. On December 15th, 2023, the NVD plans to retire all legacy data feeds and the 1.0 APIs.

The 2.0 APIs include new URL paths so that existing automated processes may continue without interruption until users have transitioned to the new service. To further assist developers working with the APIs, the NVD is documenting the best practices for popular workflows.

When the 2.0 APIs exited the open beta period, in January 2023, the 1.0 APIs became deprecated. While deprecated the 1.0 APIs will not receive updates or product support. Users may still view documentation for the 1.0 Vulnerability and 1.0 Product APIs until they are retired in December 2023.

What has changed

The APIs have undergone significant backend changes to support increasing requests from their growing user base. Many of these changes will not be apparent to the public while others—like a greater default value for resultsPerPage—will improve the speed of almost every workflow.

For many users, the most noticeable changes from 1.0 to 2.0 should include improved documentation, two new API endpoints providing the public with CPE Match Strings and Data Source records, twelve new parameters for the CVE API that allow users to filter requests based on metadata like CISA's Known Exploited Vulnerabilities (KEV), as well as two new parameters for the CPE API to search for products using their new Universally Unique Identifiers (UUID).

Additional enhancements have been added to make the APIs easier to use and more secure. Two of these changes make greater use of the request and response headers. Whereas the 1.0 APIs accepted API Keys in the request's URL query, the 2.0 APIs require the API key to be passed via the request header in an apiKey field. In the 2.0 APIs, whenever client errors occur users can examine the response header for a new field named message. The message field provides users additional information to aid in debugging.

The data in the NVD provides a catalyst for open research, learning, and discovery. For that reason, the NVD intends to make all data that would be available to users of the website also available via its APIs. To support this goal, the 2.0 APIs include significant additions to the default content returned by each API as well as a new API specifically for CVE Change History. Further supporting this mission, the CVE and Source APIs identify providers who participate in the Collaborative Vulnerability Metadata Acceptance Process (CVMAP) as primary sources where applicable.

The following table highlights a few of the larger changes between the APIs that all users should be aware of.

New approaches to getting information

1.0 API	2.0 API
The 1.0 APIs contained an endpoint used only to request information on a single CVE and second endpoint for requesting information on a collection of CVEs. The single CVE API also followed a unique URL pattern by requiring a CVE-ID to be passed via the URL path, rather than the URL query.	The single CVE API has not returned in the 2.0 APIs. The sole CVE API now includes a `cveId` parameter that returns a specific vulnerability identified by its unique CVE-ID. The CVE API accepts this parameter in the URL query.
When making iterative requests for many CVE, such as the initial population of all CVE for a local database, sorting by the last modified date may occasionally result in missing CVE. This may happen if new CVE are added during the iterative requests. Including `sortBy=publishDate` with the request avoided these errors.	The 2.0 API results are always sorted by the CVE publish date regardless of the parameters selected.
The CVE API included parameters that appended additional data or performed additional backend queries to the CPE dictionary. Because each CVE may have a dozen or more CPE associated with them, requests for thousands of CVE records could return such a large amount of data that some requests could become truncated. Reducing the `resultsPerPage` was recommended to prevent the data from being truncated.	The APIs serve specific uses. The CVE API no longer returns every detail of every associated CPE and no longer appends optional data. While the CVE API now offers additional parameters for filtering vulnerabilities associated with specific CPE, requests focused on CPE records or Match Strings should use the CPE or CPE Match Criteria APIs. It is also recommended that users of the CVE API use the default `resultsPerPage` value. This value has been optimized to allow the greatest number of results over the fewest number of requests.
By default, the CVE API's `modStartDate` & `modEndDate` parameters returned only the records where the CVE information was modified in the specified time frame. An optional parameter `includeMatchStringChange=true` could be passed with the request to return a collection of CVE where either the vulnerabilities or the associated CPE were modified in the specified time frame.	A CPE Match Criteria API has been released to provide information on valid CPE Match Strings. Along with this new API, Match Strings can now be identified by a Universally Unique Identifier (UUID). By default, the CVE API returns this UUID under the configurations object.
By default, the CPE API's `modStartDate` & `modEndDate` parameters returned a collection of CPE that were created or modified in the specified time frame. An optional parameter `includeDeprecated=true` could be passed with the request to return a collection of CPE that included CPEs deprecated in the specified time frame.	The CPE API now returns all CPE records that match the given request parameters. A new field in the CPE response object identifies whether the CPE is deprecated. If the CPE is deprecated the deprecatedBy field will provide the CPE Name that that replaces it.
The CPE API returned an optional deprecatedBy array whenever a CPE had been deprecated by another.	The CPE API also returns an optional deprecates array for relevant CPE records. This addition allows for awareness in either direction of the deprecation chain.
The APIs did not return references to CVE records marked with the "REJECT" or "Rejected" status. Depending on specific parameters, the lack of these CVE could make it appear that the API response is missing records.	In order to provide users with a complete image of the NVD, the CVE API now returns CVE records marked with the "REJECT" and "Rejected" status. A new parameter `noRejected` may be provided with the query to exclude these CVE records from the API response. Click here for more information on vulnerability statuses.
Including `apiKey={key value}`, (without brackets or spaces) in the URL path allowed users to make a greater number of requests in a given time than they could otherwise.	API keys are passed via the request header. For backwards compatibility, the 1.0 APIs will accept API Keys in either the header or the URL.
Timestamps for `modStartDate`, `modEndDate`, `pubStartDate`, and `pubEndDate` used a nonstandard datetime format.	Timestamps for `lastModStartDate`, `lastModEndDate`, `pubStartDate`, and `pubEndDate` use the extended ISO-8601 datetime format. Users may optionally provide an offset from UTC in their requests but datetime objects in the API response are always returned with a zero offset from UTC.

Renamed and retired parameters

Several parameters remain functionally unchanged from the 1.0 APIs but have been renamed in the 2.0 APIs to better illustrate their purpose.

	1.0 API		2.0 API
	`modStartDate`		`lastModStartDate`
	`modEndDate`		`lastModEndDate`
	`keyword`		`keywordSearch`
	`isExactMatch`		`keywordExactMatch`
	`cpeMatchString`		`virtualMatchString`

For reasons described in the first table, the following 1.0 parameters do not appear in the updated APIs.

CVES API:

sortBy
includeMatchStringChange

CPES API:

addOns

We want to hear from you

Is there something you feel we missed on this page? Are you confused about how to solve a unique transition problem? If you answered yes, please share your user story by emailing nvd@nist.gov. Please ensure your user story includes a description of what you are looking to do (your what) and the problem you are looking to solve (your why). Please note, while the NVD looks forward to providing you with clear and valuable transition resources, the NVD does not currently provide code snippets in any language or code reviews for any user group. The NVD also does not endorse any code base, repository, user agent, or third-party platforms.

Created September 20, 2022 , Updated August 3, 2023

You are viewing this page in an unauthorized frame window.

Information Technology Laboratory