Intelligence feeds

Feed events

GET/v1/feed/events

Response examples use synthetic data to illustrate the API structure; they are not live threat findings.

Keep your local intelligence up to date with additions, changes and revocations. Feed access requires an API key with feed permission.

Explore a feed sample before integrating. No API key required.

Choose a time window

For your first request, supply since or until. We recommend starting with a recent since and an explicit limit=50. Use since and until together for a completed window, or omit until for ongoing polling.

Use ISO 8601 timestamps with a timezone and whole seconds, such as 2026-10-04T00:00:00Z. The start is inclusive and the end is exclusive. These bounds apply to the feed event time, rather than the indicator's first or last observation.

cURL · feed time window

curl --get "https://api.virussign.com/v1/feed/events" \
  --header "x-api-key: $VIRUSSIGN_API_KEY" \
  --data-urlencode "mode=events" \
  --data-urlencode "types=file,host,url" \
  --data-urlencode "since=2026-10-04T00:00:00Z" \
  --data-urlencode "until=2026-10-04T01:00:00Z" \
  --data-urlencode "limit=50"

Parameter	Usage
mode	events returns additions, updates and revocations. snapshot returns current, unexpired upsert entries within the requested time window.
types	Comma-separated file, host and/or url. host includes both domains and IP addresses. Defaults to all three.
since	Inclusive start time. Use a timezone-aware ISO 8601 timestamp with whole seconds, for example 2026-10-04T00:00:00Z.
until	Exclusive end time, later than since. Omit for ongoing polling.
cursor	Opaque continuation cursor. Use the returned value unchanged with the same account, mode, format and types. The cursor retains the time window; omit it to start a new window.
limit	Maximum events per page. Start with 50 and set it explicitly to control page size. Larger result pages may use more credits, depending on your access plan.
format	native returns JSON with meta and items. stix returns a STIX 2.1 bundle with paging information in response headers.
view	compact returns event data. full also includes available STIX identifiers and patterns in native JSON.

Read a native JSON page

The default format returns meta and items. Events arrive in feed timestamp order. Apply upsert to add or update an indicator and revoke to withdraw it from your active feed dataset. Use each event's id for deduplication.

JSON · illustrative feed page

{
  "meta": {
    "request_id": "example-feed-request",
    "timestamp": "2026-10-04T01:05:00Z",
    "limit": 50,
    "returned": 1,
    "has_next": false,
    "next_cursor": "OPAQUE_CHECKPOINT",
    "quota_remaining": 999,
    "took_ms": 80
  },
  "items": [
    {
      "id": "event--c65a54c0-1d37-54d0-b5c3-4700e3e0c7cc",
      "timestamp": "2026-10-04T00:30:00Z",
      "action": "upsert",
      "reason": "CTX",
      "indicator": {
        "type": "domain",
        "value": "beacon.example"
      },
      "analysis": {
        "malicious": true,
        "confidence": 70
      },
      "validity": {
        "first_seen": "2026-10-03T12:00:00Z",
        "last_seen": "2026-10-04T00:25:00Z"
      }
    }
  ]
}

See the native JSON field reference below for every documented event field.

Continue and resume

Process the page, then save meta.next_cursor as your checkpoint when provided.
While meta.has_next is true, request the next page using that cursor. Keep the same account, mode, format and types.
When has_next is false, stop paging through a completed window. For an open-ended feed, pause before polling again with the latest cursor.

A cursor can still be returned when has_next is false. Its presence does not mean another page is available now. Successful feed requests count toward usage even when no events are returned. Avoid continuous polling at the end of the feed.

The cursor retains your time window. To start a different window, omit the cursor and supply new time bounds. If an empty first page has no cursor, keep your original since when polling again. For a future until, pause at the current end and resume later within that same window.

cURL · next feed page

curl --get "https://api.virussign.com/v1/feed/events" \
  --header "x-api-key: $VIRUSSIGN_API_KEY" \
  --data-urlencode "mode=events" \
  --data-urlencode "types=file,host,url" \
  --data-urlencode "cursor=YOUR_NEXT_CURSOR" \
  --data-urlencode "limit=50"

This example processes a completed window with a ten-page budget. Replace the printed events with your own processing, and save each checkpoint only after its page has been successfully processed.

Python · process feed pages

import os
import requests  # pip install requests

