API Quick Reference

This is a quick reference, or cheat sheet, to the API until I can write something more comprehensive. The API is still in development and may change at any time. I think it's pretty straight forward but if you have any questions, need help, or have some feedback, please feel free to reach out to me on Discord.

Ping a Server

Example Request: https://api.breakblocks.com/api/v0.1/status/ping/94.19.15.232:25565

If the server's ping status has not been updated recently then the API will return a status of "refreshing" and a "refresh" value of true. This means that the server's status is being queued for update and you should check back soon.


{
    "status": "refreshing",
    "refresh": true,
    "server": {
        "address": "94.19.15.232",
        "port": 25565,
        "offline_mode": 0,
        "version": "1.20-1.20.4",
        "city": null,
        "country": "Russia",
        "country_code": "RU",
        "region": "EU",
        "players_online": 0,
        "players_limit": 100,
        "motd": "         ",
        "last_ping": "2024-08-26T05:30:29.000Z",
        "asn_number": "35807",
        "asn_name": "SkyNet Ltd.",
        "favicon": null,
        "detected_mod_pack": null,
        "detected_mod_pack_short": null
    }
}

Search for Servers

URI Param	Description	Notes
asn	Filter results based on ASN number.
country	Filter results based on full country name.	This will soon also detect an ISO code if given one
country_code	Filter results based on country ISO code (ie- US, CA, MX)	This will be soon be deprecated
limit	Limit the number of results returned by the API
page	Result pagination control.
maxUsers	Filter results for servers with the maximum number of players online.
minUsers	Filter results for servers with the minimum number of players online.
org	Filter results based on ASN Organization Name (* = wildcard)
region	Filter results based on continent ISO code (ie- NA, EU, AS)
version	Version filter (* = wildcard)

Example Request to the API

Request: https://api.breakblocks.com/api/v0.1/servers/find?limit=1&version=1.7.10&asn=16276&country=Canada&maxUsers=10&minUsers=1&sort=updated


{
    "displayed": 1,
    "total": 15,
    "filtered": 0,
    "results": [
        {
            "address": "51.222.82.234",
            "port": 25572,
            "offline_mode": 0,
            "version": "1.7.10",
            "city": null,
            "country": "Canada",
            "country_code": "CA",
            "region": "NA",
            "players_online": 1,
            "players_limit": 20,
            "motd": null,
            "public": 1,
            "plugins": [ ],
            "most_players": 0,
            "last_ping": "2024-08-26T04:44:46.000Z",
            "asn_number": "16276",
            "asn_name": "OVH SAS",
            "detected_mod_pack": null,
            "detected_mod_pack_short": null,
            "motd_stripped": null,
            "players": [
                {
                    "name": "Player1",
                    "uuid": "uuid1",
                    "ping": 0
                }
            ]
        }
    ]
}