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.
| Plan | Price | Per minute | Per day | Per month | |
|---|---|---|---|---|---|
| Free | $0 — verified email required | 5 | 50 | 500 | Sign up |
| Developer | $29 / month | 60 | – | 50,000 (hard stop, never billed more) | |
| Scale | $0.002 per call ($2 per 1,000), billed monthly | 300 | – | 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:
| Header | Meaning |
|---|---|
X-API-Plan | free, developer, scale or included |
X-RateLimit-Limit / X-RateLimit-Remaining | calls allowed per minute, and left in the current minute |
X-Quota-Limit / X-Quota-Remaining | billable calls allowed this month (this day for the included plan), and left |
X-Quota-Reset | when the quota resets (ISO 8601, UTC) |
Retry-After | on a 429 for the per-minute limit: seconds to wait |
| Other limits | Value |
|---|---|
| File uploads | up to 32 MB |
| Device scans | 10 per device per day, one at a time |
| Remote fixes | 30 per device per day, one at a time per finding |
| Alerts | 30 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:
| Status | code | Meaning and what to do |
|---|---|---|
| 400 | Bad input; the message says which field. | |
| 401 | No key, or the key is wrong or revoked. | |
| 402 | licence_required | Device, fleet, fix and alert endpoints need an active OmniGuard licence. |
| 403 | email_unverified | Verify the account’s email address (Free plan, and before buying a plan). |
| 403 | The action needs the signed-in session, not an API key. | |
| 404 / 409 | Not found / conflict (for example a scan already running). | |
| 429 | rate_limited | Per-minute limit. Wait Retry-After seconds. |
| 429 | quota_day / quota_month | Plan quota used. Wait for X-Quota-Reset, or upgrade (upgrade links to the plans). |
| 502 | A threat-intelligence service did not answer. Retry shortly; nothing was billed twice. |
Lookups
| Request | What 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.exeraw 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/scans | Your recent lookups. |
GET /api/v1/scans/{id} | One lookup; a pending upload refreshes when VirusTotal finishes. |
GET /api/v1/status | Connected 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-plans | Public, no key. The plans, prices and limits above, and whether each can be bought. |
GET /api/v1/usage | Your plan, limits, calls used today and this month, when they resets, and the subscription status for a paid plan. |
GET /api/v1/status | Connected 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/portal | Signed-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/devices | Your 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}/scans | Recent 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/fleet | Each 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.csv | The 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}/fixesGET /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/alerts | Settings 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-secret | Session only. A new secret, returned once; the old one stops working. |
POST /api/v1/alerts/test | Session 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.
| Header | Meaning |
|---|---|
X-OG-Event | device_scan.finished, device_scan.failed, device_fix.failed or test |
X-OG-Timestamp | Unix seconds when it was sent |
X-OG-Signature | sha256= 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.