API (self-hosted on AWS): API Definition

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

The following snippet shows the HTTP header. Ensure to replace <API_KEY> with one of the API keys that you configured for the parameter ApiKeys when creating the CloudFormation stack.

Authorization: Bearer <API_KEY>

The following examples assume that you replace attachmentav.yourcompany.com with the actual domain name of your attachmentAV API installation.

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:

curl \
  -X POST \
  -H 'Authorization: Bearer XXX' \
  -H 'Content-Type: application/json' \
  -d '{"download_url": "https://download.yourcompany.com/path/to/file.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:

curl \
  -X POST \
  -H 'Authorization: Bearer XXX' \
  -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:

curl \
  -H 'Authorization: Bearer XXX' \
  -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. A bucket policy is required to grant attachmentAV access to the S3 objects.

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:

curl \
  -X POST \
  -H 'Authorization: Bearer XXX' \
  -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