Between Worlds API

NPCs API

The NPCs API provides access to all non-player characters in the game, including their locations, dialogue, combat stats, and interactions.

Endpoint

GET /v2/npcs

Authentication

All requests require the X-API-Key header. See Authentication for details.

Query Parameters

ParameterTypeRequiredDescription
namestringNoFilter for a specific NPC by name

Response

NPC Object

{
  name: string;
  description: string;
  species: string;
  level: number;
  difficulty: number; // 0 = Normal, 1 = Elite, 2 = Veteran
  passiveSkills: string[];
  damageMin: number;
  damageMax: number;
  armour: number;
  healthMin: number;
  healthMax: number;
  imageUrl: string;
  loot: Array<{
    itemName: string;
    chance: number;
    quantityMin: number;
    quantityMax: number;
    qualityMin: number;
    qualityMax: number;
  }>;
}

Examples

Get All NPCs

Returns a list of all NPCs in the game (excluding NPCs marked as hidden from API).

curl -H "X-API-Key: YOUR_API_KEY" \
     https://api.betweenworlds.net/v2/npcs

Response:

[
  {
    "name": "Cleaning Bot",
    "species": "Robot",
    "passiveSkills": [],
    "level": 1,
    "description": "It's trying to clean, and you're dirty!",
    "damageMin": 2,
    "damageMax": 4,
    "armour": 3,
    "healthMin": 15,
    "healthMax": 22,
    "imageUrl": "https://res.cloudinary.com/between-worlds/image/upload/v1690643718/npcs/b_76_h5r9pu.webp",
    "difficulty": 0,
    "loot": [
      {
        "itemName": "Metal",
        "chance": 50,
        "quantityMin": 1,
        "quantityMax": 2,
        "qualityMin": 0,
        "qualityMax": 3
      },
      {
        "itemName": "Cog",
        "chance": 25,
        "quantityMin": 1,
        "quantityMax": 2,
        "qualityMin": 0,
        "qualityMax": 4
      },
      {
        "itemName": "Bolt",
        "chance": 25,
        "quantityMin": 1,
        "quantityMax": 2,
        "qualityMin": 0,
        "qualityMax": 4
      }
    ]
  },
  {
    "name": "Sprat",
    "species": "Rat",
    "passiveSkills": ["Fleet Feet"],
    "level": 3,
    "description": "It's a space rat.",
    "damageMin": 8,
    "damageMax": 12,
    "armour": 6,
    "healthMin": 70,
    "healthMax": 130,
    "imageUrl": "https://res.cloudinary.com/between-worlds/image/upload/v1727726759/npcs/sprat_zoomed_jaevdh.webp",
    "difficulty": 0,
    "loot": [
      {
        "itemName": "Nutrient Packet",
        "chance": 25,
        "quantityMin": 1,
        "quantityMax": 1,
        "qualityMin": 0,
        "qualityMax": 2
      }
    ]
  }
]

Get Specific NPC

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.betweenworlds.net/v2/npcs?name=Cleaning%20Bot"

Response:

{
  "name": "Cleaning Bot",
  "species": "Robot",
  "passiveSkills": [],
  "level": 1,
  "description": "It's trying to clean, and you're dirty!",
  "damageMin": 2,
  "damageMax": 4,
  "armour": 3,
  "healthMin": 15,
  "healthMax": 22,
  "imageUrl": "https://res.cloudinary.com/between-worlds/image/upload/v1690643718/npcs/b_76_h5r9pu.webp",
  "difficulty": 0,
  "loot": [
    {
      "itemName": "Metal",
      "chance": 50,
      "quantityMin": 1,
      "quantityMax": 2,
      "qualityMin": 0,
      "qualityMax": 3
    },
    {
      "itemName": "Cog",
      "chance": 25,
      "quantityMin": 1,
      "quantityMax": 2,
      "qualityMin": 0,
      "qualityMax": 4
    },
    {
      "itemName": "Bolt",
      "chance": 25,
      "quantityMin": 1,
      "quantityMax": 2,
      "qualityMin": 0,
      "qualityMax": 4
    }
  ]
}

