Documentation

Overview

virust provides a REST API for looking up the reputation of file hashes, URLs, domains, and IP addresses. All lookups are powered by the VirusTotal public API.

Base URL: https://virust.pages.dev

Rate limit: 3 lookups per 15 minutes per IP

Authentication

Most endpoints do not require authentication. User sessions are only needed for posting comments and managing collections.

To authenticate, register or log in via POST /api/sessions. The response sets a virust_session cookie. Include this cookie in subsequent requests.

Endpoints

POST /api/lookup

Look up a file hash, URL, domain, or IP address.

Body:

{"q": "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"}

or

{"q": "https://example.com", "submit": false}

Accepted hash types: MD5 (32 hex), SHA-1 (40 hex), SHA-256 (64 hex)

Response: JSON object with verdict, detection counts, engine results, file metadata, and tags.

GET /api/history

List scan history with optional filters.

Query params: kind (file/url/domain/ip), verdict (malicious/suspicious/harmless/undetected), q (search), sort, dir, limit, offset

Summary: GET /api/history?view=summary returns aggregate counts.

GET /api/comments

List comments for a target.

Query params: target (hash/URL/domain/IP), kind (file/url/domain/ip)

POST /api/comments

Post a comment. Requires authentication.

Query params: target, kind

Body: {"text": "..."}

GET /api/collections

List collections. Requires premium VirusTotal API key.

Query params: action (list/get/items), id, kind

POST /api/collections

Create a collection or add an item. Requires premium VirusTotal API key.

Query params: action (create/add)

Body: {"name": "..."} or {"id": "...", "kind": "...", "target": "..."}

GET /api/relationships

Get related objects for a target.

Query params: target, kind, relationship

Valid relationships by kind:

• domain: subdomains, resolutions, siblings, urls, communicating_files, downloaded_files, referrer_files, historical_ssl_certificates, whois, dns_records, related_comments
• ip: resolutions, communicating_files, downloaded_files, urls, historical_ssl_certificates, related_comments
• file: behaviours, sigma_rules, crowdsourced_yara, tags, relationships, votes, comments
• url: network_location, downloaded_files, submissions, html, votes, comments

GET /api/intelligence

Search VirusTotal Intelligence. Requires premium VirusTotal API key.

Query params: q (search query)

GET /api/proxy/<path>

Generic proxy to any VirusTotal API v3 endpoint. Covers all endpoints not explicitly listed above.

Example: GET /api/proxy/domains/example.com

Allowed prefixes: /files/, /urls/, /domains/, /ip_addresses/, /collections/, /intelligence/, /graphs/, /submissions/, /comments/, /tags/, /sigma_rules/, /yara_rulesets/, /crowdsourced_yara_rules/, /feeds/, /api_keys/, /users/, /groups/, /popular_threat_labels/, /popular_threats/, /trending_threats/, /file_clusters/, /file_names/, /file_extensions/, /file_types/, /file_magics/, /file_sources/, /file_stats/, /file_trends/, /file_campaigns/, /file_malware_families/

POST /api/sessions

Register, log in, or log out.

Query params: action (register/login/logout)

Body: {"username": "...", "password": "..."}

GET /api/sessions/me

Get current session info. Returns 401 if not authenticated.

GET /api/config

Get service configuration, feature list, and endpoint reference.

Response Format

All responses are JSON. Errors return an error field with a human-readable message. Rate-limited responses include x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-window headers.

Verdict Values