# POST /reload

[back to admin](README.md) /// [home](../README.md)

Hotreload server configuration. Rereads all config files, merges with DB settings, rebuilds the permission system. All without downtime hopefully maybe.

Requires power >= `min_reload_power` (configurable).

## Request Body (optional)

```json
{
  "restart": false,
  "forced": false
}
```

| Field     | Type    | Default | Notes                                    |
|-----------|---------|---------|------------------------------------------|
| `restart` | boolean | false   | schedule a full server restart (reexec)  |
| `forced`  | boolean | false   | skip idle wait and restart immediately   |

If you send no body at all the server just does a config reload without restarting.

## Why restart?

Some things might be unable to be hot reloaded because theyre baked in the oven at startup such as:
- rate limiter settings
- server port
- database connection settings
- scheduled queries

For these feel free to do a full restart. A compliant server should reexec itself (same binary, fresh process).

## Restart modes

### Graceful restart (`restart: true, forced: false`)

Schedules a restart that waits for a configurable idle period before actually restarting. If theres user activity the timer should reset so you dont pull the rug from under active users lol.

Response:

```json
{
  "success": true,
  "message": "Configuration reloaded: server will restart after 30s of idle time...",
  "request_id": "abc123",
  "restarting": true,
  "restart_wait_seconds": 30,
  "note": "Server restart is scheduled to apply heavy config changes (rate limits)."
}
```

### Forced restart (`restart: true, forced: true`)

Restarts immediately, server should flush cached sessions to the database if it supports persistant sessions first (with a reasonable timeout so a dead DB doesnt block the restart) then reexec.

Because the server dies before it can send a json derulo response back the client wont really get a response. Just fire and forget, then wait for jsonderulo to come back lol.

Should require higher power than a normal reload (configurable via `min_manual_restart_power`).

### No restart (`restart: false`)

Just reloads config. Fast and safe.

```json
{
  "success": true,
  "message": "Configuration reloaded successfully (TOML + DB merged, RBAC rebuilt)",
  "request_id": "abc123",
  "restarting": false,
  "note": "Rate limiter and scheduled query changes require a restart to take effect."
}
```

## Error Responses

| Code | When                                                    |
|------|---------------------------------------------------------|
| 401  | no token or invalid session                             |
| 403  | power level too low (for reload or for restart)         |
| 500  | config reload failed (bad config syntax, DB error, etc) |