API Documentation

Welcome to the documentation of syrion's API.

1. /check (POST)
2. Custom Rules
3. Integration Examples

1. `/check`

This endpoint is used to verify the details of a given IP address or User-Agent. It analyzes if an IP belongs to a proxy, VPN, mobile network, datacenter, or if it is likely to belong to a bot or crawler. The endpoint also checks if the IP falls into predefined restricted ranges or matches known crawlers.

Endpoint Overview

Method: POST
URL: /check
Authentication: Requires an API key in the header (x-api-key).

Headers

The request must contain the following header:

x-api-key: A valid API key you have been provided with, e.g., test-api-key-123.

Request Body (Payload)

A JSON object is required in the body of the POST request. The following parameters are supported:

ip: (Optional) The IP address to analyze. This must be in IPv4 format. (e.g., 198.51.100.42)
user_agent: (Optional) The User-Agent string to check against known bots or crawlers. If this field is not provided, the User-Agent will be extracted from the HTTP request headers.

( Note : It is required to submit at least one of the two °__° )

Example Payload:

{
    "ip": "198.51.100.42",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
}

Response

The API returns a JSON response with details about the IP or User-Agent. Below is an overview of the response structure:

Response Fields:

status: Indicates the general status of the IP/User-Agent (e.g., normal_user, bot, suspicious, blocked).

To understand the "blocked" status see Custom Rules

ip: The IP address that was checked (if provided).
type: The type of IP/User-Agent detected. Possible values include:
- normal_user: Regular user IP/User-Agent.
- custom_user: IP/User-Agent accepted by a custom rule
- custom_blocked: IP/User-Agent blocked by a custom rule.
- proxy: Proxy detected.
- vpn: VPN detected.
- datacenter_bot: Datacenter IP identified.
- mobile: Mobile network detected. (4G)
- crawler: Associated with a crawler (bot).
- restricted: Falls within restricted ranges.
reason: A descriptive reason for the IP/User-Agent status.
location: A nested object containing the following geographical details of the IP (if provided):
- city: IP's city of origin.
- region: Region where the IP is located.
- country: Country the IP belongs to.
- zip: ZIP code associated with this IP.
- lat: Latitude coordinates.
- lon: Longitude coordinates.
ISP: The Internet Service Provider (ISP) for this IP (if provided).
ORG: The organization associated with the IP (if provided).
AS: Autonomous System (AS) information (if provided).
mobile: Whether the IP belongs to a mobile network (if provided).
proxy: Whether the IP is a proxy (if provided).
vpn: Whether the IP uses a VPN (if provided).

Example Response (Success):

{
    "status": "normal_user",
    "ip": "198.51.100.42",
    "type": "mobile",
    "reason": "IP checked and validated",
    "location": {
        "city": "New York",
        "region": "New York",
        "country": "United States",
        "zip": "10001",
        "lat": 40.7128,
        "lon": -74.0060
    },
    "ISP": "Verizon Communications",
    "ORG": "Verizon Corporation",
    "AS": "AS701 Verizon",
    "mobile": true,
    "proxy": false,
    "vpn": false
}

Error Responses:

Status Code	Description
200	Request is successful, and the IP/User-Agent details are returned.
401	Unauthorized. API key is missing or invalid.
400	Bad request. The request payload is malformed or invalid.
500	Internal server error. Something went wrong on the server side.

2. Custom Rules

Custom rules allow you to define specific conditions to accept or reject IPs based on various fields. You can create rules for IP addresses, IP ranges, and other fields. Additionally, you can enable or disable the bypass rule to skip regular filters.

Custom Rule Fields

field: The field to apply the rule to (e.g., ip, country, isp).
condition: The condition to apply. Possible values include:
- accept: Accept the IP if it matches the value.
- reject: Reject the IP if it matches the value.
- accept only: Accept only if the IP matches the value(s), otherwise reject.
- reject only: Reject only if the IP matches the value(s), otherwise accept.
value: The value to match against the field. For the bypass field, this is set to true by default.

Example Custom Rules

Here are some examples of custom rules:

IP Address: Accept a specific IP address.

{
    "field": "ip",
    "condition": "accept",
    "value": "198.51.100.42"
}

IP Range: Reject a range of IP addresses.

{
    "field": "ip",
    "condition": "reject",
    "value": "198.51.100.*"
}

Country: Reject all IPs from a specific country.

{
    "field": "country",
    "condition": "reject",
    "value": "United States"
}

ISP: Accept only IPs from a specific ISP.

