Skip to content

w33ts/virustotal-api-skill

virustotal-api

Verified

Comprehensive reference for the VirusTotal API v3, covering authentication, rate limits, endpoint usage, and the critical differences between Free (Public) and Premium (Enterprise) tiers. Use this skill whenever a user asks about VirusTotal, VT API, scanning files or URLs with VirusTotal, threat intelligence lookups, IoC enrichment, YARA hunting, Retrohunt, Livehunt, VT Intelligence search, VT Graph, VT Monitor, VT Feeds, private scanning, malware analysis via VirusTotal, or building integrations with the VirusTotal API. Also trigger when the user mentions "VT", "virustotal", hash lookups, file reputation checks, URL scanning services, sandbox detonation reports, or any workflow involving programmatic interaction with VirusTotal's threat intelligence platform — even if they don't say "API" explicitly.

FileKindSize
SKILL.mdexecutableskill md16.4 KB
references/endpoints-enterprise.mdexecutablescript13.8 KB
references/endpoints-free.mdexecutablescript11.2 KB
references/objects-and-relationships.mdexecutablescript13.3 KB

references/endpoints-free.md

View on GitHub
# VirusTotal API v3 — Free (Public) Tier Endpoints

This reference covers all endpoints accessible with a free VirusTotal Community API key.
Rate limit: 4 requests/minute, 500 requests/day.

---

## Table of Contents

