API (self-hosted on AWS): API Definition

ActionHTTP MethodHTTP Resource / Path
Scan URL and return scan resultPOST/api/v1/scan/sync/download
Scan file and return scan resultPOST/api/v1/scan/sync/binary
Scan file and return scan resultPOST/api/v1/scan/sync/form
Scan S3 object and return scan resultPOST/api/v1/scan/sync/s3

Authentication (#)

Accessing the API requires an API key. Pass the API key via an Authorization HTTP header.

The following snippet shows the HTTP header.

Authorization: Bearer <API_KEY_PLACEHOLDER>

Replace <API_KEY_PLACEHOLDER> with one of the API keys from the ApiKeys configuration parameter.

Domain name (#)

To get the domain name of your attachmentAV API installation:

  • If the DnsConfiguration configuration parameter is set to AUTO_ROUTE_53, check the DomainName configuration parameter.
  • If the DnsConfiguration configuration parameter is set to MANUAL, check your manual DNS configuration.

Actions (#)

POST /api/v1/scan/sync/download (#)

Download a file from a remote location (HTTP/HTTPS), scan the file, and return the scan result.

The request body is JSON formatted with these properties:

  • download_url (string): URL to download and scan via HTTP(S) GET.
  • download_headers: (object, optional): Headers to send when downloading the file.

The response status code is 200, and the body is JSON formatted with these properties:

  • status (string (clean, infected, no)): The scan result.
  • finding (string, optional): For infected files, the type of virus/malware that was detected.
  • size (number, optional): The file size in bytes.
  • realfiletype (string, optional): The Real File Type detected by the Sophos engine (requires version >= 1.2.0).

Example:

Replace <API_KEY_PLACEHOLDER> with one of the API keys from the ApiKeys configuration parameter. Replace attachmentav.yourcompany.com with the domain name of your attachmentAV API installation.

curl \
  -X POST \
  -H 'Authorization: Bearer <API_KEY_PLACEHOLDER>' \
  -H 'Content-Type: application/json' \
  -d '{"download_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"}' \
  'https://attachmentav.yourcompany.com/api/v1/scan/sync/download'

{"status":"clean","size":2903045,"realfiletype":"Adobe Portable Document Format (PDF)"}

POST /api/v1/scan/sync/binary (#)

Upload a file, scan the file, and return the scan result.

The request body contains the binary data (application/octet-stream).

The response status code is 200, and the body is JSON formatted with these properties:

  • status (string (clean, infected, no)): The scan result.
  • finding (string, optional): For infected files, the type of virus/malware that was detected.
  • size (number, optional): The file size in bytes.
  • realfiletype (string, optional): The Real File Type detected by the Sophos engine (requires version >= 1.2.0).

Example:

Replace <API_KEY_PLACEHOLDER> with one of the API keys from the ApiKeys configuration parameter. Replace attachmentav.yourcompany.com with the domain name of your attachmentAV API installation.

curl \
  -X POST \
  -H 'Authorization: Bearer <API_KEY_PLACEHOLDER>' \
  -H 'Content-Type: application/octet-stream' \
  -d '@path/to/file' \
  https://attachmentav.yourcompany.com/api/v1/scan/sync/binary

{"status":"clean","size":73928372,"realfiletype":"Adobe Portable Document Format (PDF)"}

POST /api/v1/scan/sync/form (#)

Upload a file, scan the file, and return the scan result.

The request body is multipart/form-data formatted and contains one file.

The response status code is 200, and the body is JSON formatted with these properties:

  • status (string (clean, infected, no)): The scan result.
  • finding (string, optional): For infected files, the type of virus/malware that was detected.
  • size (number, optional): The file size in bytes.
  • realfiletype (string, optional): The Real File Type detected by the Sophos engine (requires version >= 1.2.0).

Example:

Replace <API_KEY_PLACEHOLDER> with one of the API keys from the ApiKeys configuration parameter. Replace attachmentav.yourcompany.com with the domain name of your attachmentAV API installation.

curl \
  -H 'Authorization: Bearer <API_KEY_PLACEHOLDER>' \
  -F file=@path/to/file \
  https://attachmentav.yourcompany.com/api/v1/scan/sync/form

{"status":"clean","size":73928372,"realfiletype":"Adobe Portable Document Format (PDF)"}

POST /api/v1/scan/sync/s3 (#)

Download a file from S3, scan the file, and return the scan result.

The request body is JSON formatted with these properties:

  • bucket (string): The bucket name.
  • key (string): The object key.
  • version (string, optional): If versioning is turned on, the object version.

The response status code is 200, and the body is JSON formatted with these properties:

  • status (string (clean, infected, no)): The scan result.
  • finding (string, optional): For infected files, the type of virus/malware that was detected.
  • size (number, optional): The file size in bytes.
  • realfiletype (string, optional): The Real File Type detected by the Sophos engine (requires version >= 1.2.0).

Example:

Replace <API_KEY_PLACEHOLDER> with one of the API keys from the ApiKeys configuration parameter. Replace attachmentav.yourcompany.com with the domain name of your attachmentAV API installation.

curl \
  -X POST \
  -H 'Authorization: Bearer <API_KEY_PLACEHOLDER>' \
  -H 'Content-Type: application/json' \
  -d '{"bucket": "you-bucket", "key": "path/to/file.pdf"}' \
  'https://attachmentav.yourcompany.com/api/v1/scan/sync/s3'

{"status":"clean","size":105255200,"realfiletype":"Adobe Portable Document Format (PDF)"}

Need more help?

Write us, and we'll get back to you as soon as we can.

Send us an email