{
    "field": "isp",
    "condition": "accept only",
    "value": "Verizon Communications"
}

AS Number: Reject IPs from a specific AS number.

{
    "field": "as",
    "condition": "reject",
    "value": "AS701"
}

Organization: Accept only IPs from a specific organization.

{
    "field": "org",
    "condition": "accept only",
    "value": "Verizon Corporation"
}

User-Agent: Reject a specific User-Agent.

{
    "field": "user_agent",
    "condition": "reject",
    "value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
}

Types of IPs Returned Based on Custom Rules

The following types of IPs can be returned based on the custom rules defined:

custom_user: The IP/User-Agent is accepted by a custom rule.
custom_blocked: The IP/User-Agent is blocked by a custom rule.
bypass: The IP/User-Agent bypasses regular filters due to the bypass rule.

Concerning the Bypass Rule

When the bypass rule is enabled, the IP will not go through any of the regular filters. For example, if you have a custom rule for the Country field with the value "Italy" and the condition "Accept only," and the bypass rule is disabled, all users will be blocked except for Italian IPs. These Italian IPs will pass through the custom rule and then be subjected to the regular filters.

However, if the bypass rule is enabled, only the Italian IPs will pass through, and none of them will be subjected to the regular filters. In this case, the API will return the status user, the type bypass, and the reason Bypassed all base checks due to custom rule.

3. Integration Examples

If you have a website entirely in PHP, you can easily integrate the anti-bot check by creating a new PHP file with the following code. This script will call the API and check if the response indicates a user, bot, suspicious, or blocked status. Based on the configuration, it will redirect to a 404 page if the status is bot, blocked, or suspicious (if configured to do so).

Configuration

At the beginning of the script, you can configure the following options:

API_KEY: Your API key for accessing the anti-bot API.
BLOCK_SUSPICIOUS: Whether to block suspicious users (can be true/false).

PHP Script

<?php
// Configuration
$API_KEY = 'your-api-key';
$BLOCK_SUSPICIOUS = true;

// Function to check IP and User-Agent
function checkAntiBot($apiKey, $blockSuspicious) {
    $url = 'https://api.syrion.io/check';
    $headers = [
        'Content-Type: application/json',
        'x-api-key: ' . $apiKey
    ];
    $payload = json_encode([
        'ip' => $_SERVER['REMOTE_ADDR'],
        'user_agent' => $_SERVER['HTTP_USER_AGENT']
    ]);

    $options = [
        'http' => [
            'header' => $headers,
            'method' => 'POST',
            'content' => $payload
        ]
    ];
    $context = stream_context_create($options);
    $response = file_get_contents($url, false, $context);
    $data = json_decode($response, true);

    if ($data['status'] === 'bot' || $data['status'] === 'blocked' || ($blockSuspicious && $data['status'] === 'suspicious')) {
        header('HTTP/1.0 404 Not Found');
        exit();
    }
}

// Call the function to check the request
checkAntiBot($API_KEY, $BLOCK_SUSPICIOUS);
?>

Instructions

To include this anti-bot check in your PHP site, follow these steps:

Create a new PHP file (e.g., antibot_check.php) and paste the above script into it.
Include this file at the top of each PHP file where you want to perform the anti-bot check. For example:

<?php
include 'antibot_check.php';
// ...existing code...
?>

Other code Examples

cURL Example

curl -X POST https://api.syrion.io/check \
-H "Content-Type: application/json" \
-H "x-api-key: your-api-key" \
-d '{"ip": "198.51.100.42", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"}'

Python Example

import requests

url = "https://api.syrion.io/check"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "your-api-key"
}
payload = {
    "ip": "198.51.100.42",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

PHP Example

$url = "https://api.syrion.io/check";
$headers = [
    "Content-Type: application/json",
    "x-api-key: your-api-key"
];
$payload = json_encode([
    "ip" => "198.51.100.42",
    "user_agent" => "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
]);

$options = [
    "http" => [
        "header" => $headers,
        "method" => "POST",
        "content" => $payload
    ]
];
$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
echo $response;

JavaScript Example

const url = "https://api.syrion.io/check";
const headers = {
    "Content-Type": "application/json",
    "x-api-key": "your-api-key"
};
const payload = {
    ip: "198.51.100.42",
    user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
};

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

Go Example

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://api.syrion.io/check"
    apiKey := "your-api-key"

    payload := map[string]string{
        "ip":         "198.51.100.42",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    }
    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-api-key", apiKey)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}