Alerts¶

Manage automated notifications for new or updated records — add, list, modify subscriptions, or use polling to retrieve updates on demand. These endpoints allow applications to react to new security data in real time (webhooks) or on a schedule (email digests), or pull the latest results whenever needed (polling).

Open interactive specs

Open Redoc (interactive) Open Swagger (interactive)

How it works?¶

Alerts are built around subscriptions — saved search queries that Vulners continuously monitors for new or updated bulletins.
A subscription is triggered when a bulletin matches your query and a specific timestamp has changed since the last delivery.

Delivery methods¶

Method	How it works	Typical use case
Email	Scheduled delivery (HTML or JSON) according to a cron expression	Daily/weekly digests for security analysts
Webhook	Immediate HTTP POST to your endpoint as soon as a match is detected	Real-time integration with SIEM, SOAR, ticketing
Polling	Results are stored on Vulners side; your app fetches them via a pull endpoint	Serverless, restricted outbound networks, batch jobs

What triggers a subscription?¶

The timestamp_source parameter defines which timestamp Vulners checks to decide if a bulletin is “new” or “updated”.
Choose the source that best matches your alerting logic.

`timestamp_source` value	Triggers when…	Recommended for
`published`	Bulletin is newly published (`published` field changed)	Only brand-new records
`modified`	Any core bulletin field changed (top-level `modified`)	General-purpose updates
`timestamps.updated`	Core content refreshed (equivalent to `modified`)	Precise content tracking
`timestamps.enriched`	AI enrichments, links, or correlations added	Intelligence improvements
`timestamps.metricsUpdated`	CVSS, EPSS, AI score, or other metrics recalculated	Metric-driven alerts
`timestamps.webApplicabilityUpdated`	Web-applicability flags changed	Web asset monitoring
`timestamps.reviewed`	Manual or automated review/QA pass completed	Quality-controlled updates

Default: modified
Full reference: Database Fields → Timestamps

Alerts are built around subscriptions — saved search queries that Vulners continuously monitors for new or updated bulletins. When a matching record appears, Vulners can deliver it to you in one of three ways:

Delivery method	How it works	Use case
Email digest	Scheduled email (HTML or JSON) according to a cron expression	Daily/weekly summaries for analysts
Webhook	Real-time HTTP POST to your endpoint as soon as a match is found	Instant integration with SIEM, SOAR, ticketing systems
Polling	Results are stored on Vulners side; your application fetches them via a dedicated endpoint whenever convenient	Pull-based architecture, serverless functions, or when webhooks are not allowed

Query types¶

The query object is discriminated by the type field. All supported types are listed below:

Type	Meaning	Example
`query`	Classic Lucene query	`{ "type":"query", "query":"package:nginx severity:high" }`
`software`	CPE-based software query	`{ "type":"software", "software":[{"vendor":"nginx","product":"nginx","version":"1.24.0"}] }`
`host/generic`	Generic host (software + optional app/OS/hw)	`{ "type":"host/generic", "software":[…], "application":{…}, "operating_system":{…} }`
`host/linux`	Linux host (OS + package list)	`{ "type":"host/linux", "os":"Ubuntu","os_version":"22.04","packages":["nginx=1.24.0-2"] }`
`host/windows`	Windows host (OS + KB list + packages)	`{ "type":"host/windows", "os":"Windows Server","os_version":"2019","kb_list":["KB5030211"],"packages":["IIS"] }`

Delivery configuration¶

The delivery object is also discriminated by type:

Type	Example	Notes
`email`	`{ "type":"email", "address":"[email protected]", "format":"html", "crontab":"0 8 * * *" }`	`format`: `html` or `json`. `crontab` uses standard 5-field cron syntax.
`webhook`	`{ "type":"webhook", "address":"https://example.com/webhook" }`	Immediate push as soon as a match is detected.
`polling`	`{ "type":"polling", "endpoint":"https://example.com/fetch" }`	Results are stored; use the `fetch` endpoint to retrieve them.

Fields in subscription results¶

Use the bulletin_fields parameter to control which fields are returned. Supported values:

Field name	Description
`title`	Bulletin title
`short_description`	AI-generated short description
`type`	Source/type of the bulletin
`published`	Publication timestamp
`modified`	Last modification timestamp
`href`	Link to the original source
`metrics`	CVSS, EPSS, etc.
`exploitation`	Known exploitation data
`cvelist`	Related CVE identifiers
`ai_score`	Vulners AI prioritization score
`epss`	EPSS probability
`description`	Full description
`enchantments`	Internal enrichments
`webApplicability`	Web-specific applicability metadata
`cvelistMetrics`	Detailed CVE metrics

