MythicMC Public API (Python)

Python client for the MythicMC Public API. Python 3.10 or newer, synchronous and asynchronous, built on httpx.

Create an API key in the developer portal with your MythicMC forum account. Production keys use development limits until approved.

Install

pip install mythicmc-sdk

Install from source

pip install "git+https://github.com/mythicmcnetwork/mythicmc-sdk.git#subdirectory=python"

Usage

import os
from mythicmc import MythicMC, NotFoundError

with MythicMC(os.environ["MYTHICMC_API_KEY"]) as api:
    player = api.get_player("Vicente_1313")  # username or UUID
    print(player.rank.label, "unknown" if player.online is None else player.online)
    print(player.meta.data_as_of)  # UTC cutoff this response reflects

    try:
        survival = api.get_player_stats("Vicente_1313").survival
        print(survival.combat.kills, survival.net_worth.total if survival.net_worth else "unpublished")
    except NotFoundError:
        print("no published Survival statistics")

    for row in api.get_leaderboard("kills", "weekly").rows:
        print(row.rank, row.name, row.value)

AsyncMythicMC has the same methods as coroutines, for Discord bots and other asyncio programs:

import asyncio
import os
from mythicmc import AsyncMythicMC

async def main() -> None:
    async with AsyncMythicMC(os.environ["MYTHICMC_API_KEY"]) as api:
        profile, team = await asyncio.gather(api.get_player("Vicente_1313"), api.get_player_team("Vicente_1313"))
    print(profile.rank.label, team.team.name if team.team else "no team")

asyncio.run(main())

Both clients hold an httpx connection pool. Use them as context managers, or call close() yourself — await api.close() on the asynchronous one.

id is a username, case-insensitive, or a UUID with or without dashes.

The full API reference includes additional endpoints you can call directly over HTTP.

Replies are frozen dataclasses whose snake_case attributes come from the JSON's camelCase keys. Each reply also carries meta, parsed from the response headers, and raw, the decoded JSON body as a dict. Keys the models do not know about are ignored, so a field the API adds later reaches you through raw rather than breaking an older client.

Options

Errors

Every response the client cannot turn into data raises a MythicMCError. status is the HTTP status; message is the API's error string, or a stand-in when the response carried none.

Any other status, and a 2xx whose body is not the shape the model declares, raises MythicMCError itself. Network failures and timeouts raise httpx's own exceptions.

Examples

examples holds one file per group of endpoints, plus async_lookup.py for AsyncMythicMC.

pip install .
MYTHICMC_API_KEY=mmc_... python examples/get_player.py Vicente_1313

Set MYTHICMC_API_URL to run them against a mock server instead of the live API.

Development

pip install -e .
python -m unittest discover -s tests

API 1.1.0

See release notes for breaking changes and migration instructions.

List methods take pagination options ({ limit, cursor } in TypeScript; keyword arguments in Python). Follow nextCursor / next_cursor until null. IDs are URL-encoded. Shop reads optionally accept an ETag and return null / None on 304; otherwise use reply.meta.etag for the next conditional request.