{"openapi":"3.1.0","info":{"title":"Mizan API","version":"1.0","description":"Check players against every ban list Mizan reads before they join your server, and add your own bans. Public routes need no key; the rest take your organization's key in `X-API-Key`. Answers are JSON in a `data` envelope; errors are `{ error: { code, message } }`."},"servers":[{"url":"https://api.mizan.ac"}],"tags":[{"name":"Registry","description":"The registry: its size, the lists it reads, a player's record, and your own bans."},{"name":"Organization","description":"The organization a key belongs to, with its servers."}],"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["INVALID_REQUEST","INVALID_PLAYER_ID","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","PAYLOAD_TOO_LARGE","UNSUPPORTED_MEDIA_TYPE","RATE_LIMITED","UPSTREAM_UNAVAILABLE"]},"message":{"type":"string"},"target":{"type":"string","description":"The parameter or field the error is about, such as `player` or `bans[0].server`."},"feature":{"type":"string","description":"With `FEATURE_NOT_AVAILABLE`: the feature the route needs."}},"required":["code","message"]}},"required":["error"]},"PlayerSummary":{"type":"object","properties":{"player":{"type":"object","properties":{"provider":{"type":"string","example":"steam"},"id":{"type":"string","example":"76561197960287930"}},"required":["provider","id"]},"profile":{"type":"string","format":"uri","example":"https://mizan.ac/players/steam/76561197960287930"},"cheater":{"type":"boolean","description":"Caught cheating by Mizan's anti-cheat, or banned for cheating by any organization."},"minge":{"type":"boolean","description":"Has a conduct ban (RDM, NITRP, prop abuse, toxicity and the like) from any organization that is in force or was issued in the last year, or Mizan marked them as a minge."},"bans":{"type":"object","properties":{"total":{"type":"integer"},"active":{"type":"integer"},"sources":{"type":"integer","description":"How many organizations' lists name them."},"conduct":{"type":"integer","description":"Bans for conduct, of any age."},"categories":{"type":"array","items":{"type":"string","example":"MRDM"}},"games":{"type":"array","items":{"type":"string","example":"garrysmod"},"description":"The games of the bans that name one."},"lastAt":{"type":["string","null"],"format":"date-time","example":"2026-10-09T21:40:00.000Z"}},"required":["total","active","sources","conduct","categories","games","lastAt"]}},"required":["player","profile","cheater","minge","bans"]},"ContributedBan":{"type":"object","properties":{"player":{"type":"string","example":"76561197960276590","description":"Any game's player: `provider:id` (`steam`, `minecraft`, `fivem`, `epic`, `xbox`, `discord`), or without a prefix a Steam id in any form (SteamID64, SteamID2 `STEAM_0:0:11101`, SteamID3 `[U:1:22202]`, the account id `22202`, a `steamcommunity.com/profiles/` link), a Minecraft UUID with or without dashes, or a FiveM `license:` hash. With `server`, a bare id is read the way that server's game names players."},"server":{"type":"string","example":"darkrp-1","description":"The server it was issued on, by the key you listed it under. It gives the ban its game and mode."},"ref":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","example":"ban-1042","description":"Your own id for the ban. Sending it again updates the ban."},"reason":{"type":"string","maxLength":500,"example":"Mass RDM"},"categories":{"type":"array","items":{"type":"string","example":"MRDM"},"description":"From `MRDM RDM NITRP LTAP CNTAP CTAP FAILRP NLR MNLR RDA PROPBLOCK PTOX PRIORS CHEATING EXPLOIT HATE EVASION`. Read from the reason when left out."},"createdAt":{"type":["string","null"],"format":"date-time","example":"2026-10-09T21:40:00.000Z","description":"ISO 8601 or epoch seconds. Now when left out."},"expiresAt":{"type":["string","null"],"format":"date-time","example":"2026-10-09T21:40:00.000Z","description":"Null or left out for a permanent ban."},"playerName":{"type":"string","maxLength":64}},"required":["player","server","ref","reason"]}},"securitySchemes":{"communityKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your organization's API key, `mzn_...`. Keys made on justified.gg before Mizan's own (`jak_...`) still work. Keep it on your server."}}},"paths":{"/v1/stats":{"get":{"tags":["Registry"],"operationId":"getRegistryStats","summary":"Get the registry's size","description":"How many ban lists the registry reads, the bans on them, how many are active, and the games they cover. Updated hourly.","responses":{"200":{"description":"The counts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"lists":{"type":"integer"},"bans":{"type":"integer"},"activeBans":{"type":"integer"},"games":{"type":"integer"}},"required":["lists","bans","activeBans","games"]}},"required":["data"]},"example":{"data":{"lists":64,"bans":437163,"activeBans":301204,"games":10}}}}},"429":{"description":"Rate limited. Wait a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sources":{"get":{"tags":["Registry"],"operationId":"listRegistrySources","summary":"List the ban lists the registry reads","description":"Largest first. `state` is `reading`, `retrying` (the list refused or failed its last reads, so it is read less often) or `stopped`. `url` is the list's public page, when it has one.","responses":{"200":{"description":"The lists.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","nullable":true},"games":{"type":"array","items":{"type":"string"}},"bans":{"type":"integer"},"activeBans":{"type":"integer"},"state":{"type":"string","enum":["reading","retrying","stopped"]},"changedAt":{"type":"string","format":"date-time","example":"2026-10-09T21:40:00.000Z","nullable":true}},"required":["key","name","url","games","bans","activeBans","state","changedAt"]}},"total":{"type":"integer"}},"required":["data","total"]},"example":{"data":[{"key":"external:blackwonder","name":"BlackWonder.TF","url":"https://bans.blackwonder.tf","games":["tf2"],"bans":62060,"activeBans":61871,"state":"reading","changedAt":"2026-10-26T18:17:42.000Z"}],"total":64}}}},"429":{"description":"Rate limited. Wait a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me":{"get":{"tags":["Organization"],"security":[{"communityKey":[]}],"operationId":"getMyOrganization","summary":"Who the key is for","responses":{"200":{"description":"Your organization, its servers and what its key may do.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["reader","contributor"]},"contribute":{"type":"boolean"},"source":{"type":"string"},"servers":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"game":{"type":"string"},"mode":{"type":["string","null"]},"address":{"type":["string","null"],"example":"play.example.com:27015"},"region":{"type":["string","null"],"example":"eu"},"identity":{"type":["string","null"]}},"required":["key","name","game","mode","address","region","identity"]}}},"required":["id","name","status","contribute","source","servers"]}},"required":["data"]}}}},"400":{"description":"The request is malformed: a bad player id, server key or body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or one that is unknown, disabled or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your organization is waiting for approval or is suspended, or cannot add bans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such player, ban or route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The data behind the route is unavailable right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/players/{player}":{"get":{"tags":["Registry"],"security":[{"communityKey":[]}],"operationId":"getRegistryPlayer","summary":"Check one player","description":"The player's summary and public record: every list's bans on them, with Mizan's own marks.","parameters":[{"name":"player","in":"path","required":true,"schema":{"type":"string"},"example":"76561197960287930","description":"Any game's player: `provider:id` (`steam`, `minecraft`, `fivem`, `epic`, `xbox`, `discord`), or without a prefix a Steam id in any form (SteamID64, SteamID2 `STEAM_0:0:11101`, SteamID3 `[U:1:22202]`, the account id `22202`, a `steamcommunity.com/profiles/` link), a Minecraft UUID with or without dashes, or a FiveM `license:` hash. With `server`, a bare id is read the way that server's game names players. URL-encode SteamID3's brackets."},{"name":"server","in":"query","required":false,"schema":{"type":"string"},"example":"darkrp-1","description":"One of your servers, by its key."}],"responses":{"200":{"description":"The player's summary and record.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/PlayerSummary"},{"type":"object","properties":{"record":{"type":["object","null"]}},"required":["record"]}]}},"required":["data"]}}}},"400":{"description":"The request is malformed: a bad player id, server key or body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or one that is unknown, disabled or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your organization is waiting for approval or is suspended, or cannot add bans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such player, ban or route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The data behind the route is unavailable right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/players/lookup":{"post":{"tags":["Registry"],"security":[{"communityKey":[]}],"operationId":"lookupRegistryPlayers","summary":"Check up to 100 players","description":"For a server checking everyone on it. Each player appears once, in the order sent. Any game's player: `provider:id` (`steam`, `minecraft`, `fivem`, `epic`, `xbox`, `discord`), or without a prefix a Steam id in any form (SteamID64, SteamID2 `STEAM_0:0:11101`, SteamID3 `[U:1:22202]`, the account id `22202`, a `steamcommunity.com/profiles/` link), a Minecraft UUID with or without dashes, or a FiveM `license:` hash. With `server`, a bare id is read the way that server's game names players.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"players":{"type":"array","items":{"type":"string"},"maxItems":100},"server":{"type":"string","description":"One of your servers, by its key."}},"required":["players"]},"example":{"server":"darkrp-1","players":["76561197960287930","STEAM_0:1:19867137","[U:1:22202]"]}}}},"responses":{"200":{"description":"One summary per player.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PlayerSummary"}}},"required":["data"]}}}},"400":{"description":"The request is malformed: a bad player id, server key or body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or one that is unknown, disabled or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your organization is waiting for approval or is suspended, or cannot add bans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such player, ban or route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The data behind the route is unavailable right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bans":{"post":{"tags":["Registry"],"security":[{"communityKey":[]}],"operationId":"contributeRegistryBans","summary":"Add or update your bans","description":"Contributor organizations only. Up to 100 bans, each from one of your servers; each shows on the player's public record under your organization's name.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bans":{"type":"array","items":{"$ref":"#/components/schemas/ContributedBan"},"maxItems":100}},"required":["bans"]},"example":{"bans":[{"player":"76561197960276590","server":"darkrp-1","ref":"ban-1042","reason":"Mass RDM"}]}}}},"responses":{"200":{"description":"What was stored.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"received":{"type":"integer"},"inserted":{"type":"integer"},"updated":{"type":"integer"},"ended":{"type":"integer"}},"required":["received","inserted","updated","ended"]}},"required":["data"]}}}},"400":{"description":"The request is malformed: a bad player id, server key or body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or one that is unknown, disabled or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your organization is waiting for approval or is suspended, or cannot add bans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such player, ban or route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The data behind the route is unavailable right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bans/{ref}":{"delete":{"tags":["Registry"],"security":[{"communityKey":[]}],"operationId":"endRegistryBan","summary":"End one of your bans","description":"An unban or a successful appeal. The record keeps the ban as ended.","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"},"example":"ban-1042"}],"responses":{"200":{"description":"How many bans ended.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ended":{"type":"integer"}},"required":["ended"]}},"required":["data"]}}}},"400":{"description":"The request is malformed: a bad player id, server key or body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or one that is unknown, disabled or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your organization is waiting for approval or is suspended, or cannot add bans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such player, ban or route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Wait a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The data behind the route is unavailable right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}