The query object is discriminated by type. Supported type values and examples:

Type	Meaning	Example
`query`	Lucene query	`{ "type":"query", "query":"package:nginx severity:high" }`
`software`	Software / CPE-based query	`{ "type":"software", "software":[{ "vendor":"nginx","product":"nginx","version":"1.24.0" }]}`
`host/generic`	Generic host query (software + optional app/OS/hw)	`{ "type":"host/generic", "software":[...], "application": {...}, "operating_system": {...} }`
`host/linux`	Linux host query (os + packages list)	`{ "type":"host/linux", "os":"Ubuntu","os_version":"22.04","packages":["nginx=1.24.0-2"] }`
`host/windows`	Windows host query (os + kb_list + packages)	`{ "type":"host/windows", "os":"Windows Server","os_version":"2019","kb_list":["KB5030211"],"packages":["IIS"] }`

Delivery object is discriminated by type.

Type	Example	Notes
`webhook`	`{ "type": "webhook", "address": "https://example.com/webhook", "crontab": "0 6 * * *" }`	Webhook address must be a valid HTTP(S) URL. `crontab` uses standard 5-field cron (minute hour day month day_of_week).
`polling`	`{ "type": "polling", "endpoint": "https://example.com/fetch" }`	polling (pull) delivery — the service will store results and the `endpoint` may be used to fetch results.

The bulletin_fields parameter controls which fields are included in subscription results. Allowed values:

Field name	Description
`title`	Bulletin title
`short_description`	Short AI-generated description
`type`	Bulletin source/type
`published`	Published timestamp
`modified`	Modified timestamp
`href`	Link to source
`metrics`	Metrics object (CVSS, etc.)
`exploitation`	Exploitation info
`cvelist`	Related CVE identifiers
`ai_score`	AI-based prioritization score
`epss`	EPSS probability
`description`	Full description
`enchantments`	Internal enrichment info
`webApplicability`	Web applicability metadata
`cvelistMetrics`	CVE metrics

Default bulletin_fields (if not provided):

["title", "short_description", "type", "href", "published", "modified", "ai_score"]

Allowed timestamp_source here

Subscriptions¶

The v4 subscription API introduces a modern, typed design with full control over query logic, delivery method, result fields, and update detection.

Note

v4 endpoints use JSON bodies and typed fields as described below. Authentication: X-Api-Key header required.

Create subscription¶

Create a new subscription. Provide name, typed query, delivery, and optional settings.

Auth: X-Api-Key header required.

Request body parameters:

Name	In	Type	Required	Default	Description
`name`	body	string	yes	—	Subscription name.
`query`	body	object	yes	—	Typed query object. Check below.
`delivery`	body	object	yes	—	Delivery object (webhook or polling). Check below.
`send_empty_result`	body	boolean	yes	`false`	Send delivery even when empty.
`licenseId`	body	string/null	no	`null`	Optional license identifier (v4 field name: `licenseId`).
`bulletin_fields`	body	list[string]	no	default list	Which bulletin fields to return.
`is_active`	body	boolean	no	`true`	Activate immediately if `true`.
`timestamp_source`	body	string	no	`"modified"`	See allowed values above.
`send_empty_result`	body	boolean	no	`false`	Send delivery even when empty.

Usage:

curl Python Response

Query:

POST /api/v4/subscriptions/create/

Request example:

curl -X POST "https://vulners.com/api/v4/subscriptions/create/" \
  -H "X-Api-Key: QWNOEGW7VF99YRDWHTQBGWI4006FEUEGSSNEEVU7HR82J9MOKCTS3JT5Z0TTZ7ZC" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "name": "test_v4",
  "query": {
    "type": "query",
    "query": "cvss:[7 TO *] AND family:cve"
  },
  "delivery": {
    "type": "webhook",
    "address": "https://example.com/webhook",
    "crontab": "0 * * * *"
  },
  "send_empty_result": true
}
JSON

vulners_api.subscription_v4.create(
    name="Critical Linux vulns",
    query={"type":"query","query":"package:linux severity:critical"},
    delivery={"type":"webhook","address":"https://example.com/webhook","crontab":"0 6 * * *"},
    bulletin_fields=["id","title","description","cvss"],
    timestamp_source="modified",
    is_active=True,
    send_empty_result=False,
    licenseId="user-license-id"
)

