⌘
Librarian minecraftnoob.com
MinecraftNoob server documentation and integration reference

One place for server docs, APIs, and automation notes.

Librarian is the documentation and API entry point for the MinecraftNoob server stack. It explains how player-facing services work, which endpoints are available, how authentication is handled, and what third-party tools can safely integrate with.

The goal is simple: fewer guesses, fewer outdated wiki pages, and fewer plugin-specific instructions scattered across chat logs.

Read the docs Jump to API reference

What Librarian is for

This site is not a generic landing page. It is a working reference for people who need reliable information about the MinecraftNoob backend: plugin developers, automation maintainers, moderators, and anyone building small tools around the server.

Documentation

Service descriptions, integration rules, response formats, permission notes, and operational behavior.

  • Player and profile data model
  • Punishment and moderation events
  • Economy and account sync notes

API reference

A compact REST surface for internal dashboards, bots, web panels, and status pages.

  • Consistent JSON responses
  • Versioned endpoints
  • Clear auth requirements per route

Operational notes

The part people usually forget: rate limits, cache behavior, error meanings, and safe usage patterns.

  • Read-before-write integration policy
  • Audit-friendly token handling
  • Examples that match real requests

Documentation sections

Start here if you need context before touching the API. These sections explain the moving parts and the assumptions behind them, so integrators do not have to reverse-engineer the server behavior from trial and error.

Player records

UUID mapping, last seen timestamps, username history, linked services, and optional metadata exposed to staff tools.

Moderation data

Ban and mute states, staff notes, appeal references, and the distinction between live punishments and historical events.

Server health

Public status output, maintenance windows, degraded service markers, and behavior during restarts or partial outages.

Core API routes

The API is intentionally narrow. It exposes the data that external tools usually need without turning the server into a loosely controlled admin panel.

GET /status

Returns overall API health, current version, maintenance state, and basic backend availability markers.

GET /players/{uuid}

Fetches a player profile by UUID, including username, first seen, last seen, and service-specific flags.

GET /players/by-name/{username}

Resolves the latest known UUID for a player name. Intended for dashboards and lightweight moderation tooling.

GET /players/{uuid}/punishments

Lists active and historical moderation events visible to the token scope used for the request.

GET /leaderboards/playtime

Returns aggregated playtime rankings with pagination support and optional seasonal filters.

POST /events/ingest

Accepts trusted server-side event payloads from internal services. Not intended for public plugin usage.

Authentication and usage model

Librarian uses bearer tokens with narrow scopes. Public documentation is open to read, but the API itself should be treated as infrastructure, not as a general-purpose public endpoint.

How tokens are expected to work

  • Each integration gets its own token.
  • Read-only and write-enabled tokens are separate.
  • Tokens should be rotated when an integration changes ownership.
  • Server-to-server calls are preferred over browser-side requests.

Practical limits

  • Requests may be throttled per token and per IP.
  • Write routes should be considered internal unless explicitly documented otherwise.
  • Error payloads are structured, but sensitive backend details are intentionally omitted.
  • Old versions may be removed after a deprecation window.
Do not embed privileged API tokens in public websites, public client mods, or distributed launcher builds. Treat them as backend secrets.

Request examples

Example payloads are kept short on purpose. They show expected structure and naming, not every possible field the backend may expose for internal consumers.

Fetch a player record curl 
curl -s https://librarian.minecraftnoob.com/api/v1/players/3f1f3b71-85d2-4f32-8c63-1f4f0b9379b8 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
Example response json 
{
  "uuid": "3f1f3b71-85d2-4f32-8c63-1f4f0b9379b8",
  "username": "StoneReader",
  "first_seen": "2026-02-14T18:22:09Z",
  "last_seen": "2026-04-13T21:08:11Z",
  "flags": {
    "staff": false,
    "banned": false,
    "muted": false
  }
}
Read service status curl 
curl -s https://librarian.minecraftnoob.com/api/v1/status \
  -H "Accept: application/json"
Status response json 
{
  "status": "ok",
  "version": "v1",
  "maintenance": false,
  "time": "2026-04-14T12:00:00Z"
}

Getting started

For most integrations, the onboarding path is straightforward. The documentation is meant to be read in one pass, not pieced together from ten separate pages.

Read the data model first

Check how player identity, moderation state, and timestamps are represented before writing any integration logic.

Request a scoped token

Use a read-only token unless your service genuinely needs write access for trusted server-side event delivery.

Build against versioned routes

Use /api/v1 explicitly. Do not depend on undocumented fields or response ordering.

Handle failure states cleanly

Expect permission errors, throttling, and maintenance windows. Retry carefully and log response bodies for debugging.

FAQ

The questions below cover the usual edge cases: public access, plugin usage, and what this API is not designed to do.

Is the whole API public?

No. The documentation can be public, but most useful routes require a token. Public access is typically limited to status or other intentionally exposed metadata.

Can I call it directly from a Minecraft plugin?

Yes, but server-side integrations are preferred. Browser-side or client-distributed usage is a poor place for privileged credentials.

Does Librarian replace plugin configuration docs?

No. It complements them. Plugin-specific configuration should still live with the plugin or deployment repository. Librarian explains shared backend behavior.

Will fields change without notice?

The contract should remain stable inside a versioned API branch. Breaking changes belong in a new version or in a documented deprecation cycle.