monapi API Reference NAV Navbar

Introduction

Welcome to the monapi.io API! Use our API to access our endpoints, which provides risk, check and reputation based information for digital assets like IP's, Domain's and Email 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.

Version

The current Version of our API is v1.

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 are more than free to sign up to get your free API Key wich enables you to request our endpoints 500 per day. Sign up.

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_score": "23.3",
    "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.
Token Your API token

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.
Token Your API token

Email

Example: verify Email Address dennis@monapi.io

curl "https://api.monapi.io/v1/email/dennis@monapi.io"
import requests

url = "https://api.monapi.io/v1/email/dennis@monapi.io"

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 mail to verify
var mail = 'dennis@monapi.io'

// Authorization token
var authToken = 'Token your_api_key';

var options = {
  host: 'api.monapi.io',
  port: 443,
  path: '/api/v1/email' + mail,
  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:

{
    "message": "2.1.5 Ok",
    "is_role": false,
    "user": "dennis",
    "mail": "dennis@monapi.io",
    "is_free": false,
    "smtp_server": true,
    "is_catchall": false,
    "mx_records": true,
    "block": false,
    "domain": "monapi.io",
    "code": 250,
    "result": "deliverable",
    "is_disposable": false
}

Validate email addresses

Our Email verification API is as complete as possible, with validations made at multiple levels: response of the mail servers, disposable emails, catch all emal, free mailer, emailformat, domain information and much more.

Please be aware that anonymous users are not allowed to connect to the email endpoint. Your Token is required.

Because we focus on B2B customers we wont verify free mailer addresses. All email checks will run except we wont connect to the smtp server.

1 Email verification consumes 10 Request Hits.

You need to supply an email address. It returns the result of the verification to know if this email address is deliverable or not, with the detailed validations made.

result returns the main status of the verification. It can take 3 possible values:

  • "deliverable": the email verification is successful and the email address is valid.
  • "undeliverable": the email address is not valid.
  • "unknown": we could not verify the email.

is_disposable is true if we find this is an email address from a disposable email service.

is_free is true if we find this is an email from a webmailer or freemailer (for example yahoo or gmail).

mx_records is true if we find MX records exist on the domain of the given email address.

smtp_server is true if we connect to the SMTP server successfully.

is_catchall is true if the SMTP server accepts all the email addresses. This could increas the false positive rate

block is true if the SMTP server prevented us to perform the STMP check.

message returns the response message from the mailserver.

code returns the smtp response code from the mailserver.

HTTP Request

`GET https://api.monapi.io/v1/email/{email}

URL Parameters

Parameter Description
Email The email to verify
Token Your API token

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.
Token Your API token

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.
Token Your API token

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.