Build with VirusSign.

Your first query

Request an API key and confirm its permissions with VirusSign. Use the public API base URL below. Use your own issued key in the examples.

https://api.virussign.com

Set VIRUSSIGN_API_KEY in your local environment, then query an indicator. The examples use example.com as a placeholder.

curl --get "https://api.virussign.com/v1/ioc/domains/example.com" \
  --header "x-api-key: $VIRUSSIGN_API_KEY"

import os
import requests  # pip install requests

response = requests.get(
    "https://api.virussign.com/v1/ioc/domains/example.com",
    headers={"x-api-key": os.environ["VIRUSSIGN_API_KEY"]},
    timeout=(5, 30),
)
if response.status_code == 404:
    print("No available record; this does not mean safe.")
else:
    response.raise_for_status()
    result = response.json()
    print(result.get("indicator", {}))

Use the OpenAPI specification

The OpenAPI 3.1 specification (JSON) describes the API’s endpoints, parameters, authentication and response structures. Import it into an API client such as Postman to prepare requests, or use it with compatible tools to generate integration code. It contains no intelligence records or API keys.

Get started in Postman

1. Download the JSON file using Download OpenAPI.
2. In Postman, select Import and choose the file. Import it as a collection, or generate a collection from the imported specification.
3. Check that the API base URL is https://api.virussign.com. Set the collection’s API Key authorization header to x-api-key and use a local secret variable for your issued key.
4. Choose an endpoint, replace its example or placeholder indicator, and send the request. The request must be within your key’s permissions and uses your API quota.

Downloading or importing the specification does not make API requests or grant access. You can also follow the cURL and Python examples directly without downloading it. Generated clients may need adjustments for optional response fields and pagination.

Authentication & access

You can also connect your API key to this website to investigate indicators using your account’s permissions and allowance. Website queries and direct API requests share the same quota.

Send your API key in the x-api-key HTTP header over HTTPS. Keep the key in server-side configuration or an environment variable. Do not embed it in public JavaScript, page URLs or source control.

The public website and the API are separate access surfaces. Website access does not grant permission to redistribute intelligence or integrate it into a commercial service.

IOC lookup

Query one indicator per request. A successful response contains meta and indicator. To process a list, send individual requests with bounded concurrency.

Choose a response view

Most examples omit view and follow the service default. Use view=compact when a smaller set of fields is sufficient, for example when reviewing many related indicators. The exact fields and size depend on the indicator type and your access. Request full or full+relations only when you need additional context.

curl --get "https://api.virussign.com/v1/ioc/domains/example.com" \
  --header "x-api-key: $VIRUSSIGN_API_KEY" \
  --data-urlencode "view=compact"

To include relationships in an individual lookup, request them explicitly and start with a small limit:

curl --get "https://api.virussign.com/v1/ioc/files/YOUR_SHA256" \
  --header "x-api-key: $VIRUSSIGN_API_KEY" \
  --data-urlencode "view=full+relations" \
  --data-urlencode "limit=10"

Query a complete URL

Encode the complete URL with your HTTP client. Place q last in the query string, as shown below, and preserve the original URL’s case, path and query parameters.

curl --get "https://api.virussign.com/v1/ioc/urls" \
  --header "x-api-key: $VIRUSSIGN_API_KEY" \
  --data-urlencode "q=https://example.com/path?a=1&b=2"

response = requests.get(
    "https://api.virussign.com/v1/ioc/urls",
    headers={"x-api-key": os.environ["VIRUSSIGN_API_KEY"]},
    params={"q": "https://example.com/path?a=1&b=2"},
    timeout=(5, 30),
)
response.raise_for_status()

For subsequent URL relationship requests, use the opaque URL identifier in the returned canonical link when available. Do not assume a URL identifier is a file hash or reconstruct it from a different normalization algorithm.

Responses & data fields

Illustrative response. Available fields vary by IOC type, access and view.

{
  "meta": {
    "request_id": "example-request-id",
    "timestamp": "2026-09-30T00:00:00Z",
    "quota_remaining": 9999,
    "took_ms": 120
  },
  "indicator": {
    "type": "file",
    "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "filenames": [
      "illustrative-sample.exe"
    ],
    "analysis": {
      "malicious": true
    },
    "first_seen": "2026-09-01T00:00:00Z",
    "last_seen": "2026-09-29T00:00:00Z"
  }
}

