API Reference

Complete API documentation for PipeWorks MUD Server.

Overview

PipeWorks MUD Server provides:

  • REST API - FastAPI backend on port 8000

  • Python Package - mud_server with core game logic

  • Pydantic Models - Type-safe request/response schemas

Interactive API Docs

When the server is running, visit:

These provide interactive API exploration with:

  • All endpoints listed

  • Request/response schemas

  • Try-it-out functionality

  • Authentication testing

API Endpoints

Authentication

  • POST /register - Register temporary guest account (password must meet STANDARD policy)

  • POST /register-guest - Register guest account with server-generated username

  • POST /login - Log in and create session (returns character list)

  • POST /logout - Log out and destroy session

  • POST /change-password - Change password (password must meet STANDARD policy)

  • GET /characters - List characters for session

  • POST /characters/select - Select active character for session

Register Guest Examples

POST /register (client-supplied username)

curl -s -X POST http://localhost:8000/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "guest_demo",
    "password": "SecurePass#1234",
    "password_confirm": "SecurePass#1234"
  }'

Response (200):

{
  "success": true,
  "message": "Temporary account created successfully! You can now login as guest_demo."
}

POST /register-guest (server-generated username)

curl -s -X POST http://localhost:8000/register-guest \
  -H "Content-Type: application/json" \
  -d '{
    "password": "SecurePass#1234",
    "password_confirm": "SecurePass#1234",
    "character_name": "Guest Wanderer"
  }'

Response (200):

{
  "success": true,
  "message": "Temporary guest account created successfully! You can now login as guest_00421.",
  "username": "guest_00421"
}

Game Actions

  • POST /command - Execute game command

  • GET /status/{session_id} - Get character status

  • GET /chat/{session_id} - Get chat messages

Admin

  • GET /admin/database/players - List users (Admin+)

  • GET /admin/database/connections - Active connections (Admin+)

  • GET /admin/database/player-locations - Character locations (Admin+)

  • GET /admin/database/tables - Database table metadata (Admin+)

  • GET /admin/database/table/{table_name} - Table rows (Admin+)

  • GET /admin/database/sessions - Sessions (Admin+)

  • GET /admin/database/chat-messages - Chat logs (Admin+)

  • POST /admin/user/create - Create user account (Admin/Superuser)

  • POST /admin/user/manage - Manage user (change role, ban, delete, password)

  • POST /admin/session/kick - Kick session (Admin+)

  • POST /admin/server/stop - Stop server (Admin+)

  • POST /admin/ollama/command - Run Ollama command (Admin+)

  • POST /admin/ollama/clear-context - Clear Ollama context (Admin+)

Health

  • GET /health - Server health check

Authentication

All protected endpoints require a session_id. Depending on the endpoint, it is provided in the request body (POST), query string (GET), or URL path (/status/{session_id}, /chat/{session_id}).

Password Requirements

Registration and password changes enforce the STANDARD password policy:

  • Minimum 12 characters

  • Not a commonly used password (150+ blocked)

  • No sequential characters (abc, 123, xyz)

  • No excessive repeated characters (aaa, 1111)

Example Error Response (password too short):

{
    "detail": "Password must be at least 12 characters long (currently 8)"
}

Example Error Response (common password):

{
    "detail": "This password is too common and easily guessed. Please choose a more unique password."
}

See Security for complete password policy documentation.

Guest Accounts

Guest registrations are intended for testing/dev. Accounts created via POST /register are marked as temporary and automatically purged after 24 hours. Admin- or superuser-created accounts are not affected.

Session Creation

  1. Register: POST /register with username and password (must meet policy)

  2. Login: POST /login with credentials and receive character list

  3. Select: POST /characters/select with chosen character ID (if needed)

  4. Use: Include session_id in all subsequent requests

Session Format

Sessions are stored in the database and identified by opaque session IDs. The server validates the session ID, enforces expiration, and resolves the user role on each request.

Role-Based Access

Four user roles with hierarchical permissions:

Role

Permissions

Player

Play game, chat, manage own inventory

WorldBuilder

Player + create/edit rooms and items

Admin

WorldBuilder + create users, ban users, view logs, stop server

Superuser

Admin + role management, full system access

Error Handling

HTTP Status Codes

  • 200 OK - Request succeeded

  • 400 Bad Request - Invalid request data

  • 401 Unauthorized - Invalid or missing session

  • 403 Forbidden - Insufficient permissions

  • 404 Not Found - Resource not found

  • 500 Internal Server Error - Server error

Error Response Format

{
    "detail": "Error message describing what went wrong"
}

CORS Configuration

CORS origins are configured in config/server.ini or via environment variable.

Config File (config/server.ini):

[security]
cors_origins = https://yourdomain.com, https://api.yourdomain.com

Environment Variable (overrides config file):

export MUD_CORS_ORIGINS=https://yourdomain.com,https://api.yourdomain.com

Development default allows localhost origins only.

See config/server.example.ini for all available security settings.

WebSocket Support (Future)

Planned for real-time features:

  • Live chat updates

  • Player movement notifications

  • Room event broadcasting

Currently uses HTTP polling.

Python API Documentation

Full API documentation for all Python modules is available in the API Reference section, automatically generated from code docstrings.