{"openapi":"3.0.3","info":{"title":"MC Fleet API","version":"1.0.0","description":"Control a fleet of Hypixel bots. Authenticate with an API key generated in the web GUI, then POST a command with a `botCount`. Each command runs on up to `botCount` bots that are online and free; if you ask for more than are available, every available bot runs it.\n\nBots are handed out exclusively: while somebody is working with an account — through the web console or through this API — nobody else is given it. Commands sent with a key draw on the admin's share and hold the bots they use for a few minutes after the last one, so a sequence of calls stays on the same accounts. `GET /api/v1/bots` reports `inUse` per bot and an `available` count."},"servers":[{"url":"https://hypixelswarm.com"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer <api_key>"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"paths":{"/api/v1/commands/warpout":{"post":{"operationId":"warpout","summary":"Warp one or more players into the Cops & Crims lobby","description":"Each selected bot invites everyone named in a single party invite (/party <a> <b> <c>). As each of them accepts, the bot /p warp-s them into its Cops & Crims lobby and /p kick-s them back out of the party, so the invite stays open for whoever has not answered yet. Once the last one is warped the bot leaves the party; anyone who has not joined within 30s is given up on.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"One or more in-game names. Separate several with commas or spaces (\"Notch, Herobrine\"), or send an array instead. Up to 10 per command."},"usernames":{"type":"array","description":"Array form of `username`. Send either field, or both — they are merged and de-duplicated.","items":{"type":"string"}},"botCount":{"type":"integer","description":"How many bots should perform the action. Bots are leased exclusively while they work, so this draws on the accounts that are online and not already in use by someone else. If greater than the number available, every available bot is used (the max).","minimum":1,"example":1}},"required":["username","botCount"]},"example":{"username":"Notch, Herobrine","botCount":3}}}},"responses":{"200":{"description":"Command dispatched to the selected bots.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"action":{"type":"string"},"runId":{"type":"string","description":"identifies this run in the admin console’s live status view"},"requested":{"type":"integer","description":"botCount you asked for"},"available":{"type":"integer","description":"bots online AND not in use by a signed-in user"},"dispatched":{"type":"integer","description":"bots that actually ran it"},"notice":{"type":"string","nullable":true,"description":"set when fewer bots ran it than you asked for, and why"},"bots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"detail":{"type":"string"}}}}}}}}},"401":{"description":"Missing or invalid API key."},"409":{"description":"No bots were available — every online bot is currently in use by a signed-in user."},"422":{"description":"Validation error."}}}},"/api/v1/commands/cancelwarp":{"post":{"operationId":"cancelwarp","summary":"Cancel a pending/active warpout","description":"Each selected bot cancels its active warpout and clears its warpout queue, leaving the party if it is in one.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"Optional — recorded for the audit log. Cancel clears all warpouts on the selected bots regardless."},"botCount":{"type":"integer","description":"How many bots should perform the action. Bots are leased exclusively while they work, so this draws on the accounts that are online and not already in use by someone else. If greater than the number available, every available bot is used (the max).","minimum":1,"example":1}},"required":["botCount"]},"example":{"username":"Notch","botCount":3}}}},"responses":{"200":{"description":"Command dispatched to the selected bots.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"action":{"type":"string"},"runId":{"type":"string","description":"identifies this run in the admin console’s live status view"},"requested":{"type":"integer","description":"botCount you asked for"},"available":{"type":"integer","description":"bots online AND not in use by a signed-in user"},"dispatched":{"type":"integer","description":"bots that actually ran it"},"notice":{"type":"string","nullable":true,"description":"set when fewer bots ran it than you asked for, and why"},"bots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"detail":{"type":"string"}}}}}}}}},"401":{"description":"Missing or invalid API key."},"409":{"description":"No bots were available — every online bot is currently in use by a signed-in user."},"422":{"description":"Validation error."}}}},"/api/v1/commands/partyloop":{"post":{"operationId":"partyloop","summary":"Send party invites on repeat","description":"The warpout invite, looped. Each selected bot sends /party <a> <b> <c>, holds the invite for `holdSeconds`, leaves the party, and invites again — either `cycles` times or until stopped with /api/v1/commands/cancelloop. A bot runs one loop at a time and will not start one while it has a warpout in flight.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"One or more in-game names. Separate several with commas or spaces (\"Notch, Herobrine\"), or send an array instead. Up to 10 per command."},"usernames":{"type":"array","description":"Array form of `username`. Send either field, or both — they are merged and de-duplicated.","items":{"type":"string"}},"mode":{"type":"string","description":"\"until_stop\" (default) keeps going until cancelloop; \"count\" runs `cycles` times and stops."},"cycles":{"type":"integer","description":"How many invites to send. Required when mode is \"count\", ignored otherwise. 1–1000."},"holdSeconds":{"type":"number","description":"How long each invite is left standing before the bot leaves and re-invites. 1–300, default 3."},"gapSeconds":{"type":"number","description":"Extra pause between leaving and the next invite. 0–60, default 0."},"botCount":{"type":"integer","description":"How many bots should perform the action. Bots are leased exclusively while they work, so this draws on the accounts that are online and not already in use by someone else. If greater than the number available, every available bot is used (the max).","minimum":1,"example":1}},"required":["username","botCount"]},"example":{"username":"Notch","mode":"count","cycles":20,"holdSeconds":3,"botCount":1}}}},"responses":{"200":{"description":"Command dispatched to the selected bots.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"action":{"type":"string"},"runId":{"type":"string","description":"identifies this run in the admin console’s live status view"},"requested":{"type":"integer","description":"botCount you asked for"},"available":{"type":"integer","description":"bots online AND not in use by a signed-in user"},"dispatched":{"type":"integer","description":"bots that actually ran it"},"notice":{"type":"string","nullable":true,"description":"set when fewer bots ran it than you asked for, and why"},"bots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"detail":{"type":"string"}}}}}}}}},"401":{"description":"Missing or invalid API key."},"409":{"description":"No bots were available — every online bot is currently in use by a signed-in user."},"422":{"description":"Validation error."}}}},"/api/v1/commands/cancelloop":{"post":{"operationId":"cancelloop","summary":"Stop a running party loop","description":"Each selected bot stops its party loop and leaves the party. Needed for loops started in \"until_stop\" mode.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"Optional — recorded for the audit log. Cancel stops the loop on the selected bots regardless."},"botCount":{"type":"integer","description":"How many bots should perform the action. Bots are leased exclusively while they work, so this draws on the accounts that are online and not already in use by someone else. If greater than the number available, every available bot is used (the max).","minimum":1,"example":1}},"required":["botCount"]},"example":{"username":"Notch","botCount":1}}}},"responses":{"200":{"description":"Command dispatched to the selected bots.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"action":{"type":"string"},"runId":{"type":"string","description":"identifies this run in the admin console’s live status view"},"requested":{"type":"integer","description":"botCount you asked for"},"available":{"type":"integer","description":"bots online AND not in use by a signed-in user"},"dispatched":{"type":"integer","description":"bots that actually ran it"},"notice":{"type":"string","nullable":true,"description":"set when fewer bots ran it than you asked for, and why"},"bots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"detail":{"type":"string"}}}}}}}}},"401":{"description":"Missing or invalid API key."},"409":{"description":"No bots were available — every online bot is currently in use by a signed-in user."},"422":{"description":"Validation error."}}}},"/api/v1/commands/consistentparty":{"post":{"operationId":"consistentparty","summary":"Chase one player across accounts until one warps them","description":"A relay, not a fan-out: the accounts take turns. The first bot invites the target over and over — hold, leave, invite again. If they accept, it warps them out and the whole command is done. If Hypixel refuses the invite (their invites are off, or the bot is on their /ignore list) that account is burned and the target is handed straight to the next bot, which picks the chase up. An account that simply gets no answer after `attemptsPerBot` invites hands on too, without being burned. The command ends when someone gets warped, when the target turns out to be offline, when every selected account has tried, or when you stop it with /api/v1/commands/cancelparty. `botCount` is how many accounts the relay may work through.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"In-game name of the player to chase. One player only, unlike warpout."},"attemptsPerBot":{"type":"integer","description":"Invites one account sends before handing the target to the next. An outright refusal hands on immediately regardless. 1–1000, default 5."},"holdSeconds":{"type":"number","description":"How long each invite is left standing before the bot leaves and re-invites. 1–300, default 3."},"gapSeconds":{"type":"number","description":"Extra pause between leaving and the next invite. 0–60, default 0."},"botCount":{"type":"integer","description":"How many bots should perform the action. Bots are leased exclusively while they work, so this draws on the accounts that are online and not already in use by someone else. If greater than the number available, every available bot is used (the max).","minimum":1,"example":1}},"required":["username","botCount"]},"example":{"username":"Notch","attemptsPerBot":5,"holdSeconds":3,"botCount":10}}}},"responses":{"200":{"description":"Command dispatched to the selected bots.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"action":{"type":"string"},"runId":{"type":"string","description":"identifies this run in the admin console’s live status view"},"requested":{"type":"integer","description":"botCount you asked for"},"available":{"type":"integer","description":"bots online AND not in use by a signed-in user"},"dispatched":{"type":"integer","description":"bots that actually ran it"},"notice":{"type":"string","nullable":true,"description":"set when fewer bots ran it than you asked for, and why"},"bots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"detail":{"type":"string"}}}}}}}}},"401":{"description":"Missing or invalid API key."},"409":{"description":"No bots were available — every online bot is currently in use by a signed-in user."},"422":{"description":"Validation error."}}}},"/api/v1/commands/cancelparty":{"post":{"operationId":"cancelparty","summary":"Stop a running consistent party","description":"Stops the consistent parties running on your own bots and leaves the party. Someone else’s chase is never touched. This one ignores `botCount` for the relay itself — a relay belongs to no single account, and may have moved on to one the caller never selected — though the response still reports per selected bot.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"Optional — recorded for the audit log. Every consistent party is stopped regardless."},"botCount":{"type":"integer","description":"How many bots should perform the action. Bots are leased exclusively while they work, so this draws on the accounts that are online and not already in use by someone else. If greater than the number available, every available bot is used (the max).","minimum":1,"example":1}},"required":["botCount"]},"example":{"username":"Notch","botCount":10}}}},"responses":{"200":{"description":"Command dispatched to the selected bots.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"action":{"type":"string"},"runId":{"type":"string","description":"identifies this run in the admin console’s live status view"},"requested":{"type":"integer","description":"botCount you asked for"},"available":{"type":"integer","description":"bots online AND not in use by a signed-in user"},"dispatched":{"type":"integer","description":"bots that actually ran it"},"notice":{"type":"string","nullable":true,"description":"set when fewer bots ran it than you asked for, and why"},"bots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"detail":{"type":"string"}}}}}}}}},"401":{"description":"Missing or invalid API key."},"409":{"description":"No bots were available — every online bot is currently in use by a signed-in user."},"422":{"description":"Validation error."}}}},"/api/v1/commands/boop":{"post":{"operationId":"boop","summary":"Send /boop to a player","description":"Each selected bot runs /boop <username>.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"In-game name of the player to boop."},"botCount":{"type":"integer","description":"How many bots should perform the action. Bots are leased exclusively while they work, so this draws on the accounts that are online and not already in use by someone else. If greater than the number available, every available bot is used (the max).","minimum":1,"example":1}},"required":["username","botCount"]},"example":{"username":"Notch","botCount":5}}}},"responses":{"200":{"description":"Command dispatched to the selected bots.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"action":{"type":"string"},"runId":{"type":"string","description":"identifies this run in the admin console’s live status view"},"requested":{"type":"integer","description":"botCount you asked for"},"available":{"type":"integer","description":"bots online AND not in use by a signed-in user"},"dispatched":{"type":"integer","description":"bots that actually ran it"},"notice":{"type":"string","nullable":true,"description":"set when fewer bots ran it than you asked for, and why"},"bots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"detail":{"type":"string"}}}}}}}}},"401":{"description":"Missing or invalid API key."},"409":{"description":"No bots were available — every online bot is currently in use by a signed-in user."},"422":{"description":"Validation error."}}}},"/api/v1/commands/msg":{"post":{"operationId":"msg","summary":"Send a private message to a player","description":"Each selected bot runs /msg <player> <message> and reports delivery in its activity log.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"player":{"type":"string","description":"In-game name of the message recipient."},"message":{"type":"string","description":"The message text to send."},"botCount":{"type":"integer","description":"How many bots should perform the action. Bots are leased exclusively while they work, so this draws on the accounts that are online and not already in use by someone else. If greater than the number available, every available bot is used (the max).","minimum":1,"example":1}},"required":["player","message","botCount"]},"example":{"player":"Notch","message":"gg wp","botCount":1}}}},"responses":{"200":{"description":"Command dispatched to the selected bots.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"action":{"type":"string"},"runId":{"type":"string","description":"identifies this run in the admin console’s live status view"},"requested":{"type":"integer","description":"botCount you asked for"},"available":{"type":"integer","description":"bots online AND not in use by a signed-in user"},"dispatched":{"type":"integer","description":"bots that actually ran it"},"notice":{"type":"string","nullable":true,"description":"set when fewer bots ran it than you asked for, and why"},"bots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"detail":{"type":"string"}}}}}}}}},"401":{"description":"Missing or invalid API key."},"409":{"description":"No bots were available — every online bot is currently in use by a signed-in user."},"422":{"description":"Validation error."}}}},"/api/v1/bots":{"get":{"operationId":"listBots","summary":"List the fleet and each bot’s status","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"Current fleet snapshot."},"401":{"description":"Missing or invalid API key."}}}}}}