Type-specific context

Relationships & pagination

Replace each placeholder with the value for your request:

Relationship queries accept cursor, limit and view. Choose a relationship supported by the source indicator type below. Start with limit=10; for initial integrations, keep pages at 50 or fewer and contact us before requesting larger pages.

Available relationships vary by API key tier. Pro and Advanced access offer a broader range of relationship intelligence. Request API access to explore the options.

Not every relation applies to every IOC or permission level. A supported relation may have no items; an unsupported relation can return 404. Follow the returned next_cursor while has_next is true. Keep the IOC, relation, view and other filters unchanged while paging. Treat the cursor as opaque.

curl --get "https://api.virussign.com/v1/ioc/files/YOUR_SHA256/related_domains" \
  --header "x-api-key: $VIRUSSIGN_API_KEY" \
  --data-urlencode "limit=10"

import os
import requests

endpoint = "https://api.virussign.com/v1/ioc/files/YOUR_SHA256/related_domains"
params = {"view": "compact", "limit": 10}
seen_cursors = set()
with requests.Session() as session:
    session.headers["x-api-key"] = os.environ["VIRUSSIGN_API_KEY"]
    for _ in range(10):  # Explicit evaluation page budget.
        response = session.get(endpoint, params=params, timeout=(5, 30))
        response.raise_for_status()
        page = response.json()
        for item in page.get("items", []):
            print(item)  # Replace with idempotent processing.
        if not page.get("has_next"):
            break
        cursor = page.get("next_cursor")
        if not cursor or cursor in seen_cursors:
            raise RuntimeError("Missing or repeated pagination cursor")
        seen_cursors.add(cursor)
        params["cursor"] = cursor
        # Persist this cursor only after processing the page.
    else:
        print("Page budget reached; save the cursor before continuing.")

Record your checkpoint only after successfully processing a page. Make ingestion idempotent so that retrying a page does not create duplicate records. Embedded relationship lists in a detail response can be truncated; use standalone paging for additional results.

Feed events

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

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.

{
  "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": "example.com"
      },
      "analysis": {
        "malicious": true,
        "confidence": 70
      },
      "validity": {
        "first_seen": "2026-10-03T12:00:00Z",
        "last_seen": "2026-10-04T00:25:00Z"
      }
    }
  ]
}

Continue and resume

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

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

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 allowance:", 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 --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"

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 Quotas & usage for examples.

Quotas & usage

Your access plan defines permissions, balance or cycle allowance, and any expiration. IOC lookups and feed queries use different charging rules.

IOC and relationship queries

IOC lookups and standalone relationship pages each use one query unit. Usage is based on accepted queries, including lookups with no matching record. A request that fails or times out after processing begins may also use quota; each retry is a separate request.

Feed queries

Feed queries are charged after the query completes, based on events returned: one query unit per started block of 50 events, with a minimum of one unit per request, including empty results. At the standard rate, one query unit costs one token. Your access plan defines any account-specific rate.

For example, a request with limit=50 that returns 12 events costs one token. The minimum applies separately to every page and polling request. Charges are deducted after the feed query completes; delivery interruptions or client timeouts do not necessarily prevent a charge.

Remaining allowance

Token plans apply the token cost per query unit defined in your plan. Cycle plans deduct the same query units from the current cycle allowance. Native responses report the remaining amount in meta.quota_remaining; STIX feed responses use X-Quota-Remaining.

Rate limits and total quota are separate controls. Handle 429 even when your balance is positive. Use bounded retries and allow a pause between feed polls.

Errors & retries

{
  "detail": {
    "error": {"code": 7, "message": "quota exceeded"}
  }
}

Use explicit connection and read timeouts. A client timeout does not prove that the server cancelled a query or refunded its cost. Avoid unlimited retry loops.

Integration checklist & support

• Verify the issued key’s endpoints, permissions, quota and expiration.
• Start with a small, representative set of your own indicators.
• Tolerate omitted optional fields and unknown additional fields.
• Limit concurrency, handle errors and persist pagination checkpoints.
• Measure coverage and usefulness separately from detection accuracy.
• Confirm commercial integration, caching and redistribution rights before production use.

When reporting an issue, include the endpoint, UTC timestamp, HTTP status and meta.request_id if available. Never send your API key. Remove sensitive indicators unless they are necessary for troubleshooting.

API v1 · Contact us for integration help or to review your access plan.