API Documentation

Getting started

The MetaCert Security API allows you to look up the classification or reputation of URLs and IP addresses against our “Malware & Phishing” and “Pornography” collections. We will add more categories in the coming months.

Lookups are done via one API call that is used to check URLs against the different subscribed categories. You can get started quickly by using your favorite tool or programming language:

How to look up against subscribed categories

In the example API call below, the lookup service will check to see if http://example.org/malicious/attack.html is labeled as any of your subscribed categories.

EXAMPLE REQUEST
POST    : https://dev.metacert.com/v5/check/

HEADER  : apikey :   < your api key >
        : Content-Type:application/json

BODY    : {
              "url": "http://example.org/malicious/attack.html"
          }
Note

For the purpose of testing, this domain has, in fact, been labeled by MetaCert as “Malware & Phishing”. So when you want to test the API, this is a good URL to validate that the API is working, as it should.

EXAMPLE RESPONSE
{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "data": {
        "URLs": [],
        "Folders": [],
        "Domains": [
            {
                "domain": "example.org",
                "type": "malware-phishing"
            }
        ]
    }
}

In the example response, you can see that “Domains” is not empty. This means that the given domain is classified as ‘Malware & Phishing’ as described in the “type” field. If the URL wasn’t found you would see an empty array.

Because the domain “example.org” has been classified rather than just the URL, the response is included in the “Domains” field. This means that every URL you check against this domain will be a positive match. This is particularly useful when checking for pornography, as it potentially catches billions of URLs across the web.

Important

It’s our unique ability to label folders that set our classification system miles apart from the rest. By classifying folders, we catch millions of URLs and IP addresses that other companies miss.

For example, we have labeled imgur.com as ‘image sharing’, while the folder /r/nsfw/ is labeled as pornography. Because other companies don’t have the ability to label on the folder-level, they would either have to label imgur.com as pornography or label every image the minute they are uploaded.

Labeling the entire domain would cause a massive problem with false positives and the latter is technically impossible.

By labeling domains, sub-domains, folders and URLs, the Security API catches every image that’s ever stored in a folder in the future.

Getting results on more than one category

In this example, the Security API will check the URL http://imgur.com/r/sex/sexy.html is labeled as ‘Malware & Phishing’, ‘Image Sharing’ or ‘Pornography’.

This is a fictitious URL and is therefore safe to test at work.

Note

We have a collection for ‘Image Sharing’ websites along with 30 other categories. We will make these available to you in the very near future.

EXAMPLE REQUEST
POST    : https://dev.metacert.com/v5/check

HEADER  : apikey :  < your api key >
        : Content-Type:application/json

BODY    : {
              "url": "http://imgur.com/r/sex/sexy.html"
          }
EXAMPLE RESPONSE
{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "data": {
        "URLs": [
            {
                "url": "http://imgur.com/r/sex/sexy.html",
                "type": "xxx"
            }
        ],
        "Folders": [
            {
                "folder": "/r/sex/",
                "type": "xxx"
            }
        ],
        "Domains": [
            {
                "domain": "imgur.com",
                "type": "image-sharing"
            }
        ]
    }
}

The response for “folder” returned a type “xxx”. This means that the folder is classified as ‘Pornography’ so you should assume that this particular URL and every other URL in this folder contains pornography. Classification on this level and the ability to expose it with the Security API is pure magic.

The response also tells you that, even though, the folder and, therefore, the URL, contains XXX content, the domain is labeled as ‘Image Sharing’.

If a URL hasn’t been found under a chosen category, an empty array will be returned.

Get 150 FREE API calls EVERY month

YES, Sign me up!

Get 150 FREE API calls EVERY month

YES, Sign me up!