1. [Files](#files)
2. [URLs](#urls)
3. [Domains](#domains)
4. [IP Addresses](#ip-addresses)
5. [Comments](#comments)
6. [Analyses, Submissions & Operations](#analyses-submissions--operations)
7. [File Behaviours](#file-behaviours)
8. [Attack Tactics & Techniques](#attack-tactics--techniques)
9. [Popular Threat Categories](#popular-threat-categories)
10. [Search (Basic)](#search-basic)
11. [YARA Rules (Crowdsourced)](#yara-rules-crowdsourced)
12. [IoC Stream](#ioc-stream)
13. [Saved Searches](#saved-searches)
14. [VT Graphs](#vt-graphs)
15. [Code Insights](#code-insights)
16. [VT Augment Widget](#vt-augment-widget)

---

## Files

### Upload a file
```
POST /api/v3/files
Content-Type: multipart/form-data
```
Body: form field `file` containing the binary. Max 32MB via this endpoint.

**Response:** 200 with analysis object containing `id` (analysis ID) and `type: "analysis"`.

### Get upload URL for large files
```
GET /api/v3/files/upload_url
```
Returns a one-time-use URL for uploading files up to 650MB. POST the file to the returned URL
using the same multipart format.

### Get a file report
```
GET /api/v3/files/{id}
```
`{id}` can be an MD5, SHA-1, or SHA-256 hash. Returns the full file object with attributes
including `last_analysis_stats`, `last_analysis_results`, `type_description`, `size`, `names`,
`sha256`, `md5`, `sha1`, etc.

**Example response shape:**
```json
{
  "data": {
    "type": "file",
    "id": "<sha256>",
    "attributes": {
      "last_analysis_stats": {
        "malicious": 45,
        "suspicious": 0,
        "undetected": 25,
        "harmless": 0,
        "timeout": 1,
        "type-unsupported": 3,
        "failure": 0
      },
      "last_analysis_results": {
        "Kaspersky": {
          "category": "malicious",
          "engine_name": "Kaspersky",
          "engine_version": "22.0.1.28",
          "result": "Trojan.Win32.Generic",
          "method": "exact",
          "engine_update": "20250510"
        }
      },
      "sha256": "...",
      "md5": "...",
      "size": 123456,
      "type_description": "Win32 EXE",
      "meaningful_name": "setup.exe",
      "reputation": -45,
      "tags": ["peexe", "overlay"]
    }
  }
}
```

### Request a file rescan
```
POST /api/v3/files/{id}/analyse
```
Queues a rescan using the latest AV engine versions. Returns an analysis object.

### Comments on files
```
GET  /api/v3/files/{id}/comments         # List comments
POST /api/v3/files/{id}/comments         # Add a comment (body: {"data":{"type":"comment","attributes":{"text":"..."}}})
```

### Votes on files
```
GET  /api/v3/files/{id}/votes            # List votes
POST /api/v3/files/{id}/votes            # Vote (body: {"data":{"type":"vote","attributes":{"verdict":"malicious"|"harmless"}}})
```

### File relationships (free subset)
```
GET /api/v3/files/{id}/{relationship}
```

Free relationship types include:
- `behaviours` — sandbox behavior reports
- `bundled_files` — files contained within archives/bundles
- `collections` — collections containing this file
- `comments` — comments on this file
- `contacted_domains` — domains contacted during sandbox execution
- `contacted_ips` — IPs contacted during sandbox execution
- `contacted_urls` — URLs contacted during sandbox execution
- `dropped_files` — files dropped during sandbox execution
- `execution_parents` — files that executed this file
- `graphs` — VT graphs containing this file
- `pe_resource_children` / `pe_resource_parents` — PE resource relationships
- `sigma_analysis` — Sigma rule analysis results
- `votes` — community votes

🔒 Enterprise-only file relationships (will return ForbiddenError on free key):
`analyses`, `carbonblack_children`, `carbonblack_parents`, `compressed_parents`,
`email_attachments`, `email_parents`, `embedded_domains`, `embedded_ips`, `embedded_urls`,
`itw_domains`, `itw_ips`, `itw_urls`, `overlay_children`, `overlay_parents`,
`pcap_children`, `pcap_parents`, `related_references`, `related_threat_actors`,
`screenshots`, `similar_files`, `submissions`, `urls_for_embedded_js`

### Get Sigma / YARA rules for a file
```
GET /api/v3/sigma_analyses/{id}          # Get a Sigma rule analysis
GET /api/v3/yara_rulesets/{id}           # Get a YARA ruleset
```

---

## URLs

URL IDs in the v3 API are the base64url encoding of the URL (without trailing `=` padding).

```python
import base64
url_id = base64.urlsafe_b64encode("https://example.com".encode()).decode().rstrip("=")
# Result: "aHR0cHM6Ly9leGFtcGxlLmNvbQ"
```

### Scan a URL
```
POST /api/v3/urls
Content-Type: application/x-www-form-urlencoded
Body: url=https://example.com
```
Returns an analysis object. Poll `/analyses/{id}` for results.

### Get a URL report
```
GET /api/v3/urls/{id}
```

### Rescan a URL
```
POST /api/v3/urls/{id}/analyse
```

### Comments, votes, relationships
Same pattern as files. Free relationship types include:
`collections`, `comments`, `graphs`, `last_serving_ip_address`, `network_location`,
`related_comments`, `votes`

🔒 Enterprise-only URL relationships:
`analyses`, `communicating_files`, `contacted_domains`, `contacted_ips`, `downloaded_files`,
`embedded_js_files`, `redirecting_urls`, `redirects_to`, `referrer_files`, `referrer_urls`,
`related_references`, `related_threat_actors`, `submissions`,
`urls_related_by_tracker_id`

---

## Domains

### Get a domain report
```
GET /api/v3/domains/{domain}
```

### Rescan a domain
```
POST /api/v3/domains/{domain}/rescan
```

### Free domain relationships
`collections`, `comments`, `communicating_files`, `graphs`, `historical_ssl_certificates`,
`historical_whois`, `immediate_parent`, `parent`, `referrer_files`, `related_comments`,
`resolutions`, `siblings`, `subdomains`, `votes`

🔒 Enterprise-only: `caa_records`, `cname_records`, `downloaded_files`, `mx_records`,
`ns_records`, `related_references`, `related_threat_actors`, `soa_records`, `urls`

---

## IP Addresses

### Get an IP address report
```
GET /api/v3/ip_addresses/{ip}
```

### Rescan an IP
```
POST /api/v3/ip_addresses/{ip}/rescan
```

### Free IP relationships
`collections`, `comments`, `communicating_files`, `graphs`, `historical_ssl_certificates`,
`historical_whois`, `related_comments`, `referrer_files`, `resolutions`, `votes`

🔒 Enterprise-only: `downloaded_files`, `related_references`, `related_threat_actors`, `urls`

---

## Comments

### Global comment endpoints
```
GET    /api/v3/comments                  # Latest comments across VT
GET    /api/v3/comments/{id}             # Get a specific comment
DELETE /api/v3/comments/{id}             # Delete your own comment
GET    /api/v3/comments/{id}/{rel}       # Comment relationships
POST   /api/v3/comments/{id}/votes       # Vote on a comment
```

---

## Analyses, Submissions & Operations

### Get an analysis
```
GET /api/v3/analyses/{id}
```
Returns status and results of a scan/rescan. The `attributes.status` field will be `queued`,
`in-progress`, or `completed`. Once completed, `attributes.stats` contains detection counts.

### Get a submission
```
GET /api/v3/submissions/{id}
```

### Get an operation
```
GET /api/v3/operations/{id}
```
Operations represent long-running tasks and can be polled for completion.

---

## File Behaviours

```
GET /api/v3/files/{id}/behaviour_summary          # Summary of all sandbox reports
GET /api/v3/files/{id}/behaviour_mitre_trees       # MITRE ATT&CK summary
GET /api/v3/files/{id}/behaviours                  # All individual sandbox reports
GET /api/v3/file_behaviours/{id}                   # Specific sandbox report by ID
GET /api/v3/file_behaviours/{id}/html              # Detailed HTML report
GET /api/v3/file_behaviours/{id}/evtx              # Windows event log from sandbox
GET /api/v3/file_behaviours/{id}/pcap              # Network capture from sandbox
GET /api/v3/file_behaviours/{id}/memdump           # Memory dump from sandbox
```

Behaviour reports include: DNS lookups, HTTP conversations, IP traffic, processes tree,
files dropped, files copied, registry keys, mutexes, and more.

---

## Attack Tactics & Techniques

```
GET /api/v3/attack_tactics/{id}                    # Get a MITRE tactic
GET /api/v3/attack_tactics/{id}/{relationship}     # Related techniques
GET /api/v3/attack_techniques/{id}                 # Get a MITRE technique
GET /api/v3/attack_techniques/{id}/{relationship}  # Related tactics, subtechniques, etc.
```

🔒 The `threat_actors` relationship on attack techniques is enterprise-only.

---

## Popular Threat Categories

```
GET /api/v3/popular_threat_categories              # List popular threat categories
```

---

## Search (Basic)

```
GET /api/v3/search?query={query}
```

The basic search endpoint accepts exact indicators: file hashes (MD5/SHA-1/SHA-256), URLs,
domains, IP addresses, and tags. It does NOT support the full VT Intelligence search modifiers.
For advanced search with modifiers, you need the enterprise `/intelligence/search` endpoint.

---

## YARA Rules (Crowdsourced)

```
GET /api/v3/yara_rulesets                          # List crowdsourced YARA rulesets
GET /api/v3/yara_rulesets/{id}                     # Get a specific ruleset
GET /api/v3/yara_rulesets/{id}/{relationship}      # Related objects
```

These are community-contributed YARA rules, not your own Livehunt rules (which are 🔒).

---

## IoC Stream

The IoC Stream delivers notifications about IoCs matching your monitoring criteria.

```
GET /api/v3/ioc_stream                             # Get IoC Stream objects
GET /api/v3/ioc_stream_notifications/{id}          # Get a specific notification
DELETE /api/v3/ioc_stream_notifications/{id}       # Delete a notification
DELETE /api/v3/ioc_stream_notifications             # Delete all notifications
```

---

## Saved Searches

```
GET    /api/v3/intelligence/saved_searches          # List saved searches
GET    /api/v3/intelligence/saved_searches/{id}     # Get a saved search
POST   /api/v3/intelligence/saved_searches          # Create a saved search
PATCH  /api/v3/intelligence/saved_searches/{id}     # Update a saved search
DELETE /api/v3/intelligence/saved_searches/{id}     # Delete a saved search
POST   /api/v3/intelligence/saved_searches/{id}/share           # Share
DELETE /api/v3/intelligence/saved_searches/{id}/revoke_access    # Revoke access
```

---

## VT Graphs

```
GET    /api/v3/graphs                               # Search graphs
POST   /api/v3/graphs                               # Create a graph
GET    /api/v3/graphs/{id}                           # Get a graph
PATCH  /api/v3/graphs/{id}                           # Update a graph
DELETE /api/v3/graphs/{id}                           # Delete a graph
```

Permissions endpoints for viewers and editors are also available.

---

## Code Insights

```
POST /api/v3/code_insights                          # Analyze code blocks
```
Sends code blocks for AI-powered analysis and explanation.

---

## VT Augment Widget

```
GET /api/v3/widget/url?query={indicator}            # Get widget rendering URL
GET /api/v3/widget/html/{token}                     # Get widget HTML content
```

The widget provides an embeddable threat context panel for third-party applications.
Theming is available via the `/widget/theme` endpoint.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall