Reference

Schema

HallownestAPI is schema-first. Every entity is validated with Zod, both on import and at request time.

Boss

The boss entity. Required fields are slug, name, game, area, and summary.

lib/schema.ts

import { z } from "zod";

export const GameSchema = z.enum(["hk", "silksong"]);

export const AreaRefSchema = z.object({
  slug: z.string(),
  name: z.string(),
});

export const BossSchema = z.object({
  slug: z.string(),                       // kebab-case
  name: z.string(),
  game: GameSchema,
  optional: z.boolean().default(false),
  hp: z.record(z.enum(["base","attuned","ascended","radiant"]), z.number()).optional(),
  geo: z.number().int().optional(),
  area: AreaRefSchema,
  phases: z.array(z.object({
    name: z.string(),
    hp: z.number().optional(),
    description: z.string().optional(),
  })).optional(),
  attacks: z.array(z.object({
    name: z.string(),
    damage: z.number().optional(),
    description: z.string().optional(),
  })).optional(),
  rewards: z.array(z.string()).optional(),
  pantheon: z.array(z.string()).optional(),
  hunterJournal: z.object({
    entryNumber: z.number().optional(),
    notes: z.string().optional(),
  }).optional(),
  summary: z.string(),
  verified: z.boolean().default(false),
  sources: z.array(z.string().url()).optional(),
  updatedAt: z.string().datetime().optional(),
});

Conventions

slug: lowercase ASCII kebab-case. Stable. Never reused.
verified: set to true only after a contributor has cross-referenced the value with the game.
hp: a record keyed by difficulty tier. base is the unmodified value; attuned / ascended / radiant are HK’s Godhome scalings.
sources: external URLs that justify the data — wiki pages, decompilation dumps, dev notes.