openapi: 3.0.3
info:
  title: VirusTotal API v3 - Access Control Access Control - Group Management Access Control - User Management 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: Access Control - User Management
  description: Access Control - User Management
paths:
  /users/{id}:
    delete:
      tags:
      - Access Control - User Management
      deprecated: false
      description: 'This request deletes a given user. A user account can only be deleted by its owner, a 403 error is returned otherwise.


        An additional `x-user-password` header is required, which is used as confirmation.

        '
      operationId: deleteUserId
      parameters:
      - description: User ID or API key
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: User password, needed as confirmation.
        in: header
        name: x-user-password
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            text/plain:
              examples:
                Result:
                  value: ''
          description: '200'
        '403':
          content:
            application/json:
              examples:
                Result:
                  value: "{\n  \"error\": {\n    \"code\": \"ForbiddenError\",\n    \"message\": \"You are not authorized to perform the requested operation\"\n  }\n}"
              schema:
                properties:
                  error:
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    type: object
                type: object
          description: '403'
      security:
      - VTApiKey: []
      summary: VirusTotal Delete a User
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      tags:
      - Access Control - User Management
      deprecated: false
      description: 'This endpoint retrieves information about a user, including the privileges and quotas associated to the user. The user can be retrieved either by user ID or by API key, but the former only works if the requester is the user himself or an administrator of a group the user belongs to.


        Returns an [User](https://gtidocs.virustotal.com/reference/user-object) object.

        '
      operationId: user
      parameters:
      - description: User ID or API key
        in: path
        name: id
        required: true
        schema:
          type: string
      security:
      - VTApiKey: []
      summary: VirusTotal Get a User Object
      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
    patch:
      tags:
      - Access Control - User Management
      deprecated: false
      description: 'This request accepts a JSON body containing the user attributes to update. Attributes not present in the request body remain the same. It returns the updated [User](https://gtidocs.virustotal.com/reference/user-object) object.

        '
      operationId: patchUserId
      parameters:
      - description: User ID or API key
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                data:
                  description: User object
                  format: json
                  type: string
              required:
              - data
              type: object
      responses:
        '200':
          content:
            text/plain:
              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 Update a User Object
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{id}/relationships/{relationship}:
    get:
      tags:
      - Access Control - User Management
      deprecated: false
      description: 'This endpoint is the same as [/users/{id}/{relationship}](https://gtidocs.virustotal.com/reference/users-relationships) except it returns just the related object''s IDs (and context attributes, if any) instead of returning all attributes.

        '
      operationId: getUsersRelationshipsIds
      parameters:
      - description: Username or API key
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Relationship name (see [table](ref:user-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 Object Descriptors Related to a User
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{id}/{relationship}:
    get:
      tags:
      - Access Control - User Management
      deprecated: false
      description: 'Users are related to other objects in our dataset. As mentioned in the [Relationships](https://gtidocs.virustotal.com/reference/relationships) section, those related objects can be retrieved by sending `GET` requests to this API endpoint.


        Some relationships are only accessible to their account''s owners and their group''s admins.


        The supported relationships are documented in the [User](https://gtidocs.virustotal.com/reference/user-object#relationships) API object page.

        '
      operationId: usersRelationships
      parameters:
      - description: Username or API key
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Relationship name (see [table](ref:user-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 User
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    DataEnvelope:
      type: object
      description: Successful response envelope. The shape of `data` depends on the endpoint.
      properties:
        data:
          description: Endpoint-specific payload — usually a VirusTotal object or list of objects.
          example: {}
        meta:
          type: object
          description: Optional metadata about the response (cursors, counts, etc.).
          additionalProperties: true
        links:
          type: object
          description: Optional pagination links.
          properties:
            next:
              type: string
              format: uri
              description: URL to the next page of results.
            self:
              type: string
              format: uri
              description: URL of the current page.
          additionalProperties: true
      required:
      - data
    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.