Skip to content

Quickstart — Get started with Vulners API

Start here: quick access to API key, Python SDK, OpenAPI / Redoc docs and three basic API calls to begin using Vulners.

  • 🔑 Getting an API key

    Create an account on Vulners and generate an API key in your personal API Keys panel. Use this X-Api-Key header to authenticate requests.

    Read more

  • Vulners Python SDK

    Install the official Python SDK v4 from PyPI: pip install -U vulners. Typed data model, mirrored sync/async clients, built-in docs, agent-ready, with an embedded MCP server.

    Read more

  • OpenAPI

    Explore the full API surface with the REST playground / OpenAPI docs (try endpoints, see request/response shapes).

    OpenAPI / Playground

  • Redoc

    Use Redoc-style interactive API reference if you prefer the three-panel OpenAPI layout (navigation, docs, examples). Redoc is a common OpenAPI renderer used across projects.

    Read more about Redoc

Below — three basic API methods to try quickly.

1. Search in database

The database search mirrors the Vulners website search and supports Lucene queries. Use this API to quickly find bulletins, CVEs, advisories, exploits and more.

Auth: X-Api-Key header required.

Parameters:

Name In Type Required Description
query body string yes Lucene query string
skip body integer no Offset
size body integer no Number of results
fields body array[string] no Fields to include in the response. Use ["*"] to request all fields. Omitting returns default subset.

Usage:

Query: 

POST /api/v3/search/lucene/

Query example: 

curl -XPOST https://vulners.com/api/v3/search/lucene -H 'Content-Type: application/json' -H "X-Api-Key: YOUR_API_KEY" -d '{
"query": "Fortinet AND RCE order:published", 
"skip": 0, 
"size": 5, 
"fields": [
    "id", 
    "published", 
    "description", 
    "type", 
    "title", 
    "cvelist"]
}'


from vulners import Vulners

with Vulners(api_key="YOUR_API_KEY_HERE") as v:
    page = v.search.query(
        "Fortinet AND RCE order:published",
        limit=5,
        fields=["published", "title", "description", "cvelist"],
    )
    for bulletin in page.data:
        print(bulletin.published, "-", bulletin.title)

import asyncio

from vulners import AsyncVulners

async def main() -> None:
    async with AsyncVulners(api_key="YOUR_API_KEY_HERE") as v:
        page = await v.search.query(
            "Fortinet AND RCE order:published",
            limit=5,
            fields=["published", "title", "description", "cvelist"],
        )
        for bulletin in page.data:
            print(bulletin.published, "-", bulletin.title)

asyncio.run(main())

[
    {
        "cvelist": ["CVE-2024-20674","CVE-2024-20677"],
        "description": "Example response content (truncated)...",
        "published": "2024-01-10T18:07:38",
        "title": "Patch now! First patch Tuesday of 2024 is here"
    }
]

2. Software Audit API (batch software audit)

Submit one or many software items (CPEs or objects) and receive matched vulnerabilities. This replaces older burp endpoints.

Python examples use the Vulners Python SDK v4 (pip install -U vulners).

Parameters:

Name In Type Required Description
software body array yes Array of software entries — either CPE objects or raw CPE strings.
match body enum no partial (default) or full. full requires exact match for all provided fields.
fields body array no Which vulnerability fields to return (defaults: title, short_description, type, href, published, modified, ai_score).

Usage:

Query: 

POST /api/v4/audit/software

Example with software objects: 

curl -X POST https://vulners.com/api/v4/audit/software -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{
    "software": [
        {"vendor":"ivanti","product":"connect_secure","version":"22.7","update":"r2.4"},
        {"vendor":"sonicwall","product":"SMA 200 firmware","version":"10.2.1.5-34sv"}
    ],
    "match":"partial",
    "fields":["title","short_description"]
}'


from vulners import Vulners

with Vulners(api_key="YOUR_API_KEY_HERE") as v:
    results = v.audit.software(
        [{"part": "a", "vendor": "ivanti", "product": "connect_secure", "version": "22.7", "update": "r2.4"}],
        match="partial",
        fields=["title", "short_description"],
    )
    print(results)

import asyncio

from vulners import AsyncVulners

async def main() -> None:
    async with AsyncVulners(api_key="YOUR_API_KEY_HERE") as v:
        results = await v.audit.software(
            [{"part": "a", "vendor": "ivanti", "product": "connect_secure", "version": "22.7", "update": "r2.4"}],
            match="partial",
            fields=["title", "short_description"],
        )
        print(results)

asyncio.run(main())

3. Get CVEs for OS + version (archive)

Download a prebuilt archive (zip) of CVEs for a specific OS and version. Useful for offline analysis or integrating CVE sets into scanners. The Python SDK decodes the archive for you and returns the parsed records, while the curl variant saves the raw zip.

Python examples use the Vulners Python SDK v4 (pip install -U vulners).

Parameters:

Name In Type Required Description
os query string yes OS name (e.g. ubuntu, debian)
version query string yes OS version (e.g. 23.04, 20.04)

Usage:

Query: 

GET /api/v3/archive/distributive/

Query example: 

curl -G "https://vulners.com/api/v3/archive/distributive/" -H "X-Api-Key: YOUR_API_KEY"           --data-urlencode "os=ubuntu"           --data-urlencode "version=23.04"           --output output_data.zip


from vulners import Vulners

with Vulners(api_key="YOUR_API_KEY_HERE") as v:
    bulletins = v.archive.get_distributive("ubuntu", "23.04")
    print(len(bulletins), "bulletins in the archive")

import asyncio

from vulners import AsyncVulners

async def main() -> None:
    async with AsyncVulners(api_key="YOUR_API_KEY_HERE") as v:
        bulletins = await v.archive.get_distributive("ubuntu", "23.04")
        print(len(bulletins), "bulletins in the archive")

asyncio.run(main())