Skip to main content

Meridian 59 API (m59api)

A companion tool for Meridian 59 servers providing two optional features:

  • HTTP API - Query and control your M59 server via the maintenance port
  • Discord Webhooks - Real-time game event notifications

Each feature requires configuration in your M59 server's blakserv.cfg. Use one or both.


Quick Start

1. Configure your M59 server

Edit blakserv.cfg to enable the features you want:

For HTTP API (maintenance port access):

[Socket]
MaintenancePort      9998
MaintenanceMask      127.0.0.1

For Discord Webhooks (game event notifications):

[Webhook]
Enabled              Yes

Note: Webhook support requires PR #1176 or later. If your server fork predates this, see that PR for the implementation.

2. Install m59api

pip install m59api

Windows + Webhooks: Also install pywin32 for named pipe support:

pip install pywin32

3. Set Discord webhook URL (if using webhooks)

# Windows PowerShell:
$env:DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"

# Linux/macOS:
export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"

4. Start services (order matters!)

# Start m59api FIRST
m59api

# Then start your M59 server
./blakserv

Important: m59api must be running before the M59 server starts. The server connects to pipes created by m59api. If you start the server first, webhooks will silently fail.

5. Use the features you configured


Installation

pip install m59api

Official PyPI page: https://pypi.org/project/m59api/


Command Line Options

m59api [OPTIONS]
Option Default Description
--host 127.0.0.1 Host to bind to
--port 8000 Port to bind to
--reload off Enable auto-reload for development
--log-level info Log level (debug, info, warning, error)
--config (auto-detect) Path to m59api.json config file

Examples:

# Default settings
m59api

# Custom host/port with debug logging
m59api --host 0.0.0.0 --port 8000 --log-level debug

# With explicit config file
m59api --config /path/to/m59api.json

Real-time Webhook Integration

m59api listens for messages from your Meridian 59 server via cross-platform pipes:

  • Windows: Named pipes \\.\pipe\m59apiwebhook1 through \\.\pipe\m59apiwebhook10
  • Linux/macOS: FIFO pipes /tmp/m59apiwebhook1 through /tmp/m59apiwebhook10

When your M59 server sends events, they appear in Discord as formatted messages with timestamps and emojis.


Multi-Server Webhook Routing

For running multiple M59 servers on the same machine, each routing to different Discord channels.

How It Works

Each M59 server can be configured with a prefix in its blakserv.cfg. The prefix determines which pipes the server writes to, and m59api routes messages from each prefix to a different Discord webhook.

  blakserv.cfg         named pipes                    m59api                 Discord
  ---------------      -------------------------      -----------------      ----------------
  Prefix: prod     --> prod_m59apiwebhook1-10     --> listener: prod     --> #prod-events
  Prefix: staging  --> staging_m59apiwebhook1-10  --> listener: staging  --> #staging-events
  Prefix: dev      --> dev_m59apiwebhook1-10      --> listener: dev      --> #dev-testing
  (no prefix)      --> m59apiwebhook1-10          --> listener: default  --> fallback webhook

The prefix is any string you choose. m59api.json maps each prefix to a webhook URL, and the router sends that prefix's messages to that channel. A server with no prefix uses the unprefixed pipes and the default webhook.

Configuration

Create m59api.json in one of these locations (searched in order):

  1. Path specified by --config CLI argument
  2. Path in M59API_CONFIG environment variable
  3. ./m59api.json (current directory)
  4. ~/.m59api.json (home directory)
  5. /etc/m59api.json (Linux/macOS only)

Example m59api.json:

{
  "default_webhook_url": "https://discord.com/api/webhooks/.../fallback",
  "servers": [
    {
      "prefix": "",
      "webhook_url": "https://discord.com/api/webhooks/.../main-server"
    },
    {
      "prefix": "prod",
      "webhook_url": "https://discord.com/api/webhooks/.../prod"
    },
    {
      "prefix": "staging",
      "webhook_url": "https://discord.com/api/webhooks/.../staging"
    },
    {
      "prefix": "dev",
      "webhook_url": "https://discord.com/api/webhooks/.../dev-testing"
    }
  ]
}

M59 Server Configuration

In each server's blakserv.cfg:

# Production server
[Webhook]
Enabled              Yes
Prefix               prod

# Staging server
[Webhook]
Enabled              Yes
Prefix               staging

# Dev server
[Webhook]
Enabled              Yes
Prefix               dev

Pipe Naming

Server Prefix Pipes Created (10 per server)
(empty) m59apiwebhook1 - m59apiwebhook10
prod prod_m59apiwebhook1 - prod_m59apiwebhook10
staging staging_m59apiwebhook1 - staging_m59apiwebhook10
dev dev_m59apiwebhook1 - dev_m59apiwebhook10

Backwards Compatibility

If no m59api.json is found, m59api falls back to the DISCORD_WEBHOOK_URL environment variable and creates the default (no-prefix) pipes. Existing single-server setups continue to work without changes.

