> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# VirusTotal API reference

> API reference for the VirusTotal plugin in Corsair: every `virustotal.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Analyses

### get

`analyses.get`

Read an analysis a scan produced; its status moves from queued to completed

**Risk:** `read`

```ts theme={null}
await corsair.virustotal.api.analyses.get({ id: 'NjY0MjRlOTFjMDIyYTkyNWM0NjU2NWQzYWNlMzFmZmI6MTQ3NTA0ODI3Nw==' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | The analysis id a scan returned. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type?: string | null,
>   id?: string | null,
>   attributes?: {
>     status?: string | null,
>     date?: number | null,
>     stats?: Record<string, any> | null,
>     results?: Record<string, any> | null
>   } | null,
>   links?: Record<string, any> | null
> }
> ```

***

## Comments

### delete

`comments.delete`

Permanently delete one of your own comments, which cannot be restored

**Risk:** `destructive`

```ts theme={null}
await corsair.virustotal.api.comments.delete({ id: 'u-011915942db556bbab5137f761efe61fed2b00598fea900360b800b193a7bf31-d94d7c8a' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `deleted` | `true` | Yes | — |

***

### get

`comments.get`

Read one comment

**Risk:** `read`

```ts theme={null}
await corsair.virustotal.api.comments.get({ id: 'u-011915942db556bbab5137f761efe61fed2b00598fea900360b800b193a7bf31-d94d7c8a' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type?: comment | null,
>   id?: string | null,
>   attributes?: {
>     text?: string | null,
>     html?: string | null,
>     date?: number | null,
>     tags?: string[] | null,
>     votes?: {
>       positive?: number | null,
>       negative?: number | null,
>       abuse?: number | null
>     } | null
>   } | null,
>   links?: Record<string, any> | null
> }
> ```

***

### list

`comments.list`

List the latest comments anyone posted on VirusTotal, not only your own; filter by tag, e.g. tag:malware

**Risk:** `read`

```ts theme={null}
await corsair.virustotal.api.comments.list({ limit: 20, filter: 'tag:malware' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | Items per page. VirusTotal caps this at 40. |
| `cursor` | `string` | No | The `meta.cursor` from the previous page. |
| `filter` | `string` | No | A VirusTotal Intelligence filter expression. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type?: comment | null,
>   id?: string | null,
>   attributes?: {
>     text?: string | null,
>     html?: string | null,
>     date?: number | null,
>     tags?: string[] | null,
>     votes?: {
>       positive?: number | null,
>       negative?: number | null,
>       abuse?: number | null
>     } | null
>   } | null,
>   links?: Record<string, any> | null
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   cursor?: string | null
> } | null
> ```

***

## Domains

### get

`domains.get`

Read a domain report: registrar, dates, categories, DNS records and engine verdicts

**Risk:** `read`

```ts theme={null}
await corsair.virustotal.api.domains.get({ domain: 'acme.example' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `domain` | `string` | Yes | The domain name, not an identifier. |
| `relationships` | `string` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type?: domain | null,
>   id?: string | null,
>   attributes?: {
>     registrar?: string | null,
>     creation_date?: number | null,
>     last_update_date?: number | null,
>     expiration_date?: number | null,
>     categories?: Record<string, string> | null,
>     reputation?: number | null,
>     tags?: string[] | null,
>     last_dns_records?: any[] | null,
>     last_dns_records_date?: number | null,
>     last_analysis_stats?: {
>       harmless?: number | null,
>       suspicious?: number | null,
>       undetected?: number | null,
>       timeout?: number | null,
>       malicious?: number | null
>     } | null
>   } | null,
>   relationships?: Record<string, any> | null,
>   links?: Record<string, any> | null
> }
> ```

***

### rescan

`domains.rescan`

Ask VirusTotal to reanalyse a domain

**Risk:** `write`

```ts theme={null}
await corsair.virustotal.api.domains.rescan({ id: 'acme.example' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | The domain name to reanalyse. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type: string,
>   id: string
> }
> ```

***

## Files

### addComment

`files.addComment`

Comment on a file publicly; a word starting with # becomes a tag, and only the author can delete it

**Risk:** `write`

```ts theme={null}
await corsair.virustotal.api.files.addComment({ id: '275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f', text: '#malware seen in a phishing campaign' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | A SHA-256, SHA-1 or MD5 hash identifying the file. |
| `text` | `string` | Yes | The comment. A word starting with # becomes a tag. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type?: comment | null,
>   id?: string | null,
>   attributes?: {
>     text?: string | null,
>     html?: string | null,
>     date?: number | null,
>     tags?: string[] | null,
>     votes?: {
>       positive?: number | null,
>       negative?: number | null,
>       abuse?: number | null
>     } | null
>   } | null,
>   links?: Record<string, any> | null
> }
> ```

***

### comments

`files.comments`

List the comments on a file, newest first, with cursor paging

**Risk:** `read`

```ts theme={null}
await corsair.virustotal.api.files.comments({ id: '275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f', limit: 20 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | A SHA-256, SHA-1 or MD5 hash identifying the file. |
| `limit` | `number` | No | Items per page. VirusTotal caps this at 40. |
| `cursor` | `string` | No | The `meta.cursor` from the previous page. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type?: comment | null,
>   id?: string | null,
>   attributes?: {
>     text?: string | null,
>     html?: string | null,
>     date?: number | null,
>     tags?: string[] | null,
>     votes?: {
>       positive?: number | null,
>       negative?: number | null,
>       abuse?: number | null
>     } | null
>   } | null,
>   links?: Record<string, any> | null
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   cursor?: string | null
> } | null
> ```

***

### get

`files.get`

Read a file report by SHA-256, SHA-1 or MD5, including every engine verdict and the malicious tally

**Risk:** `read`

```ts theme={null}
await corsair.virustotal.api.files.get({ id: '275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | A SHA-256, SHA-1 or MD5 hash identifying the file. |
| `relationships` | `string` | No | Comma-separated relationships to include, such as `behaviours`. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type?: file | null,
>   id?: string | null,
>   attributes?: {
>     meaningful_name?: string | null,
>     type_description?: string | null,
>     type_tag?: string | null,
>     size?: number | null,
>     names?: string[] | null,
>     md5?: string | null,
>     sha1?: string | null,
>     sha256?: string | null,
>     ssdeep?: string | null,
>     tlsh?: string | null,
>     first_submission_date?: number | null,
>     last_submission_date?: number | null,
>     last_analysis_date?: number | null,
>     reputation?: number | null,
>     tags?: string[] | null,
>     last_analysis_results?: Record<string, any> | null,
>     last_analysis_stats?: {
>       harmless?: number | null,
>       type-unsupported?: number | null,
>       confirmed-timeout?: number | null,
>       suspicious?: number | null,
>       undetected?: number | null,
>       timeout?: number | null,
>       failure?: number | null,
>       malicious?: number | null
>     } | null
>   } | null,
>   relationships?: Record<string, any> | null,
>   links?: Record<string, any> | null
> }
> ```

***

### rescan

`files.rescan`

Ask VirusTotal to reanalyse a file already uploaded; answers an analysis id to poll, and counts against the scan quota

**Risk:** `write`

```ts theme={null}
await corsair.virustotal.api.files.rescan({ id: '275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | A SHA-256, SHA-1 or MD5 hash identifying the file. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type: string,
>   id: string
> }
> ```

***

### vote

`files.vote`

Vote a file harmless or malicious as your account

**Risk:** `write`

```ts theme={null}
await corsair.virustotal.api.files.vote({ id: '275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f', verdict: 'malicious' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | A SHA-256, SHA-1 or MD5 hash identifying the file. |
| `verdict` | `malicious \| harmless` | Yes | Which way to vote on the file. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type?: vote | null,
>   id?: string | null,
>   attributes?: {
>     verdict?: malicious | harmless | string | null,
>     date?: number | null
>   } | null,
>   links?: Record<string, any> | null
> }
> ```

***

### votes

`files.votes`

List the votes on a file with their verdicts

**Risk:** `read`

```ts theme={null}
await corsair.virustotal.api.files.votes({ id: '275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | A SHA-256, SHA-1 or MD5 hash identifying the file. |
| `limit` | `number` | No | Items per page. VirusTotal caps this at 40. |
| `cursor` | `string` | No | The `meta.cursor` from the previous page. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |
| `links` | `Record<string, any> \| null` | No | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type?: vote | null,
>   id?: string | null,
>   attributes?: {
>     verdict?: malicious | harmless | string | null,
>     date?: number | null
>   } | null,
>   links?: Record<string, any> | null
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   cursor?: string | null
> } | null
> ```

***

## Ip Addresses

### get

`ipAddresses.get`

Read an IP report: ASN and owner, country, network and engine verdicts

**Risk:** `read`

```ts theme={null}
await corsair.virustotal.api.ipAddresses.get({ ip: '203.0.113.10' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `ip` | `string` | Yes | The IPv4 or IPv6 address. |
| `relationships` | `string` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type?: ip_address | null,
>   id?: string | null,
>   attributes?: {
>     country?: string | null,
>     continent?: string | null,
>     as_owner?: string | null,
>     asn?: number | null,
>     network?: string | null,
>     regional_internet_registry?: string | null,
>     reputation?: number | null,
>     tags?: string[] | null,
>     last_analysis_date?: number | null,
>     last_analysis_results?: Record<string, any> | null,
>     last_analysis_stats?: {
>       harmless?: number | null,
>       suspicious?: number | null,
>       undetected?: number | null,
>       timeout?: number | null,
>       malicious?: number | null
>     } | null
>   } | null,
>   relationships?: Record<string, any> | null,
>   links?: Record<string, any> | null
> }
> ```

***

### rescan

`ipAddresses.rescan`

Ask VirusTotal to reanalyse an IP address

**Risk:** `write`

```ts theme={null}
await corsair.virustotal.api.ipAddresses.rescan({ id: '203.0.113.10' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | The IP address to reanalyse. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type: string,
>   id: string
> }
> ```

***

## Urls

### addComment

`urls.addComment`

Comment on a URL publicly

**Risk:** `write`

```ts theme={null}
await corsair.virustotal.api.urls.addComment({ id: 'aHR0cHM6Ly9hY21lLmV4YW1wbGUvbG9naW4', text: 'Reported to the host' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | The URL identifier: the URL as unpadded base64url, which `urlId()` produces from a raw URL, or the SHA-256 `id` a URL report returns. |
| `text` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type?: comment | null,
>   id?: string | null,
>   attributes?: {
>     text?: string | null,
>     html?: string | null,
>     date?: number | null,
>     tags?: string[] | null,
>     votes?: {
>       positive?: number | null,
>       negative?: number | null,
>       abuse?: number | null
>     } | null
>   } | null,
>   links?: Record<string, any> | null
> }
> ```

***

### comments

`urls.comments`

List the comments on a URL, with cursor paging

**Risk:** `read`

```ts theme={null}
await corsair.virustotal.api.urls.comments({ id: 'aHR0cHM6Ly9hY21lLmV4YW1wbGUvbG9naW4' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | The URL identifier: the URL as unpadded base64url, which `urlId()` produces from a raw URL, or the SHA-256 `id` a URL report returns. |
| `limit` | `number` | No | Items per page. VirusTotal caps this at 40. |
| `cursor` | `string` | No | The `meta.cursor` from the previous page. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object[] \| null` | No | — |
| `meta` | `object \| null` | No | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type?: comment | null,
>   id?: string | null,
>   attributes?: {
>     text?: string | null,
>     html?: string | null,
>     date?: number | null,
>     tags?: string[] | null,
>     votes?: {
>       positive?: number | null,
>       negative?: number | null,
>       abuse?: number | null
>     } | null
>   } | null,
>   links?: Record<string, any> | null
> }[] | null
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   cursor?: string | null
> } | null
> ```

***

### get

`urls.get`

Read a URL report by the base64url identifier `urlId()` builds or the SHA-256 id a report returns; the base64url form carries the full URL to VirusTotal

**Risk:** `read`

```ts theme={null}
await corsair.virustotal.api.urls.get({ id: 'aHR0cHM6Ly9hY21lLmV4YW1wbGUvbG9naW4' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | The URL identifier: the URL as unpadded base64url, which `urlId()` builds from a raw URL, or the SHA-256 `id` a URL report returns. A raw URL will not resolve. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type?: url | null,
>   id?: string | null,
>   attributes?: {
>     url?: string | null,
>     final_url?: string | null,
>     title?: string | null,
>     first_submission_date?: number | null,
>     last_analysis_date?: number | null,
>     last_final_url?: string | null,
>     reputation?: number | null,
>     tags?: string[] | null,
>     threat_names?: string[] | null,
>     categories?: Record<string, string> | null,
>     last_analysis_results?: Record<string, any> | null,
>     last_analysis_stats?: {
>       harmless?: number | null,
>       suspicious?: number | null,
>       undetected?: number | null,
>       timeout?: number | null,
>       malicious?: number | null
>     } | null
>   } | null,
>   relationships?: Record<string, any> | null,
>   links?: Record<string, any> | null
> }
> ```

***

### rescan

`urls.rescan`

Ask VirusTotal to reanalyse a URL already submitted

**Risk:** `write`

```ts theme={null}
await corsair.virustotal.api.urls.rescan({ id: 'aHR0cHM6Ly9hY21lLmV4YW1wbGUvbG9naW4' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | The URL identifier: the URL as unpadded base64url, which `urlId()` produces from a raw URL, or the SHA-256 `id` a URL report returns. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type: string,
>   id: string
> }
> ```

***

### scan

`urls.scan`

Submit a URL for analysis; it is added to the public dataset, answers an analysis id to poll, and cannot be withdrawn

**Risk:** `write`

```ts theme={null}
await corsair.virustotal.api.urls.scan({ url: 'https://acme.example/login' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `url` | `string` | Yes | The address to scan. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   type: string,
>   id: string
> }
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.