NAV Navbar
shell python php javascript
  • Introduction
  • IP
  • Domain
  • E-Mail
  • Geolocation
  • ASN
  • Errors
  • Introduction

    Welcome to the monapi.io Anomaly API! You can use our API to access our endpoints, which provides risk, check and reputation based information for digital assets like IP's, Domain's and E-Mail Addresses in our database.

    We have language bindings in Shell, Python PHP and Javascript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

    Our API is under active development, and we plan to release more functionality. If there are specific features that you need, please contact us.

    Server Address

    The base server address is: https://api.monapi.io

    Please note that HTTPS is suggested. HTTP will be redirected to HTTPS with 301 Status Code. You will not be able to connect through unencrypted HTTP.

    Limits / Throttling

    To avoid individual rampant applications degrading the overall user experience and to improve our application's security performance we rate limit access to our API. If you hit the Rate Limit you will get following message:

    "Request was throttled. Expected available in 3498.0 seconds."

    The monapi API has usage limits to avoid individual rampant applications degrading the overall user experience. There are two layers of limits, the first cover a shorter period of time and the second a longer period. This enables you to "burst" requests for shorter periods. There are two HTTP headers in every response describing your limits status.

    The response headers are:

    Req-Limit-Short Req-Limit-Long An example of the values of these headers:

    Req-Limit-Short: Remaining: 394 Time until reset: 3589 Req-Limit-Long: Remaining: 71994 Time until reset: 2591989 In this case, we can see that the user has 394 requests left until the short limit is reached. In 3589 seconds, the short limit will be reset. In similar fashion, the long limit has 71994 requests left, and will be reset in 2591989 seconds.

    If you feel restricted by these limits, please feel free to contact monapi support and request a higher limit. The limits are primarily here to protect the system from poorly coded applications, not to restrict you as a user.

    Authentication

    To authorize, use this code:

    import requests
    response = requests.get(
    'https://api.monapi.io', headers={'Authorization': 'Token your_api_key'})
    
    # With shell, you can just pass the correct header with each request
    curl "https://api.monapi.io" -H "Authorization: Token your_api_key"
    

    For clients to authenticate, the token key should be included in the Authorization HTTP header. The key should be prefixed by the string literal "Token", with whitespace separating the two strings.

    Our API will always be accessible for not authenticated Users. You can access our API with or without API Keys. If you want to try out our API you can do so immediately within our throttling thresholds without sign up.

    You can register for our public Alpha Test a new monapi.io API key at our developer portal.

    monapi.io expects for the API key to be included in all API requests to the server in a header that looks like the following for our authenticated users:

    Authorization: Token your_api_key

    IP

    Example: Is IP 1.1.1.1 blacklisted?

    curl "https://api.monapi.io/v1/ip/1.1.1.1"
    
    import requests
    
    url = "https://api.monapi.io/v1/ip/{ip}"
    
    headers = {
        'accept': "application/json",
        'authorization': "your_api_key"
        }
    
    response = requests.request("GET", url, headers=headers)
    
    print(response.text)
    print(response.status_code)
    
    <?php
    
    // IP to check
    $ip = '1.1.1.1';
    
    $authToken = 'your_api_key';
    
    // Init cURL
    $curl = curl_init();
    
    // Set URL & some options
    curl_setopt_array($curl, array(
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_URL => 'https://api.monapi.io/v1/ip/' . $ip
    ));
    
    // Set the authorization header
    if ($authToken) {
        curl_setopt($curl, CURLOPT_HTTPHEADER, array(
            'Authorization: Token ' . $authToken
        ));
    }
    
    // Send the request
    $response = curl_exec($curl);
    
    // Check for cURL & HTTP errors or return response content
    if (curl_errno($curl)) {
      echo 'Error: "' . curl_error($curl) . '" - Code: ' . curl_errno($curl) . "\n";
    } else {
      switch ($httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE)) {
        case 200:  # OK
          echo 'OK' . "\n";
          $responseObject = json_decode($response);
          var_dump($responseObject);
          break;
        case 404:
          echo 'Resource not found' . "\n";
          $responseObject = json_decode($response);
          var_dump($responseObject);
          break;
        default:
          echo 'Unexpected HTTP-Code: ' . $httpCode . "\n";
      }
    }
    // Close request to clear up some resources
    curl_close($curl);
    
    var https = require('https');
    
    // The IP to check
    var ip = '1.1.1.1'
    
    // Authorization token
    var authToken = 'Token your_api_key';
    
    var options = {
      host: 'api.monapi.io',
      port: 443,
      path: '/api/v1/ip/' + ip,
      headers: {
      }
    };
    
    if (authToken) {
       options.headers['Authorization'] = 'Token ' + authToken;
    }
    
    var request = https.get(options, function(res) {
       var body = "";
       res.on('data', function(data) {
          body += data;
       });
       res.on('end', function() {
         // Check response by status
         switch (res.statusCode) {
           case 200:
             console.log('HTTP Status OK, 200');
             console.log('Response DATA', body);
             break;
           case 404:
             console.log('Resource not found, 404');
             console.log('Response DATA', body);
             break;
           default:
             console.log('Unknown HTTP Status Code', res.statusCode);
             break;
         }
       })
       res.on('error', function(e) {
          console.log("Got HTTP Response error: " + e.message);
       });
    });
    
    request.on('error', (e) => {
      console.error('Request error:', e);
    });
    
    request.end();
    

    The above command returns JSON structured like this:

    {
        "ip": "1.1.1.1",
        "hostname": "one.one.one.one",
        "threat_level": "low",
        "threat_class": [
          "reputation"
          ],
        "blacklists": [
          "PACKETMAIL_EMERGING_IPS"
          ],
        "blacklists_list_count": "1",
        "city": "Research",
        "region": "Victoria",
        "postal": "3095",
        "country": "Australia",
        "iso_code": "AU",
        "longitude": 145.1833,
        "latitude": -37.7,
        "asn_organization": "Cloudflare Inc",
        "asn_number": 13335
    }
    

    Returns Threat & Geolocation Data for a given IPv4 Address

    The IP API Endpoint will test an IPv4 Address against our aggregated database with more than 400 Blacklists and threat intelligence datasources. We update our database up to 144 times per day, achieving near real time up to date data. The Test Duration is fast and usually don't take longer than 100 milliseconds.

    GET /IPv4/

    HTTP Request

    GET https://api.monapi.io/v1/ip/<ip>

    URL Parameters

    Parameter Description
    IP The IPv4 Address for which the check should be executed.

    Filtering Responses

    Geolocation GET https://api.monapi.io/v1/ip/<ip>/geo

    ASN GET https://api.monapi.io/v1/ip/<ip>/asn

    Domain

    curl "https://api.monapi.io/v1/domain/foobar.net" \
    -H "Authorization: Token your_api_key" -H "Accept: application/json"
    
    import requests
    
    url = "https://api.monapi.io/v1/domain/{domain}"
    
    headers = {
        'accept': "application/json",
        'authorization': "your_api_key"
        }
    
    response = requests.request("GET", url, headers=headers)
    
    print(response.text)
    print(response.status_code)
    
    var https = require('https');
    
    // The Domain to check
    var domain = 'google.com'
    
    // Authorization token
    var authToken = 'Token your_api_key';
    
    var options = {
      host: 'api.monapi.io',
      port: 443,
      path: '/api/v1/domain/' + domain,
      headers: {
      }
    };
    
    if (authToken) {
       options.headers['Authorization'] = 'Token ' + authToken;
    }
    
    var request = https.get(options, function(res) {
       var body = "";
       res.on('data', function(data) {
          body += data;
       });
       res.on('end', function() {
         // Check response by status
         switch (res.statusCode) {
           case 200:
             console.log('HTTP Status OK, 200');
             console.log('Response DATA', body);
             break;
           case 404:
             console.log('Resource not found, 404');
             console.log('Response DATA', body);
             break;
           default:
             console.log('Unknown HTTP Status Code', res.statusCode);
             break;
         }
       })
       res.on('error', function(e) {
          console.log("Got HTTP Response error: " + e.message);
       });
    });
    
    request.on('error', (e) => {
      console.error('Request error:', e);
    });
    
    request.end();
    
    <?php
    
    // Domain to check
    $domain = '50.63.202.22';
    
    $authToken = 'your_api_key';
    
    // Init cURL
    $curl = curl_init();
    
    // Set URL & some options
    curl_setopt_array($curl, array(
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_URL => 'https://api.monapi.io/v1/ip/' . $domain
    ));
    
    // Set the authorization header
    if ($authToken) {
        curl_setopt($curl, CURLOPT_HTTPHEADER, array(
            'Authorization: Token ' . $authToken
        ));
    }
    
    // Send the request
    $response = curl_exec($curl);
    
    // Check for cURL & HTTP errors or return response content
    if (curl_errno($curl)) {
      echo 'Error: "' . curl_error($curl) . '" - Code: ' . curl_errno($curl) . "\n";
    } else {
      switch ($httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE)) {
        case 200:  # OK
          echo 'OK' . "\n";
          $responseObject = json_decode($response);
          var_dump($responseObject);
          break;
        case 404:
          echo 'Resource not found' . "\n";
          $responseObject = json_decode($response);
          var_dump($responseObject);
          break;
        default:
          echo 'Unexpected HTTP-Code: ' . $httpCode . "\n";
      }
    }
    // Close request to clear up some resources
    curl_close($curl);
    

    The above command returns JSON structured like this:

    [
      {
          "blacklist": {
              "COINBL_HOSTS_BROWSER": "organizations",
              "HPHOSTS_WRZ": "reputation",
              "RANSOMWARE_FEED": "malware",
              "HPHOSTS_MMT": "reputation",
              "THREATCROWD": "malware",
              "COINBL_HOSTS": "organizations",
              "HPHOSTS_PHA": "reputation",
              "HPHOSTS_GRM": "spam"
          },
          "ip": "69.172.201.153",
          "domain": "foobar.net",
          "mx_blacklist": false,
          "ns_blacklist": false
      }
    ]
    

    Returns Blacklists for a given Domain

    The Domain Check will test a Domain Adress against our aggregated database with more than 100 Blacklists and threat intelligence datasources. In addition we resolve the ip address of the domain as well as NS and MX Records and search our database for those additional IP addresses too. The Test Duration is fast and usually don't take longer than 100 milliseconds.

    HTTP Request

    GET https://api.monapi.io/v1/domain/<domain>

    URL Parameters

    Parameter Description
    Domain The Domain Address you wish to check against our database.

    E-Mail

    coming soon

    Geolocation

    Example: get geolocation data for IP 1.1.1.1

    curl "https://api.monapi.io/v1/1.1.1.1/geo"
    
    import requests
    
    url = "https://api.monapi.io/v1/{ip}/geo"
    
    headers = {
        'accept': "application/json",
        'authorization': "your_api_key"
        }
    
    response = requests.request("GET", url, headers=headers)
    
    print(response.text)
    print(response.status_code)
    
    <?php
    
    // IP to geolocate
    $ip = '1.1.1.1';
    
    $authToken = 'your_api_key';
    
    // Init cURL
    $curl = curl_init();
    
    // Set URL & some options
    curl_setopt_array($curl, array(
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_URL => 'https://api.monapi.io/v1/' . $ip . '/geo'
    ));
    
    // Set the authorization header
    if ($authToken) {
        curl_setopt($curl, CURLOPT_HTTPHEADER, array(
            'Authorization: Token ' . $authToken
        ));
    }
    
    // Send the request
    $response = curl_exec($curl);
    
    // Check for cURL & HTTP errors or return response content
    if (curl_errno($curl)) {
      echo 'Error: "' . curl_error($curl) . '" - Code: ' . curl_errno($curl) . "\n";
    } else {
      switch ($httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE)) {
        case 200:  # OK
          echo 'OK' . "\n";
          $responseObject = json_decode($response);
          var_dump($responseObject);
          break;
        case 404:
          echo 'Resource not found' . "\n";
          $responseObject = json_decode($response);
          var_dump($responseObject);
          break;
        default:
          echo 'Unexpected HTTP-Code: ' . $httpCode . "\n";
      }
    }
    // Close request to clear up some resources
    curl_close($curl);
    
    var https = require('https');
    
    // The IP to geolocate
    var ip = '1.1.1.1'
    
    // Authorization token
    var authToken = 'Token your_api_key';
    
    var options = {
      host: 'api.monapi.io',
      port: 443,
      path: '/api/v1/' + ip + '/geo',
      headers: {
      }
    };
    
    if (authToken) {
       options.headers['Authorization'] = 'Token ' + authToken;
    }
    
    var request = https.get(options, function(res) {
       var body = "";
       res.on('data', function(data) {
          body += data;
       });
       res.on('end', function() {
         // Check response by status
         switch (res.statusCode) {
           case 200:
             console.log('HTTP Status OK, 200');
             console.log('Response DATA', body);
             break;
           case 404:
             console.log('Resource not found, 404');
             console.log('Response DATA', body);
             break;
           default:
             console.log('Unknown HTTP Status Code', res.statusCode);
             break;
         }
       })
       res.on('error', function(e) {
          console.log("Got HTTP Response error: " + e.message);
       });
    });
    
    request.on('error', (e) => {
      console.error('Request error:', e);
    });
    
    request.end();
    

    The above command returns JSON structured like this:

    {
        "city": "Research",
        "country": "Australia",
        "region": "Victoria",
        "hostname": "one.one.one.one",
        "longitude": 145.1833,
        "ip": "1.1.1.1",
        "latitude": -37.7,
        "iso_code": "AU",
        "postal": "3095"
    }
    

    Returns Geolocation data for a given IPv4 Address or Domain

    You can supply an IP address to lookup. The Response include all important data for your application like city, postal, country, iso_code, latitude and longitude. See the whole response with all returned data in the example to the right.

    GET /IPv4/

    HTTP Request

    GET https://api.monapi.io/v1/<ip>/geo

    URL Parameters

    Parameter Description
    IP The IPv4 Address or Domain you want to geolocate.

    ASN

    Example: get ASN data for IP 1.1.1.1

    curl "https://api.monapi.io/v1/ip/1.1.1.1/asn"
    
    import requests
    
    url = "https://api.monapi.io/v1/{ip}/asn"
    
    headers = {
        'accept': "application/json",
        'authorization': "your_api_key"
        }
    
    response = requests.request("GET", url, headers=headers)
    
    print(response.text)
    print(response.status_code)
    
    <?php
    
    // IP you want ASN data for
    $ip = '1.1.1.1';
    
    $authToken = 'your_api_key';
    
    // Init cURL
    $curl = curl_init();
    
    // Set URL & some options
    curl_setopt_array($curl, array(
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_URL => 'https://api.monapi.io/v1/' . $ip . "/asn"
    ));
    
    // Set the authorization header
    if ($authToken) {
        curl_setopt($curl, CURLOPT_HTTPHEADER, array(
            'Authorization: Token ' . $authToken
        ));
    }
    
    // Send the request
    $response = curl_exec($curl);
    
    // Check for cURL & HTTP errors or return response content
    if (curl_errno($curl)) {
      echo 'Error: "' . curl_error($curl) . '" - Code: ' . curl_errno($curl) . "\n";
    } else {
      switch ($httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE)) {
        case 200:  # OK
          echo 'OK' . "\n";
          $responseObject = json_decode($response);
          var_dump($responseObject);
          break;
        case 404:
          echo 'Resource not found' . "\n";
          $responseObject = json_decode($response);
          var_dump($responseObject);
          break;
        default:
          echo 'Unexpected HTTP-Code: ' . $httpCode . "\n";
      }
    }
    // Close request to clear up some resources
    curl_close($curl);
    
    var https = require('https');
    
    // The IP you want ASN data for
    var ip = '1.1.1.1'
    
    // Authorization token
    var authToken = 'Token your_api_key';
    
    var options = {
      host: 'api.monapi.io',
      port: 443,
      path: '/api/v1/ip/' + ip + '/asn',
      headers: {
      }
    };
    
    if (authToken) {
       options.headers['Authorization'] = 'Token ' + authToken;
    }
    
    var request = https.get(options, function(res) {
       var body = "";
       res.on('data', function(data) {
          body += data;
       });
       res.on('end', function() {
         // Check response by status
         switch (res.statusCode) {
           case 200:
             console.log('HTTP Status OK, 200');
             console.log('Response DATA', body);
             break;
           case 404:
             console.log('Resource not found, 404');
             console.log('Response DATA', body);
             break;
           default:
             console.log('Unknown HTTP Status Code', res.statusCode);
             break;
         }
       })
       res.on('error', function(e) {
          console.log("Got HTTP Response error: " + e.message);
       });
    });
    
    request.on('error', (e) => {
      console.error('Request error:', e);
    });
    
    request.end();
    

    The above command returns JSON structured like this:

    {
        "ip": "1.1.1.1",
        "system_number": 13335,
        "system_organization": "Cloudflare Inc"
    }
    

    Returns autonomous system number (ASN) data for a given IPv4 Address

    What is an Autonomous System (AS)?

    An AS is a group of IP networks operated by one or more network operator(s) that has a single and clearly defined external routing policy.

    GET /IPv4/

    HTTP Request

    GET https://api.monapi.io/v1/<ip>/asn

    URL Parameters

    Parameter Description
    IP The IPv4 Address you want ASN data for.

    Errors

    The monapi.io API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- The digital asset requested is hidden for administrators only.
    404 Not Found -- The specified digital asset could not be found.
    405 Method Not Allowed -- You tried to access a digital asset with an invalid method.
    406 Not Acceptable -- You requested a format that isn't json.
    410 Gone -- The digital asset requested has been removed from our servers.
    418 I'm a teapot.
    429 Too Many Requests -- You're requesting too many digital assets! Slow down!
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.