Mudhaven - The Guild of Worlds

API Reference

One contract across every world.

All endpoints use HTTPS, versioned paths, bounded inputs, predictable JSON errors, and narrow authorization.

v1
01

Endpoint index

Available version 1 APIs

POST/api/v1/mud/worlds/{endpoint-key}/heartbeatMUD heartbeat POST/api/v1/byond/projects/{project-key}/heartbeatBYOND heartbeat GET/api/v1/weather/alertsWeather alerts
02

Transport and format

HTTPS and JSON

  • Use the canonical host https://mudhaven.net.
  • JSON clients send Content-Type: application/json.
  • BYOND may use its associative form POST contract.
  • API failures return JSON even when the request was form encoded.
  • Unknown fields are rejected instead of silently retained.
03

Authentication

Project-scoped heartbeat credentials

MUD and BYOND heartbeat credentials belong to one approved active service. Mudhaven stores only a SHA-256 token hash and an eight-character display hint. The plaintext token is displayed once and cannot be recovered later.

  • Prefer Authorization: Bearer TOKEN.
  • Never place a token in a URL query string.
  • Keep tokens out of public repositories, downloads, browsers, player clients, logs, and error reports.
  • Rotate after suspected disclosure; revoke when reporting should stop.
  • The weather endpoint is public and does not accept or require a token.
04

Response codes

Handle failures predictably

200AcceptedHeartbeat saved or public weather state returned.
401UnauthorizedEndpoint or token is invalid, revoked, or rotated.
403Inactive serviceThe hosting service is not currently approved and Active.
413Payload too largeThe request exceeded its bounded API body allowance.
422Invalid dataA required value, field, protocol, or configured custom type failed validation.
429Too many requestsReturn to the interval provided by the successful response.
500/503Temporary failureDo not block the game loop; retry later without exposing secrets in logs.
05

Intervals and limits

Follow the server's polling hints

MUD heartbeat60 seconds
BYOND heartbeat60 seconds
Weather polling300 seconds
Heartbeat offline300 seconds

Successful responses provide the authoritative recommended interval. Rate limits are abuse ceilings, not recommended operating frequencies.

06

Versioning

Stable paths, additive evolution

Current endpoints live under /api/v1. Mudhaven may add optional response fields without changing the version, so clients should ignore fields they do not understand. Breaking request or meaning changes require a new versioned path and a documented migration period.

07

Related public data

MSSP discovery documents

An eligible approved MUD listing may publish a fresh directory document at /worlds/{world-slug}/mssp.json. This is a public discovery document, not a heartbeat credential or control API. Availability depends on the owner's opt-in and fresh validated MSSP evidence.

Review MUD protocolsContact Mudhaven