API Quick Start

Authorization

Requests are authenticated using API keys. While API keys are not a requirement for using the API, any request that doesn't include an API key will suffer lower rate limits. Please contact us via email or discord to obtain an API key.

You can provide your API key in the form of the Authorization header or the token url parameter.

https://api.safelink.gg/v1/check?token=YOUR_API_TOKEN

Authorization: YOUR_API_KEY

Identification

While we love that you are using our API, we would like to know who you are. If you do not have an API key, you must provide an identity to make requests.

You can provide your identity using the User-Agent or X-Identity headers. We would like your identity to follow this schema:

$ApplicationName ($url, $version)

For example:

User-Agent: SafeLinkBot (https://safelink.gg, 2.0)

Scanning a link

By far the simplest way to scan links is to just send a POST request with the links you would like scanned. You will receive a list of Scan objects with flags and other metadata you can use to classify the links.

Scan Links

POST https://api.safelink.gg/v1/check

Submits links to scan. The connection will be kept open until the links are done scanning. No polling is necessary. For more information on scans refer to the Scan object

Request Body

Name	Type	Description
urls*	Array	An array of link strings.
timeout	float	Time in seconds until cutting the request short and returning whatever data was gathered.

200: OK Links were scanned

{
    "status": 200,
    "data": [
        {
            "url": "https://i-am-a-scam.com",
            "status": 200,
            "flags": [
                "SCAM"
            ],
            "content_type": "text/html",
            "similar_to": [],
            "scam_score": 39.0,
            "meta": {
                "title": "Scam page title",
                "description": "Meta description",
                "image": "https://i-am-a-scam.com/image.jpg",
                "type": "website",
                "site_name": "ScamSite"
            },
            "title": "ScamSite | Get scammed",
            "scan_timestamp": 1641687942,
            "scan_length": 1.622185230255127
        }
    ]
}

400: Bad Request Your link array or timeout was malformed

{
    "status": 400,
    "description": "Invalid Request",
    "message": "No URLs were provided"
}

Take a look at how you might call this method:

curl

curl https://api.safelink.gg/v1/check
    -H "Authorization: YOUR_API_KEY"  
    -d "urls[]=https://example.com"  

Python (aiohttp)

import aiohttp
import asyncio

async def main():
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.safelink.gg/v1/check",
            json={
                "urls": ["https://example.com"],
                "timeout": 60
            },
            headers={
                "Authorization": "YOUR_API_TOKEN"
            }
        ) as response:
        
            data = await response.json()
            
            print(data.get("data"))
            
if __name__ == "__main__":
    asyncio.run(main())

Python (requests)

import requests

def main():
    data = requests.post(
        "https://api.safelink.gg/v1/check",
        data={
            "urls": ["https://example.com"],
            "timeout": 60
        },
        headers={
            "Authorization": "YOUR_API_TOKEN"
        }
    )
    
    print(data.json().get("data"))
    
if __name__ == "__main__":
    main()

Reporting

If you detect or think that a link or domain should be flagged, but isn't, you can submit it with the proper flags here to be looked over by the SafeLink team.

Report Links

POST https://api.safelink.gg/v1/report

Submits links for review.

Request Body

Name	Type	Description
reports*	Array	An array of Report objects.

200: OK Reports were received

{
    "status": 200,
    "data": {}
}

400: Bad Request Your Reports were malformed

{
    "status": 400,
    "description": "Invalid Request",
    "message": "No Reports were provided."
}