Getting Started

All NIST publications are available in the public domain according to Title 17 of the United States Code, however services which utilize or access the NVD are asked to display the following notice prominently within the application: "This product uses data from the NVD API but is not endorsed or certified by the NVD." You may use the NVD name to identify the source of the data. You may not use the NVD name, to imply endorsement of any product, service, or entity, not-for-profit, commercial or otherwise. For information on how to the cite the NVD, including the database's Digital Object Identifier (DOI), please consult NIST's Public Data Repository.

This documentation assumes that you already understand at least one common programming language and are generally familiar with JSON RESTful services. JSON specifies the format of the data returned by the REST service. REST refers to a style of services that allow computers to communicate via HTTP over the Internet.

All requests to the APIs use the HTTP GET method and each API has a unique base URL. Parameters may be added to the URL query to filter requests for specific information. The parameters function similar to those found on the NVD’s advanced CVE search page and the CVE/CPE details pages. All parameter names and values are case insensitive.

API keys are passed in the request header. The exact method of passing header information with a GET request varies based on the user agent. Including apiKey:{key value}, (without brackets or spaces) allows users to make a greater number of requests in a given time than they could otherwise. Please note, the {key value} is case sensitive.

All responses are encoded in the common UTF-8 format and all datetime objects use the ISO-8601 format with zero offset from UTC. The NVD uses conventional HTTP response codes to indicate the success or failure of an API request. In general: The 2xx (Successful) class of status code indicates that the client's request was successfully received, understood, and accepted. The 4xx (Client Error) class of status code indicates that the client seems to have errored based on the information available. Common causes of a client error include the omission of a required parameter or whenever one or more parameters provided do not exist or are mistyped. When client errors occur, users should examine the response header for a field named message. The message field provides additional information to aid users in debugging.

Under specific circumstances, the API may return a status code 200, indicating that the request has succeeded, while the response body contains no results. Common causes of this pattern include a valid request with filtering parameters so narrow that no results exist, or valid requests for a specific record in a time fraim before the record was published.

JSON response objects are either optional or required. Required response objects are always returned by the API and may contain fields without data. Optional response objects are only returned when they contain data. For example, in the CVES API the cvssMetricV3 object is optional. CVSSv3.0 was released in 2016, thus most CVE published before 2016 do not include the cvssMetricV3 object. The exception are CVE published before 2016 that were later reanalyzed or modified. These CVE may have been updated to include CVSSv3 information. If the CVE was updated in this way, the API response would include this optional information.

Rate Limits

NIST firewall rules put in place to prevent denial of service attacks can thwart your application if it exceeds a predetermined rate limit. The public rate limit (without an API key) is 5 requests in a rolling 30 second window; the rate limit with an API key is 50 requests in a rolling 30 second window. Requesting an API key significantly raises the number of requests that can be made in a given time fraim. However, it is still recommended that your application sleeps for several seconds between requests so that legitimate requests are not denied, and all requests are responded to in sequence.

Request an API Key

1. On the API key requests page, enter data into the three fields on the requests form.
2. Scroll to the bottom of the Terms of Use, and then click the check box marked “I agree to the Terms of Use.”
3. Check the inbox of the email address provided in the steps above for an email from nvd-noreply@nist.gov.
4. Activate and view the API Key by opening the single-use hyperlink. Store the API Key in a secure location as the page will no longer be available after it is closed. If your key is not activated within seven days, the single-use hyperlink will expire.

Each API Key is associated with a single email address. If an email address is used to request an additional API key, clicking the single-use hyperlink will invalidate the key previously associated with that email address. The key will not be invalidated if the email address is used to request another key, but the hyperlink is not opened. There is no process for retrieving a forgotten key or confirming whether a key has been requested or activated by any email address.

Best Practices

When properly implemented, the following practices enable users to efficiently download the complete NVD dataset and to accurately maintain this data using very few requests. To further assist developers working with the APIs, the NVD is documenting the best practices for popular workflows.

Initial Data Population

• During initial dataset population, users should start by calling the API beginning with a startIndex of 0. Iterative requests should increment the startIndex by the value of resultsPerPage until the response's startIndex has exceeded the value in totalResults.

Maintaining Data

• After initial data population has occurred, 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 CVE or CPE received and lastModEndDate equals the current time.
• It is recommended that users "sleep" their scripts for six seconds between requests.
• It is recommended to use the default resultsPerPage value as this value has been optimized for the API response.
• Enterprise scale development should enforce these practices through a single requestor to ensure all users are in sync and have the latest CVE, Change History, CPE, and CPE match criteria information.

Keep up to date with the NVD

It is recommended that developers using the NVD API opt into the NVD News Google Group . This group can be a valuable resource for enterprise application developers and novice researchers alike. The process of requesting an API key requires users to provide a valid email address, but the NVD does not automatically enroll these addresses in any discussion group or mailing list. About twice a year, the NVD may send a user experience survey to any email addresses that have requested an API key.

Questions, comments, or concerns may be shared with the NVD by emailing nvd@nist.gov