U.S. flag   An official website of the United States government
Dot gov

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Https

Secure .gov websites use HTTPS
A lock (Dot gov) or https:// means you've safely connected to the .gov website. Share sensitive information only on official, secure websites.

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. The 2.0 APIs have been released in an open beta. In this release the APIs could contain some bugs and changes to the schema will not affect versioning. Any changes to the schema after the APIs leave the open beta will affect versioning. Approximately 12 months after this release the NVD will 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.

You may still view documentation for the 1.0 Vulnerability and 1.0 Product APIs but new users are discouraged from starting with the 1.0 APIs as they will be retired in 2023. To further assist developers working with the APIs, the NVD is documenting the best practices for popular workflows.

What has changed

The APIs have undergone significant backend changes to support increasing requests from its 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, six new parameters for the CVE API that allow users to filter requests based on metadata like 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. The 2.0 APIs include significant additions to the default content returned by each API and later this year the NVD will release another endpoint specifically for CVE change histories. 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.

Requests which include the published date parameter and do not include the last modified date parameter are automatically returned an API response containing the most recently published CVE first. All other requests are automatically returned an API response with the with the most recently modified CVE first.

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 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.

The CVE API now returns CVE records marked with the "REJECT" and "Rejected" status. As a rule these records should be ignored. 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.


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

Arrow pointing right

lastModStartDate

modEndDate

Arrow pointing right

lastModEndDate

keyword

Arrow pointing right

keywordSearch

isExactMatch

Arrow pointing right

keywordExactMatch

cpeMatchString

Arrow pointing right

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.