API

The RetroMC API provides developers and the broader community with programmatic access to server data and functionalities, and as such, this API is primarily designed to support the creation of tools and applications by developers.

Access to the RetroMC API is intended for everyone who wish to create applications or services that utilize RetroMC server data.
Users are encouraged to use the API responsibly, adhering to any usage limits or guidelines established by staff members to ensure smooth operations.

Please note that while the API aims to be stable and reliable, the availability and stability of various endpoints may vary, and users should design their applications to handle potential data inconsistencies or API changes.

The following sections of this page documents the available endpoints, request formats, and the types of data that can be accessed, with detailed information on each endpoint, including required parameters, response formats, and example requests and responses.

Developers are encouraged to join the RetroMC Discord community to seek support, share their projects, and stay updated on API developments and server news; further assistance, questions regarding the API, and/or issue reporting can be done through a ticket.

GET api.retromc.org/api/v1/server/players

Description

This endpoint retrieves the current player count, the maximum number of players, and detailed information about each player online on the RetroMC server.

HTTP Method

GET

Request Parameters

None.

Response Format

• player_count (int): The current number of online players.
• players (array): A list of objects, each representing an online player. Each object contains:
  • world_environment (string): The environment of the world the player is in.
  • world (string): The name of the world the player is in.
  • world_uuid (string): The UUID of the world the player is in.
  • name (string): The player's name.
  • x (double): The player's X coordinate.
  • y (double): The player's Y coordinate.
  • z (double): The player's Z coordinate.
  • display_name (string): The player's display name, with formatting codes.
  • uuid (string): The player's UUID.
• max_players (int): The maximum number of players that can be online on the server.
• error (boolean): Indicates whether there was an error processing the request.

Example Response

{
  "player_count": 7,
  "players": [
    {
      "world_environment": "NORMAL",
      "world": "retromc",
      "world_uuid": "957e3d83-9d39-4fa7-a1f8-5294af4e3ab9",
      "name": "NolantheWise",
      "x": 3595.826182438679,
      "y": 79,
      "z": 11263.400089164146,
      "display_name": "§8[§cDonator§4++§8]§fNolantheWise§f§f",
      "uuid": "0c793e7f-4b0d-44a1-97b5-dfbf445358de"
    },
    {
      "world_environment": "NORMAL",
      "world": "retromc",
      "world_uuid": "957e3d83-9d39-4fa7-a1f8-5294af4e3ab9",
      "name": "SapphicPuppy",
      "x": 14573.611347380005,
      "y": 7,
      "z": 2025.9099524425576,
      "display_name": "§f[§aCitizen§f]SapphicPuppy§f",
      "uuid": "34bec2b7-faea-465a-b851-e7daea539471"
    },
    {
      "world_environment": "NORMAL",
      "world": "retromc",
      "world_uuid": "957e3d83-9d39-4fa7-a1f8-5294af4e3ab9",
      "name": "JeppsDoudid",
      "x": -13984.699999988079,
      "y": 67,
      "z": 6775.485096728297,
      "display_name": "§f[§aCitizen§f]JeppsDoudid§f",
      "uuid": "444a32ac-0a7b-42f1-8ac5-4a66f5fe9aff"
    },
    {
      "world_environment": "NORMAL",
      "world": "retromc",
      "world_uuid": "957e3d83-9d39-4fa7-a1f8-5294af4e3ab9",
      "name": "Garsooon",
      "x": -4791.995808385358,
      "y": 99.46610926093814,
      "z": -1647.7623934769274,
      "display_name": "§f[§3Helper§f]§f~&5Garsooon§f",
      "uuid": "69aebc38-fe71-454f-b281-c1ec936ef4b0"
    },
    {
      "world_environment": "NORMAL",
      "world": "retromc",
      "world_uuid": "957e3d83-9d39-4fa7-a1f8-5294af4e3ab9",
      "name": "Lunar_Ec1ipse",
      "x": 12883.237297332853,
      "y": 67,
      "z": 12219.86913122631,
      "display_name": "§6[§aCitizen§6]§fLunar_Ec1ipse§f",
      "uuid": "6c801d7f-876f-49df-a042-99ce5cca8836"
    },
    {
      "world_environment": "NORMAL",
      "world": "retromc",
      "world_uuid": "957e3d83-9d39-4fa7-a1f8-5294af4e3ab9",
      "name": "AYoungJew69",
      "x": 12927.129332973122,
      "y": 61,
      "z": 5312.651226453099,
      "display_name": "§f[§bMystic§f]~§6AYoungJew69§f§f",
      "uuid": "96d9f05a-e7d6-4e17-88be-35610e8c4d0d"
    },
    {
      "world_environment": "NORMAL",
      "world": "retromc",
      "world_uuid": "957e3d83-9d39-4fa7-a1f8-5294af4e3ab9",
      "name": "64BrokenElytras",
      "x": 10898.368902312031,
      "y": 71,
      "z": 12186.997460237853,
      "display_name": "§8[§7Wanderer§8]§f64BrokenElytras§f",
      "uuid": "7bab9fc0-7975-48c0-86f3-9d46666be835"
    }
  ],
  "max_players": 100,
  "error": false
}