endpoint = "https://api.virussign.com/v1/feed/events"
params = {
    "mode": "events",
    "types": "file,host,url",
    "since": "2026-10-04T00:00:00Z",
    "until": "2026-10-04T01:00:00Z",
    "limit": 50,
}
# To resume this window, set params["cursor"] to your saved checkpoint.
with requests.Session() as session:
    session.headers["x-api-key"] = os.environ["VIRUSSIGN_API_KEY"]
    for _ in range(10):  # Explicit page budget for evaluation.
        response = session.get(endpoint, params=params, timeout=(5, 60))
        response.raise_for_status()
        page = response.json()
        for event in page["items"]:
            print(event)  # Replace with durable, idempotent processing.
        meta = page["meta"]
        cursor = meta.get("next_cursor")
        if cursor:
            # Save only after all events on this page are processed.
            print("Checkpoint:", cursor)
        print("Remaining quota:", meta.get("quota_remaining"))
        if not meta["has_next"]:
            break  # Finished this completed time window.
        if not cursor or cursor == params.get("cursor"):
            raise RuntimeError("Missing or repeated feed cursor")
        params["cursor"] = cursor
    else:
        print("Page budget reached; resume from the last checkpoint.")

Snapshot mode

Use mode=snapshot to retrieve current, unexpired upsert entries within the selected time window. Use mode=events for ongoing change tracking, including revocations. Start a new request without a cursor when switching modes.

STIX output

Set format=stix to receive a STIX 2.1 bundle. Read indicators from objects; revocations are represented by revoked=true. Pagination and remaining quota are supplied in response headers instead of a meta object. The media type is application/stix+json;version=2.1.

cURL · STIX feed and headers

curl --get --include "https://api.virussign.com/v1/feed/events" \
  --header "x-api-key: $VIRUSSIGN_API_KEY" \
  --data-urlencode "mode=events" \
  --data-urlencode "types=file,host,url" \
  --data-urlencode "since=2026-10-04T00:00:00Z" \
  --data-urlencode "until=2026-10-04T01:00:00Z" \
  --data-urlencode "limit=50" \
  --data-urlencode "format=stix"

Response header	Meaning
X-Limit	Requested page size.
X-Has-More	1 means more events are available now; 0 means the current end has been reached.
X-Next-Cursor	Continuation checkpoint, when available. Its presence alone does not mean another page is available.
X-Quota-Remaining	Remaining credit balance or cycle query quota after charging.
Link	Continuation URL with rel="next", when a cursor is available. Check X-Has-More before following it immediately.

Use X-Has-More to control paging, and save X-Next-Cursor after processing the bundle. Selecting STIX does not change the billing rule. See Credits & usage for details.

Fields are conditional unless stated otherwise. Types below describe populated values; optional values may also be null. Access labels describe capability, not guaranteed data for every indicator.

Native JSON fields

metaobject

Native feed response metadata.

Fields in meta
Field	Type	Meaning
`request_id`	string	Request identifier. Include it when contacting support.
`timestamp`	string	Response time in UTC. ISO 8601 timestamp with timezone.
`quota_remaining`	integer	Remaining credits or cycle query quota when reported.
`took_ms`	integer	Processing duration in milliseconds, when provided.
`limit`	integer	Requested page size.
`returned`	integer	Number of events on this page.
`has_next`	boolean	More events are currently available within this window.
`next_cursor`	string / null	Continuation checkpoint. It can remain present at the current end; check has_next before immediately paging.

items[]array<object>

Events in feed timestamp order.

Fields in items[]
Field	Type	Meaning
`id`	string	Event identifier for deduplication.
`timestamp`	string	Feed event time; since and until apply to this field. ISO 8601 timestamp with timezone.
`action`	string	upsert adds or updates; revoke withdraws an indicator from the active dataset.
`reason`	string	Reason code describing the change, when available. Preserve unknown codes for forward compatibility.
`tags`	array<string>	Event labels.
`context`	JSON	Optional additional JSON context. The shape varies by event; do not assume a fixed set of keys.

items[].indicatorobject

Indicator represented by a feed event.

Fields in items[].indicator
Field	Type	Meaning
`type`	string	Concrete indicator type. The host request option includes domain and ip.
`value`	string	Indicator value. For URLs, this is the complete URL, unlike the opaque value in URL lookup responses.
`version`	string	IP version when applicable.
`md5`	string	MD5 file digest, when available.
`sha1`	string	SHA1 file digest, when available.
`sha256`	string	SHA256 file digest, when available.

