VirusTotal YARA Hunting - IoC Stream API

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.