openapi: 3.0.3
info:
  title: VirusTotal API v3 - Access Control Access Control - Group Management IoC Investigation - URLs 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 - URLs
  description: IoC Investigation - URLs
paths:
  /urls:
    post:
      summary: VirusTotal Scan URL
      description: 'This returns an [Analysis](https://gtidocs.virustotal.com/reference/analyses-object) ID. The analysis can be retrieved by using the [Analysis](https://gtidocs.virustotal.com/reference/analysis) endpoint.

        '
      operationId: scanUrl
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  description: URL to scan
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
      deprecated: false
      security:
      - VTApiKey: []
      tags:
      - IoC Investigation - URLs
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /urls/{id}:
    get:
      tags:
      - IoC Investigation - URLs
      deprecated: false
      description: '> 📘

        >

        > See [URL identifiers](https://gtidocs.virustotal.com/reference/urls#url-identifiers) from more information about how to generate a valid URL identifier for a URL.


        Returns a [URL](https://gtidocs.virustotal.com/reference/url-object) object.

        '
      operationId: urlInfo
      parameters:
      - description: URL identifier or base64 representation of URL to scan (w/o padding)
        in: path
        name: id
        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 a URL Report
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /urls/{id}/analyse:
    post:
      tags:
      - IoC Investigation - URLs
      deprecated: false
      description: "> \U0001F4D8 See [URL identifiers](https://gtidocs.virustotal.com/reference/urls#url-identifiers) from more information about how to generate a valid URL identifier for a URL.\n\nReturns a [Analysis](https://gtidocs.virustotal.com/reference/analyses-object) object descriptor which can be used in the [GET/analyses/{id}](https://gtidocs.virustotal.com/reference/analysis) API endpoint to get further information about the analysis status.\n\n```json Example response\n{\n    \"data\": {\n        \"id\": \"u-a354494a73382ea0b4bc47f4c9e8d6c578027cd4598196dc88f05a22b5817293-1604933101\",\n        \"type\": \"analysis\"\n    }\n}\n```\n"
      operationId: urlsAnalyse
      parameters:
      - description: URL 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 Request a URL Rescan (re-analyze)
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /urls/{id}/comments:
    get:
      tags:
      - IoC Investigation - URLs
      deprecated: false
      description: "Returns a list of [Comment](https://gtidocs.virustotal.com/reference/comments) objects.  \nCheck comments done in VT Community regarding a specific URL.\n\n> \U0001F4D8 See [URL identifiers](https://gtidocs.virustotal.com/reference/urls#url-identifiers) from more information about how to generate a valid URL identifier for a URL.\n\n- `data`: list of (\"comment\" objects)[ref:comment-object].\n- `links`: contains \"self\" with a reference to this group of comments and \"next\", with a reference to the next group.\n- `cursor`: contains the cursor token used to access the next group of comments.\n"
      operationId: urlsCommentsGet
      parameters:
      - description: URL identifier
        in: path
        name: id
        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 a URL
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - IoC Investigation - URLs
      deprecated: false
      description: "> \U0001F4D8 See [URL identifiers](https://gtidocs.virustotal.com/reference/urls#url-identifiers) from more information about how to generate a valid URL identifier for a URL.\n\nWith this endpoint you can post a comment for a given URL. 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/comments) object.\n"
      operationId: urlsCommentsPost
      parameters:
      - description: URL identifier
        in: path
        name: id
        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
              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 Add a Comment on a URL
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /urls/{id}/relationships/{relationship}:
    get:
      tags:
      - IoC Investigation - URLs
      deprecated: false
      description: 'This endpoint is the same as [/urls/{id}/{relationship}](https://gtidocs.virustotal.com/reference/relationships) except it returns just the related object''s IDs (and context attributes, if any) instead of returning all attributes.

        '
      operationId: urlsRelationshipsIds
      parameters:
      - description: URL ID
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Relationship name (see [table](ref:url-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'
      summary: VirusTotal Get Object Descriptors Related to a URL
      security:
      - VTApiKey: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /urls/{id}/votes:
    get:
      tags:
      - IoC Investigation - URLs
      deprecated: false
      description: '> 📘 See [URL identifiers](https://gtidocs.virustotal.com/reference/urls#url-identifiers) from more information about how to generate a valid URL identifier for a URL.


        Returns a list of [Vote](https://gtidocs.virustotal.com/reference/vote-object) objects.

        '
      operationId: urlsVotesGet
      parameters:
      - description: URL identifier
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Maximum number of votes 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 Votes on a URL
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - IoC Investigation - URLs
      deprecated: false
      description: "> \U0001F4D8 See [URL identifiers](https://gtidocs.virustotal.com/reference/urls#url-identifiers) from more information about how to generate a valid URL identifier for a URL.\n\nWith this endpoint you can post a vote for a given URL. The body for the `POST` request must be the JSON representation of a vote object. Notice 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: urlsVotesPost
      parameters:
      - description: URL identifier
        in: path
        name: id
        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: '{}'
              schema:
                properties: {}
                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 \\\"malicious\\\" for this url\"\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 on a URL
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /urls/{id}/{relationship}:
    get:
      tags:
      - IoC Investigation - URLs
      deprecated: false
      description: "> \U0001F4D8 See [URL identifiers](https://gtidocs.virustotal.com/reference/urls#url-identifiers) from more information about how to generate a valid URL identifier for a URL.\n\nURL objects have number of relationships to other URLs and 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 URL objects are documented in the [URL](https://gtidocs.virustotal.com/reference/url-object) API object page.\n"
      operationId: urlsRelationships
      parameters:
      - description: URL identifier
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Relationship name (see [table](ref:url-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 a URL
      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.