Virus and Malware Scan API by attachmentAV

Virus and Malware Scan API by attachmentAV

The attachmentAV API provides real-time virus and malware scanning powered by Sophos's industry-leading detection engine. Scan files via URL download, direct upload, multipart form, or Amazon S3 — with both synchronous and asynchronous modes. The API guarantees 100% uptime and is available across four global regions.

Base URLs

The API is available in four regional endpoints:

Region	Base URL
Europe	https://eu.developer.attachmentav.com/v1/
United States	https://us.developer.attachmentav.com/v1/
Canada	https://canada.developer.attachmentav.com/v1/
India	https://india.developer.attachmentav.com/v1/

Authentication

All requests require an API key passed via the x-api-key HTTP header. An active subscription is required.

x-api-key: YOUR_API_KEY

Endpoints

Synchronous Scan Endpoints

Method	Endpoint	Max File Size	Description
POST	/v1/scan/sync/download	200 MB	Scan a file from a remote URL
POST	/v1/scan/sync/binary	10 MB	Scan a directly uploaded binary file
POST	/v1/scan/sync/form	10 MB	Scan a file via multipart/form-data
POST	/v1/scan/sync/s3	200 MB	Scan a file from an S3 bucket

All synchronous endpoints have a 60-second timeout and return results immediately.

Asynchronous Scan Endpoints

Method	Endpoint	Max File Size	Description
POST	/v1/scan/async/download	5 GB	Async scan from a remote URL
POST	/v1/scan/async/s3	5 GB	Async scan from an S3 bucket
GET	/v1/scan/async/result	—	Retrieve async scan results (stored 24h)

Async results can be retrieved via callback URL or polling with a trace_id.

Utility Endpoints

Method	Endpoint	Description
GET	/v1/test	Validate your API key (returns 204)
GET	/v1/usage	Get remaining credits and quota
GET	/v1/whoami	Get your tenant information

Scan Response Format

{
  "status": "clean",
  "finding": null,
  "size": 12345,
  "realfiletype": "application/pdf"
}

• status — "clean", "infected", or "no" (unable to scan)
• finding — Detected malware name (only when infected)
• size — File size in bytes
• realfiletype — Actual file type detected by Sophos

JavaScript Example

import { AttachmentAV } from '@attachmentav/virus-scan-sdk-ts';

const av = new AttachmentAV({
  apiKey: 'YOUR_API_KEY',
  region: 'us'
});

// Scan a file by URL
const result = await av.scanSync({
  download_url: 'https://example.com/document.pdf'
});

console.log(result.status);  // 'clean' or 'infected'
console.log(result.finding); // malware name if infected

Python Example

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://us.developer.attachmentav.com/v1'

headers = {
    'x-api-key': API_KEY,
    'Content-Type': 'application/json'
}

# Scan a file by URL
response = requests.post(
    f'{BASE_URL}/scan/sync/download',
    headers=headers,
    json={'download_url': 'https://example.com/document.pdf'}
)

result = response.json()
print(f"Status: {result['status']}")
if result['status'] == 'infected':
    print(f"Threat: {result['finding']}")

cURL Example

# Scan a file by URL
curl -X POST 'https://us.developer.attachmentav.com/v1/scan/sync/download' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"download_url": "https://example.com/document.pdf"}'

# Upload and scan a file directly
curl -X POST 'https://us.developer.attachmentav.com/v1/scan/sync/binary' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @localfile.pdf

# Check remaining credits
curl 'https://us.developer.attachmentav.com/v1/usage' \
  -H 'x-api-key: YOUR_API_KEY'

SDKs

• JavaScript/TypeScript: npm install @attachmentav/virus-scan-sdk-ts
• Python: pip install attachmentav-virus-malware-scan-sdk
• Java: Maven dependency com.attachmentav:virus-scan-sdk:0.6.0

S3 Integration

Scan files directly from your S3 buckets by granting attachmentAV read access via a bucket policy:

curl -X POST 'https://us.developer.attachmentav.com/v1/scan/sync/s3' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"bucket": "my-bucket", "key": "uploads/document.pdf"}'

Async Scanning with Callbacks

For large files (up to 5 GB), use async scanning with a callback URL:

const response = await fetch(
  'https://us.developer.attachmentav.com/v1/scan/async/download',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      download_url: 'https://example.com/large-file.zip',
      callback_url: 'https://yourapp.com/webhook/scan-result',
      trace_id: 'upload-12345'
    })
  }
);
// Results are POSTed to your callback_url when complete

Use Cases

• File Upload Protection — Scan user-uploaded files before storing them
• Email Attachment Scanning — Check attachments for malware in real time
• Cloud Storage Security — Scan files in S3 buckets automatically
• API Gateway Integration — Add virus scanning to your API pipeline
• Compliance — Meet security requirements for handling file uploads

Get Started →

Full API Documentation →