MUD Game API

Report your world in one heartbeat.

An approved hosted MUD can replace one current public snapshot every minute. Mudhaven cannot use this credential for shell access, files, databases, game commands, or member authentication.

POST

Endpoint

Send the current snapshot

POSThttps://mudhaven.net/api/v1/mud/worlds/{endpoint-key}/heartbeat

The endpoint key begins with mud_ and is not a sequential database ID. The approved service owner receives the exact endpoint and a one-time token from Account Hosting.

Authentication

Use a server-side Bearer token

Authorization: Bearer YOUR_MUD_API_TOKEN
Content-Type: application/json

Never publish this token.

Keep it out of downloadable source, player-visible commands, logs, crash reports, repositories, and browser code. Rotation invalidates the previous token immediately.

Request body

Send public game facts only

FieldRequirementContract

statusRequiredonline, starting, or maintenance

playersRequiredInteger from 0 through 10,000

max_playersOptional1 through 10,000; never below current players

game_versionOptionalPublic label up to 64 characters

codebase_versionOptionalPublic engine/codebase label up to 64 characters

uptime_secondsOptionalNon-negative integer capped at ten years

rooms, areas, mobiles, objectsOptionalBounded non-negative world totals

protocolsOptionalKnown keys with strict JSON booleans

customOptionalUp to six owner-configured public facts

Example

Post JSON with curl

curl --fail-with-body --silent --show-error \
  --request POST \
  --url "YOUR_MUD_HEARTBEAT_ENDPOINT" \
  --header "Authorization: Bearer YOUR_MUD_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"status":"online","players":12,"game_version":"2.4.1","uptime_seconds":86400,"protocols":{"mssp":true,"gmcp":true}}'

Accepted response

{
  "ok": true,
  "world": "mud_random_endpoint_key",
  "received_at": "2026-08-11T12:00:00+00:00",
  "recommended_interval_seconds": 60,
  "offline_after_seconds": 300,
  "accepted_protocols": 2,
  "accepted_custom_fields": 0
}

Optional facts

Protocols and custom fields

Accepted protocol keys are mssp, gmcp, msdp, mccp2, mtts, mxp, mslp, msp, tls, and websocket. Values must be literal JSON true or false.

Custom keys must be configured by the owner before the game sends them. Supported types are short text, non-negative integers, and booleans. Every heartbeat replaces the previous custom snapshot, so omitted values disappear.

Do not send private data.

Player names, accounts, email addresses, IP addresses, chat, passwords, saves, database details, and arbitrary metadata are rejected or prohibited.

Timing

Report once per minute

Use the response's recommended_interval_seconds. By default, a report becomes delayed after 150 seconds and offline after 300 seconds. Mudhaven stores one mutable snapshot and preserves the highest reported player count.

Review response codes Add weather announcements