Skip to main content

Endpoint Documentation

Please make sure you're using these endpoints respecting our usage guidelines.

Current Endpoint URL

All URLs provided below follow this protocol and hostname.
https://smponline-api.callmecarson.live

General

GET /

Returns a status report on the APIs. Status code 200 will always be returned unless the server is down. If the server is down, you will receive some sort of error code (5xx) from Cloudflare. The format of this is subject to change at any time and should be considered informational.

Chest Shops

GET /quickshop/v1/getAllShops

Returns 500 error and JSON Object if an error occurred. Possible errors are

  • {"error":"NOT_CACHED"}
  • {"error":"INTERNAL_ERROR"}

Returns 200 if valid. Result data is a JSON Array of shop data. Note that SNBT data is only returned for in-stock shops for items with enchantments, paintings, and potions to keep response sizes small.

Below is an example of a JSON object you may find inside of the response JSON array. 

{
    "id": 439,
    "owner": {
        "name": "_AdamGolden_",
        "uuid": "a66ac146-c6cd-40e3-b3be-3d21735a2480"
    },
    "location": {
        "x": 8317,
        "y": 64,
        "z": 9444,
        "world": "world"
    },
    "type": "SELLING",
    "price": 2,
    "remaining": 9,
    "item": {
        "type": "PAINTING",
        "quantity": 1,
        "name": "[Joy of Painting] Canvas (LONG)",
        "snbt": "{\"minecraft:custom_data\":{PublicBukkitValues:{\"smponline:canvas_author_uuid\":\"a66ac146-c6cd-40e3-b3be-3d21735a2480\",\"smponline:xerca_item\":\"xercapaint:item_canvas_long\",\"xercapaint:canvas_author\":\"_AdamGolden_\",\"xercapaint:canvas_generation\":3,\"xercapaint:canvas_id\":\"a66ac146-c6cd-40e3-b3be-3d21735a2480_1751403978\",\"xercapaint:canvas_title\":\"The Werner Wide\",\"xercapaint:canvas_version\":199}},\"minecraft:custom_model_data\":{strings:[\"xercapaint:item_canvas_long\"]},\"minecraft:item_name\":'{\"color\":\"red\",\"fallback\":\"[Joy of Painting] Canvas (LONG)\",\"italic\":false,\"translate\":\"item.xercapaint.item_canvas_long\"}',\"minecraft:max_stack_size\":1}"
    }
}

Economy

WSS /economy/v1/ws

The SMP API may be restarted at any time, which will end your WebSocket connection without notice. Ensure that your code automatically reconnects if the WebSocket is closed.

Your WebSocket must identify itself with a User-Agent header. If your WebSocket client library does not support this, you will be unable to use WebSockets. Make sure to follow the guidelines on WebSocket user agents.

Connect via WebSocket to start receiving live data from the server on economy transactions as they happen. The WebSocket will not respond to any messages sent by clients.

If the server's behaving, you will receive a {"hello-from-eco-v1":timestamp} message upon connection, as well as periodic ping events to keep the connection alive. Below are the events currently sent by the backend on this endpoint.

Event: Auction Complete
{
	"event": "auctionComplete",
	"timestamp": 1759112390254,
	"data": {
		"item": {
			"type": "SHULKER_BOX",
			"amount": 1,
			"snbt": "{\"minecraft:container\":[{item:{components:{\"minecraft:stored_enchantments\":{levels:{\"minecraft:punch\":2,\"minecraft:quick_charge\":2,\"minecraft:unbreaking\":3}}},count:1,id:\"minecraft:enchanted_book\"},slot:0}],\"minecraft:custom_name\":'\":!!: book :!!:\"'}"
		},
		"finalBid": 6
	}
}
Event: Shop Transaction
{
	"event": "shopTransaction",
	"timestamp": 1759113897534,
	"data": {
		"type": "buyFromShop", // OR 'sellToShop'
		"currencyAmount": 2, // amount of Diamonds involved in this transaction
		"itemPrice": 1, // cost of 'item' below, as listed on shop sign
		"item": {
			"type": "DARK_OAK_LOG",
			"amount": 192, // amount as listed on the shop sign
			"snbt": "{}"
		},
		"totalAmount": 384, // player purchased 384 Dark Oak Logs here
		"location": {
			"x": -957,
			"y": 110,
			"z": -5283,
			"world": "world"
		}
	}
}

Health Report

GET /health/v1/report

Returns 200 unless something went very wrong. Intended for internal use but may be useful for third party websites.

Below is an example of the JSON output, with some annotations explaining what stuff is.

{
    "tick": {
        "last": 1759037321034, // previous tick ms timestamp 
        "latest": 1759037321084, // current tick ms timestamp
        "gap": 50, // the gap between the last two tick in ms
        "healthy": true // if this is considered "healthy"
    },
    "memory": {
        "free": 14817745664, // free bytes of memory
        "allocated": 51539607552, // allocated bytes of memory
        "max": 51539607552 // max allowed bytes of memory to the jvm
    },
    "ping": {
        "players": 103, // player count
        "highLatencySamples": [ // array of poor player pings in ms
            264,
            274,
            458
        ],
        // the rest of these are self explanatory
        "minPing": 18, 
        "maxPing": 458,
        "avgPing": 82,
        "medianPing": 70
    }
}

Back to top