Reference

API

Everything the web panel does goes through a REST API under /api/v1, documented as OpenAPI 3.1. Use it for billing systems, Discord bots, scripts and monitoring.

• API reference: every endpoint, parameter and response, generated from the OpenAPI document.
• Your own panel serves the same reference at /api/v1/docs and the raw document at /api/v1/openapi.json.

Authentication

There are two ways to authenticate.

API keys (recommended for tools)

Create a key on your account page under API keys (Users and permissions) and send it as a bearer token:

curl -s https://panel.example.com/api/v1/services \
  -H "Authorization: Bearer ngcpk_..."

• A key acts as the account that created it, limited by the key’s scopes if it has any.
• Keys do not need CSRF tokens.
• Keys cannot create other keys, change passwords or change two-step verification.
• The admin IP allow-list applies to keys of SuperAdmins and Admins.
• A scoped key reaches services only if its scopes include services:all or services:create.

Session cookie (what the browser uses)

1. Sign in:

   curl -s -c jar.txt -H "Content-Type: application/json" \
     -d '{"login": "alice", "password": "..."}' \
     https://panel.example.com/api/v1/auth/login
   

   The answer is either {"status": "ok", "csrf_token": "...", "user": {...}}, or, with two-step verification on, {"status": "mfa_required", "mfa_token": "..."}. In the second case send the code within five minutes:

   curl -s -c jar.txt -H "Content-Type: application/json" \
     -d '{"mfa_token": "...", "code": "123456"}' \
     https://panel.example.com/api/v1/auth/login/mfa
   

   ("recovery_code" instead of "code" uses a recovery code.)

2. The session lives in the ngcp_session cookie (HttpOnly). Every state-changing request (POST, PUT, PATCH, DELETE) must also carry the CSRF token in the X-CSRF-Token header. GET /api/v1/auth/me returns it again:

   curl -s -b jar.txt -X POST -H "X-CSRF-Token: <csrf_token>" \
     https://panel.example.com/api/v1/services/12/restart
   

3. POST /api/v1/auth/logout ends the session; POST /api/v1/auth/logout-all ends all of yours.

Request bodies must be JSON (Content-Type: application/json); the only exception is upload chunks.

Responses

Errors

Every error uses the same envelope:

{
  "error": {
    "code": "validation_failed",
    "message": "slots must be 2 to 256",
    "details": [
      {"location": "body.slots", "message": "must be 2 to 256", "value": 500}
    ]
  }
}

code is stable and meant for programs; message is meant for people. Common codes:

Unknown paths under /api/ always answer with this envelope, never with the web page.

Rate limits

Behind a reverse proxy, set NGCP_TRUSTED_PROXIES so limits apply per client, not per proxy.

Common tasks

H='Authorization: Bearer ngcpk_...'
P=https://panel.example.com/api/v1

# Services you can see, with live status
curl -s "$P/services" -H "$H"

# Start / stop / restart / kill / update / reinstall / cancel_install / suspend / unsuspend
curl -s -X POST "$P/services/12/start" -H "$H"

# Send a console line
curl -s -X POST "$P/services/12/console" -H "$H" -H 'Content-Type: application/json' -d '{"line": "say hello"}'

# Create a service
curl -s -X POST "$P/services" -H "$H" -H 'Content-Type: application/json' \
  -d '{"name": "Survival", "game_id": "minecraft_java", "node_id": 3, "slots": 20,
       "variables": {"accept_eula": "true"}, "start": true}'

# Nodes with status and metrics
curl -s "$P/nodes" -H "$H"

# Audit log
curl -s "$P/audit-events?limit=50" -H "$H"

Automation endpoints: Scheduled tasks, Backups, RCON and player counts, Mod manager, Notifications.

WebSocket

GET /ws upgrades to a WebSocket that carries live service updates and consoles. Browsers authenticate with the session cookie; tools can send Authorization: Bearer ngcpk_... on the upgrade request. The Origin, if sent, must be the panel’s own host.

Messages are JSON. Subscribe to topics:

{"type": "subscribe", "topic": "service:12"}
{"type": "subscribe", "topic": "console:12"}
{"type": "unsubscribe", "topic": "console:12"}
{"type": "input", "service_id": 12, "line": "say hello"}

Events look like {"type": "metrics", "topic": "service:12", "data": {...}}. Control answers are {"type": "subscribed" | "unsubscribed" | "error", "topic": "...", "message": "..."}.

• One socket can hold up to 64 topics. input lines are console input and are audited.
• The server pings every 25 seconds and re-checks your session every 30 seconds; signing out closes the socket with code 4001.
• A client that cannot keep up is disconnected (code 1013); reconnect and subscribe again.

Versioning

The API path carries the major version (/api/v1). NGCP is pre-1.0: endpoints may still be added or changed between releases; check the changelog. GET /api/v1/version returns the controller’s build version.