API 2.0

The following processes are intended to assist new and experienced developers working with the NVD APIs. The processes described below are suggestions provided to make requests more efficient and to keep local repositories up to date. The NVD does not currently provide code snippets in any language or code reviews for any user group. The NVD does not endorse any code base, repository, user agent, or third-party platforms.

1. Request and activate an API Key

   NIST firewall rules put in place to prevent denial of service attacks can thwart your application if it exceeds a predetermined rate limit. Requesting an API key significantly raises the number of requests that can be made in a given time frame.

   • Additional information on API Keys and how to request them is provided on the start here page.
   • API Keys are associated with the email address of a single requestor.
   • Enterprise scale applications should use a single API Key.

2. Create a local repository for the CVE & CPE records

   The CPE API uses a single JSON schema to define the structure of the response data while the more complex CVE API response may contain up to four schemas. Each of the documents below describe a different aspect of the response but all include information on data types, regex patterns, maximum character length, and similar information that can support developers and database administrators looking to create their own local repository.

   • CPE API Schema
   • CVE API Schema
   • CVSSv3.1 Schema
   • CVSSv3.0 Schema
   • CVSSv2.0 Schema

3. Make iterative requests to the CVE & CPE APIs

   Start by calling the API beginning with a startIndex of 0. Successive requests should increment the startIndex by the value of resultsPerPage until the response's startIndex has exceeded the value in totalResults.

   • All requests to the APIs use the HTTP GET method
   • API keys are passed in the request header using apiKey:{key value}. Please note, the {key value} is case sensitive
   • Note the time that each request is sent to the API.
   • “Sleep” the script six seconds between requests.

4. Stay up to date with new data

   After initial data population the last modified date parameters provide an efficient way to update a user's local repository and stay within the API rate limits. No more than once every two hours, automated requests should include a range where lastModStartDate equals the time of the last record received from that and lastModEndDate equals the current time.

We want to hear from you

Is there a workflow you would like to see added to this page? Are you confused about how to solve a unique workflow 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 workflows, 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.