> ## 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.

# Write endpoints

> All POST endpoints that require an X-API-Key header.

All `POST` routes require the `X-API-Key` header. Include your configured secret key with every write request.

```bash theme={null}
-H "X-API-Key: your_secret_key_here"
```

See [Authentication](/api/authentication) for details on generating and configuring the key.

## Error responses

These error responses apply to every write endpoint:

| Status | Meaning                                                         |
| ------ | --------------------------------------------------------------- |
| `401`  | Missing or incorrect `X-API-Key` header                         |
| `400`  | Bad request — missing field, invalid value, or disallowed input |
| `500`  | Internal server error                                           |

```json theme={null}
{ "ok": false, "error": "Unauthorized — X-API-Key required for write endpoints." }
```

```json theme={null}
{ "ok": false, "error": "<description of what was wrong>" }
```

```json theme={null}
{ "ok": false, "error": "Internal server error" }
```

***

## POST /api/server/start

Starts the Minecraft server by issuing `serv start`.

<Note>
  The start, stop, and restart endpoints send a command to the `serv` CLI and return immediately. A successful response means the command was issued — not that the server has finished starting or stopping. Poll [GET /api/status](/api/endpoints/read#get-apistatus) to confirm the resulting state.
</Note>

```bash theme={null}
curl -X POST http://your-server:6767/api/server/start \
  -H "X-API-Key: your_key"
```

**Response**

```json theme={null}
{
  "ok": true,
  "message": "Server start command issued."
}
```

<ResponseField name="ok" type="boolean" required>
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string" required>
  Confirmation that the command was issued.
</ResponseField>

***

## POST /api/server/stop

Stops the Minecraft server by issuing `serv stop`.

<Note>
  The start, stop, and restart endpoints send a command to the `serv` CLI and return immediately. A successful response means the command was issued — not that the server has fully stopped. Poll [GET /api/status](/api/endpoints/read#get-apistatus) to confirm the resulting state.
</Note>

```bash theme={null}
curl -X POST http://your-server:6767/api/server/stop \
  -H "X-API-Key: your_key"
```

**Response**

```json theme={null}
{
  "ok": true,
  "message": "Server stop command issued."
}
```

<ResponseField name="ok" type="boolean" required>
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string" required>
  Confirmation that the command was issued.
</ResponseField>

***

## POST /api/server/restart

Restarts the Minecraft server by issuing `serv restart`.

<Note>
  The start, stop, and restart endpoints send a command to the `serv` CLI and return immediately. A successful response means the command was issued — not that the restart has completed. Poll [GET /api/status](/api/endpoints/read#get-apistatus) to confirm the resulting state.
</Note>

```bash theme={null}
curl -X POST http://your-server:6767/api/server/restart \
  -H "X-API-Key: your_key"
```

**Response**

```json theme={null}
{
  "ok": true,
  "message": "Server restart command issued."
}
```

<ResponseField name="ok" type="boolean" required>
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string" required>
  Confirmation that the command was issued.
</ResponseField>

***

## POST /api/command

Sends a command directly to the Minecraft server console via tmux.

<ParamField body="command" type="string" required>
  The console command to send (e.g. `"say hello"`, `"op PlayerName"`, `"difficulty hard"`).
</ParamField>

<Warning>
  Commands containing shell special characters — `;`, `&`, `|`, `` ` ``, `$`, `(`, `)`, `{`, `}`, `[`, `]`, `<`, `>`, `\` — are rejected with a `400` error. These characters are blocked to prevent shell injection, since commands are forwarded directly to the server console over tmux.
</Warning>

```bash theme={null}
curl -X POST http://your-server:6767/api/command \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"command": "say hello"}'
```

**Response**

```json theme={null}
{
  "ok": true,
  "message": "Command sent: say hello"
}
```

<ResponseField name="ok" type="boolean" required>
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string" required>
  Confirmation including the command that was sent.
</ResponseField>

***

## POST /api/whitelist/add

Adds a player to the Minecraft server whitelist.

<ParamField body="player" type="string" required>
  The player's username. Must match `[a-zA-Z0-9_]{1,16}` — alphanumeric characters and underscores only, between 1 and 16 characters.
</ParamField>

```bash theme={null}
curl -X POST http://your-server:6767/api/whitelist/add \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"player": "NewPlayer"}'
```

**Response**

```json theme={null}
{
  "ok": true,
  "message": "NewPlayer added to whitelist."
}
```

<ResponseField name="ok" type="boolean" required>
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string" required>
  Confirmation including the player name that was added.
</ResponseField>

***

## POST /api/whitelist/remove

Removes a player from the Minecraft server whitelist.

<ParamField body="player" type="string" required>
  The player's username. Must match `[a-zA-Z0-9_]{1,16}` — alphanumeric characters and underscores only, between 1 and 16 characters.
</ParamField>

```bash theme={null}
curl -X POST http://your-server:6767/api/whitelist/remove \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"player": "OldPlayer"}'
```

**Response**

```json theme={null}
{
  "ok": true,
  "message": "OldPlayer removed from whitelist."
}
```

<ResponseField name="ok" type="boolean" required>
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string" required>
  Confirmation including the player name that was removed.
</ResponseField>

***

## POST /api/backup

Triggers a background backup by running `serv backup -s`. The backup runs silently in the background — the endpoint returns immediately without waiting for it to finish.

```bash theme={null}
curl -X POST http://your-server:6767/api/backup \
  -H "X-API-Key: your_key"
```

**Response**

```json theme={null}
{
  "ok": true,
  "message": "Backup triggered. Check /api/backups shortly."
}
```

<ResponseField name="ok" type="boolean" required>
  `true` when the backup process was launched successfully.
</ResponseField>

<ResponseField name="message" type="string" required>
  Confirmation that the backup was triggered. Poll [GET /api/backups](/api/endpoints/read#get-apibackups) to see when the new archive appears.
</ResponseField>