{
  "id": "subscription-uuid",
  "name": "Critical Linux vulns",
  "query": { "type": "query", "query": "package:linux severity:critical" },
  "delivery": { "type": "webhook", "address": "https://example.com/webhook", "crontab": "0 6 * * *" },
  "bulletin_fields": ["id", "title", "description", "cvss"],
  "timestamp_source": "modified",
  "is_active": true,
  "send_empty_result": false,
  "licenseId": "user-license-id"
}

List subscriptions¶

Return all subscriptions available to the authenticated account (supports paging via query params if needed).

Auth: X-Api-Key header required.

Usage:

curl Python Response

Query:

GET /api/v4/subscriptions/list/

Example:

curl -G "https://vulners.com/api/v4/subscriptions/list/" -H "X-Api-Key: YOUR_API_KEY"

vulners_api.subscription_v4.get_list()

[
  {
    "id": "subscription-uuid-1",
    "name": "Critical Linux vulns",
    "query": { "type": "query", "query": "package:linux severity:critical" },
    "delivery": { "type": "webhook", "address": "https://example.com/webhook", "crontab": "0 6 * * *" },
    "is_active": true
  }
]

Get subscription¶

Retrieve full subscription object by id.

Auth: X-Api-Key header required.

Parameters:

Name	In	Type	Required	Description
`subscription_id`	query	string	yes	Subscription identifier

Usage:

curl Python Response

Query:

GET /api/v4/subscriptions/get/?subscription_id=subscription-uuid

Example:

curl -G "https://vulners.com/api/v4/subscriptions/get/" -H "X-Api-Key: YOUR_API_KEY" --data-urlencode "subscription_id=subscription-uuid"

vulners_api.subscription_v4.get(subscription_id="subscription-uuid")

{
  "id": "subscription-uuid",
  "name": "Critical Linux vulns",
  "query": { "type": "query", "query": "package:linux severity:critical" },
  "delivery": { "type": "webhook", "address": "https://example.com/webhook", "crontab": "0 6 * * *" },
  "bulletin_fields": ["title","short_description","href","published"],
  "timestamp_source": "modified",
  "is_active": true,
  "send_empty_result": false,
  "licenseId": null
}

Update subscription¶

Update an existing subscription. Provide id and the fields to change.

Auth: X-Api-Key header required.

Request body parameters:

Name	In	Type	Required	Default	Description
`id`	body	string	yes	—	Subscription identifier.
`name`	body	string	yes	—	Subscription name.
`query`	body	object	yes	—	Typed query object. Check below.
`delivery`	body	object	yes	—	Delivery object (webhook or polling). Check below.
`send_empty_result`	body	boolean	yes	`false`	Send delivery even when empty.
All other parameters from Create	body	—	no	—	Same meanings as create.

Errors

Code	Description
`149`	Subscription not found
`400`	Invalid license ID

Usage:

curl Python Response

Query:

PUT /api/v4/subscriptions/update/

Request example:

curl -X PUT "https://vulners.com/api/v4/subscriptions/update/" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "id": "subscription-uuid",
  "name": "",
  "query": {
    "type": "query",
    "query": "cvss:[7 TO *] AND family:cve"
  },
  "delivery": {
    "type": "webhook",
    "address": "https://example.com/webhook",
    "crontab": "0 * * * *"
  },
  "sendEmptyResult":"true"
}
JSON

vulners_api.subscription_v4.update(
    id="subscription-uuid",
    name="Updated subscription",
    query={"type":"query","query":"package:nginx severity:high"},
    delivery={"type":"webhook","address":"https://example.com/new-webhook","crontab":"*/30 * * * *"},
    bulletin_fields=["id","title"],
    timestamp_source="published",
    is_active=False,
    send_empty_result=True
)

{ "id": "subscription-uuid" }

Delete subscription¶

Delete a subscription by id.

Auth: X-Api-Key header required.

Parameters:

Name	In	Type	Required	Description
`id`	body	string	yes	Subscription identifier

Errors

Code	Description
`404`	Subscription not found

Usage:

curl Python Response

Query:

DELETE /api/v4/subscriptions/delete/

Request example:

curl -X DELETE "https://vulners.com/api/v4/subscriptions/delete/?id=subscription-uuid" \
  -H "X-Api-Key: YOUR_API_KEY"

