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:
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/virustotal/refs/heads/main/openapi/virustotal-yara-hunting-livehunt-api-openapi.yml