Skip to main content

REST API Overview

The VT4AI REST API provides HTTP endpoints for integrating VirusTotal intelligence into web applications, microservices, and any system that can make HTTP requests.

Key Features​

  • 🌐 HTTP/JSON Interface: Standard REST API with OpenAPI documentation
  • 🔄 Async Operations: High-performance async handling for concurrent requests
  • 🎨 Multiple Formats: JSON, Markdown, XML, and raw output formats
  • 📊 Built-in Templates: Pre-configured filtering for AI-optimized responses
  • 🔒 API Key Authentication: Secure access control
  • 📖 Auto-Generated Docs: Interactive Swagger/OpenAPI documentation

Quick Start​

Install with API Dependencies​

pip install "vt4ai[api]"

Start the Server​

# Set your VirusTotal API key
export VT4AI_API_KEY="your_virustotal_api_key"

# Start the server
python -m vt4ai.api.server

# Or use uvicorn directly
uvicorn vt4ai.api.server:app --host 0.0.0.0 --port 8000

Access the API​

  • Base URL: http://localhost:8000
  • API Docs: http://localhost:8000/docs
  • OpenAPI Spec: http://localhost:8000/openapi.json

API Endpoints​

File Analysis​

Get File Report​

GET /api/v1/files/{file_hash}

Parameters:

  • file_hash (path): MD5, SHA1, or SHA256 hash
  • format (query): Output format (json, markdown, xml, raw)

Example:

curl "http://localhost:8000/api/v1/files/275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f?format=json" \
  -H "X-API-Key: your_virustotal_api_key"

Get File Relationships​

GET /api/v1/files/{file_hash}/relationships/{relationship}

Parameters:

  • file_hash (path): File hash
  • relationship (path): Relationship type
  • limit (query): Number of results (1-100, default: 10)
  • cursor (query): Pagination cursor

Example:

curl "http://localhost:8000/api/v1/files/abc123/relationships/contacted_domains?limit=20" \
  -H "X-API-Key: your_virustotal_api_key"

URL Analysis​

Get URL Report​

GET /api/v1/urls/analyze

Parameters:

  • url (query): URL to analyze
  • format (query): Output format

Example:

curl "http://localhost:8000/api/v1/urls/analyze?url=https://example.com&format=markdown" \
  -H "X-API-Key: your_virustotal_api_key"

Domain Analysis​

Get Domain Report​

GET /api/v1/domains/{domain}

Parameters:

  • domain (path): Domain name
  • format (query): Output format

Example:

curl "http://localhost:8000/api/v1/domains/example.com?format=json" \
  -H "X-API-Key: your_virustotal_api_key"

IP Analysis​

Get IP Report​

GET /api/v1/ips/{ip_address}

Parameters:

  • ip_address (path): IPv4 or IPv6 address
  • format (query): Output format

Example:

curl "http://localhost:8000/api/v1/ips/8.8.8.8?format=json" \
  -H "X-API-Key: your_virustotal_api_key"

Metadata Endpoints​

Get Available Templates​

GET /templates

Returns a summary of all available templates organized by object type.

Get Relationship Types​

GET /api/v1/files/relationships/types

Returns all available file relationship types with descriptions.

Authentication​

The API uses API key authentication via the X-API-Key header:

X-API-Key: your_virustotal_api_key

Environment Variable​

Set your API key as an environment variable:

export VT4AI_API_KEY="your_key_here"

Per-Request Authentication​

Pass the key in each request header:

curl -H "X-API-Key: your_key" "http://localhost:8000/api/v1/files/abc123"

Response Formats​

JSON Response (Default)​

{
  "data": {
    "file_type": "executable",
    "malicious_count": 45,
    "reputation": "malicious"
  },
  "format": "json"
}

Markdown Response​

{
  "data": "# File Report: abc123\n\n## Analysis Results\n...",
  "format": "markdown"
}

Error Response​

{
  "detail": "Error retrieving file report: Invalid hash format"
}

Status Codes​

  • 200: Success
  • 400: Bad Request (invalid parameters)
  • 401: Unauthorized (missing/invalid API key)
  • 404: Not Found (resource not found in VirusTotal)
  • 429: Rate Limit Exceeded
  • 500: Internal Server Error

Rate Limiting​

The API respects VirusTotal's rate limits:

  • Public API: 4 requests/minute
  • Premium API: Higher limits based on subscription
  • Enterprise API: Highest limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 4
X-RateLimit-Remaining: 3
X-RateLimit-Reset: 1640995200

Configuration​

Server Configuration​

# Custom host and port
uvicorn vt4ai.api.server:app --host 127.0.0.1 --port 3000

# Production deployment
uvicorn vt4ai.api.server:app --host 0.0.0.0 --port 8000 --workers 4

Environment Variables​

# Required
VT4AI_API_KEY="your_virustotal_api_key"

# Optional
VT4AI_DEFAULT_FORMAT="json"
VT4AI_MAX_WORKERS=4
VT4AI_LOG_LEVEL="INFO"

Integration Examples​

Python with requests​

import requests

def analyze_file(file_hash, api_key):
    url = f"http://localhost:8000/api/v1/files/{file_hash}"
    headers = {"X-API-Key": api_key}
    params = {"format": "json"}

    response = requests.get(url, headers=headers, params=params)
    return response.json()

JavaScript/Node.js​

async function analyzeFile(fileHash, apiKey) {
  const response = await fetch(
    `http://localhost:8000/api/v1/files/${fileHash}?format=json`,
    {
      headers: {
        'X-API-Key': apiKey
      }
    }
  );
  return await response.json();
}

cURL Scripts​

#!/bin/bash
API_KEY="your_key_here"
BASE_URL="http://localhost:8000/api/v1"

# Analyze file
curl -H "X-API-Key: $API_KEY" \
     "$BASE_URL/files/$1?format=markdown" \
     | jq -r '.data'

Performance Tips​

Concurrent Requests​

The API handles concurrent requests efficiently:

import asyncio
import aiohttp

async def analyze_multiple_files(file_hashes, api_key):
    async with aiohttp.ClientSession() as session:
        tasks = []
        for hash_value in file_hashes:
            url = f"http://localhost:8000/api/v1/files/{hash_value}"
            headers = {"X-API-Key": api_key}
            tasks.append(session.get(url, headers=headers))

        responses = await asyncio.gather(*tasks)
        return [await r.json() for r in responses]

Template Usage​

Use templates to optimize response size:

# Optimized: only essential data
curl "http://localhost:8000/api/v1/files/abc123"

# Full data: larger response
curl "http://localhost:8000/api/v1/files/abc123?format=raw"

Deployment​

Docker Deployment​

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 8000

CMD ["uvicorn", "vt4ai.api.server:app", "--host", "0.0.0.0", "--port", "8000"]

Production Considerations​

  1. Reverse Proxy: Use nginx or similar for production
  2. SSL/TLS: Enable HTTPS for security
  3. Monitoring: Set up health checks and logging
  4. Scaling: Use multiple workers for high traffic

Next Steps​