seraph

Minimal async Python wrapper for the Seraph API.

Requires Python 3.14+

Install

pip install git+https://github.com/proxhyhq/seraph.git

Quick start

import asyncio
import seraph

async def main():
    async with seraph.Seraph(api_key="your-key") as client:
        bl = await client.blacklist("player-uuid")
        print(bl.data.username, bl.data.blacklist.reason)

asyncio.run(main())

Methods

All methods are async and raise SeraphError on any non-2xx response.

blacklist(player: str) → BlacklistResponse

Fetch a player's blacklist record. player is a UUID or username.

bl = await client.blacklist("4fa6e55b-d66a-43c6-949d-a5116ae2d39f")

bl.success            # bool
bl.data.uuid          # str
bl.data.username      # str
bl.data.blacklist     # BlacklistInfo | None
bl.data.safelist      # PlayerSafelistInfo | None
bl.data.annoylist     # AnnoylistInfo | None
bl.data.bot           # BotInfo | None
bl.data.member        # MemberInfo | None
bl.data.name_change   # NameChangeInfo | None
bl.data.statistics    # Statistics | None
bl.data.custom_tag    # str | None

safelist(player: str) → SafelistResponse

Check whether a player is on your personal safelist.

sl = await client.safelist("4fa6e55b-...")
sl.safelist.valid   # bool
sl.safelist.uuid    # str

cubelify_blacklist(uuid: str, *, score: str | None = None) → CubelifyResponse

Cubelify-formatted blacklist data. score is a comma-separated list of sniper score factors.

cub = await client.cubelify_blacklist("4fa6e55b-...", score="bhop,killaura")

cub.score            # CubelifyScore | None  (.mode, .value)
cub.tags             # tuple[CubelifyTag, ...]
cub.tags[0].tag_name # str
cub.tags[0].alert    # bool — Seraph mod integration flag
cub.timestamp        # str

add_sniper(report: SniperReport) → SniperReport

Submit a sniper report. Requires staff-level API key.

report = seraph.SniperReport(
    uuid="4fa6e55b-...",
    reason="Sniped bombies",
    report_type="sniping",
    evidence="https://youtube.com/...",
)
result = await client.add_sniper(report)

skin() → bytes

Fetch a random Minecraft skin as raw PNG bytes.

png = await client.skin()
open("skin.png", "wb").write(png)

fetch_tags() → list[UserTag]

Fetch all tags associated with the authenticated account.

tags = await client.fetch_tags()
tags[0].tag_name     # str
tags[0].color        # int
tags[0].tag_options  # tuple[UserTag, ...]  — nested

update_tag(update: TagUpdate) → dict[str, bool]

Create or update a user tag.

await client.update_tag(seraph.TagUpdate(
    api_key="your-key",
    tag_name="VIP",
    text="VIP",
    color="#00ff00",
    enabled=True,
))

website_user() → dict

Fetch general info for the authenticated account. Returns a raw dict (schema varies).

Error handling

try:
    bl = await client.blacklist("bad-uuid")
except seraph.SeraphError as e:
    print(e.status)        # HTTP status code (int)
    print(e.cause)         # human-readable message (str)
    print(e.code)          # API error code (int)
    for detail in e.errors:
        print(detail.name, detail.reason)

Models

All response models are frozen dataclasses (slots=True, frozen=True). Input models (SniperReport, TagUpdate) are mutable. Every model exposes from_dict / to_dict if you need to work with raw JSON.

Model	Description
BlacklistResponse	Full player blacklist record
BlacklistData	Nested data inside BlacklistResponse
BlacklistInfo	Blacklist sub-record
AnnoylistInfo	Annoylist sub-record
PlayerSafelistInfo	Safelist sub-record inside blacklist data
BotInfo	Bot detection sub-record
MemberInfo	Member sub-record
NameChangeInfo	Name-change history sub-record
Statistics	Encounter/threat statistics
SafelistResponse	Personal safelist check result
CubelifyResponse	Cubelify-formatted blacklist data
CubelifyScore	Sniper score (mode, value)
CubelifyTag	Individual Cubelify tag
SniperReport	Input/output for sniper reports
UserTag	Website user tag (recursive via tag_options)
TagUpdate	Input for creating/updating a tag
TagOption	Age-based option within a TagUpdate
SeraphError	Raised on any API error
ErrorDetail	Individual error detail inside SeraphError

Running tests

uv run pytest