v1.0 Beta

Public API

Read-only REST API for Vampires vs. Werewolves game data. Build Discord bots, fan wikis, build calculators, and stat trackers. No account required for public endpoints.

Beta notice: The public API is in beta. Endpoints and response shapes may change. Breaking changes will be announced in patch notes and on Discord with 2 weeks notice.

Overview

The VvW Public API exposes read-only game data. All responses are JSON. Authentication is not required for public endpoints, but rate limits apply.

What you can build: Discord bots that look up item stats · Fan wiki data feeds · Build calculators · Leaderboard trackers · Crafting profit tools

Base URL

https://duskmaw.com/api/public/v1

All endpoints are relative to this base URL. Responses use UTF-8 encoding. All timestamps are ISO 8601 in UTC.

Authentication

Public endpoints require no authentication. Pass an optional X-VvW-Client header to identify your application — this helps us contact you before breaking changes.

# Optional but recommended
X-VvW-Client: my-discord-bot/1.0 (contact@example.com)

Rate Limits

Tier	Limit	Window
Anonymous	60 requests	Per minute
With X-VvW-Client	120 requests	Per minute

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.

Items

GET /items List all items

Query Parameters

Parameter	Type	Description
typeoptional	string	Filter by item type: `weapon`, `armor`, `consumable`, `rune`, `accessory`
rarityoptional	string	`common`, `rare`, `epic`, `legendary`
pageoptional	integer	Page number, default 1
limitoptional	integer	Results per page, max 100, default 50

Example Response

{
  "total": 976,
  "page": 1,
  "items": [
    {
      "id": 1001,
      "name": "Void-Forged Blade",
      "type": "weapon",
      "rarity": "legendary",
      "stats": { "atk": 312, "crit_chance": 0.12, "lifesteal": 0.08 },
      "required_level": 60,
      "set": "Void Sentinel",
      "wiki_url": "https://duskmaw.com/wiki/items/void-forged-blade.html"
    }
  ]
}

GET /items/{id} Single item by ID

Parameter	Type	Description
idrequired	integer	Item ID (1001–1976)

Monsters

GET /monsters List all monsters

Parameter	Type	Description
zoneoptional	string	Filter by zone slug (e.g. `moonstone-highlands`)
typeoptional	string	`normal`, `elite`, `boss`
page / limitoptional	integer	Pagination

{
  "total": 291,
  "monsters": [
    {
      "id": 201,
      "name": "Void Abomination",
      "type": "boss",
      "zone": "void-zone",
      "level_range": [55, 65],
      "hp": 48000,
      "drops": [1018, 1019, 1021]
    }
  ]
}

Recipes

GET /recipes All crafting recipes

Parameter	Type	Description
stationoptional	string	`forge`, `alchemist`, `enchanter`, `runesmith`
result_item_idoptional	integer	Filter by the item the recipe produces

{
  "total": 383,
  "recipes": [
    {
      "id": "recipe_void_blade",
      "station": "forge",
      "result_item_id": 1001,
      "materials": [
        { "item_id": 501, "qty": 5 },
        { "item_id": 502, "qty": 3 }
      ],
      "required_level": 55,
      "craft_time_seconds": 3600
    }
  ]
}

Skills

GET /skills All skills by class

Parameter	Type	Description
subclassoptional	string	`blood-mage`, `shadow-assassin`, `dark-knight`, `berserker`, `pack-shaman`, `moon-warrior`

{
  "total": 130,
  "skills": [
    {
      "id": "V01",
      "name": "Blood Drain",
      "subclass": "blood-mage",
      "type": "active",
      "damage_formula": "ATK * 1.8 + INT * 0.4",
      "cooldown": 3,
      "lifesteal": 0.2,
      "unlock_level": 20
    }
  ]
}

Leaderboard

Privacy note: Only players with public profiles appear in leaderboard results. Player names are display names, not internal IDs.

GET /leaderboard Top players by category

Parameter	Type	Description
categoryrequired	string	`pvp`, `prestige`, `wealth`, `faction`
factionoptional	string	`vampire` or `werewolf`
limitoptional	integer	Max 100, default 25

{
  "category": "pvp",
  "season": "S4",
  "updated_at": "2026-04-30T12:00:00Z",
  "entries": [
    { "rank": 1, "name": "GrizzledFang", "faction": "werewolf", "elo": 2847, "subclass": "berserker" },
    { "rank": 2, "name": "LordMalachite", "faction": "vampire", "elo": 2791, "subclass": "shadow-assassin" }
  ]
}

Factions

GET /factions/war Current faction war standings

{
  "season": "Eclipse War S4",
  "ends_at": "2026-06-21T00:00:00Z",
  "vampire": { "score": 1482300, "territories": 14 },
  "werewolf": { "score": 1391700, "territories": 11 }
}

Error Codes

HTTP Status	Code	Meaning
400	bad_request	Missing or invalid parameter
404	not_found	Resource does not exist
429	rate_limited	Too many requests — check X-RateLimit-Reset
500	server_error	Internal error — please report on Discord

{
  "error": "not_found",
  "message": "Item with id 9999 does not exist",
  "status": 404
}

Changelog

2026-04-30 v1.0 Beta launch — Items, Monsters, Recipes, Skills, Leaderboard, Faction War endpoints live.

Community Uses

Built something with the VvW API? Let us know on Discord — we feature community tools on this page.

Get notified of breaking changes: Join the #vvw-api Discord channel to receive API update announcements. API consumers with X-VvW-Client headers may be contacted directly before breaking changes ship.