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
Global default (all endpoints)	200 requests	Per minute, per IP
Sensitive auth endpoints	3–30 requests	Per minute or per hour, per IP

The global default applies to every endpoint. Individual endpoints that touch credentials, tokens or OAuth flows (login, register, password reset, email verification, OAuth callbacks, session revocation) carry their own stricter limit on top of it, so a response can be rate limited well below 200/minute.

Rate limit headers are included on every response that reached a rate-limited endpoint (requests rejected earlier, e.g. an unauthenticated call to a protected route, may omit them): X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Exceeding a limit returns 429 Too Many Requests with a Retry-After header.

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.