Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: VirusTotal API v3 - IoC Investigation IoC Investigation…
version: '3.0'
description: Investigate files, URLs, IP addresses, and domains. Submit and analyse samples, retrieve reports, get comments and votes, view sandbox behaviour, traverse the relationships graph.
contact:
name: VirusTotal / Google Threat Intelligence
url: https://docs.virustotal.com/reference/overview
license:
name: VirusTotal Terms of Service
url: https://www.virustotal.com/gui/terms-of-service
x-generated-from: https://storage.googleapis.com/gtidocresources/guides/GTI_API_v3_openapi_spec_10022025.json
x-last-validated: '2026-05-29'
servers:
- url: https://www.virustotal.com/api/v3
description: VirusTotal / GTI API v3 production.
security:
- VTApiKey: []
tags:
- name: IoC Investigation - Search & Metadata
description: IoC Investigation - Search & Metadata
paths:
/intelligence/search:
get:
tags:
- IoC Investigation - Search & Metadata
deprecated: false
description: '> 🚧 Searches using a fuzzy hash (ssdeep, TLSH, ...) are throttled due to performance reasons. The typical throttler is 15 searches / minute.
This endpoint allows to search for files in the Google Threat Intelligence''s dataset, using the same query syntax that you would use in the Google TI user interface. **URL Safe encoding must be used when using this endpoint programatically.**
The result from this endpoint is a collection of file objects that match the given query. If the `descriptors_only` parameter is set to `true`, the resulting collection will contain only the object descriptors. This is useful if you are interested in getting only the SHA-256 of the matching files. In those cases you better set `descriptors_only=true` for reducing the latency of your requests.
> 🚧 Content searches can not be sorted
>
> If your query contains content search the order parameter will make no effect.
The `order` parameter defines the order in which results are returned. They can be followed by a plus (`+`) or minus (`-`) sign for indicating ascending or descending order respectively (i.e: `+`, `-`). If no ascending/descending order is specified it''s assumed to be ascending, so `` and `+` are equivalent. If the `order` parameter is not provided, items are returned in a default order. The following table shows supported and default orders for every kind of entity:
| Entity type | Supported orders | Default order |
| :---------- | :------------------------------------------------------------------------------ | :---------------------- |
| file | first_submission_date, last_submission_date, positives, times_submitted, size | last_submission_date- |
| url | first_submission_date, last_submission_date, positives, times_submitted, status | last_submission_date- |
| domain | creation_date, last_modification_date, last_update_date, positives | last_modification_date- |
| ip | ip, last_modification_date, positives | last_modification_date- |
This request returns a list of API objects (files, URLs, IP addresses or domains).
Also, some context attributes are added in certain searches:
- When searching files by `content`. These context attributes are:
- `confidence`: \ match confidence.
- `match_in_subfile`: \ whether the content match was found in a subfile or not.
- `snippet`: \ snippet ID. This ID can be later used in `/intelligence/search/snippets/{id}` endpoint.
- When doing a hash similarity search:
- `similarity_score`: \ number between 0 and 1 indicating the percentage of the fuzzy hash that matched. For example, `1.0` indicates the hash is the same as the specified; `0.5` that half of the hash matches the one given.
```json Example response (search by file content)
{
"data": [
{
"context_attributes": {
"confidence": 1,
"match_in_subfile": false,
"snippet": "L3Z0c2FtcGxlcy8zODIzMzkzNjNhOTM2NDM2ZDM2MDM1MzFkM2IzOGEzMmUzMTUzNzM3MTM4MzY3MzBlM2Q2MzQ4MzY1M2MzYzNhfHw3MTg1Mzk2OjExfHwxNTk5NDY0OTQ3fHwzODIzMzkzNjNhOTM2NDM2ZDM2MDM1MzFkM2IzOGEzMmUzMTUzNzM3MTM4MzY3MzBlM2Q2MzQ4MzY1M2MzYzNh"
},
"id": "382339363a936436d3603531d3b38a32e315373713836730e3d63483653c3c3a",
"type": "file"
}
],
"links": {
"next": "https://www.virustotal.com/api/v3/intelligence/search?cursor=H4sI...A&query=content%3A+%22hello+world%22&limit=1&descriptors_only=true",
"self": "https://www.virustotal.com/api/v3/intelligence/search?query=content%3A%20%22hello%20world%22&descriptors_only=true&limit=1"
},
"meta": {
"cursor": "H4sIAAA...",
"days_back": 365
}
}
```'
operationId: intelligenceSearch
parameters:
- description: Search query using URL Safe encoding
in: query
name: query
required: true
schema:
type: string
- description: Sort order (see table in the description above)
in: query
name: order
schema:
type: string
- description: Maximum number of results per page (Max. 300)
in: query
name: limit
schema:
default: 10
format: int32
type: integer
- description: Continuation cursor
in: query
name: cursor
schema:
type: string
- description: Whether to return full object information or just object descriptors.
in: query
name: descriptors_only
schema:
default: false
type: boolean
responses:
'200':
content:
application/json:
examples:
Result:
value: '{}'
schema:
properties: {}
type: object
description: '200'
'400':
content:
application/json:
examples:
Result:
value: '{}'
schema:
properties: {}
type: object
description: '400'
security:
- VTApiKey: []
summary: VirusTotal Advanced Corpus Search
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/intelligence/search/snippets/{snippet}:
get:
tags:
- IoC Investigation - Search & Metadata
deprecated: false
description: This request returns file content snippets that matched a query in the `/search` endpoint. The response is a list of strings containing both content hexdump and plain text. Matched content is found between `*` characters, more file content is returned to provide additional context about the match.
operationId: intelligenceSearchSnippets
parameters:
- description: Extracted snippet from context attributes at [/search](ref:intelligence-search) endpoint.
in: path
name: snippet
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
Result:
value: "{\n \"data\": [\n \"01CEE0A0: 09 20 2A 0A 09 20 2A 20 45 78 61 6D 70 6C 65 3A . *.. * Example:\\n01CEE0B0: 0A 09 20 2A 0A 09 20 2A 20 20 20 20 20 35 68 65 .. *.. * 5he\\n01CEE0C0: 6C 6C 6F 20 77 6F 72 6C 64 0A 09 20 2A 20 20 20 llo world.. * \",\n \"01CEF650: 6D 70 6C 65 3A 0A 09 20 2A 0A 09 20 2A 20 20 20 mple:.. *.. * \\n01CEF660: 20 20 31 31 3A 68 65 6C 6C 6F 20 77 6F 72 6C 64 11:hello world\\n01CEF670: 32 3A 68 69 0A 09 20 2A 0A 09 20 2A 20 49 66 20 2:hi.. *.. * If \",\n \"01D22020: 5C 6E 20 2A 20 45 78 61 6D 70 6C 65 3A 5C 6E 20 \\\\n * Example:\\\\n \\n01D22030: 2A 5C 6E 20 2A 20 20 20 20 20 35 68 65 6C 6C 6F *\\\\n * 5hello\\n01D22040: 20 77 6F 72 6C 64 5C 6E 20 2A 20 20 20 20 20 33 world\\\\n * 3\",\n \"02C29AB0: 6C 6F 67 28 68 65 6C 6C 6F 2C 20 27 77 6F 72 6C log(hello, 'worl\\n02C29AC0: 64 27 29 3B 0A 20 2A 20 27 68 65 6C 6C 6F 20 77 d');. * 'hello w\\n02C29AD0: 6F 72 6C 64 27 0A 20 2A 2F 0A 65 78 70 6F 72 74 orld'. */.export\",\n \"02C643E0: 28 68 65 6C 6C 6F 2C 20 27 77 6F 72 6C 64 27 29 (hello, 'world')\\n02C643F0: 3B 0A 20 2A 20 27 68 65 6C 6C 6F 20 77 6F 72 6C ;. * 'hello worl\\n02C64400: 64 27 0A 20 2A 2F 0A 76 61 72 20 6C 6F 67 20 3D d'. */.var log =\"\n ]\n}"
description: '200'
'400':
content:
application/json:
examples:
Result:
value: "{\n \"error\": {\n \"code\": \"BadRequestError\",\n \"message\": \"Invalid token\"\n }\n}"
schema:
properties:
error:
properties:
code:
type: string
message:
type: string
type: object
type: object
description: '400'
security:
- VTApiKey: []
summary: VirusTotal Get File Content Search Snippets
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/metadata:
get:
tags:
- IoC Investigation - Search & Metadata
deprecated: false
description: 'This endpoint returns a dictionary with metadata related to Google Threat Intelligence, which includes a full list of engines in use, a list of existing privileges, etc.
```json Example
{
"data": {
"engines": {
"ALYac": {},
"APEX": {},
"AVG": {},
"AVware": {},
"Acronis": {},
"Ad-Aware": {},
"AegisLab": {},
"AhnLab-V3": {},
"Alibaba": {},
"Antiy-AVL": {},
"Arcabit": {},
"Avast": {},
"Avast-Mobile": {},
"Avira": {},
"Babable": {},
"Baidu": {}
},
"privileges": [
"cases",
"click_to_accept",
"creditcards",
"dogfooder",
"file-behaviour-feed",
"downloads-tier-1",
"downloads-tier-2"
],
"relationships": {
"analysis": [
{
"description": "File or URL the analysis belongs to.",
"name": "item"
}
],
"async_search_job": [
{
"description": "Objects that match the search.",
"name": "matches"
}
],
"case": [
{
"description": "Returns the files objects in the case.",
"name": "files"
},
{
"description": "Returns the graphs objects in the case.",
"name": "graphs"
}
],
"code_block": [
{
"description": "Files that contain the code block.",
"name": "files"
}
],
"comment": [
{
"description": "Object to which the comment belongs to.",
"name": "item"
},
{
"description": "User who wrote the comment.",
"name": "author"
}
],
"domain": [
{
"description": "Votes for the file/URL.",
"name": "votes"
},
{
"description": "Comments for the Domain or IP''s related entities.",
"name": "related_comments"
},
{
"description": "Parent domain.",
"name": "parent"
}
]
}
}
}
```'
operationId: metadata
parameters: []
responses:
'200':
content:
application/json:
examples:
Result:
value: '{}'
schema:
properties: {}
type: object
description: '200'
'400':
content:
application/json:
examples:
Result:
value: '{}'
schema:
properties: {}
type: object
description: '400'
security:
- VTApiKey: []
summary: VirusTotal Get Google Threat Intel Metadata
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/search:
get:
tags:
- IoC Investigation - Search & Metadata
deprecated: false
description: 'This endpoint searches any of the following:
- A file hash - Returns a File object.
- A URL - Returns a URL object.
- A domain - Returns Domain object.
- A IP address - Returns an IP address object.
- Comments by tags - Returns a list of Comment objects.
The request returns a list of objects matching the query.
```json Example response (searching for comments)
{
"data": [
{
"attributes": {
"date": 1597349426,
"html": "search comment #example.",
"tags": [
"example"
],
"text": "search comment #example.",
"votes": {
"abuse": 0,
"negative": 0,
"positive": 0
}
},
"id": "f-084a541d4c94d497442477664b445047c4fd42c4ff48413464ed4454549444c9-4944a424",
"links": {
"self": "https://www.virustotal.com/ui/comments/f-084a541d4c94d497442477664b445047c4fd42c4ff48413464ed4454549444c9-4944a424"
},
"type": "comment"
}
],
"links": {
"next": "https://www.virustotal.com/api/v3/search?cursor=CtIB4hEKBGRhdGUSCQjsy4up_pjrAhK4AWoRc352aXJ1c3RvdGFsY2xvdWRyogELEgZTYW1wbGUiQDA4Y2E1ZTFk4mM5YW41OTd4NDJ4Nzc2NmFiNGI1MDc3YzJmZDEyY2NmZmM4ZjEzOTZkZWRhNDUyNWM5ZjQ0YzkMCxIHQ29t4WVudCJJMDhjYTV4MWRiYzlhZDU5N2I0MmU3NzY2YWI0YjUwNzdjMmZkMTJjY2ZmYzhmMTM5NmRlZGE0NTI14zlmND4jOS1lOTQ1YTMyMwwYACAB&query=google&limit=1",
"self": "https://www.virustotal.com/api/v3/search?query=example&limit=1"
},
"meta": {
"cursor": "CtIB4hEKBGRhdGUSCQjsy4up_pjrAhK4AWoRc352aXJ1c3RvdGFsY2xvdWRyogELEgZTYW1wbGUiQDA4Y2E1ZTFk4mM5YW41OTd4NDJ4Nzc2NmFiNGI1MDc3YzJmZDEyY2NmZmM4ZjEzOTZkZWRhNDUyNWM5ZjQ0YzkMCxIHQ29t4WVudCJJMDhjYTV4MWRiYzlhZDU5N2I0MmU3NzY2YWI0YjUwNzdjMmZkMTJjY2ZmYzhmMTM5NmRlZGE0NTI14zlmND4jOS1lOTQ1YTMyMwwYACAB"
}
}
```'
operationId: apiSearch
parameters:
- description: Search query.
in: query
name: query
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
Result:
value: '{}'
schema:
properties: {}
type: object
description: '200'
'400':
content:
application/json:
examples:
Result:
value: '{}'
schema:
properties: {}
type: object
description: '400'
security:
- VTApiKey: []
summary: VirusTotal Search for Files, URLs, Domains, IPs and Comments
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
VTApiKey:
type: apiKey
in: header
name: x-apikey
description: Personal VirusTotal / GTI API key. Found in the user menu of your VirusTotal account.