PulseConnect API Reference

Conventions

Base URL

http://<your-server>:7070/api/v1

Default port is 7070, configurable via api.port in config.yml. The plugin serves plain HTTP — if you're exposing the API to the internet, put it behind a reverse proxy (nginx, Caddy, Cloudflare) for HTTPS.

Authentication

All endpoints except POST /auth/login and POST /auth/register require a JWT in the Authorization header:

Authorization: Bearer <token>

Tokens are obtained via login (see below). They expire after 24 hours by default (api.token-expiry-hours in config). When a token expires, the server returns 401 Unauthorized and the client should re-login.

Content type

All request bodies are JSON. All response bodies are JSON. Set Content-Type: application/json on requests.

Errors

Failed requests return an HTTP error status (4xx or 5xx) with a JSON body:

{ "error": "Human-readable message" }

Common status codes:

Permissions

Most endpoints require a specific permission. The Owner role bypasses all permission checks. Other staff have the permissions explicitly granted to them by the Owner.

The full permission catalog is documented at the bottom of this page.

Auth

Bootstrap and registration

POST /auth/register creates user accounts. There are two distinct modes:

Bootstrap mode — when zero accounts exist in the database (fresh install, or after the database has been wiped), /auth/register is callable without authentication. The first call creates the Owner. Once any account exists, bootstrap mode closes permanently and the endpoint requires an Owner JWT.

In practice, the Owner is normally created automatically from the admin: block in config.yml on first server startup, and direct calls to /auth/register are only needed for the post-bootstrap case (creating additional staff users, which require Owner auth).

Request body for both modes:

{
  "username": "new-user",
  "password": "their-password",
  "role": "staff"
}

role is "owner" or "staff". Only one Owner exists per server; attempting to create a second returns 409 Conflict.

Login (worked example)

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your-password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "username": "admin",
  "role": "owner"
}

After 5 failed attempts in 15 minutes (configurable), the (username, IP) pair is locked out and 429 Too Many Requests is returned. The lockout window resets on a successful login.

/auth/me response shape

{
  "username": "admin",
  "role": "owner",
  "permissions": ["dashboard.view", "console.view", "..."]
}

For Owner accounts, permissions is the full catalog. For other roles, it's only what the Owner has granted.

Server

Status (worked example)

GET /api/v1/server/status
Authorization: Bearer <token>

Response:

{
  "online": true,
  "version": "Paper 1.21.4",
  "motd": "A Minecraft Server",
  "onlinePlayers": 3,
  "maxPlayers": 20,
  "tps1m": 19.98,
  "tps5m": 19.95,
  "tps15m": 19.93,
  "usedMemoryMb": 2048,
  "maxMemoryMb": 8192,
  "uptimeMs": 14400000
}

Players

Moderation

Console / Commands

Body: { "command": "say Hello world" }

Response: { "success": true, "message": "..." }

stop, restart, and reload are blocked at the command level — use the dedicated /server/* endpoints instead.

Tickets

Tickets are created by players in-game via /ticket create <message>, not via the API. The API is staff-side only.

Worlds

Analytics

Files

The file editor is sandboxed to the server's plugins/ directory. Symlinks that escape are rejected by canonical-path validation. Editable extensions: .yml, .yaml, .json, .properties, .txt, .conf. Other files are listed but not editable. 1MB file size cap.

Writes use optimistic locking via the expected_hash field. If the file changed since you last read it, the server returns 409 Conflict with the current hash so you can re-read and decide whether to overwrite.

Write request

{
  "path": "Essentials/config.yml",
  "content": "...",
  "expected_hash": "sha256-of-the-content-when-you-last-read-it"
}

Conflict response (409)

{
  "error": "File changed since you last read it",
  "current_hash": "sha256-of-current-content"
}

Notifications (push)

Per-user, self-service. Used by the iOS app to register device tokens for APNs. No permission required beyond authentication.

Third-party integrations can ignore this section unless they're building their own iOS app.

Audit Log

Pagination is keyset-based: pass the timestamp of the oldest row from the previous page as before.

WebSocket

A single WebSocket connection delivers all real-time events.

ws://<server>:7070/api/v1/ws?token=<jwt>

The token is passed as a query parameter (WebSocket upgrades don't carry custom headers reliably across implementations). It's verified on connect; an invalid token closes the connection immediately with code 1008.

Envelope

Every server-to-client message has this envelope:

{
  "type": "event_type",
  "data": { ... },
  "timestamp": 1730390400000
}

timestamp is server-side milliseconds since epoch, applied at the moment the event was produced. Per-event fields go in data.

Event types

Example payload

{
  "type": "chat",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Notch",
    "message": "hello world"
  },
  "timestamp": 1730390400000
}

Client-to-server messages

Clients can send messages on the WebSocket, but the plugin currently only logs them — there are no client-initiated commands over the WebSocket. To execute a server command, use POST /command.

Permissions Catalog

The complete list of permission keys, used in PUT /auth/users/{username}/permissions:

Defaults

When the Owner creates a new staff user without specifying permissions explicitly, they get a view-only set:

dashboard.view, analytics.view, console.view, players.view, tickets.view, worlds.view, chat.view, files.view, notifications.server_lag, notifications.server_stop

The Owner toggles individual write permissions on per-staff-member.

Versioning

The API is versioned in the URL path (/api/v1/...). Breaking changes will go to /api/v2; /api/v1 will continue to work alongside.

Adding new endpoints, new optional fields, or new permission keys is not considered breaking. Removing or renaming endpoints, removing fields, or changing field types is.

Examples

Get current player count (curl)

TOKEN=$(curl -s -X POST http://localhost:7070/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}' \
  | jq -r .token)

curl -s http://localhost:7070/api/v1/server/status \
  -H "Authorization: Bearer $TOKEN" \
  | jq .onlinePlayers

Send a broadcast from a Discord bot (Python)

import requests

base = "http://your-server:7070/api/v1"

# Login once at startup
token = requests.post(f"{base}/auth/login", json={
    "username": "discord-bot",
    "password": "..."
}).json()["token"]

headers = {"Authorization": f"Bearer {token}"}

# Send a broadcast
requests.post(f"{base}/command", headers=headers, json={
    "command": "say [Discord] Server restart in 5 minutes"
})

Watch chat in real time (Node)

const WebSocket = require("ws");

const ws = new WebSocket(`ws://your-server:7070/api/v1/ws?token=${TOKEN}`);

ws.on("message", (data) => {
  const event = JSON.parse(data);
  if (event.type === "chat") {
    console.log(`<${event.data.name}> ${event.data.message}`);
  }
});

Support

• Bug reports / feature requests: email support@pulsepanelapp.com
• General questions: pulsepanelapp.com