openapi: 3.0.3 info: title: VirusTotal API v3 - Access Control Access Control - Group Management YARA Hunting - Livehunt 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 - Livehunt description: YARA Hunting - Livehunt paths: /intelligence/hunting_notification_files: get: tags: - YARA Hunting - Livehunt deprecated: false description: "> ❗️ Important\n> \n> Hunting notifications files are no longer showed in the web interface. Use the [/api/v3/ioc_stream](https://gtidocs.virustotal.com/reference/get-objects-from-the-ioc-stream) endpoint instead to retrieve objects from IoC-Stream notifications.\n\nEach file object returned, _in addition to all the file details_, has a `context_attributes` property that contains information about the Google Threat Intelligence Hunting Livehunt notification tied to the file, this is an example:\n\n```json Example context attributes for a matching file\n\"context_attributes\": {\n \"match_in_subfile\": false,\n \"notification_date\": 1543301214,\n \"notification_id\": \"961092289288866-4582222113734656-3c7f77cc43338e14824c111671beef30\",\n \"notification_snippet\": \"00 61 64 64 41 75 64 69 6F [...]\",\n \"notification_source_key\": \"b3190c38\",\n \"notification_tags\": [\n \"bozok\",\n \"rats\",\n \"a2d2906f7ad5265165c25baed76d342b48b8bc5f4d9db6004e9e6dd72eaea4e1\"\n ],\n \"ruleset_id\": \"5706526672224256\",\n \"ruleset_name\": \"rats\",\n \"rule_name\": \"Bozok\",\n \"rule_tags\": [],\n}\n```\n\nOther than that, the `filter` parameter allows to filter the matching files according to the Google TI Hunting Livehunt notification properties. You can filter by the name of the matching rule, match date, rule namespace, ruleset or file hash. Notice however that this only works with the exact keyword, not substrings of it.\n\nFor more information check the [user's hunting_notification_files relationship](https://gtidocs.virustotal.com/reference/user-hunting_notification_files).\n" operationId: huntingNotificationFiles parameters: - description: Maximum number of notifications to retrieve in: query name: limit schema: default: '10' type: string - description: Continuation cursor in: query name: cursor schema: type: string - description: String to search with in the hunting notification tags in: query name: filter schema: type: string - description: Maximum number of notifications counted (meta.count in the response) 10,000 max in: query name: count_limit schema: default: 200 format: int32 type: integer 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 Retrieve File Objects for Livehunt Notifications x-microcks-operation: delay: 0 dispatcher: FALLBACK /intelligence/hunting_notifications: delete: tags: - YARA Hunting - Livehunt deprecated: false description: 'This endpoint deletes Google Threat Intelligence Hunting Livehunt notifications in bulk. If the `tag` parameter is specified all your notifications with the given tag will be deleted. If the `tag` parameter is not specified all your notifications will be deleted. ' operationId: deleteHuntingNotifications parameters: - description: Delete notifications with the given tag in: query name: tag 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 Delete Livehunt Notifications x-microcks-operation: delay: 0 dispatcher: FALLBACK get: tags: - YARA Hunting - Livehunt deprecated: false description: "> ❗️ Important\n> \n> Hunting notifications are no longer showed in the web interface. Use the [/api/v3/ioc_stream](https://gtidocs.virustotal.com/reference/get-objects-from-the-ioc-stream) endpoint (with `descriptors_only=true`) instead to retrieve IoC-Stream notifications.\n\n> \U0001F6A7 Retrieving matching files rather than just notifications\n> \n> This API endpoint retrieves lists of hunting notification objects, but you may be more interested in retrieving the actual file objects tied to those notifications, you have two different options to do this:\n> \n> - Ask for the file relation when retrieving the hunting notifications, this will embed the descriptor for the file in the response, which includes the file identifier. This file identifier can then be used to perform a file object lookup via the file endpoint.\n> \n> - Make use of the [hunting notification files](https://gtidocs.virustotal.com/reference/hunting_notification_files) endpoint, which returns a lists of file objects tied to your notifications, along with metadata about the hunting notification match.\n\nThis endpoint returns the notifications triggered by your own Livehunt rulesets, or by any other rule owned by somebody else and shared with you.\n\nThe `filter` parameter allows to filter the notification according to the values of certain attributes. For example you can get the notifications that are tagged as `my_rule` with `tag:my_rule`. Tags are automatically generated and include the matching file's SHA-256, the ruleset's name, and the identifier for the YARA rule matching the file.\n\nYou can also filter the notifications based on the ruleset's owner. With `owner:some_user`, you will get notifications generated by those rules that some_user shared with you. If you are interested only on those notifications triggered by your own rules, use the `owner` filter with you own user name. You can also combine multiple filters by separating them with spaces, for example: `filter=tag:my_rule owner:foo`.\n\nIn addition, it is possible to filter by the notifications date. The date parameter accepts both UTC timestamps or `%Y-%m-%d` date formats with ranges (-, +). For example, `filter=date:1626960086+` returns the notifications that were generated since `Thu 22 Jul 2021 15:21:26 CEST`, `filter=date:2021-07-22-` returns the notifications generated before July 22th, 2021 and `filter=date:2021-07-21+ date:2021-07-23-` returns notifications generated since the July 21th, 2021 and before the July 23th, 2021.\n\nThe `order` parameters control the order in which notifications are returned, you can get them by ascending date with `date+`, and by descending date with `date-`. If no order is specified they will be order by descending date.\n\nFor more information check the [Hunting Notification](https://gtidocs.virustotal.com/reference/hunting-notification-object) API object documentation.\n" operationId: listHuntingNotifications parameters: - description: Maximum number of notifications to retrieve in: query name: limit schema: default: '10' type: string - description: Return the notifications matching the given criteria only in: query name: filter schema: type: string - description: Continuation cursor in: query name: cursor schema: type: string - description: Maximum number of notifications counted (meta.count in the response) 10,000 max in: query name: count_limit schema: default: 200 format: int32 type: integer 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 Livehunt Notifications x-microcks-operation: delay: 0 dispatcher: FALLBACK /intelligence/hunting_notifications/{id}: delete: tags: - YARA Hunting - Livehunt deprecated: false description: VirusTotal Delete a Livehunt Notification operationId: deleteHuntingNotification parameters: - description: Notification identifier 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' security: - VTApiKey: [] summary: VirusTotal Delete a Livehunt Notification x-microcks-operation: delay: 0 dispatcher: FALLBACK get: tags: - YARA Hunting - Livehunt deprecated: false description: VirusTotal Get a Livehunt Notification Object operationId: getHuntingNotification parameters: - description: Notification identifier 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' security: - VTApiKey: [] summary: VirusTotal Get a Livehunt Notification Object x-microcks-operation: delay: 0 dispatcher: FALLBACK /intelligence/hunting_rulesets: delete: tags: - YARA Hunting - Livehunt deprecated: false description: 'This API call deletes all rulesets owned by the user and removes the user from the list of editors in rules shared with them. This operation is asynchronous: the handler launches a background job and returns immediately. This API endpoint returns a [Operation](https://gtidocs.virustotal.com/reference/operation-object) object. ' operationId: deleteAllHuntingRulesets parameters: - description: Since this is a very destructive operation, this additional header must be set to your username. in: header name: x-confirm-delete required: true schema: type: string responses: '200': content: application/json: examples: Result: value: '' description: '200' '400': content: application/json: examples: Result: value: "{\n \"error\": {\n \"code\": \"BadRequestError\",\n \"message\": \"Send a x-confirm-delete header with your username as a confirmation\"\n }\n}" schema: properties: error: properties: code: type: string message: type: string type: object type: object description: '400' security: - VTApiKey: [] summary: VirusTotal Remove All Livehunt Rulesets x-microcks-operation: delay: 0 dispatcher: FALLBACK get: tags: - YARA Hunting - Livehunt deprecated: false description: "This endpoint returns the Google Threat Intelligence Hunting Livehunt rulesets viewable by the user making the request. A ruleset is viewable by a user either if it was created by the user or if it was shared with him by someone else. This endpoint is equivalent to `GET /users/{user}/hunting_rulesets`, where `{user}` is the username of the user owning the API key. In fact, if you look carefully at the example response below you'll notice that the `self` and `next` links do not point to `/intelligence/hunting_rulesets` but to `/users/{user}/hunting_rulesets`\n\n```json Example response\n{\n \"data\": [\n {\n \"type\": \"hunting_ruleset\",\n \"id\": \"{id}\",\n \"links\": {\n \t\"self\": \"https://www.virustotal.com/api/v3/intelligence/hunting_rulesets/{id}\"\n },\n \"attributes\": {\n \"creation_date\": 1523635880,\n \"enabled\": true,\n \"limit\": 1000,\n \"modification_date\": 1525263069,\n \"name\": \"foo\",\n \"notification_emails\": [],\n \"rules\": \"rule foo {condition: false}\"\n }\n },\n { .. ruleset 2 .. },\n { .. ruleset 3 .. },\n { .. ruleset 4 .. },\n ],\n \"meta\": {\n \"cursor\": \"Cu0FCsACCpIC9xuRl9v...\"\n },\n \"links\": {\n \"self\": \"https://www.virustotal.com/api/v3/users/{user}/hunting_rulesets\",\n \"next\": \"https://www.virustotal.com/api/v3/users/{user}/hunting_rulesets?cursor=Cu0FCsACCpIC9xuRl9v...\"\n }\n}\n```\n\nThe `filter` parameter allows to filter the rulesets according to the values of certain attributes. For example you can get only the enabled rulesets with `enabled:true`. With `name:foo` and `rules:foo` you can search for rulesets having the word \"foo\" in their names or in the YARA rules respectively. Notice however that this only works with full words (words delimited by non-alphanumeric characters), if the ruleset's name is \"foobar\" it won't appear if you filter with `name:foo`. You can also filter the rulesets with the same tag, by using for example `filter=tag:auto`.\n\nYou can combine multiple filters separating them with spaces, for example: `filter=enabled:true name:foo`.\n\nThe `order` parameters control the order in which rulesets are returned, accepted orders are: `name`, `creation_date` and `modification_date`. You can prepend `+` and `-` suffixes to specify ascending and descending orders (examples: `name-`, `creation_date+`, ). If not suffix is specified the order is ascending by default.\n" operationId: listHuntingRulesets parameters: - description: Maximum number of rulesets to retrieve in: query name: limit schema: default: 10 format: int32 type: integer - description: Return the rulesets matching the given criteria only in: query name: filter schema: type: string - description: Sort order in: query name: order schema: type: string - description: Continuation cursor in: query name: cursor 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 Get Livehunt Rulesets x-microcks-operation: delay: 0 dispatcher: FALLBACK post: tags: - YARA Hunting - Livehunt deprecated: false description: "This endpoint creates a new Google Threat Intelligence Hunting Livehunt ruleset. The request's body must have the following structure:\n\n```json Example request\n{\n \"data\": {\n \"type\": \"hunting_ruleset\",\n \"attributes\": {\n \"name\": \"foobar\",\n \"enabled\": true,\n \"limit\": 100,\n \"rules\": \"rule foobar { strings: $ = \\\"foobar\\\" condition: all of them }\",\n \"notification_emails\": [\"wcoyte@acme.com\", \"rrunner@acme.com\"],\n \"match_object_type\": \"file\"\n }\n }\n}\n```\n\nUse the `match_object_type` to specify the expected entity kind to match with this ruleset. Allowed values are `file`, `url`, `domain` and `ip`.\n\nThe `name` and `rules` attributes are required, the remaining ones are optional.\n\n```json Example response\n{\n \"type\": \"hunting_ruleset\",\n \"id\": \"{id}\",\n \"links\": {\n \"self\": \"https://www.virustotal.com/api/v3/intelligence/hunting_ruleset/{id}\"\n },\n \"data\": {\n \"attributes\": {\n \"name\": \"foobar\",\n \"enabled\": true,\n \"limit\": 100,\n \"creation_date\": 1521016318,\n \"modification_date\": 1521016318,\n \"number_of_rules\": 1,\n \"rules\": \"rule foobar { strings: $ = \\\"foobar\\\" condition: all of them }\",\n \"notification_emails\": [\"notifications@acme.com\"],\n \"match_object_type\": \"file\"\n }\n }\n}\n```\n" operationId: createHuntingRuleset parameters: [] requestBody: content: application/json: schema: properties: data: default: '{ "type": "hunting_ruleset", "attributes": { "name": "Test ruleset", "enabled": true, "limit": 100, "rules": "rule foobar { strings: $ = \"foobar\" condition: all of them }", "notification_emails": [], "match_object_type": "file" } }' description: A Malware Hunting ruleset format: json type: string required: - data type: object security: - VTApiKey: [] summary: VirusTotal Create a New Livehunt Ruleset responses: '200': description: Successful VirusTotal API response. content: application/json: schema: $ref: '#/components/schemas/DataEnvelope' '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' x-microcks-operation: delay: 0 dispatcher: FALLBACK /intelligence/hunting_rulesets/{id}: delete: tags: - YARA Hunting - Livehunt deprecated: false description: VirusTotal Delete a Livehunt Ruleset operationId: deleteHuntingRuleset parameters: - description: Ruleset identifier 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' security: - VTApiKey: [] summary: VirusTotal Delete a Livehunt Ruleset x-microcks-operation: delay: 0 dispatcher: FALLBACK get: tags: - YARA Hunting - Livehunt deprecated: false description: 'Returns a [Hunting Ruleset](https://gtidocs.virustotal.com/reference/hunting-ruleset-object) object. ' operationId: getHuntingRuleset parameters: - description: Ruleset identifier 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' security: - VTApiKey: [] summary: VirusTotal Get a Livehunt Ruleset x-microcks-operation: delay: 0 dispatcher: FALLBACK patch: tags: - YARA Hunting - Livehunt deprecated: false description: "```json Example request\n{\n \"data\": {\n \"type\": \"hunting_ruleset\",\n \"id\": \"{id}\",\n \"attributes\": {\n \"enabled\": true,\n \"limit\": 10,\n \"name\": \"bar\",\n \"notification_emails\": [\"notifications@acme.com\"],\n \"rules\": \"rule foo {condition: false}\"\n }\n }\n}\n```\n\nReturns the updated [Hunting Ruleset](https://gtidocs.virustotal.com/reference/hunting-ruleset-object) object.\n" operationId: modifyHuntingRuleset parameters: - description: Ruleset identifier in: path name: id required: true schema: type: string requestBody: content: application/json: schema: properties: data: description: A Hunting Ruleset object format: json type: string required: - data type: object 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 Update a Livehunt Ruleset x-microcks-operation: delay: 0 dispatcher: FALLBACK /intelligence/hunting_rulesets/{id}/relationships/editors: post: tags: - YARA Hunting - Livehunt deprecated: false description: VirusTotal Grant Livehunt Ruleset Edit Permissions for a User or Group operationId: editHuntingRulesetRelationship parameters: - description: Ruleset identifier in: path name: id required: true schema: type: string requestBody: content: application/json: schema: properties: data: description: A list of user/groups to be added as editors or set as owners of the ruleset format: json type: string type: object 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 Grant Livehunt Ruleset Edit Permissions for a User or Group x-microcks-operation: delay: 0 dispatcher: FALLBACK /intelligence/hunting_rulesets/{id}/relationships/editors/{user_or_group_id}: delete: tags: - YARA Hunting - Livehunt deprecated: false description: VirusTotal Revoke Livehunt Ruleset Edit Permission from a User or Group operationId: deleteHuntingRulesetEditor parameters: - description: Ruleset identifier in: path name: id required: true schema: type: string - description: User or group ID in: path name: user_or_group_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' security: - VTApiKey: [] summary: VirusTotal Revoke Livehunt Ruleset Edit Permission from a User or Group x-microcks-operation: delay: 0 dispatcher: FALLBACK get: tags: - YARA Hunting - Livehunt deprecated: false description: "This endpoint returns true if the user has editing access to the Hunting ruleset.\n\n```json Response example\n{\n \"data\": true\n}\n```\n" operationId: checkUserHuntingRulesetEditor parameters: - description: Ruleset identifier in: path name: id required: true schema: type: string - description: User or group ID in: path name: user_or_group_id required: true schema: type: string responses: '200': content: application/json: examples: Result: value: "{\n \"data\": true\n}" schema: properties: data: default: true type: boolean type: object 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' security: - VTApiKey: [] summary: VirusTotal Check if a User or Group is a Livehunt Ruleset Editor x-microcks-operation: delay: 0 dispatcher: FALLBACK /intelligence/hunting_rulesets/{id}/relationships/owner: post: tags: - YARA Hunting - Livehunt deprecated: false description: 'Note: The new owner must be a member of the same group the ruleset was created with. ' operationId: transferLivehuntRulesetToAnotherUser parameters: - description: Ruleset identifier in: path name: id required: true schema: type: string requestBody: content: application/json: schema: properties: data: description: A user object descriptor format: json type: string type: object 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 Transfer Livehunt Ruleset to Another User x-microcks-operation: delay: 0 dispatcher: FALLBACK /intelligence/hunting_rulesets/{id}/relationships/{relationship}: get: tags: - YARA Hunting - Livehunt deprecated: false description: 'Same as [/hunting_rulesets/{id}/{relationships}](https://gtidocs.virustotal.com/reference/get-hunting-ruleset-full-relationships) except it returns just the related object''s descriptor (and context attributes, if any) instead of returning all attributes. ' operationId: getHuntingRulesetRelationship parameters: - description: Ruleset identifier in: path name: id required: true schema: type: string - description: Relationship name (see [table](ref:hunting-ruleset-object#relationships)) in: path name: relationship 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 Get Object Descriptors Related to a Livehunt Ruleset x-microcks-operation: delay: 0 dispatcher: FALLBACK /intelligence/hunting_rulesets/{id}/{relationship}: get: tags: - YARA Hunting - Livehunt deprecated: false description: "Hunting Rulesets objects have relationships to other objects. As mentioned in the [Relationships](https://gtidocs.virustotal.com/reference/relationships) section, those related objects can be retrieved by sending `GET` requests to the relationship URL. \n\nThe relationships supported by Hunting Rulesets objects are documented in the [Hunting Rulesets](https://gtidocs.virustotal.com/reference/hunting-ruleset-object#relationships) API object page.\n" operationId: getHuntingRulesetFullRelationships parameters: - description: Ruleset identifier in: path name: id required: true schema: type: string - description: Relationship name (see [table](ref:hunting-ruleset-object#relationships)) in: path name: relationship 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 Get Objects Related to a Livehunt Ruleset x-microcks-operation: delay: 0 dispatcher: FALLBACK components: schemas: DataEnvelope: type: object description: Successful response envelope. The shape of `data` depends on the endpoint. properties: data: description: Endpoint-specific payload — usually a VirusTotal object or list of objects. example: {} meta: type: object description: Optional metadata about the response (cursors, counts, etc.). additionalProperties: true links: type: object description: Optional pagination links. properties: next: type: string format: uri description: URL to the next page of results. self: type: string format: uri description: URL of the current page. additionalProperties: true required: - data 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.