Between Worlds API

Users API

The Users API provides access to user profiles, including their equipment, inventory, and biography.

Endpoint

GET /v2/users

Authentication

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

Query Parameters

ParameterTypeRequiredDescription
namestringNoFilter for a specific user by name
equipmentstringNoInclude equipment data in response (any value)
biographystringNoInclude biography in response (any value)
inventorystringNoInclude inventory in response (only for own user, any value)

Response

User Object

{
  name: string;
  createdAt: string;         // ISO 8601 date string
  roles: string[];           // Array of role names (e.g., ["user"], ["admin"])
  tags: any[];               // Array of user tags
  biography?: string;        // Only if requested with biography parameter
  equipment?: Array<{        // Only if requested with equipment parameter
    itemName: string;
    quality: number;         // 0-4 quality level
    moduleSlots: number;
    modules: any[];
  }>;
  inventory?: Array<{        // Only if requested with inventory parameter (own user only)
    itemName: string;
    quality: number;
    quantity: number;
    // ... other inventory properties
  }>;
}

Examples

Get All Users (Basic Info)

Returns a list of all users with basic information (name, creation date, roles).

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

Response:

[
  {
    "biography": "",
    "name": "test",
    "roles": ["user"],
    "tags": [],
    "equipment": [],
    "createdAt": "2025-12-14T19:41:26.126Z"
  },
  {
    "biography": "",
    "name": "admin",
    "roles": ["admin"],
    "tags": [],
    "equipment": [],
    "createdAt": "2025-12-14T19:41:26.191Z"
  },
  {
    "biography": "UHM....",
    "createdAt": "2026-01-09T12:54:24.886Z",
    "equipment": [],
    "roles": ["user"],
    "tags": [],
    "name": "UHM"
  }
]

Get Specific User with Equipment

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.betweenworlds.net/v2/users?name=Tester&equipment=true"

Response:

{
  "biography": "",
  "createdAt": "2025-12-15T21:07:55.838Z",
  "equipment": [
    {
      "itemName": "Hat",
      "quality": 0,
      "moduleSlots": 0,
      "modules": []
    },
    {
      "itemName": "Metal Covered Shirt",
      "quality": 2,
      "moduleSlots": 0,
      "modules": []
    },
    {
      "itemName": "Metal Stick",
      "quality": 1,
      "moduleSlots": 0,
      "modules": []
    },
    {
      "itemName": "Metal Covered Shorts",
      "quality": 0,
      "moduleSlots": 0,
      "modules": []
    },
    {
      "itemName": "Boots",
      "quality": 0,
      "moduleSlots": 0,
      "modules": []
    }
  ],
  "roles": ["user"],
  "tags": [],
  "name": "Tester"
}

Get Specific User with Biography

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.betweenworlds.net/v2/users?name=UHM&biography=true"

Response:

{
  "biography": "UHM....",
  "createdAt": "2026-01-09T12:54:24.886Z",
  "equipment": [],
  "roles": ["user"],
  "tags": [],
  "name": "UHM"
}

Get Own Inventory

To retrieve inventory, you must be the owner of the API key (keys are associated with a specific user).

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.betweenworlds.net/v2/users?name=YourUsername&inventory=true"

Response:

{
  "biography": "",
  "name": "YourUsername",
  "roles": ["user"],
  "tags": [],
  "equipment": [],
  "createdAt": "2025-12-14T19:41:26.126Z",
  "inventory": [
    {
      "itemName": "Nutrient Packet",
      "quality": 2,
      "quantity": 5
    },
    {
      "itemName": "Metal",
      "quality": 1,
      "quantity": 10
    }
  ]
}

Get All Data for Own User

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.betweenworlds.net/v2/users?name=YourUsername&equipment=true&biography=true&inventory=true"

JavaScript Example

const apiKey = 'YOUR_API_KEY';

// Get specific user with equipment
async function getUserWithEquipment(userName) {
  const params = new URLSearchParams({
    name: userName,
    equipment: 'true',
  });

  const response = await fetch(`https://api.betweenworlds.net/v2/users?${params}`, {
    headers: {
      'X-API-Key': apiKey,
    },
  });

  return response.json();
}

// Usage
getUserWithEquipment('Tester').then((user) => console.log(user));

Error Responses

Status CodeDescription
400 Bad RequestInvalid parameters or missing required fields
404 Not FoundUser with specified name not found
500 Internal Server ErrorServer error occurred

Notes

  • Inventory Access: Inventory data is only available when requesting your own user data.
  • Optional Fields: Use the equipment, biography, and inventory parameters to include additional data. Omitting these parameters will exclude the respective data from the response
  • Anonymous Users: Users marked as anonymous are not included in the API responses
  • Cached Data: User data is cached for 5 minutes to improve performance
  • Equipment Quality: Equipment items have a quality field ranging from 0-4:
    • 0 - Ragged/Shoddy
    • 1 - Rough/Worn
    • 2 - Reliable/Fine
    • 3 - Polished/Superior
    • 4 - Exquisite/Pristine
  • All Fields Returned: When using parameters like equipment=true or biography=true, note that the API returns all standard fields (name, roles, tags, equipment, biography, createdAt) regardless of which specific parameters are requested