API Reference

Status: Framework

The API is in design phase. The model runs on live servers today but the public API is not yet accepting requests.

Overview

The Mortdecai API translates natural language into Minecraft commands. Connect it to your server — your plugin sends player chat to the API, receives commands back, and executes them via RCON.

Your Server → Your Plugin → Mortdecai API → Commands → Your RCON

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer mk_your_key_here

Keys are obtained by registering and maintaining a positive data contribution rate.

Endpoints

POST /v1/translate

Translate natural language to Minecraft commands.

Request:

{
  "prompt": "give me a diamond sword with sharpness 5",
  "player": "Steve",
  "server_context": {
    "version": "1.21.x",
    "server_type": "paper",
    "online_players": ["Steve", "Alex"]
  }
}

Response:

{
  "commands": ["give Steve minecraft:diamond_sword[enchantments={sharpness:5}] 1"],
  "risk_level": 3,
  "reasoning": "Standard give command with 1.21 enchantment syntax",
  "credits_remaining": 99
}

POST /v1/pray

God mode — dramatic AI character response.

Request:

{
  "prayer": "lord I am starving grant me food",
  "player": "Steve",
  "server_context": {"version": "1.21.x"}
}

Response:

{
  "commands": ["give Steve minecraft:cooked_beef 32", "give Steve minecraft:bread 16"],
  "message": "A humble plea reaches my ears. You shall not go hungry, mortal.",
  "risk_level": 3,
  "credits_remaining": 98
}

POST /v1/contribute

Submit a training example. Earn credits if accepted.

Request:

{
  "prompt": "sudo give me a trident with riptide 3 and loyalty 3",
  "expected_output": {
    "commands": [],
    "reasoning": "Riptide and loyalty are mutually exclusive enchantments"
  },
  "notes": "Negative example — should return empty commands"
}

Response:

{
  "accepted": true,
  "credits_earned": 15,
  "quality_score": 0.92,
  "credits_remaining": 113
}

GET /v1/contribute/needed

Returns categories where contributions are most valuable.

{
  "most_needed": [
    {"category": "modded_commands", "coverage": 0.0, "bonus_multiplier": 3},
    {"category": "execute_chains", "coverage": 0.45, "bonus_multiplier": 2},
    {"category": "multilingual", "coverage": 0.12, "bonus_multiplier": 2}
  ]
}

GET /v1/model/info

{
  "model": "mortdecai-v4",
  "base": "Qwen3.5-9B",
  "training_examples": 3369,
  "command_accuracy": 0.755,
  "safety_compliance": 0.997,
  "avg_latency_ms": 4006
}

Credit System

Tier	Starting	Monthly	Contribution Rate
Free	100	100	5-20 per accepted
Contributor	500	Unlimited	10+ submissions/month
Paid	Per purchase	N/A	Optional

Integration Example

import requests

API = "https://api.mortdec.ai"
KEY = "mk_your_key"

def on_player_chat(player, message):
    """Call from your Minecraft plugin when a player types a command."""
    if message.startswith("!ai "):
        resp = requests.post(f"{API}/v1/translate", 
            headers={"Authorization": f"Bearer {KEY}"},
            json={"prompt": message[4:], "player": player}
        ).json()

        for cmd in resp["commands"]:
            execute_rcon(cmd)  # Your RCON function