Validation

  • Invalid webhook URLs (not starting with https://) log a warning but don't fail startup
  • Missing webhook_url for a server entry causes that entry to be skipped
  • No hot-reload: restart m59api after config changes

Troubleshooting

Config file not loading

Check which config file m59api is using:

m59api --log-level debug

Use an explicit path:

m59api --config /full/path/to/m59api.json

Webhooks not appearing in Discord

Check startup order:

# WRONG - server starts first, pipes don't exist yet
./blakserv &
m59api

# RIGHT - m59api creates pipes first
m59api &
sleep 2
./blakserv

Verify pipes exist:

# Windows PowerShell
Get-ChildItem \\.\pipe\ | Select-String "m59api"

# Linux/macOS
ls -la /tmp/*m59apiwebhook*

Test webhook URL manually:

curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"content":"Test message"}'

Messages going to wrong Discord channel

Check which webhook URL is routing to the pipe:

m59api --log-level debug
# Look for lines like: "Routing messages from prod_m59apiwebhook1 to https://..."

Verify prefix in your M59 server's blakserv.cfg:

[Webhook]
Prefix               prod  # Must match config file

m59api not receiving messages

Check M59 server webhook is enabled:

# In blakserv.cfg
[Webhook]
Enabled              Yes

Check pipe permissions (Linux/macOS):

ls -la /tmp/*m59apiwebhook*
# Should show: prw-rw-rw- (pipes)

Test pipe manually:

# Linux/macOS
echo '{"message":"Test from pipe"}' > /tmp/m59apiwebhook1

# Windows PowerShell
"Test" | Out-File -FilePath \\.\pipe\m59apiwebhook1 -Encoding ASCII

HTTP API not responding

Check maintenance port config:

# In blakserv.cfg
[Socket]
MaintenancePort      9998
MaintenanceMask      127.0.0.1

Test maintenance port:

# Should connect successfully
telnet 127.0.0.1 9998

Check m59api is running:

# Windows
tasklist | findstr m59api

# Linux/macOS
ps aux | grep m59api

Security

m59api exposes an HTTP API with admin endpoints (account creation, server commands). Follow these guidelines for production deployments:

m59api --host 127.0.0.1

This is the default. Webhooks still work (outbound to Discord), but the HTTP API is only accessible locally.

Do NOT expose to the internet

Using --host 0.0.0.0 exposes all admin endpoints to anyone who can reach the port. The blakserv MaintenanceMask setting does NOT protect against m59api relaying commands.

Remote access via SSH tunnel

If you need remote access to Swagger UI:

# From your local machine
ssh -L 8000:localhost:8000 user@your-server

Then open http://localhost:8000/docs in your browser.

Firewall rules

If you must expose the API, use firewall rules (AWS Security Groups, iptables) to restrict access to specific IPs.


API Documentation


How It Works

  • HTTP API: Connects to Meridian 59 maintenance port to query/control server state
  • Real-time Integration: Listens for push messages via OS pipes for instant Discord notifications
  • Cross-platform: Works on Windows (named pipes), Linux and macOS (FIFO pipes)
  • Multi-server: Routes messages from different server prefixes to different Discord webhooks

Disclaimer

This project is an independent, community-created tool for managing Meridian 59 servers.
It is not affiliated with, endorsed by, or supported by the official Meridian 59 project or its trademark holders.

Use at your own risk.
No warranty is provided. The authors are not responsible for any issues, data loss, or damages resulting from the use of this software.

Meridian 59 is a registered trademark of Andrew and Christopher Kirmse.
The official Meridian 59 repository can be found at:
https://github.com/Meridian59/Meridian59

Metadata

Release files for m59api 0.2.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for m59api 0.2.4
File Size Uploaded Provenance Actions
m59api-0.2.4.tar.gz 32.2 kB Without provenance Details for m59api-0.2.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for m59api 0.2.4
File Interpreter ABI Platform Actions
m59api-0.2.4-py3-none-any.whl Python 3 none any Details for m59api-0.2.4-py3-none-any.whl

Total release size: 60.3 kB

Release files / m59api-0.2.4.tar.gz

Download URL m59api-0.2.4.tar.gz
Size 32.2 kB
Tags Source
SHA-256 checksum
How to use checksums
16165c10351a143de633822371e51af493d1a71b92706e5206528d83d74b9610
BLAKE2b-256 checksum
How to use checksums
be335cb36148fd83bcaa75e4812e49fb1fdd2ba77a9134f1ab3fd3d8f36f2865
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.5

Release files / m59api-0.2.4-py3-none-any.whl

Download URL m59api-0.2.4-py3-none-any.whl
Size 28.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f41ab46cf9a46408f3157dfe1ed35800d4fc1c13426704261c949393ccd5153e
BLAKE2b-256 checksum
How to use checksums
5b1951c6d185f5eeebf4310a614cff95ceeb9d833835aabdcb3be1b0e07333ba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.5

Security for m59api 0.2.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.4 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page