vulners_api.subscription_v4.delete(id="subscription-uuid")

{ "id": "subscription-uuid" }

Polling¶

Polling subscriptions send HTTP POSTs to a generated polling URL whenever new results match the subscription query.

Add polling subscription¶

Create a new polling subscription that will POST search results to a generated polling endpoint.

Auth: X-Api-Key header required.

Parameters:

Name	In	Type	Required	Description
`query`	body	string	yes	Lucene search query that defines matching criteria (e.g. viewCount:[50 TO *] order:viewCount last 8 days).

Usage:

curl Python Response

Query:

POST /api/v3/subscriptions/addWebhookSubscription/

Query example:

curl -XPOST https://vulners.com/api/v3/subscriptions/addWebhookSubscription/ -H "X-Api-Key: YOUR_API_KEY" -H 'Content-Type: application/json' -d '{
"query": "viewCount:[50 TO *] order:viewCount last 8 days"
}'

    new_webhook = vulners_api.add_webhook("viewCount:[50 TO *] order:viewCount last 8 days")

{
    "result": "OK",
    "data": {
        "subscriptionid": "{subscription id}",
        "subscription": {
        "id": "{subscription id}",
        "query": "viewCount:[50 TO *] order:viewCount last 8 days",
        "active": true,
        "webhook": "https://vulners.com/api/v3/subscriptions/webhook?newest_only=true&subscriptionid={subscription id}&apiKey={api key}"
        }
    }
}

List polling subscriptions¶

Retrieve all polling subscriptions for the authenticated account.

Auth: X-Api-Key header required.

Usage:

curl Python Response

Query:

GET /api/v3/subscriptions/listWebhookSubscriptions/

Query example:

curl -G "https://vulners.com/api/v3/subscriptions/listWebhookSubscriptions/" -H "X-Api-Key: YOUR_API_KEY"

vulners_api.get_webhooks()

{
  "result": "OK",
  "data": {
    "subscriptions": [
      {
        "id": "{subscription id}",
        "query": "viewCount:[50 TO *] order:viewCount last 8 days",
        "active": true,
        "webhook": "https://vulners.com/api/v3/subscriptions/webhook?newest_only=true&subscriptionid={subscription id}&apiKey={api key}"
      }
    ]
  }
}

Enable/Disable polling subscription¶

Toggle an existing polling subscription on or off.

Auth: X-Api-Key header required.

Parameters:

Name	In	Type	Required	Description
`subscriptionid`	body	string	yes	Subscription identifier returned when creating the polling subscription.
`active`	body	string	yes	`true` to enable, `false` to disable.

Usage:

curl Response

Query:

POST /api/v3/subscriptions/enableWebhookSubscription/

Query example:

curl -XPOST https://vulners.com/api/v3/subscriptions/enableWebhookSubscription/ -H "X-Api-Key: YOUR_API_KEY" -H 'Content-Type: application/json' -d '{
"subscriptionid": "{subscription id}",
"active": false
}'

    {
    "result": "OK",
    "data": {}
    }

Read polling subscription¶

Polling subscription endpoint used by Vulners to deliver results — you can also poll the polling endpoint to retrieve recent deliveries. Use newest_only to fetch only newest updates.

Auth: X-Api-Key header required (when calling as API), but note that the generated polling URL already includes the apiKey query parameter for delivery.

Parameters:

Name	In	Type	Required	Description
`subscriptionid`	query	string	yes	Subscription identifier returned when creating the polling.
`newest_only`	query	boolean/string	no	`true` to return only newest items; `false` for full result set.

Usage:

curl Response

Query:

GET /api/v3/subscriptions/webhook/

Query example:

curl -G "https://vulners.com/api/v3/subscriptions/webhook/" -H "X-Api-Key: YOUR_API_KEY" \
  --data-urlencode "subscriptionid={subscription-id}" \
  --data-urlencode "newest_only=false"

    Search results

Email notifications¶

Email notifications (subscriptions) management via API as well as via web interface.

List email subscriptions¶

List all email subscriptions for the authenticated account.

Auth: X-Api-Key header required.

Usage:

curl Python Response

Query:

GET /api/v3/subscriptions/listEmailSubscriptions/

Query example:

curl -X GET 'https://vulners.com/api/v3/subscriptions/listEmailSubscriptions/' -H "X-Api-Key: YOUR_API_KEY"

