Asomiru APIv1

Open your server page on Asomiru → Asomiru API → Enable API and create key. Server ownership must be verified. Save the key: every request uses it.

Set your key in a terminal:

Then fetch your server:

players is the current player count, maxPlayers is the number of slots, and activeVotes is the number of active votes. checkedAt tells you when the monitor last checked the server. An unavailable server has status: "offline". Minecraft returns a version such as 1.21.1 instead of a map. Unknown values are null.

Base URL: https://api.asomiru.com/v1. The key selects your server, so you do not need a server ID in requests. Call the API from a backend, bot or game plugin. Keep the key out of public browser JavaScript.

Fields you can show on your dashboard:

• connectClicks.total: clicks on Connect on Asomiru. These are referrals, not confirmed game joins. Repeated clicks from the same browser within 30 seconds count once.
• connectClicks.uniqueBrowsers: an estimate of unique referrals during this period.
• votes.received: votes received during the period.
• reportedJoins: game joins reported by your plugin. It stays zero until you send data.
• players.average and players.peak: average and peak player counts from successful checks.
• monitoring.availabilityPercent: the percentage of checks where the server responded. It is null when no checks are available.

Periods: day is the last 24 hours, week is 7 days, and month is 30 days. The default is week. Statistics are cached for 30 seconds. All response timestamps use UTC.

This example is shortened to two points. day returns hourly points; week and month return daily points. at is the start of the hour or day. The first and last points may cover only part of that interval. Empty intervals are included. When no player count was measured, averagePlayers and peakPlayers are null, not zero.

An Asomiru ID is a permanent website account ID, such as ASM-1-0000-0042-20. Players can find it in their account. Changing a nickname, email or Steam account does not change it. Send the complete ID, including hyphens. The last two digits help detect typing mistakes. Previously issued IDs also remain valid in the API.

A game ID identifies an account in the game. Your plugin reads it from the game server after the player has authenticated. Players link their game account once. After that, they vote on the website and your plugin finds their votes using the game ID. Players do not need to copy their Asomiru ID on each join.

There are two linking methods.

Steam. The player links Steam in their Asomiru settings and clicks Enable rewards with Steam on your server page. For CS, Team Fortress 2, Rust and Left 4 Dead, your plugin uses the authenticated player’s SteamID64. Send it as a string: JavaScript rounds integers this large. ARK and Valheim support Steam linking too; accounts from other platforms can use a game code.

In-game code. On Minecraft, read the connected player’s UUID and request a code:

Show the code only to that player. On your server page, they enter it and click Link and enable rewards. Codes last ten minutes and work once. A new code can be requested after one minute. If the response is lost, wait a minute and request another code.

AsomiruBridge for Minecraft provides /asomiru link. It runs on Paper/Spigot 1.21.1+, Java 21 and online-mode=true. Servers using a proxy or separate login system need an integration that verifies that authentication before linking. A UUID, SteamID or nickname typed into chat does not prove account ownership.

For another platform, use its permanent account ID: 3–64 characters consisting of letters, digits, _, : or -. Keep its format consistent across requests. Do not use a changeable nickname.

Send up to 50 players. The response preserves their order, so you can check players when they join or in a periodic batch.

rewards: true means the link is active. A player without an active link appears as null.

Every endpoint with a player field accepts these references:

An Asomiru ID is an identifier, not a password. Your key can only access links for your server. An older link may return asomiruId: null; the player can update it on the server page. Existing reward checks using the game ID continue to work.

Use this to show whether a player has voted and how many rewards await collection:

activeVotes counts votes still active for this server; each lasts 30 days. pendingRewards counts vote events not yet acknowledged, including events temporarily held by another delivery. This request does not reserve or consume anything.

Use the next section to issue rewards. Do not reward every response with voted: true: that would reward the same vote repeatedly.

Link the game account first, then ask the player to vote. Only votes made after linking create reward events. An earlier vote can appear in votes/check without a corresponding reward event.

1. Claim events. Generate a UUID requestId and save it in your plugin before sending the request.

Each events[].id identifies one vote. A request returns up to 20 events. No new votes and an unavailable link both return:

2. Save the events. Write them into your plugin’s persistent queue. Give events[].id a unique constraint so that receiving it twice cannot create a second reward. After a lost response, repeat claim with the same requestId. While the delivery is valid, the API returns the same batch and excludes these events from other deliveries.

3. Acknowledge receipt. Once the queue is saved, send ack before leaseUntil, normally within two minutes:

ack confirms that you saved the events, not that an item was delivered in the game. Process your saved queue under your reward rules. Keep processed event IDs until expiresAt, and share that ledger between all workers for the same server. Protect the game-side action too: for example, record the event ID and balance change in one game database transaction. If a game command cannot do this, review an ambiguous crash outcome rather than blindly running it again.

For LEASE_EXPIRED, create a new requestId and call claim again. Vote event IDs stay the same, allowing your queue to recognize duplicates. Repeating ack returns acknowledged: true while the delivery record is retained, up to two days. Pending votes remain available for up to 30 days.

Existing integrations using playerId continue to work. Supply either playerId or player, never both.

For aggregate statistics, count the joins in one minute and send a single request. Player accounts are not needed:

Generate a new eventId and current timestamp for each batch. After a failure, resend the same data and ID. Each request accepts 1–1000 joins from the last 24 hours, with a limit of ten requests per minute. Results appear as reportedJoins in server statistics. Join reports come from your plugin and do not affect the monitoring ranking.

Download the Asomiru API client and extract asomiru-sdk into your project. Node.js 22.13+; no additional libraries are needed.

The archive includes examples/rewards.mjs, which saves request IDs and votes in SQLite before acknowledging receipt. Use it as the starting point for your own reward queue. Game-side item delivery belongs in your game plugin.

The client retries safe requests with their original IDs after a connection failure. On a rate limit, it throws AsomiruError with code and retryAfter. Refreshing a bot or website’s online count once a minute is usually enough.

Limits are 120 requests per server per minute and 300 per IP. POST bodies are limited to 2 KB, or 24 KB for players/resolve. Statistics are cached for 30 seconds; personal responses are not cached. All timestamps are UTC.

Keep the key on your server. Rotating it disables the previous key. Disabling the API or changing ownership ends access to player links. Unlinking Steam also makes that Steam identity’s linked accounts unavailable.

Full fields and responses: OpenAPI. Minecraft implementation: AsomiruBridge source. Integration questions: support@asomiru.com.