GET api.retromc.org/api/v1/server/chat

Description

This endpoint retrieves a list of recent chat messages from the RetroMC server.

HTTP Method

GET

Request Parameters

• startUnixTime (optional, int): The Unix timestamp to start fetching chat messages from. If not provided, it defaults to fetching the most recent messages.

Response Format

• unixTime (int): The current Unix timestamp at the server.
• messages (array): A list of chat messages. Each message object contains:
  • code (string): A unique code for the message.
  • channel (string): The chat channel the message was sent in.
  • display_name (string): The display name of the user who sent the message, with formatting codes.
  • message (string): The text of the chat message.
  • uuid (string): The UUID of the user who sent the message.
  • username (string): The username of the user who sent the message.
  • timestamp (int): The Unix timestamp when the message was sent.
• error (boolean): Indicates whether there was an error processing the request.
• startUnixTime (int): The Unix timestamp used as the starting point for fetching chat messages.

Example Response

{
  "unixTime": 1711595379,
  "messages": [
    {
      "code": "1848120f",
      "channel": "global",
      "display_name": "§f[§3Helper§f]§f~§5Garsooon§f§f",
      "message": "wb",
      "uuid": "69aebc38-fe71-454f-b281-c1ec936ef4b0",
      "username": "Garsooon",
      "timestamp": 1711595366
    },
    {
      "code": "1507ee0f",
      "channel": "global",
      "display_name": "§f[§6Moderator§f]~§8blck§chrt§f§f",
      "message": "ty",
      "uuid": "183251d2-5cb1-4ed5-98dd-bba22b880f34",
      "username": "1blckhrt",
      "timestamp": 1711595369
    }
  ],
  "error": false,
  "startUnixTime": 0
}

GET api.retromc.org/api/v1/village/getVillageList

Description

This endpoint retrieves a list of villages along with their owner information.

HTTP Method

GET

Request Parameters

None.

Response Format

• villages (array): A list of villages. Each village object contains:
  • owner (string): The UUID of the village owner.
  • name (string): The name of the village.
  • uuid (string): The UUID of the village.

Example Response

{
  "villages": [
    {
      "owner": "8fa8f70d-eb7d-4743-b0ad-837cdfb69f4e",
      "name": "netherlogin",
      "uuid": "00a53536-3a77-40ba-a539-f867bbbe9f7c"
    },
    {
      "owner": "43640a41-9800-4b62-9244-c5834d440aaa",
      "name": "Chunkview",
      "uuid": "01686cb0-28ff-4096-a610-0622615c2d7a"
    },
    {
      "owner": "07f3c6d2-f500-42f7-847c-4a895cff844e",
      "name": "New_Zealand",
      "uuid": "019896e3-90c2-4195-bfcb-6938342f79c8"
    },
    {
      "owner": "74c68e1e-7a04-4052-8009-8b3db955369e",
      "name": "Wondaria",
      "uuid": "01d1385d-fe53-49f3-8ecd-7bb07ce8d7cf"
    },
    {
      "owner": "eca8c74c-849e-4aaa-b844-56d91b3cf5f3",
      "name": "Thornrun",
      "uuid": "0220284c-39dd-490b-886d-29b4af39714d"
    }
  ],
  "error": false
}

GET api.retromc.org/api/v1/village/getVillage

Description

Retrieves detailed information about a specific village by its UUID, including owner, assistants, members, spawn location, balance, creation time, flags, and the total number of claims.

HTTP Method

GET

Request Parameters

• uuid (required, string): The UUID of the village to retrieve information about.

Response Format

• owner (string): The UUID of the village owner.
• assistants (array of strings): UUIDs of the village assistants.
• found (boolean): Indicates if the village was found.
• spawn (object): The spawn location of the village with:
  • world (string): The name of the world.
  • x (int): X coordinate.
  • y (int): Y coordinate.
  • z (int): Z coordinate.
