Introduction

Endpoints

Multiple base URLs are available, segregated by geographic region. For compliance purposes, data sent to a specific region never leaves that region.

Note that URLs must include the API version, with the latest version currently at v1

Authentication

API keys are used to authenticate requests. When subscribing to Verisys Antivirus API, we create a default API key for you, and you can create amd manage additional API keys at the Verisys Licensing & Support site.

A valid API key must be sent in an X-API-Key HTTP header with every request.

Rate Limits

To ensure sufficient capacity for all API consumers, we use request rate limiting, on a per-API key basis.

The API returns HTTP code 429 when it receives too many requests, and also returns a Retry-After header, which contains the minimum number of seconds that must be waited before the API can handle another request.

For API requests that are not rate limited, the response includes headers that indicate the current state of your rate limit quota:

If you are having difficulties with limits, please feel free to contact us.

File Size Limits

The maximum permitted file sizes are shown below.

NSFW Image scanning APIs support the following image formats:

Credits

Credits Each plan comes with a set number of credits, and 1 credit is consumed when you make a request to an API endpoint that requests file scanning:

• /v1/malware/scan/*

• /v1/malware/submit/*

• /v1/nsfw/images/scan/*

• /v1/nsfw/images/submit/*

Every API response includes headers containing information about your remaining credits:

If you need more credits, you can upgrade your plan at any time, or purchase a credit addon that provides additional credits.

Versioning

This API uses versioning. A new API version is released whenever we introduce any backwards-incompatible changes to the API, such as changing a parameter name or type, or deprecating an endpoint. Previous versions will remain functional, but will be considered deprecated, and it is therefore strongly recommended to always use the latest version. When making an API request, the desired version must be used to prefix the endpoint path, for example to call v1 of the ping endpoint: https://gb1.api.av.ionxsolutions.com/v1/ping

Data Retention

Files sent to the API for Malware/NSFW scanning are only kept for the short time it takes to perform the scan, and are then immediately and permanently deleted. Files are not shared with any third parties, and are processed solely for the purposes of the request Malware/NSFW scan.

Validation

API endpoints perform validation on all input. Any request that fails validation will result in an error response with HTTP status code 422. The response body will be a ValidationProblemDetails that contains details of all validation errors.

Errors

Verisys Antivirus API uses standard HTTP response codes to indicate the success or failure of an API request. In case of an error, the response body will be a ProblemDetails that contains additional information about the error.

Webhooks

Verisys Antivirus API provides endpoints for performing both synchronous and asynchronous scans. When performing an asynchronous scan, there are two different means to later obtain the scan result:

1. Polling: repeatedly calling a Fetch Scan Result endpoint (e.g. /v1/malware/{id}, /v1/nsfw/images/{id}) until the result is available

2. Callback/webhook: we automatically contact one of your API endpoints when the result is available

If you provided a valid callback URL in your asynchronous scan request, when the scan result is available our system will automatically send a POST request to the specified URL with a ScanResult object as the payload.

Each webhook request will include an X-Api-Signature header, which contains an HMAC-256 signature computed over the payload. You can verify that webhook requests originated from the Verisys Antivirus API by computing the HMAC-256 signature and comparing it to the X-Api-Signature header. Each Verisys Antivirus API account uses a unique webhook secret for the HMAC key, which you can find at the Verisys Licensing & Support site.

Security & Privacy

All data in transit is secured by TLS.

Files submitted for scanning are stored in encrypted format (using AES-256), and are only kept for as long as is required to complete the scan - often as little as 1 second.

Verisys Antivirus API is fully compliant with GDPR. Files submitted to a particular region will never leave that region - your data will never traverse jurisdictions, allowing you to remain compliant.

Content Type Detection

When submitting files for Malware/NSFW scans, we will also detect the actual content type (the real content type can differ from that purported by the file extension) by scanning the file signature. The following content types are currently supported: