{ "openapi" : "3.1.0", "info" : { "title" : "EarthMC API", "version" : "4", "description" : "The official API for EarthMC", "contact" : { "name" : "EarthMC", "url" : "https://earthmc.net/" } }, "paths" : { "/v4" : { "get" : { "summary" : "Get live information about the server", "responses" : { "200" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Server" }, "example" : "{\"version\":\"1.21.11\",\"moonPhase\":\"LAST_QUARTER\",\"timestamps\":{\"newDayTime\":36000,\"serverTimeOfDay\":60073},\"status\":{\"hasStorm\":false,\"isThundering\":false},\"stats\":{\"time\":12648,\"fullTime\":180924648,\"maxPlayers\":800,\"numOnlinePlayers\":715,\"numOnlineNomads\":26,\"numResidents\":72913,\"numNomads\":29605,\"numTowns\":5563,\"numTownBlocks\":368175,\"numNations\":199,\"numQuarters\":14824,\"numCuboids\":21000},\"voteParty\":{\"target\":5000,\"numRemaining\":4967}}\n" } } }, "502" : { "description" : "If the game server is down or the API is disabled" } } } }, "/v4/advancements" : { "get" : { "summary" : "Get a list of advancements completed on the server, along with the date it was completed on and the player that did it", "responses" : { "200" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Advancements" }, "example" : "{minecraft:adventure/totem_of_undying\":{\"player\":\"77b181f2-61da-49cb-93a7-17e0febf0511\",\"date\":\"2026-04-18\"}}\n" } } }, "503" : { "description" : "If the advancements service is currently unavailable or disabled" } } } }, "/v4/events" : { "get" : { "summary" : "Server-Sent-Events (SSE) endpoint, providing real time events as they happen on the server", "parameters" : [ { "name" : "Authorization", "in" : "header", "description" : "You must include a valid EarthMC API key to connect, in the format 'Bearer '", "required" : true, "schema" : { "type" : "string" } }, { "name" : "listen", "in" : "query", "description" : "Comma-separated list of the events you wish to listen to", "required" : true, "schema" : { "type" : "string" }, "example" : "NewDay,TownCreated,NationCreated" } ], "responses" : { "200" : { "description" : "SSE stream established", "content" : { "text/event-stream" : { "schema" : { "$ref" : "#/components/schemas/EventStream" } } } } }, "security" : [ { "BearerAuth" : [ ] } ] } }, "/v4/location" : { "post" : { "summary" : "Query location data", "requestBody" : { "description" : "Target and type, search type, radius", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/NearbyQuery" }, "example" : "{\n \"target_type\": \"TOWN\",\n \"target\": \"Melbourne\",\n \"search_type\": \"TOWN\",\n \"radius\": 100,\n \"strict\": true\n}\n" } }, "required" : true }, "responses" : { "200" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "example" : "[\n [\n {\n \"name\":\"Jyväskylä\",\n \"uuid\":\"0b69c00d-c112-4ca0-a16c-ce551120e464\"\n },\n {\n \"name\":\"Watson\",\n \"uuid\":\"5851f859-0c4e-49bb-9e5c-5a2f9121585c\"\n }\n ]\n]\n" } } }, "400" : { "description" : "BadRequestResponse is thrown if your query is invalid. One 'pair' (array) of coordinates (E.g. [0, 0]) or an array of pairs (E.g. [[0, 0], [100, 100] is expected." } } } }, "/v4/mcmmo" : { "post" : { "summary" : "Query mcMMO data", "requestBody" : { "description" : "Specify a player UUID to query and include a valid API key", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UUIDKey" }, "example" : "{\n \"query\": \"5b8274bf-b162-4336-85a0-48f9d5380a78\",\n \"key\": \"\"\n}\n" } }, "required" : true }, "responses" : { "200" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/McMMO" } }, "example" : "[\n {\n \"name\": \"Veyronity\",\n \"ACROBATICS\": 21,\n \"ALCHEMY\": 0,\n \"ARCHERY\": 0,\n \"AXES\": 0,\n \"CROSSBOWS\": 0,\n \"EXCAVATION\": 0,\n \"FISHING\": 0,\n \"HERBALISM\": 0,\n \"MACES\": 0,\n \"MINING\": 1,\n \"REPAIR\": 0,\n \"SALVAGE\": 0,\n \"SMELTING\": 0,\n \"SPEARS\": 0,\n \"SWORDS\": 0,\n \"TAMING\": 0,\n \"TRIDENTS\": 0,\n \"UNARMED\": 0,\n \"WOODCUTTING\": 50\n }\n]\n" } } }, "401" : { "description" : "If you don't specify an API key or the key doesn't match a known player" }, "403" : { "description" : "If the owner of the API key doesn't match with the queried player, and the queried player has their information private" }, "404" : { "description" : "If the item in your query returns null, a NotFound error is thrown instead of returning an empty array" }, "429" : { "description" : "This endpoint has a cooldown of 1 hour" } } } }, "/v4/mcmmo-top" : { "post" : { "summary" : "Query mcMMO leaderboard data. Note that the information is cached for 15 minutes", "requestBody" : { "description" : "Specify a player UUID to query and include a valid API key", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/McMMOTopQuery" }, "example" : "{\n \"query\": \"MINING\",\n \"key\": \"\"\n}\n" } }, "required" : true }, "responses" : { "200" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/McMMOTop" } }, "example" : "[\n {\n \"skill\": \"power\",\n \"1\": {\n \"player\": \"K1kimor\",\n \"level\": 12078\n },\n \"2\": {\n \"player\": \"Veyronity\",\n \"level\": 72\n },\n \"3\": {\n \"player\": \"Andre1098\",\n \"level\": 29\n },\n \"lastUpdated\": 1779619278\n }\n]\n" } } }, "401" : { "description" : "If you don't specify an API key or the key doesn't match a known player" }, "429" : { "description" : "This endpoint has a cooldown of 2 minutes" } } } }, "/v4/mm" : { "get" : { "summary" : "Query Mystery Master leaderboard data", "responses" : { "200" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/MysteryMasterEntry" } }, "example" : "[{\"name\":\"nahember\",\"uuid\":\"31c426fb-70fe-4612-9122-d256af182d6f\",\"change\":\"UP\"},{\"name\":\"FindItCooper\",\"uuid\":\"e83a3e70-13d7-43b1-a91f-bef87bbd9fe9\",\"change\":\"UP\"}]\n" } } }, "503" : { "description" : "If the Mystery Master service is currently unavailable or disabled" } } } }, "/v4/nations" : { "get" : { "summary" : "Get a list of all nations and their UUIDs", "responses" : { "200" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "example" : "[{\"name\":\"North_America\",\"uuid\":\"851d8de8-e401-4685-8ca2-87ad030f2695\"},{\"name\":\"Japan\",\"uuid\":\"32d05375-2745-48c7-99df-418d27f00d34\"}]\n" } } } } }, "post" : { "summary" : "Query nation data", "requestBody" : { "description" : "Specify a nation name or UUID to query, optionally include API key", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UUIDKey" }, "example" : "{\n \"query\": \"Egypt\",\n \"key\": \"\"\n}\n" } }, "required" : true }, "responses" : { "200" : { "description" : "When using multi-querying with an array, some may fail silently, as not to disrupt the other successful queries", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Nation" } } } } }, "404" : { "description" : "If the item(s) in your query (all) return null, a NotFound error is thrown instead of returning an empty array" } } } }, "/v4/online" : { "get" : { "summary" : "Get a count & list of online players, excluding those who have opted out", "responses" : { "200" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Online" }, "example" : "{\"count\":720,\"players\":[{\"name\":\"Czipsu35\",\"uuid\":\"12a19eee-6539-4634-89bc-4398ab8de870\"}]}\n" } } } } } }, "/v4/players" : { "post" : { "summary" : "Query player data", "requestBody" : { "description" : "Specify a player name or UUID to query, optionally include API key", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UUIDKey" }, "example" : "{\n \"query\": \"Veyronity\",\n \"key\": \"\"\n}\n" } }, "required" : true }, "responses" : { "200" : { "description" : "When using multi-querying with an array, some may fail silently, as not to disrupt the other successful queries", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Player" } } } } }, "404" : { "description" : "If the item(s) in your query (all) return null, a NotFound error is thrown instead of returning an empty array" } } }, "get" : { "summary" : "Get a list of all players and their UUIDs", "responses" : { "200" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "example" : "[{\"name\":\"K1kimor\",\"uuid\":\"686b1bfa-38de-4eb9-9628-43ed3b56b76e\"},{\"name\":\"Veyronity\",\"uuid\":\"5b8274bf-b162-4336-85a0-48f9d5380a78\"}]\n" } } } } } }, "/v4/pursuits" : { "post" : { "summary" : "Query pursuits leaderboard data", "requestBody" : { "description" : "Specify a player UUID to query and include a valid API key", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StringKey" }, "example" : "{\n \"query\": \"ALL\",\n \"key\": \"\"\n}\n" } }, "required" : true }, "responses" : { "200" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Pursuits" } } } } }, "400" : { "description" : "If you specify an invalid pursuit type. Allowed types: player, town, nation, all" }, "401" : { "description" : "If you don't specify an API key or the key doesn't match a known player" }, "404" : { "description" : "If no server pursuits were found" }, "429" : { "description" : "This endpoint has a cooldown of 60 seconds" }, "503" : { "description" : "If the pursuits service is currently unavailable or disabled" } } } }, "/v4/quarters" : { "post" : { "summary" : "Query quarters data", "requestBody" : { "description" : "Specify a quarter UUID to query, optionally include API key", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UUIDKey" }, "example" : "{\n \"query\": \"5fb3b17a-c67e-476e-b8ad-f030955ef8ea\",\n \"key\": \"\"\n}\n" } }, "required" : true }, "responses" : { "200" : { "description" : "When using multi-querying with an array, some may fail silently, as not to disrupt the other successful queries", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Quarter" } } } } }, "404" : { "description" : "If the item(s) in your query (all) return null, a NotFound error is thrown instead of returning an empty array" } } }, "get" : { "summary" : "Get a list of all quarters and their UUIDs", "responses" : { "200" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "example" : "[{\"name\":\"Dull Residence\",\"uuid\":\"53040e8f-c269-4514-a9a8-af2aac278e4e\"},{\"name\":\"Annoying Flat\",\"uuid\":\"08150543-bfbd-489b-96a0-df95f9a1782f\"}]\n" } } } } } }, "/v4/shop" : { "post" : { "summary" : "Query shop data", "requestBody" : { "description" : "Specify a player UUID to query and include a valid API key", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UUIDKey" }, "example" : "{\n \"query\": \"5b8274bf-b162-4336-85a0-48f9d5380a78\",\n \"key\": \"\"\n}\n" } }, "required" : true }, "responses" : { "200" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Shops" } }, "example" : "[{\n \"1\": {\n \"id\": 120,\n \"item\": \"COPPER_BLOCK\",\n \"price\": 2,\n \"amount\": 4,\n \"type\": \"selling\",\n \"stock\": 5\n }\n}]\n" } } }, "401" : { "description" : "If you don't specify an API key or the key doesn't match a known player" }, "403" : { "description" : "If the owner of the API key doesn't match with the queried player, and the queried player has their information private" }, "404" : { "description" : "If the item in your query returns null, a NotFound error is thrown instead of returning an empty array" }, "429" : { "description" : "This endpoint has a cooldown of 1 hour for loading information, and 60 seconds for reading cached information" }, "500" : { "description" : "If the target player's shops could not be loaded due to an internal error" } } } }, "/v4/towns" : { "get" : { "summary" : "Get a list of all towns and their UUIDs", "responses" : { "200" : { "description" : "OK", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "example" : "[{\"name\":\"Bern\",\"uuid\":\"d170e904-17d7-403d-9523-b036d3bd88bf\"},{\"name\":\"Fiji\",\"uuid\":\"2778efd7-8637-40db-bfe6-6353446e28f3\"}]\n" } } } } }, "post" : { "summary" : "Query town data", "requestBody" : { "description" : "Specify a town name or UUID to query, optionally include API key", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UUIDKey" }, "example" : "{\n \"query\": \"Giza\",\n \"key\": \"\"\n}\n" } }, "required" : true }, "responses" : { "200" : { "description" : "When using multi-querying with an array, some may fail silently, as not to disrupt the other successful queries", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Town" } } } } }, "404" : { "description" : "If the item(s) in your query (all) return null, a NotFound error is thrown instead of returning an empty array" } } } } }, "components" : { "schemas" : { "EventStream" : { "type" : "object", "properties" : { } }, "AdvancementData" : { "type" : "object", "properties" : { "player" : { "type" : "string", "format" : "uuid" }, "date" : { "type" : "string" } } }, "Advancements" : { "type" : "object", "properties" : { "minecraft:advancement/path" : { "$ref" : "#/components/schemas/AdvancementData" } } }, "BankHistory" : { "type" : "object", "properties" : { "time" : { "type" : "integer", "format" : "int64" }, "type" : { "type" : "string" }, "amount" : { "type" : "integer", "format" : "int32" }, "balance" : { "type" : "integer", "format" : "int32" }, "reason" : { "type" : "string" } }, "required" : [ "time", "amount", "balance" ] }, "Loc" : { "type" : "object", "properties" : { "x" : { "type" : "integer", "format" : "int32" }, "z" : { "type" : "integer", "format" : "int32" } }, "required" : [ "x", "z" ] }, "Location" : { "type" : "object", "properties" : { "location" : { "$ref" : "#/components/schemas/Loc" }, "isWilderness" : { "type" : "boolean" }, "town" : { "$ref" : "#/components/schemas/NameUUID" }, "nation" : { "$ref" : "#/components/schemas/NameUUID" } }, "required" : [ "isWilderness" ] }, "McMMO" : { "type" : "object", "properties" : { "name" : { "type" : "string" }, "ACROBATICS" : { "type" : "integer", "format" : "int32" }, "ALCHEMY" : { "type" : "integer", "format" : "int32" }, "ARCHERY" : { "type" : "integer", "format" : "int32" }, "AXES" : { "type" : "integer", "format" : "int32" }, "CROSSBOWS" : { "type" : "integer", "format" : "int32" }, "EXCAVATION" : { "type" : "integer", "format" : "int32" }, "FISHING" : { "type" : "integer", "format" : "int32" }, "HERBALISM" : { "type" : "integer", "format" : "int32" }, "MACES" : { "type" : "integer", "format" : "int32" }, "MINING" : { "type" : "integer", "format" : "int32" }, "REPAIR" : { "type" : "integer", "format" : "int32" }, "SALVAGE" : { "type" : "integer", "format" : "int32" }, "SMELTING" : { "type" : "integer", "format" : "int32" }, "SPEARS" : { "type" : "integer", "format" : "int32" }, "SWORDS" : { "type" : "integer", "format" : "int32" }, "TAMING" : { "type" : "integer", "format" : "int32" }, "TRIDENTS" : { "type" : "integer", "format" : "int32" }, "UNARMED" : { "type" : "integer", "format" : "int32" }, "WOODCUTTING" : { "type" : "integer", "format" : "int32" } }, "required" : [ "ACROBATICS", "ALCHEMY", "ARCHERY", "AXES", "CROSSBOWS", "EXCAVATION", "FISHING", "HERBALISM", "MACES", "MINING", "REPAIR", "SALVAGE", "SMELTING", "SPEARS", "SWORDS", "TAMING", "TRIDENTS", "UNARMED", "WOODCUTTING" ] }, "McMMOTop" : { "type" : "object", "properties" : { "skill" : { "type" : "string" }, "1" : { "$ref" : "#/components/schemas/McMMOTopEntry" }, "2" : { "$ref" : "#/components/schemas/McMMOTopEntry" }, "3" : { "$ref" : "#/components/schemas/McMMOTopEntry" }, "lastUpdated" : { "type" : "integer", "format" : "int64" } }, "required" : [ "lastUpdated" ] }, "McMMOTopEntry" : { "type" : "object", "properties" : { "player" : { "type" : "string" }, "level" : { "type" : "integer", "format" : "int32" } }, "required" : [ "level" ] }, "McMMOTopQuery" : { "type" : "object", "properties" : { "skill" : { "type" : "string" }, "key" : { "type" : "string" } } }, "MysteryMasterEntry" : { "type" : "object", "properties" : { "name" : { "type" : "string" }, "uuid" : { "type" : "string", "format" : "uuid" }, "change" : { "type" : "string" } } }, "NameUUID" : { "type" : "object", "properties" : { "name" : { "type" : "string" }, "uuid" : { "type" : "string", "format" : "uuid" } } }, "Nation" : { "type" : "object", "properties" : { "name" : { "type" : "string" }, "uuid" : { "type" : "string", "format" : "uuid" }, "board" : { "type" : [ "string", "null" ] }, "dynmapColour" : { "type" : [ "string", "null" ] }, "dynmapOutline" : { "type" : [ "string", "null" ] }, "wiki" : { "type" : [ "string", "null" ] }, "discord" : { "type" : [ "string", "null" ] }, "king" : { "$ref" : "#/components/schemas/NameUUID" }, "capital" : { "$ref" : "#/components/schemas/NameUUID" }, "timestamps" : { "$ref" : "#/components/schemas/NationTimestamps" }, "status" : { "$ref" : "#/components/schemas/NationStatus" }, "stats" : { "$ref" : "#/components/schemas/NationStats" }, "coordinates" : { "$ref" : "#/components/schemas/NationCoordinates" }, "residentsArray" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "towns" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "outlaws" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "allies" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "enemies" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "sanctioned" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "ranks" : { "type" : "object", "additionalProperties" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } } }, "embargoes" : { "$ref" : "#/components/schemas/NationEmbargoes" }, "pacts" : { "$ref" : "#/components/schemas/NationPacts" }, "bankhistory" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/BankHistory" }, "description" : "Only visible when queried with a nation leader/chancellor/treasurer's API key" } } }, "NationCoordinates" : { "type" : "object", "properties" : { "spawn" : { "$ref" : "#/components/schemas/SpawnCoordinates" } } }, "NationEmbargoes" : { "type" : "object", "properties" : { "own" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "against" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } } } }, "NationPacts" : { "type" : "object", "properties" : { "active" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/PactEntry" } }, "pending" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/PactEntry" } } } }, "NationPursuitEntry" : { "type" : "object", "properties" : { "nation" : { "type" : "string", "format" : "uuid" }, "score" : { "type" : "number", "format" : "double" } }, "required" : [ "score" ] }, "NationPursuitLeaderboard" : { "type" : "object", "properties" : { "name" : { "type" : "string" }, "isActive" : { "type" : "boolean" }, "top" : { "type" : "object", "additionalProperties" : { "$ref" : "#/components/schemas/NationPursuitEntry" } } }, "required" : [ "isActive" ] }, "NationStats" : { "type" : "object", "properties" : { "nationBonus" : { "type" : "integer", "format" : "int32" }, "numTownBlocks" : { "type" : "integer", "format" : "int32" }, "numResidents" : { "type" : "integer", "format" : "int32" }, "numTowns" : { "type" : "integer", "format" : "int32" }, "numOutlaws" : { "type" : "integer", "format" : "int32" }, "numAllies" : { "type" : "integer", "format" : "int32" }, "numEnemies" : { "type" : "integer", "format" : "int32" }, "balance" : { "type" : "number", "format" : "double" } }, "required" : [ "nationBonus", "numTownBlocks", "numResidents", "numTowns", "numOutlaws", "numAllies", "numEnemies", "balance" ] }, "NationStatus" : { "type" : "object", "properties" : { "isOpen" : { "type" : "boolean" }, "isPublic" : { "type" : "boolean" }, "isNeutral" : { "type" : "boolean" } }, "required" : [ "isOpen", "isPublic", "isNeutral" ] }, "NationTimestamps" : { "type" : "object", "properties" : { "registered" : { "type" : "integer", "format" : "int64" } }, "required" : [ "registered" ] }, "NearbyQuery" : { "type" : "object", "properties" : { "target_type" : { "type" : "string" }, "target" : { "type" : "string" }, "search_type" : { "type" : "string" }, "radius" : { "type" : "integer", "format" : "int32" }, "strict" : { "type" : [ "boolean", "null" ] } }, "required" : [ "radius" ] }, "Online" : { "type" : "object", "properties" : { "count" : { "type" : "integer", "format" : "int32" }, "players" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } } }, "required" : [ "count" ] }, "Pact" : { "type" : "object", "properties" : { "sender" : { "type" : "string" }, "receiver" : { "type" : "string" }, "status" : { "type" : "string" }, "stats" : { "$ref" : "#/components/schemas/PactStats" } } }, "PactEntry" : { "type" : "object", "properties" : { "NATION" : { "$ref" : "#/components/schemas/Pact" } } }, "PactStats" : { "type" : "object", "properties" : { "createdAt" : { "type" : "integer", "format" : "int64" }, "expiresAt" : { "type" : "integer", "format" : "int64" }, "duration" : { "type" : "integer", "format" : "int32" } }, "required" : [ "createdAt", "expiresAt", "duration" ] }, "Player" : { "type" : "object", "properties" : { "name" : { "type" : "string" }, "uuid" : { "type" : "string", "format" : "uuid" }, "title" : { "type" : [ "string", "null" ] }, "surname" : { "type" : [ "string", "null" ] }, "formattedName" : { "type" : [ "string", "null" ] }, "about" : { "type" : [ "string", "null" ] }, "town" : { "$ref" : "#/components/schemas/NameUUID" }, "nation" : { "$ref" : "#/components/schemas/NameUUID" }, "timestamps" : { "$ref" : "#/components/schemas/PlayerTimestamps" }, "status" : { "$ref" : "#/components/schemas/PlayerStatus" }, "stats" : { "$ref" : "#/components/schemas/PlayerStats" }, "perms" : { "$ref" : "#/components/schemas/TownyPerms" }, "ranks" : { "$ref" : "#/components/schemas/PlayerRanks" }, "friends" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } } } }, "PlayerPursuitEntry" : { "type" : "object", "properties" : { "player" : { "type" : "string", "format" : "uuid" }, "score" : { "type" : "number", "format" : "double" } }, "required" : [ "score" ] }, "PlayerPursuitLeaderboard" : { "type" : "object", "properties" : { "name" : { "type" : "string" }, "isActive" : { "type" : "boolean" }, "top" : { "type" : "object", "additionalProperties" : { "$ref" : "#/components/schemas/PlayerPursuitEntry" } } }, "required" : [ "isActive" ] }, "PlayerRanks" : { "type" : "object", "properties" : { "townRanks" : { "type" : "array", "items" : { "type" : "string" } }, "nationRanks" : { "type" : "array", "items" : { "type" : "string" } } } }, "PlayerStats" : { "type" : "object", "properties" : { "balance" : { "type" : "number", "format" : "double" }, "numFriends" : { "type" : "integer", "format" : "int32" } }, "required" : [ "balance", "numFriends" ] }, "PlayerStatus" : { "type" : "object", "properties" : { "isOnline" : { "type" : "boolean" }, "isNPC" : { "type" : "boolean" }, "isMayor" : { "type" : "boolean" }, "isKing" : { "type" : "boolean" }, "hasTown" : { "type" : "boolean" }, "hasNation" : { "type" : "boolean" } }, "required" : [ "isOnline", "isNPC", "isMayor", "isKing", "hasTown", "hasNation" ] }, "PlayerTimestamps" : { "type" : "object", "properties" : { "registered" : { "type" : "integer", "format" : "int64" }, "joinedTownAt" : { "format" : "int64", "type" : [ "integer", "null" ] }, "lastOnline" : { "format" : "int64", "description" : "Only null if this resident is an NPC", "type" : [ "integer", "null" ] } }, "required" : [ "registered" ] }, "Pursuits" : { "type" : "object", "properties" : { "PLAYER" : { "$ref" : "#/components/schemas/PlayerPursuitLeaderboard" }, "TOWN" : { "$ref" : "#/components/schemas/TownPursuitLeaderboard" }, "NATION" : { "$ref" : "#/components/schemas/NationPursuitLeaderboard" } } }, "Quarter" : { "type" : "object", "properties" : { "uuid" : { "type" : "string", "format" : "uuid" }, "type" : { "type" : "string" }, "owner" : { "$ref" : "#/components/schemas/NameUUID" }, "town" : { "$ref" : "#/components/schemas/NameUUID" }, "timestamps" : { "$ref" : "#/components/schemas/QuarterTimestamps" }, "status" : { "$ref" : "#/components/schemas/QuarterStatus" }, "stats" : { "$ref" : "#/components/schemas/QuarterStats" }, "colour" : { "type" : "array", "items" : { "type" : "integer", "format" : "int32" } }, "trusted" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "cuboids" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/QuarterCuboid" } } } }, "QuarterCuboid" : { "type" : "object", "properties" : { "cornerOne" : { "type" : "array", "items" : { "type" : "integer", "format" : "int32" } }, "cornerTwo" : { "type" : "array", "items" : { "type" : "integer", "format" : "int32" } } } }, "QuarterStats" : { "type" : "object", "properties" : { "price" : { "format" : "int32", "type" : [ "integer", "null" ] }, "volume" : { "type" : "integer", "format" : "int32" }, "numCuboids" : { "type" : "integer", "format" : "int32" } }, "required" : [ "volume", "numCuboids" ] }, "QuarterStatus" : { "type" : "object", "properties" : { "isEmbassy" : { "type" : "boolean" } }, "required" : [ "isEmbassy" ] }, "QuarterTimestamps" : { "type" : "object", "properties" : { "registered" : { "type" : "integer", "format" : "int64" }, "claimedAt" : { "format" : "int64", "type" : [ "integer", "null" ] } }, "required" : [ "registered" ] }, "Server" : { "type" : "object", "properties" : { "version" : { "type" : "string" }, "moonPhase" : { "type" : "string" }, "timestamps" : { "$ref" : "#/components/schemas/ServerTimestamps" }, "status" : { "$ref" : "#/components/schemas/ServerWeather" }, "stats" : { "$ref" : "#/components/schemas/ServerStats" }, "voteParty" : { "$ref" : "#/components/schemas/VoteParty" } } }, "ServerStats" : { "type" : "object", "properties" : { "time" : { "type" : "integer", "format" : "int32" }, "fullTime" : { "type" : "integer", "format" : "int64" }, "maxPlayers" : { "type" : "integer", "format" : "int32" }, "numOnlinePlayers" : { "type" : "integer", "format" : "int32" }, "numOnlineNomads" : { "type" : "integer", "format" : "int32" }, "numResidents" : { "type" : "integer", "format" : "int32" }, "numNomads" : { "type" : "integer", "format" : "int32" }, "numTowns" : { "type" : "integer", "format" : "int32" }, "numTownBlocks" : { "type" : "integer", "format" : "int32" }, "numNations" : { "type" : "integer", "format" : "int32" }, "numQuarters" : { "type" : "integer", "format" : "int32" }, "numCuboids" : { "type" : "integer", "format" : "int32" } }, "required" : [ "time", "fullTime", "maxPlayers", "numOnlinePlayers", "numOnlineNomads", "numResidents", "numNomads", "numTowns", "numTownBlocks", "numNations", "numQuarters", "numCuboids" ] }, "ServerTimestamps" : { "type" : "object", "properties" : { "newDayTime" : { "type" : "integer", "format" : "int32" }, "serverTimeOfDay" : { "type" : "integer", "format" : "int32" } }, "required" : [ "newDayTime", "serverTimeOfDay" ] }, "ServerWeather" : { "type" : "object", "properties" : { "hasStorm" : { "type" : "boolean" }, "isThundering" : { "type" : "boolean" } }, "required" : [ "hasStorm", "isThundering" ] }, "Shop" : { "type" : "object", "properties" : { "id" : { "type" : "integer", "format" : "int32" }, "item" : { "type" : "string" }, "price" : { "type" : "integer", "format" : "int32" }, "amount" : { "type" : "integer", "format" : "int32" }, "type" : { "type" : "string" }, "stock" : { "type" : "integer", "format" : "int32" } }, "required" : [ "id", "price", "amount", "stock" ] }, "Shops" : { "type" : "object", "properties" : { "1" : { "$ref" : "#/components/schemas/Shop" }, "2" : { "$ref" : "#/components/schemas/Shop" }, "3" : { "$ref" : "#/components/schemas/Shop" } } }, "SpawnCoordinates" : { "type" : "object", "properties" : { "world" : { "type" : "string" }, "x" : { "type" : "number", "format" : "double" }, "y" : { "type" : "number", "format" : "double" }, "z" : { "type" : "number", "format" : "double" }, "yaw" : { "type" : "number", "format" : "float" }, "pitch" : { "type" : "number", "format" : "float" } }, "required" : [ "x", "y", "z", "yaw", "pitch" ] }, "StringKey" : { "type" : "object", "properties" : { "query" : { "type" : "string" }, "key" : { "type" : "string" } } }, "Town" : { "type" : "object", "properties" : { "name" : { "type" : "string" }, "uuid" : { "type" : "string", "format" : "uuid" }, "board" : { "type" : [ "string", "null" ] }, "founder" : { "type" : "string" }, "wiki" : { "type" : [ "string", "null" ] }, "discord" : { "type" : [ "string", "null" ] }, "mayor" : { "$ref" : "#/components/schemas/NameUUID" }, "nation" : { "$ref" : "#/components/schemas/NameUUID" }, "timestamps" : { "$ref" : "#/components/schemas/TownTimestamps" }, "status" : { "$ref" : "#/components/schemas/TownStatus" }, "stats" : { "$ref" : "#/components/schemas/TownStats" }, "perms" : { "$ref" : "#/components/schemas/TownyPerms" }, "coordinates" : { "$ref" : "#/components/schemas/TownCoordinates" }, "residents" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "trusted" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "outlaws" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "quarters" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } }, "ranks" : { "type" : "object", "additionalProperties" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/NameUUID" } } }, "warps" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/TownWarp" } }, "bankhistory" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/BankHistory" }, "description" : "Only visible when queried with a nation leader/chancellor/treasurer's API key" } } }, "TownCoordinates" : { "type" : "object", "properties" : { "spawn" : { "$ref" : "#/components/schemas/SpawnCoordinates" }, "homeBlock" : { "type" : "array", "items" : { "type" : "integer", "format" : "int32" } }, "townBlocks" : { "type" : "array", "items" : { "type" : "integer", "format" : "int32" } }, "worlds" : { "type" : "object", "additionalProperties" : { "$ref" : "#/components/schemas/TownCoordinatesWorldEntry" } } } }, "TownCoordinatesWorldEntry" : { "type" : "object", "properties" : { "townblocks" : { "items" : { "type" : "integer", "format" : "int32" }, "type" : [ "array", "null" ] } } }, "TownPursuitEntry" : { "type" : "object", "properties" : { "town" : { "type" : "string", "format" : "uuid" }, "score" : { "type" : "number", "format" : "double" } }, "required" : [ "score" ] }, "TownPursuitLeaderboard" : { "type" : "object", "properties" : { "name" : { "type" : "string" }, "isActive" : { "type" : "boolean" }, "top" : { "type" : "object", "additionalProperties" : { "$ref" : "#/components/schemas/TownPursuitEntry" } } }, "required" : [ "isActive" ] }, "TownStats" : { "type" : "object", "properties" : { "numTownBlocks" : { "type" : "integer", "format" : "int32" }, "maxTownBlocks" : { "type" : "integer", "format" : "int32" }, "numResidents" : { "type" : "integer", "format" : "int32" }, "numTrusted" : { "type" : "integer", "format" : "int32" }, "numOutlaws" : { "type" : "integer", "format" : "int32" }, "balance" : { "type" : "number", "format" : "double" }, "forSalePrice" : { "format" : "double", "type" : [ "number", "null" ] } }, "required" : [ "numTownBlocks", "maxTownBlocks", "numResidents", "numTrusted", "numOutlaws", "balance" ] }, "TownStatus" : { "type" : "object", "properties" : { "isPublic" : { "type" : "boolean" }, "isOpen" : { "type" : "boolean" }, "isNeutral" : { "type" : "boolean" }, "isCapital" : { "type" : "boolean" }, "isOverclaimed" : { "type" : "boolean" }, "isRuined" : { "type" : "boolean" }, "isForSale" : { "type" : "boolean" }, "hasNation" : { "type" : "boolean" }, "canOutsiderSpawn" : { "type" : "boolean" }, "canPassiveMobsSpawn" : { "type" : "boolean" }, "hasSnowAccumulation" : { "type" : "boolean" }, "hasFriendlyFire" : { "type" : "boolean" } }, "required" : [ "isPublic", "isOpen", "isNeutral", "isCapital", "isOverclaimed", "isRuined", "isForSale", "hasNation", "canOutsiderSpawn", "canPassiveMobsSpawn", "hasSnowAccumulation", "hasFriendlyFire" ] }, "TownTimestamps" : { "type" : "object", "properties" : { "registered" : { "type" : "integer", "format" : "int64" }, "joinedNationAt" : { "format" : "int64", "type" : [ "integer", "null" ] }, "ruinedAt" : { "format" : "int64", "type" : [ "integer", "null" ] } }, "required" : [ "registered" ] }, "TownWarp" : { "type" : "object", "properties" : { "name" : { "type" : "string" }, "uuid" : { "type" : "string", "format" : "uuid" }, "createdAt" : { "type" : "integer", "format" : "int64" }, "createdBy" : { "type" : "string" }, "access" : { "type" : "string" }, "location" : { "$ref" : "#/components/schemas/WarpLocation" } }, "required" : [ "createdAt" ] }, "TownyFlags" : { "type" : "object", "properties" : { "pvp" : { "type" : "boolean" }, "explosions" : { "type" : "boolean" }, "fire" : { "type" : "boolean" }, "mobs" : { "type" : "boolean" } }, "required" : [ "pvp", "explosions", "fire", "mobs" ] }, "TownyPerms" : { "type" : "object", "properties" : { "build" : { "type" : "array", "items" : { "type" : "boolean" } }, "destroy" : { "type" : "array", "items" : { "type" : "boolean" } }, "switch" : { "type" : "array", "items" : { "type" : "boolean" } }, "itemUse" : { "type" : "array", "items" : { "type" : "boolean" } }, "flags" : { "$ref" : "#/components/schemas/TownyFlags" } } }, "UUIDKey" : { "type" : "object", "properties" : { "query" : { "type" : "string" }, "key" : { "type" : "string" } } }, "VoteParty" : { "type" : "object", "properties" : { "target" : { "type" : "integer", "format" : "int32" }, "numRemaining" : { "type" : "integer", "format" : "int32" } }, "required" : [ "target", "numRemaining" ] }, "WarpLocation" : { "type" : "object", "properties" : { "x" : { "type" : "integer", "format" : "int32" }, "y" : { "type" : "integer", "format" : "int32" }, "z" : { "type" : "integer", "format" : "int32" } }, "required" : [ "x", "y", "z" ] } } } }