subsctiptions = vulners_api.subscription.list()

{
  "result": "OK",
  "data": {
    "subscriptions": [
      {
        "id": "3C5SC5C5IS6DG9HE8BG470LBWBJWU0GTO2OAN93DLUJCSCH3SYWO1S13I8K17DSB",
        "active": false,
        "confirmed": false,
        "query": "viewCount:[50 TO *] order:viewCount last 5 days",
        "query_type": "lucene",
        "link_query": "/search?query=viewCount%3A%5B50%20TO%20%2A%5D%20order%3AviewCount%20last%205%20days",
        "crontab": "0 0 * * *",
        "deliveryAddress": "[email protected]",
        "deliveryFormat": "html"
      }
    ]
  }
}

Add subscription¶

Create a new scheduled email subscription.

Auth: X-Api-Key header required.

Parameters:

Name	In	Type	Required	Description
`query`	body	string	yes	Lucene query for items to include in the digest.
`email`	body	string	yes	Recipient email address.
`format`	body	string	yes	html or json.
`crontab`	body	string	yes	Cron-style schedule (e.g. 0 0 * * *).
`query_type`	body	string	no	Typically "lucene".

Usage:

curl Python Response

Query:

POST /api/v3/subscriptions/addEmailSubscription/

Query example:

curl -X POST 'https://vulners.com/api/v3/subscriptions/addEmailSubscription/' -H "X-Api-Key: YOUR_API_KEY" -H 'Content-Type: application/json' -d '{
    "query": "viewCount:[50 TO *] order:viewCount last 5 days",
    "email": "[email protected]",
    "format": "html",
    "crontab": "0 0 * * *",
    "query_type": "lucene"
}'

add_subscription = vulners_api.subscription.add("viewCount:[50 TO *] order:viewCount last 9 days", 
email="[email protected]")

{
  "result": "OK",
  "data": {
    "id": "{subscription id}",
    "active": false,
    "confirmed": false,
    "query": "viewCount:[50 TO *] order:viewCount last 5 days",
    "query_type": "lucene",
    "link_query": "/search?query=viewCount%3A%5B50%20TO%20%2A%5D%20order%3AviewCount%20last%205%20days",
    "crontab": "0 0 * * *",
    "deliveryAddress": "[email protected]",
    "deliveryFormat": "html"
  }
}

Edit subscription¶

Modify delivery schedule, format, or activation status.

Auth: X-Api-Key header required.

Parameters:

Name	In	Type	Required	Description
`subscriptionid`	body	string	yes	Subscription identifier.
`format`	body	string	yes	New format (json or html).
`crontab`	body	string	yes	New cron schedule.
`active`	body	string	yes	`true` to enable, `false` to disable.

Usage:

curl Python Response

Query:

POST api/v3/subscriptions/editEmailSubscription/

Query example:

curl -X POST 'https://vulners.com/api/v3/subscriptions/editEmailSubscription/' -H "X-Api-Key: YOUR_API_KEY" -H 'Content-Type: application/json' -d '{
    "subscriptionid": "{subscription id}",
    "format": "json",
    "crontab": "0 1 * * *",
    "active": "false"
}'

edit_subscription = vulners_api.subscription.edit(
    subscriptionid="subscription_id",
    active="false"
)

{
  "result": "OK",
  "data": {
    "id": "3C5SC5C5IS6DG9HE8BG470LBWBJWU0GTO2OAN93DLUJCSCH3SYWO1S13I8K17DSB",
    "active": false,
    "confirmed": false,
    "query": "",
    "query_type": "lucene",
    "link_query": "/search?query=",
    "crontab": "0 1 * * *",
    "deliveryAddress": "[email protected]",
    "deliveryFormat": "json"
  }
}

Delete subscription¶

Remove an email subscription

Auth: X-Api-Key header required.

Parameters:

Name	In	Type	Required	Description
`subscriptionid`	body	string	yes	Subscription identifier.

Usage:

curl Python Response

Query:

POST /api/v3/subscriptions/removeEmailSubscription/

Query example:

curl -X POST 'https://vulners.com/api/v3/subscriptions/removeEmailSubscription/' -H "X-Api-Key: YOUR_API_KEY" -H 'Content-Type: application/json' -d '{
    "subscriptionid": "{subscription id}"
}'

delete_subscription = vulners_api.subscription.delete(
    subscriptionid="subscription_id",
)

{
  "result": "OK",
  "data": {}
}