openapi: 3.0.3 info: title: VirusTotal API v3 - Access Control Access Control - Group Management YARA Hunting - IoC Stream API version: '3.0' description: Manage users, groups, service accounts, API quotas, and overall account usage in VirusTotal / Google Threat Intelligence. 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: YARA Hunting - IoC Stream description: YARA Hunting - IoC Stream paths: /ioc_stream: delete: tags: - YARA Hunting - IoC Stream deprecated: false description: 'Uses the same filters than the IoC Stream ([GET /ioc_stream](https://gtidocs.virustotal.com/reference/get-objects-from-the-ioc-stream)) to delete all the matching notifications. ' operationId: deleteNotificationsFromTheIocStream parameters: - description: Filter string in: query name: filter schema: type: string responses: '200': content: application/json: examples: Result: value: '' description: '200' '429': content: application/json: examples: Result: value: "{\n \"error\": {\n \"code\": \"TooManyRequests\",\n \"message\": \"Notifications already being deleted. Depending on volume this may take a while.\"\n}" description: '429' summary: VirusTotal Delete Notifications from the IoC Stream security: - VTApiKey: [] x-microcks-operation: delay: 0 dispatcher: FALLBACK get: tags: - YARA Hunting - IoC Stream deprecated: false description: "The IoC stream endpoint returns different types of objects (files, URLs, domains, IP addresses) coming from multiple origins (you can restrict the returned types by using the filters explained below). In addition, depending on the origin of the notification there will be different context attributes added to these objects.\n\nThe possible context attributes in IoC Stream objects are:\n\n- `notification_id`: \\<_string_> Always present. This string identifies the notification, and can be used to retrieve the notification individually (by using [GET /ioc_stream_notifications/{id}](https://gtidocs.virustotal.com/reference/get-an-ioc-stream-notification)) or to delete it ([DELETE /ioc_stream_notifications/{id}](https://gtidocs.virustotal.com/reference/delete-an-ioc-stream-notification)).\n- `notification_date`: \\<_int_> Always present. Date when the notification was created (UTC timestamp).\n- `origin`: \\<_string_> Always present. The notification's origin. In the case of Livehunt or Retrohunt the origin is `hunting`.\n- `sources`: \\<_list of dictionaries_> Always present. The different sources associated to the notification. In the case of Livehunt the only source is always the hunting ruleset that triggered the notification.\n- `tags`: \\<_list of strings_> List of notification's tags (if any). These tags can be used to filter the objects by using the `notification_tag:` filter.\n- `hunting_info`: \\<_dictionary_> Only present for notifications of `hunting` origin. It contains additional contextual information from Livehunt. Its structure is the following:\n - `rule_name`: \\<_string_> matched rule name.\n - `rule_tags`: \\<_list of strings_> matched rule tags.\n - `snippet`: \\<_string_> matched contents inside the file as hexdump. Contains `begin_highlight` and `end_highlight` substrings to indicate the part of the file that produced the match and give additional context about surrounding bytes in the match.\n - `source_country`: \\<_string_> country where the matched file was uploaded from.\n - `source_key`: \\<_string_> unique identifier for the source in ciphered form.\n\nAllowed filters with examples (they can be combined in the same filter string):\n\n- `date:2023-02-07T10:00:00+`: Returns objects from notifications generated after 2023-02-07T10:00:00 (UTC)\n- `date:2023-02-07-`: Returns objects from notifications generated before 2023-03-07T00:00:00 (UTC)\n- `origin:hunting`: Returns objects from notifications coming from Livehunt. Allowed values: `hunting, subscriptions`.\n- `entity_id:objectId`: Return objects whose ID is `objectId`\n- `entity_type:file`: Return only file objects. Allowed values: `file, domain, url, ip_address`\n- `source_type:hunting_ruleset`: The type of source object that triggered the notification. Allowed values: `hunting_ruleset, retrohunt_job, collection, threat_actor`.\n- `source_id:objectId`: The ID of the source object that triggered the notification. In the case of hunting the notification's source object ID corresponds to the hunting ruleset's ID.\n- `notification_tag:ruleName`: Notifications with `ruleName` in their tags. In the case of notifications coming from Livehunt there are several tags in each notification, like the rule name or the username of the ruleset's owner.\n\nAllowed orders:\n\n- `date-` (default): Sorts by most recent notifications first.\n- `date+`: Sorts by oldest notification first.\n" operationId: getObjectsFromTheIocStream parameters: - description: Number of objects to retrieve (max 40) in: query name: limit schema: default: 10 format: int32 type: integer - description: The response returns only objects descriptors instead of whole VT objects in: query name: descriptors_only schema: default: false type: boolean - description: Filter string in: query name: filter schema: type: string - description: Continuation cursor in: query name: cursor schema: type: string - description: Sort order in: query name: order schema: type: string responses: '200': content: application/json: examples: Result: value: "{\n\t\"meta\": {\n\t\t\"cursor\": \"Ck0KEQoEZGF0ZRIJCLnz1ObJg_0CEjRqEXN-dmlydXN0b3RhbGNsb3Vkch8LEhVJT0NTdHJlYW1Ob3RpZmljYXRpb24YsK2w2iEMGAAgAQ==\"\n\t},\n\t\"data\": [\n\t\t{\n\t\t\t\"type\": \"file\",\n\t\t\t\"id\": \"c9c4ee34d9c9f769f884f720e1d37ce1e864aae1be81a4a274bb1a88704cb11c\",\n\t\t\t\"context_attributes\": {\n\t\t\t\t\"notification_id\": \"9047905968\",\n\t\t\t\t\"origin\": \"hunting\",\n\t\t\t\t\"hunting_info\": {\n\t\t\t\t\t\"rule_name\": \"vulnerability_weaponization\"\n\t\t\t\t},\n\t\t\t\t\"tags\": [\n\t\t\t\t\t\"c9c4ee34d9c9f769f884f720e1d37ce1e864aae1be81a4a274bb1a88704cb11c\",\n\t\t\t\t\t\"vulnerability_weaponization\",\n\t\t\t\t\t\"ransomware\"\n\t\t\t\t],\n\t\t\t\t\"sources\": [\n\t\t\t\t\t{\n\t\t\t\t\t\t\"type\": \"hunting_ruleset\",\n\t\t\t\t\t\t\"id\": \"7926136120\",\n\t\t\t\t\t\t\"label\": \"Ransomware\"\n\t\t\t\t\t}\n\t\t\t\t],\n\t\t\t\t\"notification_date\": 1675778611\n\t\t\t}\n\t\t}\n\t],\n\t\"links\": {\n\t\t\"self\": \"https://www.virustotal.com/api/v3/ioc_stream?limit=1&filter=date%3A2023-02-07T10%3A00%3A00%2B%20entity_type%3Afile%20origin%3Ahunting&descriptors_only=true\",\n\t\t\"next\": \"https://www.virustotal.com/api/v3/ioc_stream?filter=date%3A2023-02-07T10%3A00%3A00-+entity_type%3Afile+origin%3Ahunting&cursor=Ck0KEQoEZGF0ZRIJCLnz1ObJg_0CEjRqEXN-dmlydXN0b3RhbGNsb3Vkch8LEhVJT0NTdHJlYW1Ob3RpZmljYXRpb24YsK2w2iEMGAAgAQ%3D%3D&limit=1&descriptors_only=true\"\n\t}\n}" schema: properties: data: items: properties: context_attributes: properties: hunting_info: properties: rule_name: type: string type: object notification_date: default: 0 type: integer notification_id: type: string origin: type: string sources: items: properties: id: type: string label: type: string type: type: string type: object type: array tags: items: type: string type: array type: object id: type: string type: type: string type: object type: array links: properties: next: type: string self: type: string type: object meta: properties: cursor: type: string type: object type: object description: '200' '400': content: application/json: examples: Result: value: "{\n\t\"error\": {\n\t\t\"message\": \"origin \\\"notHunting\\\" is not valid. Valid origins are: hunting,subscriptions\",\n\t\t\"code\": \"BadRequestError\"\n\t}\n}" schema: properties: error: properties: code: type: string message: type: string type: object type: object description: '400' summary: VirusTotal Get Objects from the IoC Stream security: - VTApiKey: [] x-microcks-operation: delay: 0 dispatcher: FALLBACK /ioc_stream_notifications/{id}: delete: tags: - YARA Hunting - IoC Stream deprecated: false description: 'Deletes an IoC Stream notification. ' operationId: deleteAnIocStreamNotification parameters: - description: The ID of the IoC Stream notification in: path name: id required: true schema: type: string responses: '200': content: application/json: examples: Result: value: '' description: '200' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Object not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limit or quota exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: VirusTotal Delete an IoC Stream Notification security: - VTApiKey: [] x-microcks-operation: delay: 0 dispatcher: FALLBACK get: tags: - YARA Hunting - IoC Stream deprecated: false description: 'Returns an IoC Stream notification. ' operationId: getAnIocStreamNotification parameters: - description: The ID of the IoC Stream notification in: path name: id 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' summary: VirusTotal Get an IoC Stream Notification security: - VTApiKey: [] x-microcks-operation: delay: 0 dispatcher: FALLBACK components: schemas: Error: type: object description: Standard VirusTotal API error envelope. properties: code: type: string description: Machine-readable error code. example: NotFoundError message: type: string description: Human-readable error message. example: Resource not found required: - code - message ErrorResponse: type: object description: Error response envelope returned by the VirusTotal API. properties: error: $ref: '#/components/schemas/Error' required: - error securitySchemes: VTApiKey: type: apiKey in: header name: x-apikey description: Personal VirusTotal / GTI API key. Found in the user menu of your VirusTotal account.