Get Elite Difficulty NPC

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.betweenworlds.net/v2/npcs?name=Cleaning%20Boss"

Response:

{
  "name": "Cleaning Boss",
  "species": "Robot",
  "passiveSkills": ["Heavy Hands"],
  "level": 5,
  "description": "It's trying to boss, and you're not a Cleaning Bot!",
  "damageMin": 15,
  "damageMax": 20,
  "armour": 8,
  "healthMin": 300,
  "healthMax": 400,
  "imageUrl": "https://res.cloudinary.com/between-worlds/image/upload/v1618426421/sci-fiskilliconspack/b_06_vf54tu.webp",
  "difficulty": 1,
  "loot": [
    {
      "itemName": "Energy Bar",
      "chance": 100,
      "quantityMin": 1,
      "quantityMax": 2,
      "qualityMin": 0,
      "qualityMax": 2
    },
    {
      "itemName": "Cleaning Instrument",
      "chance": 50,
      "quantityMin": 1,
      "quantityMax": 1,
      "qualityMin": 0,
      "qualityMax": 4
    },
    {
      "itemName": "Metal",
      "chance": 50,
      "quantityMin": 1,
      "quantityMax": 3,
      "qualityMin": 0,
      "qualityMax": 1
    }
  ]
}

JavaScript Example

const apiKey = 'YOUR_API_KEY';

// Get all NPCs
async function getAllNPCs() {
  const response = await fetch('https://api.betweenworlds.net/v2/npcs', {
    headers: {
      'X-API-Key': apiKey,
    },
  });

  return response.json();
}

// Get specific NPC
async function getNPC(npcName) {
  const url = `https://api.betweenworlds.net/v2/npcs?name=${encodeURIComponent(npcName)}`;
  const response = await fetch(url, {
    headers: {
      'X-API-Key': apiKey,
    },
  });

  return response.json();
}

// Usage
getAllNPCs().then((npcs) => console.log(npcs));
getNPC('Cleaning Bot').then((npc) => console.log(npc));

NPC Difficulty Levels

NPCs have different difficulty levels indicated by the difficulty field:

  • 0 (Normal) - Standard enemies with basic stats
  • 1 (Elite) - Stronger enemies with enhanced stats and passive skills
  • 2 (Veteran) - Very powerful enemies with high stats and unique abilities

NPC Properties

Species

The type of creature the NPC is (Robot, Rat, Human, Demon, Slime, etc.)

Combat Stats

All NPCs have combat statistics:

  • damageMin / damageMax - Damage range for attacks
  • healthMin / healthMax - Health point range
  • armour - Damage reduction

Passive Skills

Array of passive abilities the NPC possesses (e.g., "Fleet Feet", "Heavy Hands")

Loot

Items that can be obtained from defeating the NPC:

  • itemName - Name of the dropped item
  • chance - Probability of drop (0-100)
  • quantityMin / quantityMax - Amount range that can drop
  • qualityMin / qualityMax - Quality range of the dropped item (0-4)

Error Responses

Status CodeDescription
400 Bad RequestInvalid parameters, unknown NPC name, or NPC is hidden from API
405 Method Not AllowedOnly GET requests are supported

Notes

  • Hidden NPCs: Some NPCs may be hidden from the API and won't appear in responses
  • Name Parameter: NPC names are case-sensitive. Make sure to URL-encode NPC names with spaces
  • All NPCs: When no name parameter is provided, all non-hidden NPCs are returned

Use Cases

  • Create combat guides with NPC stats and strategies
  • Build loot tables and drop rate calculators
  • Display NPC bestiaries with species information
  • Develop difficulty-based encounter guides
  • Create item farming guides based on NPC drops
  • Build game wikis and databases