Alerts¶

Manage automated notifications for new or updated records — add/list/modify webhook subscriptions or create email subscriptions. These endpoints let applications react to new security data in real time (webhooks) or on a schedule (email digests).

Subscriptions (v4)¶

Webhook & subscription management redesigned: v4 subscriptions provide a typed query object, explicit delivery configuration, selectable bulletin_fields, and control over timestamp_source and empty-result deliveries. These endpoints are intended for programmatic subscription lifecycle management (create, update, list, get, delete) and to support both webhook and pooling deliveries.

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 pooling). 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.

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).
`pooling`	`{ "type": "pooling", "endpoint": "https://example.com/fetch" }`	Pooling (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

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.

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

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 pooling). 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

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

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" }

Webhook¶

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

Add webhook¶

Create a new webhook subscription that will POST search results to a generated webhook 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).

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 webhooks¶

Retrieve all webhook subscriptions for the authenticated account.

Auth: X-Api-Key header required.

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 webhook¶

Toggle an existing webhook 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 webhook.
`active`	body	string	yes	`true` to enable, `false` to disable.

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 webhook¶

Webhook endpoint used by Vulners to deliver results — you can also poll the webhook 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 webhook 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 webhook.
`newest_only`	query	boolean/string	no	`true` to return only newest items; `false` for full result set.

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.

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".

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.

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.

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": {}
}