Server API

An API for your Minecraft server (a plugin or mod), a bot or your own backend: enforce the same whitelist the launcher uses, manage it, and report how many players are online.

API keys

Create keys in the dashboard under Developer → API keys. Each key has:

• a name, so you know which server uses it;
• permissions — give it only what it needs;
• optionally, a list of instances it may touch (all by default);
• optionally, an expiry.

Two presets cover the usual cases: Server plugin (instances:read, whitelist:read, status:write) and Whitelist manager (instances:read, whitelist:read, whitelist:write).

The key (nk_…) is shown once; only a hash is stored. Send it as:

x-api-key: nk_…

Keep it on the server only, never in a player's client. Revoke a key from the same page; it stops working at once. A workspace can have up to 25 keys.

The original single workspace key (Settings → API key) still works. It acts as a key with instances:read, whitelist:read and status:write on every instance.

Base URL: https://api.neko-launcher.com/api/v1/server. Responses use the envelope { code, message, data }.

Routes

An instance outside the key's instance list answers 404, as if it did not exist.

List instances

GET /server/instances

data is the list of instances this key may read (name, displayName, visibility, enforceWhitelist, whitelistCount).

Check one player

GET /server/instances/<name>/whitelist/check?uuid=<uuid>
GET /server/instances/<name>/whitelist/check?username=<name>

Either query parameter; UUID with or without dashes, username case-insensitive.

{ "code": 200, "message": "OK", "data": { "allowed": true, "matchType": "uuid" } }
json

allowed follows the launcher's own rule: true for an open instance (OFFICIAL, or PUBLIC/UNLISTED without Enforce whitelist), otherwise true only for an active whitelist entry.

Read the whitelist

GET /server/instances/<name>/whitelist?limit=500&cursor=<nextCursor>

Pages of active entries (id, matchType, minecraftUuid, username, addedAt, expiresAt). limit defaults to 500, maximum 2000; pass nextCursor from the previous page to continue until it is null.

Change the whitelist

The write routes take the same bodies as the Whitelist API: add with { value, matchType?, username?, expiresAt? }, set an expiry with { expiresAt } (null clears it), bulk routes with up to 1000 ids.

curl -X POST https://api.neko-launcher.com/api/v1/server/instances/my-smp/whitelist \
  -H "x-api-key: nk_..." -H "content-type: application/json" \
  -d '{"value":"Notch","expiresAt":"2026-12-31T23:59:00+07:00"}'
bash

Changes made here send the same webhooks as changes made in the dashboard.

Report online players

POST https://api.neko-launcher.com/mcstatus/report
{ "instanceId": "<name>", "online": 12 }

The launcher shows this number on the instance card.

Errors

SDK

The official Node.js SDK wraps every route and verifies webhooks. It has no dependencies and works on Node 18+.

npm install @neko-launcher/sdk
bash

import { NekoClient, constructEvent } from '@neko-launcher/sdk';

const neko = new NekoClient({ apiKey: process.env.NEKO_API_KEY });

const { allowed } = await neko.checkPlayer('my-smp', { uuid: player.uuid });

for await (const entry of neko.whitelistEntries('my-smp')) {
  // full sync, page by page
}

const entry = await neko.addPlayer('my-smp', { value: 'Notch', expiresAt: new Date(Date.now() + 30 * 864e5) });
await neko.setExpiry('my-smp', entry.id, null);
await neko.removePlayer('my-smp', entry.id);
await neko.reportOnline('my-smp', 12);

// In your webhook endpoint (raw body!)
const event = constructEvent({ body: rawBody, headers: req.headers, secret: process.env.NEKO_WEBHOOK_SECRET });
js

Failed calls throw NekoApiError with the HTTP status and the API's message. See the package README for every method.

Example: a login check

Loading diagram…

Cache positive answers for a minute or two and fail closed (deny) if the API cannot be reached, or fail open according to your own policy; the API is not on the game's hot path otherwise. For large servers, sync the full list with whitelistEntries() on start-up and keep it current with webhooks.

See also

• Whitelist API and webhooks
• Whitelist and applications
• HTTP headers and authentication