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 collection by name (archive)

Download the full archive of a collection, e.g. every Ubuntu advisory (type=ubuntu). Useful for offline analysis or integrating vulnerability data into scanners. The server streams a gzipped archive or redirects to the CDN; the Python SDK decodes it and returns the parsed records. Collection names come from /api/v4/search/collections; see Get collection by name for details.

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

Parameters:

Name In Type Required Description
type query string yes Collection name (e.g. ubuntu, exploitdb)

Usage:

Query:

GET /api/v4/archive/collection/

Query example:

curl -GOJL "https://vulners.com/api/v4/archive/collection/" -H "X-Api-Key: YOUR_API_KEY" --data-urlencode "type=ubuntu"

from vulners import Vulners

with Vulners(api_key="YOUR_API_KEY_HERE") as v:
    records = v.archive.fetch_collection(type="ubuntu")
    print(len(records), "records in the archive")
import asyncio

from vulners import AsyncVulners

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

asyncio.run(main())