VirusTotal IoC Investigation - IP addresses API

openapi: 3.2.0
info:
  title: VirusTotal API v3 - IoC Investigation IoC Investigation…
  version: '3.0'
  description: Investigate files, URLs, IP addresses, and domains. Submit and analyse samples, retrieve reports, get comments and votes, view sandbox behaviour, traverse the relationships graph.
  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: IoC Investigation - IP addresses
  description: IoC Investigation - IP addresses
paths:
  /ip_addresses/{ip}:
    get:
      tags:
      - IoC Investigation - IP addresses
      deprecated: false
      description: Returns an IP address object.
      operationId: ipInfo
      parameters:
      - description: IP address
        in: path
        name: ip
        required: true
        schema:
          type: string
      - description: The name of your tool or service. This is required to obtain the gti_assesment data
        in: header
        name: x-tool
        required: false
        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 an IP Address Report
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /ip_addresses/{ip}/comments:
    get:
      tags:
      - IoC Investigation - IP addresses
      deprecated: false
      description: Returns a list of Comment objects.
      operationId: ipCommentsGet
      parameters:
      - description: IP address
        in: path
        name: ip
        required: true
        schema:
          type: string
      - description: Maximum number of comments to retrieve
        in: query
        name: limit
        schema:
          default: 10
          format: int32
          type: integer
      - 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 Comments on an IP Address
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - IoC Investigation - IP addresses
      deprecated: false
      description: 'With this endpoint you can post a comment for a given IP address. The body for the POST request must be the JSON representation of a comment object. Notice however that you don''t need to provide an ID for the object, as they are automatically generated for new comments.


        Any word starting with # in your comment''s text will be considered a tag, and added to the comment''s tag attribute.


        ```json Example request

        {

        "data": {

        "type": "comment",

        "attributes": {

        "text": "Lorem #ipsum dolor sit ..."

        }

        }

        }

        ```


        Returns a Comment object.'
      operationId: ipCommentsPost
      parameters:
      - description: IP address
        in: path
        name: ip
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                data:
                  default: '{"type": "comment", "attributes": {"text": "Lorem ipsum dolor sit ..."}}'
                  description: A comment object
                  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 Add a Comment to an IP Address
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /ip_addresses/{ip}/relationships/{relationship}:
    get:
      tags:
      - IoC Investigation - IP addresses
      deprecated: false
      description: This endpoint is the same as /ip_addresses/{ip}/{relationship} except it returns just the related object's IDs (and context attributes, if any) instead of returning all attributes.
      operationId: ipRelationshipsIds
      parameters:
      - description: IP address
        in: path
        name: ip
        required: true
        schema:
          type: string
      - description: Relationship name (see [table](ref:ip-object#relationships))
        in: path
        name: relationship
        required: true
        schema:
          type: string
      - description: Maximum number of related objects to retrieve
        in: query
        name: limit
        schema:
          default: '10'
          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 Object Descriptors Related to an IP Address
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /ip_addresses/{ip}/votes:
    get:
      tags:
      - IoC Investigation - IP addresses
      deprecated: false
      description: Returns a list of Vote objects.
      operationId: ipVotes
      parameters:
      - description: IP Address
        in: path
        name: ip
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                Result:
                  value: "{\n    \"data\": [\n        {\n            \"attributes\": {\n                \"date\": 1574246328,\n                \"value\": 47,\n                \"verdict\": \"harmless\"\n            },\n            \"id\": \"i-1.1.1.1-a68784ad\",\n            \"links\": {\n                \"self\": \"https://www.virustotal.com/api/v3/votes/i-1.1.1.1-a68784ad\"\n            },\n            \"type\": \"vote\"\n        },\n        {\n            \"attributes\": {\n                \"date\": 1569486791,\n                \"value\": -1,\n                \"verdict\": \"malicious\"\n            },\n            \"id\": \"i-1.1.1.1-e15e57e9\",\n            \"links\": {\n                \"self\": \"https://www.virustotal.com/api/v3/votes/i-1.1.1.1-e15e57e9\"\n            },\n            \"type\": \"vote\"\n        }\n    ],\n    \"links\": {\n        \"self\": \"https://www.virustotal.com/api/v3/ip_addresses/1.1.1.1/votes?limit=10\"\n    }\n}"
              schema:
                properties:
                  data:
                    items:
                      properties:
                        attributes:
                          properties:
                            date:
                              default: 0
                              type: integer
                            value:
                              default: 0
                              type: integer
                            verdict:
                              type: string
                          type: object
                        id:
                          type: string
                        links:
                          properties:
                            self:
                              type: string
                          type: object
                        type:
                          type: string
                      type: object
                    type: array
                  links:
                    properties:
                      self:
                        type: string
                    type: object
                type: object
          description: '200'
        '400':
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                properties: {}
                type: object
          description: '400'
      security:
      - VTApiKey: []
      summary: VirusTotal Get Votes on an IP Address
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - IoC Investigation - IP addresses
      deprecated: false
      description: 'With this endpoint you can post a vote for a given file. The body for the POST request must be the JSON representation of a vote object. Note however that you don''t need to provide an ID for the object, as they are automatically generated for new votes.


        The verdict attribute must have be either harmless or malicious.


        ```json Example request

        {

        "data": {

        "type": "vote",

        "attributes": {

        "verdict": "harmless"

        }

        }

        }

        ```


        Returns a Vote object.'
      operationId: ipVotesPost
      parameters:
      - description: IP Address
        in: path
        name: ip
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                data:
                  default: '{"type": "vote", "attributes": {"verdict": "malicious"}}'
                  description: Vote object
                  format: json
                  type: string
              required:
              - data
              type: object
      responses:
        '200':
          content:
            application/json:
              examples:
                Result:
                  value: "{\n    \"data\": {\n        \"attributes\": {\n            \"date\": 1574246672,\n            \"value\": 1,\n            \"verdict\": \"harmless\"\n        },\n        \"id\": \"i-IP-a68784ad\",\n        \"links\": {\n            \"self\": null\n        },\n        \"type\": \"vote\"\n    }\n}"
              schema:
                properties:
                  data:
                    properties:
                      attributes:
                        properties:
                          date:
                            default: 0
                            type: integer
                          value:
                            default: 0
                            type: integer
                          verdict:
                            type: string
                        type: object
                      id:
                        type: string
                      links:
                        properties:
                          self: {}
                        type: object
                      type:
                        type: string
                    type: object
                type: object
          description: '200'
        '400':
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                properties: {}
                type: object
          description: '400'
        '409':
          content:
            application/json:
              examples:
                Result:
                  value: "{\n    \"error\": {\n        \"code\": \"AlreadyExistsError\",\n        \"message\": \"User \\\"UserName\\\" already voted \\\"harmless\\\" for this ip_address\"\n    }\n}"
              schema:
                properties:
                  error:
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    type: object
                type: object
          description: '409'
      security:
      - VTApiKey: []
      summary: VirusTotal Add a Vote to an IP Address
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /ip_addresses/{ip}/{relationship}:
    get:
      tags:
      - IoC Investigation - IP addresses
      deprecated: false
      description: 'IP addresses have number of relationships to other objects. As mentioned in the Relationships section, those related objects can be retrieved by sending `GET` requests to the relationship URL.


        All available relationships are documented in the IP address API object page.'
      operationId: ipRelationships
      parameters:
      - description: IP address
        in: path
        name: ip
        required: true
        schema:
          type: string
      - description: Relationship name (see [table](ref:ip-object#relationships))
        in: path
        name: relationship
        required: true
        schema:
          type: string
      - description: Maximum number of related objects to retrieve
        in: query
        name: limit
        schema:
          default: 10
          format: int32
          type: integer
      - 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 Objects Related to an IP Address
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    VTApiKey:
      type: apiKey
      in: header
      name: x-apikey
      description: Personal VirusTotal / GTI API key. Found in the user menu of your VirusTotal account.