• creationTime (int): Unix timestamp of when the village was created.
• balance (int): The current balance of the village.
• members (array of strings): UUIDs of the village members.
• name (string): The name of the village.
• flags (object): Various boolean flags related to village settings such as:
  • MEMBERS_CAN_INVITE (boolean): Whether members can invite others.
  • RANDOM_CAN_ALTER (boolean): Whether random players can alter the village.
  • MOBS_CAN_SPAWN (boolean): Whether mobs can spawn in the village.
  • ASSISTANT_CAN_WITHDRAW (boolean): Whether assistants can withdraw from the village balance.
  • MOB_SPAWNER_BYPASS (boolean): Whether the mob spawner bypass is enabled.
• claims (int): The number of claims the village has.
• error (boolean): Indicates whether there was an error processing the request.
• uuid (string): The UUID of the village.

Example Response

{
  "owner": "413e630d-d87a-4cb7-adaf-01af67d014b2",
  "assistants": [
    "d9700caa-8dab-4561-bfaa-707de4246966",
    "413e630d-d87a-4cb7-adaf-01af67d014b2",
    "795b6cec-195d-4645-8d5c-6ff32053f529",
    "9ce02968-72c0-41a1-a9f6-d4651ef31ba9",
    "db7db941-6923-4855-a879-1ae655c16122",
    "f03e6b30-95a6-4cba-bda5-23140593424b",
    "6f07f480-9de3-4fdd-b81e-8780e3aed9cb",
    "30b7d93e-acfb-4727-8c39-7a6d451ccb95",
    "d311182e-d1c3-4076-a8de-1908e8333c8d",
    "bb4d79b2-1bac-42c8-9a7b-16433fce0fd5",
    "977ee282-508c-4e1f-9a7a-1d0fff81fd36",
    "d251776a-9df6-49ce-8b38-a59d7b2dc9ee"
  ],
  "found": true,
  "spawn": {
    "world": "retromc",
    "x": -924,
    "y": 74,
    "z": -1186
  },
  "creationTime": 1640995200,
  "balance": 10,
  "members": [
    "7ba8a59d-e970-4313-897d-975e617d9ac3",
    "9286cb50-31d6-4ba2-a8dc-67607815bf32",
    "fc88334d-32af-43e2-bfdf-83390ab7e5b1",
    "e8fee250-1bd8-4805-8cd2-6157bed9aa98",
    "0cb288a6-4824-475b-b69f-7ae09dd50973",
    "e202faa0-ff11-4659-982b-4f4ed69f3705",
    "d9700caa-8dab-4561-bfaa-707de4246966",
    "933fecc8-7214-4e64-8310-562af20e88cc",
    "47e67e0f-de3c-4916-b87b-265bd7f9d2df",
    "413e630d-d87a-4cb7-adaf-01af67d014b2",
    "123f3c41-ef29-48ff-889f-799a67e17869",
    "6f07f480-9de3-4fdd-b81e-8780e3aed9cb",
    "33bb0ee0-322e-4031-83b0-ddec86238e0d",
    "71041fce-4cc6-4e44-aa49-07c7bff8b5a3",
    "eed3b061-63c1-47be-9c5c-233e0b9c2a27",
    "3a3c3c97-025c-4ed8-9727-ac0e3d65ed7f",
    "95d46a84-1f6c-469e-8409-8add12db858f",
    "23e6b46f-622f-4316-b7e8-3d44a54f759a",
    "5800fc63-db7c-4607-b150-6b356ba66f76",
    "0036b691-2099-4d89-84db-65f7518d39d1",
    "cb7d5351-54b2-4ff5-b57e-f3429ab95cd2",
    "5aa96969-84c4-450c-b20a-0244ed713739",
    "a86a7805-98e9-4f5a-8578-6680c0bd5c1e",
    "985b9366-cdc1-45c2-aa7b-cd6a0837e47f",
    "514ddc28-b81f-4035-9624-e8dbd9962310",
    "62bec40f-e65a-41cb-a444-fbfc611a42ef",
    "2dee7884-ccde-4cc4-ae5e-ca2d12d67696"
  ],
  "name": "Kekistan",
  "flags": {
    "MEMBERS_CAN_INVITE": false,
    "RANDOM_CAN_ALTER": false,
    "MOBS_CAN_SPAWN": false,
    "ASSISTANT_CAN_WITHDRAW": false,
    "MOB_SPAWNER_BYPASS": false
  },
  "claims": 10795,
  "error": false,
  "uuid": "87ffd0aa-cc0b-47ba-9794-1ad690369612"
}