Accessing API

Request API Key

Access to the MAGIC service requires an API key.

To request a key, send an email to support@cythereal.com with the subject “Key Request”. Include your name and email address you want the key to be registered under.

Please note that as part of our minimal verification of identities, we do not provide keys to email addresses pointing to open email services, such as, gmail.com, yahoo.com, aol.com, and many others. Please request a key using your business or university email address.

API Endpoints

The MAGIC API can be directly accessed (using curl, for example) at:

The endpoints are documented at API Reference

Swagger UI

A Swagger UI for API documentation and interactive use can also be found at:

MAGIC SDK

Note

The MAGIC SDK is the preferred way of programatically accessing the MAGIC API.

An SDK in several different languages can be found at:

Documentation of how to use the SDK can be found at the link given above.

MAGIC Client

The MAGIC Client is a command line utility named vbclient. This client provides access to the functionality exposed by the MAGIC API.

This client requires python version 2.7. Older versions of python and python 3 are not supported at this time.

Access to the MAGIC service requires an API Key. If you don’t have one yet, please Request API Key.

There are three options for installing the MAGIC CLI Client:

All installation methods will result in the executable vbclient being created. This executable provides the CLI interface to MAGIC.

Once installed, the client must be configured

Stand Alone Executable

A single executable is provided that packages all necessary libraries for the MAGIC client. Simply download the appropriate version, place it in your PATH, and configure the client.

Version Download URL
Linux https://bitbucket.org/cythereal/virusbattle-sdk/downloads/vbclient
Windows https://bitbucket.org/cythereal/virusbattle-sdk/downloads/vbclient.exe

Install Using Pip

The cythereal-sdk package on PyPi is provided for installation via pip.:

pip install -U cythereal-sdk

Build from Source

The source for the MAGIC CLI client is released under the Apache License and can be found at https://bitbucket.org/cythereal/virusbattle-sdk.

To install the client from source:

git clone http://bitbucket.org/cythereal/virusbattle-sdk.git
pip install ./virusbattle-sdk

This will create the vbclient command available in your path.

Configure the client before continuing.

Configure MAGIC Client

Accessing the MAGIC client requires an API Key. If you do not have one, first request a key.

The vbclient program expects an environment variable named VIRUSBATTLE_KEY to contain your API key for accessing MAGIC.

On Linux, place the following in your .bashrc:

export VIRUSBATTLE_KEY=<your API key>

On Windows you can use the System Property Editor to add a new environment variables and set the value.