← Back to the Scan page

OmniGuard Scan API

Check files, links, domains and IP addresses against VirusTotal, abuse.ch (MalwareBazaar, URLhaus, ThreatFox), AbuseIPDB, Google Safe Browsing and urlscan.io; scan and fix the computers that run OmniGuard on your licence; and get a signed alert when something is found. Every answer comes with a remediation plan.

Contents: Plans & limits · Access · Rate limits & quota headers · Errors · Lookups · Usage & billing · Devices · Fleet · Remote fixes · Schedules · Alerts · Webhooks · OpenAPI 3.1 spec

Plans & limits

Every plan needs an OmniGuard account. Limits are per account: all of an account’s API keys share them. Billable calls are the lookups (POST /api/v1/scan and POST /api/v1/scan/file); reading your results, usage, keys and status is free and only rate limited.

PlanPricePer minutePer dayPer month
Free$0 — verified email required550500Sign up
Developer$29 / month60–50,000 (hard stop, never billed more)
Scale$0.002 per call ($2 per 1,000), billed monthly300–no allowance; 1,000,000 safety ceiling (ask to raise)

Accounts with an active OmniGuard licence also get lookups included (20 a minute, 300 a day) plus the device, fleet, remote-fix and alert endpoints, which act on licensed computers. Day limits reset at 00:00 UTC and month limits on the 1st (UTC). Uploading an unknown file to VirusTotal (share=1) is available on Developer, Scale and licences.

Access

Create a key on the Scan page (it is shown once and stored only as a hash) and send it on every request:

Authorization: Bearer ogk_...

The same endpoints work from the signed-in account page. A few actions that change your account or a device need the signed-in session and are refused with an API key (403): managing API keys, requesting a remote fix, and changing alert or schedule settings.

Rate limits & quota headers

Every authenticated answer carries your plan and what is left, so a client can pace itself without calling /usage:

HeaderMeaning
X-API-Planfree, developer, scale or included
X-RateLimit-Limit / X-RateLimit-Remainingcalls allowed per minute, and left in the current minute
X-Quota-Limit / X-Quota-Remainingbillable calls allowed this month (this day for the included plan), and left
X-Quota-Resetwhen the quota resets (ISO 8601, UTC)
Retry-Afteron a 429 for the per-minute limit: seconds to wait
Other limitsValue
File uploadsup to 32 MB
Device scans10 per device per day, one at a time
Remote fixes30 per device per day, one at a time per finding
Alerts30 per account per hour (email at most 10)

Errors

Errors are JSON {"error": "a sentence for a person", "code": "for_programs"}. code is present where a program should react differently:

StatuscodeMeaning and what to do
400Bad input; the message says which field.
401No key, or the key is wrong or revoked.
402licence_requiredDevice, fleet, fix and alert endpoints need an active OmniGuard licence.
403email_unverifiedVerify the account’s email address (Free plan, and before buying a plan).
403The action needs the signed-in session, not an API key.
404 / 409Not found / conflict (for example a scan already running).
429rate_limitedPer-minute limit. Wait Retry-After seconds.
429quota_day / quota_monthPlan quota used. Wait for X-Quota-Reset, or upgrade (upgrade links to the plans).
502A threat-intelligence service did not answer. Retry shortly; nothing was billed twice.

Lookups

RequestWhat it does
POST /api/v1/scan
{"target": "example.com"}
Checks a SHA-256/SHA-1/MD5 hash, URL, domain or IP. The type is detected; force it with "type": "hash"|"url"|"domain"|"ip".
POST /api/v1/scan/file?share=0&name=x.exe
raw body, Content-Type: application/octet-stream
Checks a file by its SHA-256. With share=1 an unknown file is uploaded to VirusTotal (which shares uploads with its community; never upload private documents) and the scan is pending until VirusTotal finishes.
GET /api/v1/scansYour recent lookups.
GET /api/v1/scans/{id}One lookup; a pending upload refreshes when VirusTotal finishes.
GET /api/v1/statusConnected services and your limits.

