ASTROWORLD API
Free, public Minecraft data API. JSON responses, CORS enabled, no auth required.
Base URL: https://api.astroworldmc.com
Endpoints
/api/v1/mobs?search=&type=&category=All 76 Minecraft mobs with stats, drops, behavior
/api/v1/mobs/:idSingle mob by ID or name slug
/api/v1/biomes?search=&dimension=&category=&rarity=All 64 biomes with terrain, colors, spawns
/api/v1/biomes/:nameSingle biome by ID or name slug
/api/v1/items?search=&category=100 items with crafting recipes, stats, enchantments
/api/v1/items/:idSingle item by ID or name slug
/api/v1/enchantments?search=&category=40 enchantments with levels, compatibility, effects
/api/v1/enchantments/:idSingle enchantment by ID or name slug
/api/v1/structures?search=&dimension=&category=&rarity=24 structures with loot tables, locations, dangers
/api/v1/structures/:idSingle structure by ID or name slug
/api/v1/commands?search=&category=&permissionLevel=57 commands with syntax, params, examples
/api/v1/commands/:nameSingle command by name
/api/v1/versions?search=&type=&edition=36 version entries with features and changelogs
/api/v1/versions/:slugSingle version by slug (e.g. 1-21)
/api/v1/achievements?search=&tab=&difficulty=111 advancements with tabs, difficulty, rewards
/api/v1/achievements/:slugSingle achievement by slug
/api/v1/trades?search=All villager professions with full trade tables
/api/v1/trades/:idSingle profession trade data by ID
/api/healthAPI health check
Pretty Print
Add ?pretty=true to any list endpoint for formatted JSON output. Single lookups such as /api/v1/mobs/creeper always come back compact.
Quick Start
JavaScript
const res = await fetch("https://api.astroworldmc.com/api/v1/mobs?search=creeper");
const data = await res.json();
console.log(data.data[0].name); // "Creeper"Python
import requests
res = requests.get("https://api.astroworldmc.com/api/v1/mobs/creeper")
mob = res.json()["data"]
print(mob["name"]) # Creepercurl
curl -s https://api.astroworldmc.com/api/v1/biomes?dimension=nether | jq '.data[].name'
Rate Limits
| Tier | Limit | Window |
|---|---|---|
| Free | 100 requests | per minute per IP |
Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Response Format
Success (200)
{
"success": true,
"count": 76,
"data": [...]
}Error (404)
{
"success": false,
"error": "Mob not found"
}Filtering and Lookups
Every list endpoint takes search, which matches part of the name and ignores case, so /api/v1/mobs?search=spider returns both Spider and Cave Spider. On versions it also looks at the update name: ?search=trails finds 1.20, Trails & Tales.
The other filters only return exact matches, and the value you send is lowercased first, so type=Hostile works as well as type=hostile. Filters combine: /api/v1/biomes?dimension=overworld&rarity=very_rare returns Eroded Badlands and Mushroom Fields.
| Endpoint | Filter | Values in the data |
|---|---|---|
/mobs | type, category | passive, neutral, hostile, boss |
/biomes | dimension | overworld, nether, end |
/biomes | category | temperate, cold, warm, ocean, underground, beach_special, nether, end |
/biomes | rarity | common, uncommon, rare, very_rare |
/items | category | tool, weapon, armor, food, block, redstone, potion, music_disc, transportation, miscellaneous |
/enchantments | category | melee, ranged, mining, armor, universal, special |
/structures | dimension | overworld, nether, end |
/structures | category | overworld_surface, overworld_underground, ocean, nether, end |
/structures | rarity | common, uncommon, rare, very_rare, unique |
/commands | category | player, world, server, data, display, logic, gameplay, special, time_weather, bossbar, execute |
/commands | permissionLevel | 0, 2, 3, 4 |
/versions | type | major-release, minor-release |
/versions | edition | java |
/achievements | tab | minecraft, nether, end, adventure, husbandry |
/achievements | difficulty | easy, medium, hard, expert |
Single lookups take the ID or the name written as a slug. /api/v1/mobs/cave-spider, /api/v1/items/diamond-sword and /api/v1/biomes/cherry-grove all work, and biomes also answer to the full ID, minecraft:plains. Versions accept 1.21 as well as 1-21, commands are found by name without the slash, and trades by profession ID, such as /api/v1/trades/librarian.
The trade data covers the 13 villager professions that have a workstation. The wandering trader is not part of it.
What Each Resource Returns
A list wraps its results in data next to a count; a single lookup puts the object itself under data and has no count. A field that does not apply is null rather than missing, like the durability of a food item or the tamingMethod of a mob nobody can tame.
| Resource | Fields |
|---|---|
mobs | name, id, type, category, hp, damage (easy, normal, hard), xpDrop (min, max), spawnBiomes, spawnConditions, drops (item, count, chance), behavior, weaknesses, tameable, tamingMethod, breedable, breedingItem, versionAdded, notes |
biomes | name, id, dimension, category, temperature, precipitation, terrainFeatures, uniqueBlocks, spawningMobs, structuresFound, colors (grass, water, foliage, sky), rarity, versionAdded, notes |
items | name, id, category, stackSize, durability, description, obtainedBy, craftingRecipe (pattern, ingredients, output, station), enchantable, applicableEnchantments, foodValue (hunger, saturation), fuelValue, versionAdded, notes |
enchantments | name, id, maxLevel, description, effectPerLevel, applicableItems, incompatibleWith, obtainedFrom, weight, treasureOnly, curseOf, category, versionAdded, notes |
structures | name, id, dimension, category, biomes, rarity, yLevel (min, max), features, hostileMobs, loot (item, chance, count), uniqueLoot, howToFind, dangers, rewards, versionAdded, notes |
commands | name, syntax, description, parameters (name, type, optional, description), permissionLevel, category, examples (code, explanation), commonMistakes, relatedCommands, versionAdded, notes |
versions | slug, name, edition, releaseDate, type, updateName, majorFeatures, notableChanges, notableFixes, previousVersion, nextVersion |
achievements | slug, name, id, description, tab, icon, howToComplete, parent, difficulty, xpReward, prerequisites, rewards, isChallenge, isGoal, versionAdded |
trades | id, name, workstation, description, biomeSpecific, levels (level, name, trades with gives, givesAmount, receives, receivesAmount, maxUses and edition, plus priceEmeralds, gives2 and notes where they apply) |
Two fields that look alike use different scales. A drop chance on a mob is a percentage, so the iron ingot a zombie drops at 2.5 means 2.5%. A loot chance on a structure is a fraction between 0 and 1, so the bread in a village chest at 0.62 means 62%.
Trade levels run Novice, Apprentice, Journeyman, Expert and Master. Each trade has an edition of both or java, and the java ones exist only in Java Edition.
Errors, Limits and CORS
The limit is 100 requests per IP address per minute. That minute starts with your first request, and request 101 inside it gets status 429, a Retry-After header with the seconds that are left, and this body:
{
"success": false,
"error": "Rate limit exceeded. Max 100 requests per minute."
}Every API response carries X-RateLimit-Remaining, so a script can pause before it runs out. Only paths under /api/ count toward the limit; opening this page does not.
A lookup that finds nothing returns 404 with an error that names what was missing, such as Mob not found or Version not found. All routes answer the OPTIONS preflight with 204 and send Access-Control-Allow-Origin: *, which is why the API works from JavaScript in a browser without a proxy.
For uptime checks there is /api/health. It returns status ok, the current timestamp and the API version, 1.0.0.
Common Questions
Do I need an API key?
No. There is no sign-up and no key; you call the URLs directly. The free tier does ask for a visible dofollow link to api.astroworldmc.com on any page that uses the data.
How many requests can I make?
100 per minute from one IP address. Request 101 inside the same minute gets a 429 response with a Retry-After header, and every response tells you how many requests are left in X-RateLimit-Remaining.
Can I use the API from JavaScript in the browser?
Yes. Every route sends Access-Control-Allow-Origin: * and answers the OPTIONS preflight with 204, so fetch works from any origin.
How does search work?
search matches part of the name and ignores case, so ?search=spider on /api/v1/mobs returns Spider and Cave Spider. On /api/v1/versions it also matches the update name. The other filters need an exact value, such as rarity=very_rare.
Why does my lookup return 404?
Single lookups need the ID or the name as a slug, such as cave-spider or 1-21. Commands are looked up without the slash, so /api/v1/commands/give works, and the trade data covers the 13 villager professions but not the wandering trader.
Attribution
The free tier requires a visible dofollow link on any page that uses this API:
<a href="https://api.astroworldmc.com">Powered by Astroworld API</a>