> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.eraus.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands

> What the API can run in your server, how a command gets there, and the rules it follows.

Send a command with [`POST /v1/server/commands`](https://apidocs.eraus.gg/api/run-command). The key needs the `commands` scope.

```json theme={null}
{ "command": ":peacetimer 15" }
```

The leading `:` is optional. Names and aliases aren't case sensitive.

## Command list

| Command | Aliases | Usage | What it does |
| - | - | - | - |
| `announce` | `ann`, `announcement`, `m`, `n`, `h` | `:announce <message>` | Shows a popup to everyone in the server. |
| `pm` | `message`, `dm`, `msg` | `:pm <player> <message>` | Shows a popup to one player. |
| `kick` | | `:kick <player> [reason]` | Kicks one player. |
| `ban` | | `:ban <player or user ID> [reason] [duration]` | Bans from this server. The duration goes last, such as `30m`, `12h`, `7d` or `1d12h`. Leave it out for a permanent ban. Works for players who aren't online. |
| `unban` | | `:unban <user ID>` | Lifts a ban. |
| `kill` | | `:kill <player>` | Kills one player. |
| `respawn` | `refresh`, `load` | `:respawn <player>` | Respawns one player. |
| `heal` | | `:heal <player>` | Heals one player to full. |
| `peacetimer` | `peace`, `ptimer` | `:peacetimer <minutes>` | Starts a peace timer, 1 to 120 minutes. Guns are put away. |
| `prioritytimer` | `prty`, `priority` | `:prioritytimer <minutes>` | Starts a priority timer, 1 to 120 minutes. |
| `endtimer` | `stoptimer` | `:endtimer [peace or priority]` | Ends one timer, or both if you don't say which. |
| `peacetime` | | `:peacetime <on or off>` | Turns peacetime on or off. |
| `weather` | `setweather` | `:weather <type>` | Sets the weather. `Auto` goes back to the normal cycle. |
| `time` | `settime` | `:time <HH:MM>` | Sets the time of day, in 24-hour time. |
| `carwipe` | `cw` | `:carwipe` | Clears every empty vehicle after a 1 minute countdown. Once a minute at most. |
| `lock` | | `:lock` | Only staff can join. |
| `unlock` | | `:unlock` | Anyone can join again. |
| `callout` | `incident` | `:callout [fire, robbery, pursuit, traffic, medical or random]` | Starts an incident callout. Needs the Roleplay Pack. |

[`GET /v1/commands`](https://apidocs.eraus.gg/api/list-commands) returns this list as JSON, so your tool can show it without hard-coding it.

## Rules

These rules are the same for every key, and the game checks them again before anything runs.

> [accordion] One player at a time, by exact name
>
> Player arguments must be an exact username (not case sensitive) or a Roblox user ID. Partial names, display names, `all`, `others` and `me` are refused, so a typo can't hit the wrong person or the whole server.

> [accordion] Staff and the owner are protected
>
> `kick`, `ban` and `kill` can't target the server owner, anyone with a staff rank, or ERA developers. Use the in-game console for staff.

> [accordion] Text is filtered
>
> Announcements, messages and reasons go through Roblox's text filter before anyone sees them. If filtering fails, the command fails. Unfiltered text is never shown. Messages can be up to 200 characters.

> [accordion] Always labelled as the API
>
> Popups are headed **\[API] · \<key name>** in blue, so players can tell them apart from staff. Kick and ban messages, peacetime notices and the server's command logs say `[API] <key name>` too. Name your keys clearly.

> [accordion] Commands that aren't listed can't run
>
> Anything not in the table, such as `:fly`, `:give`, `:god` or rank changes, is refused with `restricted_command` before it reaches the game.

> [accordion] Jailed and cuffed players stay put
>
> `respawn` won't work on a player who's cuffed, being held, or in jail, so it can't be used as a way out.

## How a command reaches the game

1. The API checks the key, the scope, the command and the rate limit, then answers `202` with a command id.
2. It sends the command straight to the live server through Roblox's messaging service. This usually takes under a second.
3. If that doesn't arrive, the server picks it up on its next sync, within about 10 seconds.
4. The server runs it once (repeats are ignored), then reports back whether it worked.
5. A command that hasn't reached the server within **60 seconds** expires and doesn't run.

Check the result with [`GET /v1/server/commands/{id}`](https://apidocs.eraus.gg/api/get-command):

```json theme={null}
{
  "id": "cmd_9qk3v0nfqg74ib8y",
  "command": ":kick Darkbot99 Spamming",
  "status": "succeeded",
  "message": "Kicked Darkbot99.",
  "key": "Discord Bot",
  "createdAt": 1793875464,
  "completedAt": 1793875465
}
```

| Status | Meaning |
| - | - |
| `queued` | Waiting for the server. |
| `succeeded` | It ran. `message` says what happened. |
| `failed` | The game refused it. `message` says why, such as "Staff and the owner can't be kicked through the API." |
| `expired` | It didn't reach the server within 60 seconds. |

Results are kept for 7 days. If you use [webhooks](https://apidocs.eraus.gg/webhooks.md), the `api.command` event delivers the same result as it happens.

## Limits

* 20 commands a minute per key (5 at once), and 30 a minute per server across all keys.
* The game also stops after 20 API commands in a minute, whatever the API allows.
* The server has to be online. Offline servers answer `server_offline`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.