items[].indicator.linksobject

Optional navigation links.

Fields in items[].indicator.links
Field	Type	Meaning
`self`	string	Canonical resource link, when provided.

items[].analysisobject

Feed assessment signals.

Fields in items[].analysis
Field	Type	Meaning
`malicious`	boolean	Malicious classification. A false value alone does not establish safety.
`confidence`	number	Assessment confidence score when available; higher values indicate stronger confidence. Scale: 0–100; not a probability.
`severity`	string	Severity label when an assessment is available.
`family`	string	Associated malware family.
`risk_score`	number	Risk score associated with this event; higher values indicate greater risk. Scale: 0–100; not a probability.

items[].validityobject

Observation and validity times.

Fields in items[].validity
Field	Type	Meaning
`first_seen`	string	First observation time. ISO 8601 timestamp with timezone.
`last_seen`	string	Latest observation time. ISO 8601 timestamp with timezone.
`expires_at`	string	Indicator expiry time when specified. ISO 8601 timestamp with timezone.

items[].stixobject

STIX references in native full output.

Fields in items[].stix
Field	Type	Meaning
`indicator_id`	string	STIX indicator identifier.
`pattern`	string	STIX indicator pattern.

STIX bundle fields

response

Fields in response
Field	Type	Meaning
`type`	string	STIX bundle.
`id`	string	Bundle identifier.

objects[]array<object>

STIX indicators.

Fields in objects[]
Field	Type	Meaning
`type`	string	STIX object type.
`spec_version`	string	STIX version.
`id`	string	STIX indicator identifier.
`created`	string	STIX object creation time. ISO 8601 timestamp with timezone.
`modified`	string	STIX object modification time. ISO 8601 timestamp with timezone.
`name`	string	Indicator name.
`indicator_types`	array<string>	STIX indicator categories.
`pattern`	string	STIX indicator pattern.
`pattern_type`	string	Pattern language.
`valid_from`	string	Start of indicator validity. ISO 8601 timestamp with timezone.
`valid_until`	string	End of indicator validity. ISO 8601 timestamp with timezone.
`confidence`	number	STIX confidence score; higher values indicate stronger confidence. Scale: 0–100; not a probability.
`labels`	array<string>	Indicator labels.
`revoked`	boolean	True when the indicator has been revoked.
`x_virussign_reason`	string	VirusSign change reason code.
`x_virussign_severity`	number	Numeric severity value in this STIX extension; native JSON uses a severity label.
`x_virussign_risk_score`	number	VirusSign risk score; higher values indicate greater risk. Scale: 0–100; not a probability.
`x_virussign_first_seen`	string	First observation time. ISO 8601 timestamp with timezone.
`x_virussign_last_seen`	string	Latest observation time. ISO 8601 timestamp with timezone.
`x_virussign_context`	JSON	Optional additional JSON context; its shape varies by event.

objects[].external_references[]array<object>

References identifying the VirusSign event.

Fields in objects[].external_references[]
Field	Type	Meaning
`source_name`	string	Reference name.
`external_id`	string	VirusSign indicator reference (type and identifier).
`url`	string	Related resource link when available.

objects[].x_virussign_hashesobject

Additional file hashes.

Fields in objects[].x_virussign_hashes
Field	Type	Meaning
`md5`	string	MD5 digest.
`sha1`	string	SHA1 digest.
`sha256`	string	SHA256 digest.

Illustrative response

Illustrative data showing the response structure. Optional fields may be omitted.

JSON · illustrative intelligence feeds

{
  "type": "bundle",
  "id": "bundle--f9bc2d98-cf5d-4f35-9987-7a1c71079570",
  "objects": [
    {
      "type": "indicator",
      "spec_version": "2.1",
      "id": "indicator--0b79ef36-e2ea-4c26-8dd9-a84674c410f7",
      "created": "2026-01-15T12:00:00Z",
      "modified": "2026-01-15T12:00:00Z",
      "name": "beacon.example",
      "indicator_types": [
        "malicious-activity"
      ],
      "pattern": "[domain-name:value = 'beacon.example']",
      "pattern_type": "stix",
      "valid_from": "2026-01-15T12:00:00Z",
      "confidence": 60
    }
  ]
}

Appearance

Search results