API
The server API and the public API for websites and bots.
API tokens #
API tokens (/api-tokens, permission api.manage): tokens for websites and bots, each limited to the abilities you tick (players.read, players.stats, players.punishments, players.message, servers.read, servers.broadcast), optionally expiring. Shown once, stored hashed, revocable, with last use and IP. See Public API below.
Every server endpoint except auth needs Authorization: Bearer <token>. All responses are JSON.
| Method | Path | Purpose |
|---|---|---|
| GET | /health |
Public liveness probe (used by the circuit breaker) |
| POST | /server/auth |
{server_id, api_key} → {token, expires_at_unix, poll_interval_seconds} |
| POST | /server/heartbeat |
{tps, uptime_seconds, max_players, version, metadata, players:[{uuid,username,ip}]} → {pending_actions}. Opens or closes sessions to match the reported player list, and keeps each player's in-game sign-in alive from the address it reports |
| GET | /server/queue |
Claim up to 25 actions: {actions:[{id,type,scope,attempt,payload}]} |
| POST | /server/queue/ack |
{results:[{id, status: completed|failed|rejected, message}]} |
| POST | /server/players/session |
{events:[{event: join|quit, uuid, username, ip, at, data?}]}. A quit with data is saved and the session released in one transaction |
| POST | /server/players/data |
{players:[{uuid, base_version, balance, stats{}, data{}, email?, language?}]} → {saved:{uuid:version}, skipped:{uuid:reason}} |
| GET | /server/players/{uuid} |
Pre-login profile + active ban/mute + session_conflict (added) |
| POST | /server/events |
Batched chat / private_message / command / death / custom events (added) |
| POST | /server/punishments |
In-game /nban etc., applied network-wide (added) |
| POST | /server/players/link |
{uuid, code} from in-game /link. Returns game_code for the player to type on the portal (two-way linking) (portal) |
| POST | /server/players/access |
{uuid} from /access: a one-time temporary-access link (url, minutes); 422 has_account or not_signed_in (portal) |
| POST | /server/players/verify |
{uuid, code, confirm} from /verify. Approves sign-in, recovery or temporary-access challenges (temporary access: 422 not_signed_in unless they're signed in in-game) (portal) |
| POST | /server/players/account |
`{uuid, action: info |
| POST | /server/friends |
{uuid, action, target} from /friend (friends) |
| GET | /server/chat-filter?version= |
Chat filter rules as regexes; {changed:false} when the version is current (chat filter) |
| GET | /server/textmojis?version= |
Textmoji list and one regex that finds them; {changed:false} when the version is current (textmojis) |
| POST | /server/coins |
`{uuid, action: balance |
| GET | /server/globals?version= |
Global value definitions: network values and per-player defaults; {changed:false} when current (global values) |
| POST | /server/reports |
{uuid, target?, category?, description?, location?} from /report. Registered: returns portal url; unregistered: files the report (reports) |
| POST | /server/progress |
{players:[{uuid, counters:{"kill_mob:ZOMBIE":3}, gauges:{reach_level:40}}]}: progress for quests and badges (quests) |
| POST | /server/inbox |
{uuid, action: count|list|read|delete|claim, page?, id?}. Lists put waiting rewards (kind: reward) before messages; claim gives a reward on this server; auctioned items come back as stacks (item data) (inbox, rewards) |
| POST | /server/auctions |
{uuid, action: browse|sell|bid|cancel|check, ...}: browse {page?, mode?: all|mine|bids, search?}, sell {item, name, material, amount, price, hours?, request}, bid {auction, amount}, cancel {auction}, check {request}. Scoped to the server's category; replies carry enabled, settings and balance (auctions) |
| POST | /server/coin-exchange |
{uuid, action: status|to_money|to_global|check, coins?, paid?, request?}: status gives this server's settings (enabled, to_money, to_money_rate, to_global, to_global_rate, min_coins, max_coins, daily_coins, source), balance and left_today; to_money {coins, request} takes the global coins and replies with the money to give; to_global {coins, paid, request} gives the coins for money the server already took (refused if paid isn't what the rate asks now); check {request} says whether one went through (done, direction, money) (coin exchange) |
| POST | /server/dungeons |
{action: menu|overview|start|join|leave|left|begin|finish, uuid?, dungeon?, run?, result?, stats?, left?}: menu gives the open dungeons for the player (needs, attempts left, rewards, why not) and raids forming or running on this server, with each dungeon's reward_list, drops and xp for its rewards menu; overview gives the player's last ended raid on a server of this category (raid: the dungeon, status, time, leader, server, totals and every member's stats, left and rewards; null when none); start {dungeon} makes a raid with them as leader; join/leave {run}; left {run} marks a player who left a raid that has begun (Left mid raid: no clear rewards); begin {run} (leader) gives the build, its markers and spawners and the party; finish {run, result: cleared|failed|abandoned, stats: {uuid: {damage, kills, deaths}}, left: [uuid]} records it and gives the rewards, replying with given per player (dungeons) |
| POST | /server/wish |
{uuid, action: status|wish|check|storage|collect, count?, request?, page?, id?}: status gives enabled, cost, counts, balance, pity (since_rare, since_legendary, rare_at, legendary_at, soft_from), tiers and items (each with chance, its own, and odds, its real chance of being won) and storage (prizes waiting); wish {count: 1|3|10, request} rolls on the panel, takes the global coins once and replies with results; check {request} says whether a batch went through; storage {page} lists prizes waiting (45 a page); collect {id?} collects one, or a page with no id, giving it on this server (gatcha) |
| POST | /server/stocks |
{uuid, action: status|buy|sell, stock?, shares?, all?, request?}: status gives enabled, fee, max_shares, max_trade, amounts, balance, stocks (each with ticker, name, icon, active, price_text, change_text, colour, shares, value, cost, profit_text, profit_colour, and buy, sell and sell_all: what 1, 10 and 100 shares come to, fee included) and portfolio (value, cost, profit); buy {stock, shares, request} and sell {stock, shares or all: true, request} trade with global coins and answer with ok, message and the whole status again. A request sent twice is one trade (stock market) |
| POST | /server/premium-shop |
{uuid, action: status|buy|codes, kind?: player|crew|island|pets, days?, price?, code?}: offers, balance, their Premium and their crew's, island and pets (active, until, until_text, offers [{days, price, label}] (every length sold for coins, empty when off), offer {price, days} (the shortest) or null, paid; pets also on and via_premium) and store_url; buy takes global coins and adds the days (for island and pets, days picks the length, the shortest without it; a length no longer sold is refused). With a discount code, offers it works on have the discounted price and the full base_price, and discount {code, ok, message} says what it does; buy sends the code and the discounted price. codes lists their personal discount codes (codes [{code, discount, for, ends, ends_text}]) (the /store menu) |
| POST | /server/modifiers |
{uuid, action: get|bless, key?, minutes?, reason?} → {xp, xp_modifiers[], blessings[]}. bless only gives blessings marked "Scripts may give it" (blessings, player XP rates) |
| POST | /server/quests |
{uuid, action: active|available|start|abandon|achievements, quest?} (quests) |
| POST | /server/combat-log |
{uuid, attacker_uuid?, seconds_left, location, applied:[{type, value, amount}]}; the panel takes global coin penalties (combat log) |
| POST | /server/loadouts |
{uuid, action: list|use|save|delete, loadout?, money?, name?, items?}; use returns the items to give, save matches carried items to the shop (loadouts) |
| POST | /server/shop |
{action: list} → the group's Item Shop items; {action: buy, uuid, item, quantity?, money?}; {action: sell, uuid, item, lots} (item shop) |
| GET | /server/translations?version= |
Every language's words; {changed:false} when current (translations) |
| POST | /server/bounties |
{uuid, action: place|check|list|claim, target?, target_uuid?, amount?} (bounties) |
| POST | /server/console |
{lines:[...]}, up to 500 new lines of logs/latest.log (console) |
| POST | /tebex/webhook |
Tebex webhooks (signed with the webhook secret): payments, refunds, disputes, subscriptions ending (Store) |
| POST | /server/jobs |
Jobs: config, player, menu, join, leave, save (progress and level-ups; the reply hands back job XP from quests), change, change_status, change_cancel (job change requests for staff) (network/Players/Jobs.sk) |
| POST | /server/islands |
Islands: config, get, create, build (blocks from the last save, else the schematic), heartbeat (islands loaded here; rules and members back), rules (changed in game), save (blocks, chests and mobs), visit, subscription (the owner's island subscription and the coins offer), subscribe (buy or renew it with global coins at the price shown, optional days for a length, else the shortest; a refusal has reason coins_off, offer_gone, price_changed or insufficient_funds, with need and have). get, create, build and visit need the island's owner to have an island subscription (subscription_required when not) (survival/game/Server/Game/Islands/Island.sk) |
| POST | /server/tag |
Tag: config (settings, skills, maps), player, buy / upgrade / equip, spawn / clear_spawns, result (tag/Tag.sk) |
| POST | /server/pit-skills |
Pit skills: config (slot levels, skills), player, buy / upgrade / equip (pit/Combat/Skills.sk) |
| GET | /server/bosses?version= |
Bosses on for this server's category: stats, equipment, summon item, reward set and special attacks with compiled timelines for network/Combat/Anim.sk, and lookup (what /bosses shows players: stats, attacks in words, summoning, dungeons, rewards with chances; null for bosses hidden from the lookup); {changed:false} when the version is current (network/Combat/Bosses.sk) |
| GET | /server/combat?version= |
Combat: this server's combat settings, elements and reactions, weapon skills (with compiled timelines for network/Combat/Anim.sk) and custom enchantments; {changed:false} when the version is current (network/Combat/Combat.sk) |
| POST | /server/classes |
Classes and class skills: config (on here?, rules, classes, skills), player, choose, buy / upgrade / equip (network/Players/Classes.sk) |
| POST | /server/skill-xp |
Skill levels from casting: config (enabled, xp_per_cast, passive_seconds, levels, per_skill), player {uuid} (skills: {"pit:3": {xp, level}}), record {players: [{uuid, casts: {"class:12": 2}}]} (queued every 30 seconds; skills the player doesn't own are skipped, at most 500 casts per skill per batch, level-ups notify the player) (network/Players/SkillXp.sk) |
| POST | /server/pit-kit |
Pit kit layout: get, save (slots), reset (pit/Kits/KitLayout.sk) |
| POST | /server/crews |
{uuid, action: info|invite|accept|decline|leave|war|quests|rewards, target?, extra?}: war takes target status/declare/accept/decline/cancel/surrender/mutual and extra a crew tag; rewards hands out waiting crew quest items, money and XP (crews) |
| GET | /server/news?limit=5 |
The latest live announcements and news players can read (portal or website), pinned first: type, title, summary, date and the link to read it (the website's page when it's set up) (network/Panel/News.sk, /news) |
| POST | /server/script-load |
{trigger: start|update|reload, version?, log}: Skript's ERROR and WARN lines from logs/latest.log after this server loaded its scripts; replaces its last load report (updater/Updater.sk, see Script load results in updates.md) |
Public API (API tokens) #
Send Authorization: Bearer ntk_… (from API tokens). 120 requests/minute per token. A missing or revoked token gets 401, a missing ability 403.
| Method | Path | Ability |
|---|---|---|
| GET | /players?search=&online=1&per_page= |
players.read |
| GET | /players/{uuid or username} |
players.read (+ players.stats adds coins, badges, quests completed, crew) |
| GET | /players/{player}/punishments |
players.punishments |
| POST | /players/{player}/message {message} |
players.message (in-game message if online; audited) |
| GET | /servers, /servers/{identifier} |
servers.read |
| POST | /servers/broadcast {message, group?} |
servers.broadcast (audited) |
Queue semantics #
Queue semantics. A global action creates one row per enabled server, so each server acknowledges its own copy. Actions are claimed under a row lock. If an action isn't acknowledged within 60 seconds it's delivered again, up to 3 attempts, then marked failed. A failed ack is retried with backoff; rejected is final. Undelivered actions expire after their TTL: 30 minutes by default, 5 minutes for broadcasts, never for rank changes. You can retry or cancel actions from Action queue.
Data safety #
Data safety. A server can only write a player's data while the player is on that server (not_session_owner). Every save also sends base_version. A server can't overwrite a newer version written by a different server (stale_version), which protects progress after a server ran offline from its local cache.
Rate limits #
Rate limits. By default, 600 requests/minute per server and 30 auth attempts/minute per IP (NETWORK_API_RATE, NETWORK_AUTH_RATE). Responses are 429 {"error":"rate_limited"} with Retry-After, and Skript pauses for that long.
Trusted server IPs. Once a server signs in to auth with its API key, its IP is trusted, and nothing under /api/v1/server is rate limited from it (several servers on one machine share an IP). Trust lasts 30 days from the last sign-in, and goes when the server is deleted. To trust an IP by hand, add it to NETWORK_TRUSTED_IPS (comma-separated). Behind a reverse proxy, set TRUSTED_PROXIES first, or the proxy's IP gets trusted for everyone.
Keys #
Keys. The API key (nsk_…) is shown once when a server is registered or its key is rotated, and only a SHA-256 hash is stored. Bearer tokens (nst_…) last 24 hours and are also stored hashed. Rotating the key, revoking tokens or disabling the server cuts access immediately. You can also restrict each server to specific source IPs.
Player API #
Players make up to 3 read-only tokens at Account > API (me.read, public.read). Routes are under /api/v1/player (me, me/stats, me/history, players/{name}, .../stats, .../history, leaderboards/{stat}), limited per token to 150 requests a minute or 300 with Premium (player-api limiter, with X-RateLimit-* headers and a JSON 429). Docs are public at /developers. Staff tokens can't use it.
Website API and WordPress plugin #
Tokens from Developers > API tokens with the site.read ability can read what the public pages show. Send them as Authorization: Bearer ntk_.... All of these are GET, limited to 120 requests a minute, and follow the same rules as their page, so hidden, draft and private things stay out.
Route under /api/v1/site |
Gives | Options |
|---|---|---|
overview |
Network name, players online, each game mode | |
updates |
Updates log, with the body as Markdown and HTML | type, mode, per_page, page |
news |
Live announcements and news ticked for the website, pinned first: slug, type, title, summary, HTML, picture, category, tags, author, dates | type (news, announcement), category, per_page, page |
news/{slug} |
One of those, or 404 | |
events |
Events on now, coming up, and ended in the last 14 days | |
partners |
Visible partners, and the tags to filter by | tag, per_page, page |
leaderboards, leaderboards/{key} |
Public leaderboards with their entries | |
crews, crews/{tag} |
Public crews; a private crew shows its tag and name only | search, per_page, page |
players |
Player search: public profiles whose name has these letters, exact match first, then names starting with them, then the rest. Private profiles are never found. Each has username, premium, head, url (their profile). 422 unless search is 2 to 16 letters, numbers or _ |
search, limit (up to 25, default 10) |
players/{name} |
A public profile, with only the sections its player chose; game modes with their slug, and head |
|
players/{name}/stats |
Stats per game mode and added up, Premium, head; private players show as private | |
players/{name}/history |
One stat by day | stat, mode, days |
stat-leaderboards, stat-leaderboards/{stat} |
What can be ranked; the top players for one stat, with heads | mode, limit (up to 100) |
store |
Premium and credit products, whether the store is open, buy links on the portal; coin_name and coin_offers (Player and Crew: Premium for global coins, when on); passes (the island subscription and Pets Premium: lengths for coins, the PayPal option and a link); gift_cards (a link, or null when off); discount_codes (codes are entered on the panel) |
|
programs |
Open programs (YouTuber and so on): name, description, requirements, profile tag, member count and the link to apply |
integrations/wordpress/neutine-portal is a WordPress plugin that uses these. Zip that folder and upload it in WordPress, then fill in Settings > Neutine Portal. Give it a token with only site.read. It adds the shortcodes neutine_status, neutine_updates, neutine_events, neutine_partners, neutine_leaderboard, neutine_stat_leaderboard (any stat, with heads), neutine_crews, neutine_crew, neutine_player, neutine_stats (stats and a history graph), neutine_store (everything for sale in tabs: Premium, Crew: Premium, the island subscription, Pets Premium, credits and gift cards, with every way to pay above them: PayPal, global coins, credits, gift cards and discount codes; bought on the panel; layout="list" for one long list), neutine_news (news, opening each article on the same page), neutine_programs (programs to apply to on the panel) and neutine_player_search. Version 1.5.6; integrations/wordpress/neutine-portal.zip is the folder ready to upload. The token stays on the WordPress server, answers are cached there, and visitors get the last good answer if the panel is down.
- Player search (
[neutine_player_search page="/player/" limit="10"], or the Neutine player search block): a search box. Results link topage?name=Name(older links with?neutine_name=still work); put[neutine_stats]or[neutine_player]with nonameon that page and it shows the player in the address. Withoutpage, results open the player's profile on the panel. - One game mode at a time:
[neutine_stats]and[neutine_player]show the most played game mode with links to the others (?neutine_mode=<slug>, andallfor the network totals in[neutine_stats]). A fixedmode="pit"shows only that game mode, with no links. - What visitors type (a search, a name or game mode in the address) is checked first (letters, numbers and
_; game modes must be the player's own), kept for a minute, and the site asks the panel at most 60 times a minute for these, so visitors can't make the panel do lots of work. Everything else is cached as before. - Heads fall back to a plain face if mc-heads.net can't load.