Each answer has verdict (malicious, suspicious, clean or unknown), summary, providers (each service's answer and report link) and remediation (steps with OmniGuard actions and Windows/Linux commands).

curl -H "Authorization: Bearer ogk_..." -H "Content-Type: application/json" \
     -d '{"target":"https://example.com/download.exe"}' https://buy.nsite.tech/api/v1/scan

Usage & billing

GET /api/api-plansPublic, no key. The plans, prices and limits above, and whether each can be bought.
GET /api/v1/usageYour plan, limits, calls used today and this month, when they resets, and the subscription status for a paid plan.
GET /api/v1/statusConnected services, your plan and limits.
POST /api/v1/billing/checkout
{"plan": "developer"|"scale"}
Signed-in session only. A Stripe Checkout url to start the plan.
POST /api/v1/billing/portalSigned-in session only. A Stripe billing-portal url to change or cancel the plan and see invoices.
curl -s -D - -o /dev/null -H "Authorization: Bearer ogk_..." https://buy.nsite.tech/api/v1/usage
# X-API-Plan: developer
# X-Quota-Limit: 50000
# X-Quota-Remaining: 48211
# X-Quota-Reset: 2026-11-01T00:00:00.000Z

Devices

A device is a computer running OmniGuard with your licence. From OmniGuard 3.52, remote scans are allowed by default on licensed devices (older versions need Allow remote scans turned on); the person at the computer can turn it off in OmniGuard Settings, and OmniGuard shows on screen whenever a remote scan runs. The report has OmniGuard's findings plus file hashes, remote addresses and domains checked against threat intelligence — never file contents.

GET /api/v1/devicesYour devices: id, name, online, remote_scans, remote_fixes.
POST /api/v1/devices/{id}/scans
{"kind": "quick"|"full"}
Queues a scan; the device starts within a minute when online. 202 with the scan id.
GET /api/v1/devices/{id}/scansRecent scans of the device.
GET /api/v1/devices/{id}/scans/{scanId}One scan: status (queued, sent, enriching, done, failed, cancelled), verdict, summary, indicators, remediation, the device report, and its fixes.

Fleet

POST /api/v1/devices/scans
{"kind": "quick"|"full"}
Queues a scan on every device that allows remote scans; results lists each device and why any did not start. 3 a minute.
GET /api/v1/fleetEach device's latest finished scan, totals by verdict, and the OmniGuard findings and threat-intelligence indicators across devices, grouped with the devices they were seen on (most serious first).
GET /api/v1/fleet/report.csvThe same as a spreadsheet, one row per finding or indicator per device. Cells that start with = + - @ are prefixed with ' so a spreadsheet never runs them as formulas.

A printable version is at /scan/report (print it or save it as a PDF).

Remote fixes

When Allow remote fixes is on in OmniGuard on the device (on by default on licensed devices from OmniGuard 3.53; it can be turned off there), a finding in a scan report that carries a fix can be fixed from your account. Only the finding's sig and, where OmniGuard offered a choice (for example trust / kill), that choice are sent; the device checks the finding again and applies OmniGuard's own fix. No command can be sent. Signed-in session only.

POST /api/v1/devices/{id}/fixes
{"scan_id": "...", "sig": "...", "choice": "trust"}
Queues the fix (202). choice is required when the finding's fix.choices is not empty.
GET /api/v1/devices/{id}/fixes
GET /api/v1/devices/{id}/fixes/{fixId}
status (queued, sent, done, failed, cancelled) and the device's result.

Scheduled scans

GET /api/v1/devices/{id}/schedule{"freq": "off"} or the schedule with next_run, last_run, last_error.
PUT /api/v1/devices/{id}/schedule
{"freq": "daily"|"weekly"|"off", "kind": "quick", "hour": 3, "weekday": 1, "tz": "America/Los_Angeles"}
Local hour 0–23 in the IANA time zone tz; weekday 0 (Sunday) to 6 for weekly. Signed-in session only.

Alerts

You can be told when a device scan finishes at or above your chosen level (malicious, suspicious or all), when a scheduled scan cannot run, and when a remote fix is not applied — by email to your account address, a webhook, or both. Each scan or fix is alerted once.

GET /api/v1/alertsSettings and the last 20 alerts.
PUT /api/v1/alerts
{"email": true, "webhook_url": "https://...", "level": "malicious"}
Session only. Setting a new webhook URL returns webhook_secret once.
POST /api/v1/alerts/rotate-secretSession only. A new secret, returned once; the old one stops working.
POST /api/v1/alerts/testSession only. Sends a test alert on every channel.

Webhooks

The webhook must be a public https:// address on port 443; addresses that resolve to private, loopback or other reserved networks are refused. Deliveries are POST with a JSON body, an 8 second timeout, and no redirects. Any 2xx answer counts as delivered.

HeaderMeaning
X-OG-Eventdevice_scan.finished, device_scan.failed, device_fix.failed or test
X-OG-TimestampUnix seconds when it was sent
X-OG-Signaturesha256= hex HMAC-SHA256 of timestamp + "." + raw body with your webhook secret
{
  "event": "device_scan.finished",
  "created": "2026-10-15T16:03:12.000Z",
  "device": { "id": "95afb0c4...", "name": "OFFICE-PC" },
  "scan": { "id": "msc_...", "kind": "quick", "trigger": "schedule", "status": "done",
            "verdict": "malicious", "summary": "Action needed: ...", "findings": 3, "indicators": 1,
            "url": "https://buy.nsite.tech/scan" }
}

Verify every delivery before acting on it: recompute the signature over the raw body, compare in constant time, and reject timestamps more than 5 minutes old.

// Node.js (Express): app.post('/omniguard', express.raw({ type: 'application/json' }), handler)
const crypto = require('crypto');
function verify(req, secret) {
  const ts = req.get('X-OG-Timestamp'), got = (req.get('X-OG-Signature') || '').replace(/^sha256=/, '');
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const want = crypto.createHmac('sha256', secret).update(ts + '.').update(req.body).digest('hex');
  return got.length === want.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want));
}
# Python
import hashlib, hmac, time
def verify(headers, raw_body: bytes, secret: str) -> bool:
    ts = headers.get("X-OG-Timestamp", "")
    got = headers.get("X-OG-Signature", "").removeprefix("sha256=")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    want = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(got, want)

Notes

Lookups are cached for 6 hours. Private addresses and local names (.local, .lan, ...) from a device report are never sent to threat-intelligence services. Device scan results are kept for 30 days.