> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poplock.scyne.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> A zero-dependency, single-file HTTP API for managing the PopLock Minecraft server.

The PopLock API is a single-file, zero-dependency Node.js HTTP server built on Node's built-in modules. It exposes a REST interface for reading server state and issuing management commands. The service runs as a systemd unit and survives reboots.

**Default port:** `6767`

## Base URL

```text theme={null}
http://<your-server-ip>:6767
```

## Endpoint tiers

The API splits its routes into two tiers:

* **Public read endpoints** — all `GET` routes. No authentication required. Safe to call from any client.
* **Secured write endpoints** — all `POST` routes. Require an `X-API-Key` header carrying your configured secret key.

See [Authentication](/api/authentication) for details on how to pass the key.

## Endpoint map

### Read endpoints (public)

| Method | Route                          | Description                                    |
| ------ | ------------------------------ | ---------------------------------------------- |
| `GET`  | `/`                            | Plain text `servreport` output                 |
| `GET`  | `/api`                         | Endpoint index and API version                 |
| `GET`  | `/api/status`                  | Online/offline status, version, uptime, memory |
| `GET`  | `/api/players/online`          | List of currently online players               |
| `GET`  | `/api/players/whitelist`       | Full whitelist                                 |
| `GET`  | `/api/logs/latest?lines=200`   | Latest server log (adjustable line count)      |
| `GET`  | `/api/logs/snapshot?lines=200` | Snapshot cron log                              |
| `GET`  | `/api/backups`                 | All backups listed with size and type          |
| `GET`  | `/api/properties`              | `server.properties` as JSON                    |
| `GET`  | `/api/report`                  | `servreport` as JSON                           |

### Write endpoints (secured — require `X-API-Key`)

| Method | Route                   | Description                                                   |
| ------ | ----------------------- | ------------------------------------------------------------- |
| `POST` | `/api/server/start`     | Start the Minecraft server                                    |
| `POST` | `/api/server/stop`      | Stop the Minecraft server                                     |
| `POST` | `/api/server/restart`   | Restart the Minecraft server                                  |
| `POST` | `/api/command`          | Send a console command (body: `{"command": "say hello"}`)     |
| `POST` | `/api/whitelist/add`    | Add player to whitelist (body: `{"player": "username"}`)      |
| `POST` | `/api/whitelist/remove` | Remove player from whitelist (body: `{"player": "username"}`) |
| `POST` | `/api/backup`           | Trigger a silent background backup                            |

For full request and response details, see [Read endpoints](/api/endpoints/read) and [Write endpoints](/api/endpoints/write).

## Get started

<CardGroup cols={2}>
  <Card title="Installation" icon="server" href="/api/installation">
    Copy the files, generate an API key, and start the systemd service.
  </Card>

  <Card title="Authentication" icon="key" href="/api/authentication">
    Learn how to pass your API key and handle auth errors.
  </Card>
</CardGroup>