Reference — API Overview¶

Read this page first. It collects the small set of concepts that appear everywhere across the Reference: authentication, response fields, and how to identify software/OS using CPE. These concepts are intentionally platform-agnostic — useful whether you call the REST endpoints directly (curl) or use the Python SDK.

Vulners APIs return targeted vulnerability intelligence for software, operating systems and KB lists. To get accurate results you usually need to provide:

• What you’re scanning (software packages, installed KBs, or OS).
• How you describe them (raw CPE string or structured CPE object).
• Optional filters (fields to return, partial vs full matching).

It's recommended to skim this page once so endpoint examples make sense.

This section contains the complete API reference, organized by service: - Search - Collections - Audit - Notifications - Reporting

Use the interactive viewers to explore the OpenAPI spec:

Authentication¶

All private endpoints require an API key. Send your key in the header:

X-Api-Key: YOUR_API_KEY

Default response fields¶

Most examples and SDK calls return a compact, practical set of fields by default. If you need more data, use the fields parameter to request additional properties.

Public endpoints are marked where authentication is not required.

CPE Usage in Vulners API¶

Vulners accepts software/OS identifiers as raw CPE strings or as structured CPE objects. Use whichever is easier - objects are friendlier when you want partial matching or to add attributes.

What is CPE?¶

Common Platform Enumeration (CPE) is a structured naming scheme for IT systems, software, and packages. A CPE name (a.k.a. URI) like:

cpe:<cpe_version>:<part>:<vendor>:<product>:<version>:<update>:<edition>:<language>:<sw_edition>:<target_sw>:<target_hw>:<other>

or the shortest can be like:

cpe:2.3:a:microsoft:windows_10:21h2

consists of:

• part — a (application), o (operating system), or h (hardware)
• vendor — who makes/distributes the software/hardware (e.g., microsoft)
• product — the product name (e.g., windows_10)
• version — version number or label (e.g., 21h2)

CPE objects can include additional attributes such as update, sw_edition, target_sw, target_hw, and language. The official NISTIR 7695 standard describes valid values and usage for these fields.

Below is a summary of additional fields supported in the Vulners API, which you can provide to refine the search accuracy:

• update (str): Specifies the software update version to refine the search for vulnerabilities related to a specific update level. Examples include service packs (e.g sp1) for Windows, patch versions, hotfixes, or other minor updates.

  Official NIST 7695 for update

  Values for this attribute SHOULD be vendor-specific alphanumeric strings characterizing the particular update, service pack, or point release of the product. Values for this attribute SHOULD be selected from an attribute-specific valid-values list, which MAY be defined by other specifications that utilize this specification.

• language (str): Defines the language edition of the software, if applicable. Use this to target vulnerabilities in localized versions of the software.

  Official NIST 7695 for language

  Values for this attribute SHALL be valid language tags as defined by [RFC5646], and SHOULD be used to define the language supported in the user interface of the product being described. Although any valid language tag MAY be used, only tags containing language and region codes SHOULD be used.

• sw_edition (str): Indicates the specific edition of the software. (e.g., home_premium for Windows, continuous for Acrobat Reader, or server for Linux)

  Official NIST 7695 for sw_edition

  Values for this attribute SHOULD characterize how the product is tailored to a particular market or class of end users. Values for this attribute SHOULD be selected from an attribute-specific valid-values list, which MAY be defined by other specifications that utilize this specification. Any character string meeting the requirements for WFNs (cf. 5.3.2) MAY be specified as the value of the attribute.

• target_sw (str): Specifies the platform where the software runs, such as windows, macOS, linux, or other environments like java, chrome, azure, etc. If not specified, the search will include software that runs on any * platforms.

  Official NIST 7695 for target_sw

  Values for this attribute SHOULD characterize the software computing environment within which the product operates. Values for this attribute SHOULD be selected from an attribute-specific valid-values list, which MAY be defined by other specifications that utilize this specification.

• target_hw (str): Identifies the hardware platform for the software, such as x86, x64, arm, or specific devices like router or mobile.

  Official NIST 7695 for target_hw

  Values for this attribute SHOULD characterize the instruction set architecture (e.g., x86) on which the product being described or identified by the WFN operates. Bytecode-intermediate languages, such as Java bytecode for the Java Virtual Machine or Microsoft Common Intermediate Language for the Common Language Runtime virtual machine, SHALL be considered instruction set architectures.

Using CPE in Requests¶

Throughout this documentation, it’ll show how to specify software via CPE in the following (or similar) ways:

• Full raw CPE string, e.g.:

  {"software": "cpe:2.3:a:mozilla:firefox:117.0:*:*:*:*:*:*:*"}
  

• Object with separate fields (recommended for partial matching or additional attributes):

  {
    "part": "a",
    "vendor": "mozilla",
    "product": "firefox",
    "version": "117.0",
    "update": "sp1",
    "language": "en",
    "sw_edition": "home_premium",
    "target_sw": "windows",
    "target_hw": "x64"
  }
  

Both approaches are valid in different endpoints. See the corresponding sections for exact syntax.