openapi: 3.0.3
info:
  title: VirusTotal API v3 - Access Control Access Control - Group Management IoC Investigation - IP addresses 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: 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](https://gtidocs.virustotal.com/reference/ip-object) 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](https://gtidocs.virustotal.com/reference/comment-object) 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.\n\nAny word starting with # in your comment's text will be considered a tag, and added to the comment's tag attribute.\n\n```json Example request\n{\n  \"data\": {\n    \"type\": \"comment\",\n    \"attributes\": {\n    \t\"text\": \"Lorem #ipsum dolor sit ...\"\n    }\n  }\n}\n```\n\nReturns a [Comment](https://gtidocs.virustotal.com/reference/comment-object) object.\n"
      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}](https://gtidocs.virustotal.com/reference/ip-relationships) 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](https://gtidocs.virustotal.com/reference/vote-object) 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](https://gtidocs.virustotal.com/reference/vote-object). Note however that you don't need to provide an ID for the object, as they are automatically generated for new votes.\n\nThe verdict attribute must have be either harmless or malicious.\n\n```json Example request\n{\n  \"data\": {\n    \"type\": \"vote\",\n    \"attributes\": {\n    \t\"verdict\": \"harmless\"\n    }\n  }\n}\n```\n\nReturns a [Vote](https://gtidocs.virustotal.com/reference/vote-object) object.\n"
      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](https://gtidocs.virustotal.com/reference/relationships) section, those related objects can be retrieved by sending `GET` requests to the relationship URL. \n\nAll available relationships are documented in the [IP address](https://gtidocs.virustotal.com/reference/ip-object) API object page.\n"
      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.