Configuration

Note

This plugin hasn’t been approved by Modrinth yet, so you can’t download it from Modrinth right now.

HMTAPI’s config lives at plugins/HMTAPI/config.yml. It is created on first start and is never overwritten by an update.

The default file

# The interface the API binds to. Use "127.0.0.1" to only allow local access.
bind_address: "0.0.0.0"
# The port the API runs on. Must be between 1 and 65535.
port: 4567
# How long a request may wait for the server thread. Must be between 1 and 60.
request_timeout_seconds: 5

# Any valid Java time zone ID, e.g. "UTC" or "Europe/Berlin".
time_zone: "UTC"
# Any valid java.time DateTimeFormatter pattern.
date_format: "yyyy/MM/dd HH:mm:ss"
# Used instead of a date when a player has never joined your server.
never_seen_value: "never"

endpoints:
  users:
    require_player: true
    object:
      username: "{username}"
      last_login: "{last_login}"
      balance: "{papi:%vault_eco_balance%}"

  global:
    require_player: false
    object:
      server_name: "{papi:%server_name%}"

Server settings

bind_address

The network interface the API listens on.

Default	0.0.0.0
Example	127.0.0.1, 192.168.1.20

0.0.0.0 accepts connections from every network your server is attached to, which is what you want if the API should be reachable from the internet. 127.0.0.1 accepts connections from the machine itself only.

If you want the API reachable only from a local reverse proxy, set this to 127.0.0.1. See Security.

port

The TCP port the API listens on.

Default	4567
Range	1 – 65535

If the port is already in use, HMTAPI logs an error and disables itself rather than crashing the server. Common conflicts are 25565 (Minecraft itself) and ports used by a proxy or panel.

request_timeout_seconds

How long a request may wait for the Minecraft server before HMTAPI gives up on it.

Default	5
Range	1 – 60

A request needs the server to do the work, for example looking up a player and running PlaceholderAPI placeholders. On a busy server this can take a moment. If a request runs longer than this limit, HMTAPI answers with 503 and moves on rather than letting requests pile up.

Raise this if you regularly get 503 responses on a laggy server. Lower it if you want fast failures. See Performance.

Formatting settings

These control how {last_login} and {last_seen} are rendered.

time_zone

The time zone dates are converted to.

Default	UTC
Examples	UTC, Europe/Berlin, America/New_York

Any valid Java time zone ID works, including fixed offsets such as Europe/Berlin+02:00.

date_format

The pattern used to format dates.

Default	yyyy/MM/dd HH:mm:ss
Example	dd.MM.yyyy HH:mm

Any valid DateTimeFormatter pattern works. Common tokens:

Token	Meaning	Example
yyyy	Year	2026
MM	Month	09
dd	Day	25
HH	Hour (00–23)	22
mm	Minute	13
ss	Second	20

never_seen_value

Shown instead of a date when a player has never joined your server.

Default	never
Example	null, -, never joined

A player who has never logged in has no last-login date. HMTAPI substitutes this text instead.

Invalid values

HMTAPI never refuses to start because of a bad config value. If a setting is not usable, it logs a warning naming the setting, uses the default, and keeps serving. Your server stays up.

[HMTAPI] Invalid port '70000' in config.yml, it must be between 1 and 65535. Falling back to 4567.

The same applies to request_timeout_seconds, time_zone, date_format and bind_address. Always check the console after changing the config — warnings there explain why a setting is not what you expected.

What needs a restart

Setting	Applies on
bind_address	Restart only
port	Restart only
request_timeout_seconds	/hmtapi reload
time_zone	/hmtapi reload
date_format	/hmtapi reload
never_seen_value	/hmtapi reload
endpoints	/hmtapi reload

bind_address and port are read once when HMTAPI starts. If you change either and reload, HMTAPI tells you so in the console and keeps using the old address until the next restart.

Applying changes

/hmtapi reload

Requires the hmtapi.reload permission. See Commands.

Next steps

• Endpoints — the endpoints section in detail
• Placeholders — what you can put inside object