# Reference catalogs

Read classes, playable races, factions, and hunter pet families in JavaScript or JSON.

Source: https://warcraftforever.com/developers/catalogs/

Build character selectors, class filters, and pet-family pickers without an account or API key. Every snapshot identifies its client build; `nameLocale` reports the actual language of each name, including English fallback.

## JavaScript

```html
<script src="https://warcraftforever.com/catalog/latest.js"></script>
<script>
  async function loadOptions() {
    const [classes, races, families] = await Promise.all([
      $WF.Classes.list({ locale: 'enUS' }),
      $WF.Races.list({ locale: 'enUS' }),
      $WF.Pets.families({ locale: 'enUS' })
    ]);
    const race = await $WF.Races.get('high-order-skyborne');
    const availableClasses = classes.filter((cls) => race.classIds.includes(cls.id));
    console.log({ races, families, availableClasses });
  }
  loadOptions().catch(console.error);
</script>
```

The library extends `WarcraftForever.Classes`, `.Races`, `.Factions`, and `.Pets`. `$WF` follows the [alias rules](https://warcraftforever.com/developers/quickstart/#short-namespace); add `?alias=0` to avoid creating it. It works independently of Talents and Tooltips, in either load order.

Classes, races, and factions have `list(options)` and `get(idOrSlug, options)`. An unknown lookup returns `null`. Pets has `families(options)` and `family(id, options)`. All reads return promises; failures reject so your application can show a retry state. Editing a returned object does not change later reads.

Catalogs load lazily: the first read fetches one shared manifest and the complete requested collection. Further `get` and `list` calls use memory, including lookups that return `null`. Concurrent calls share the same request. Classes, races, factions, and pet families each load only when used; dataset and locale entries remain separate. Failed loads can be retried. The manifest and successful catalogs stay cached for the page or client lifetime; reload the page or create a new module client to discover newer data.

`options.channel` defaults to the published default. `options.locale` accepts a client locale or browser language and otherwise follows the browser. Supported client locales are `enUS`, `deDE`, `esES`, `frFR`, `koKR`, `ptBR`, `ruRU`, and `zhCN`. Missing translations use English with `nameLocale: 'enUS'`. Player faction names currently use English.

`$WF.Catalog.manifest()` returns published builds, channels, and source provenance. Classes include their class-wide specialization and an icon URL. Races carry `faction` and `classIds`, with stable English slugs including separate High Order and Windshaper Skyborne keys. Player faction IDs are API enums: `1` for Alliance and `2` for Horde, distinct from reputation faction IDs.

Pet families are animal families with a configured diet in the client `CreatureFamily` table. They retain client IDs and raw `foodMask` and `talentType` fields. These describe the client definition; they do not establish whether an individual NPC can be tamed. Individual creatures, locations, abilities, and models are outside this catalog.

## HTTP JSON and pinned data

```js
const origin = 'https://warcraftforever.com';
async function readJson(path) {
  const response = await fetch(origin + path);
  if (!response.ok) {
    throw new Error(`Catalog read failed: ${response.status}`);
  }
  return response.json();
}
const manifest = await readJson('/api/catalog/v1/manifest');
const { dataset } = manifest.channels[manifest.defaultChannel];
const payload = await readJson(`/api/catalog/v1/${dataset}/enUS/races`);
console.log(payload.build, payload.data);
```

The manifest lists `classes`, `races`, `factions`, and `pet-families`. Each resource response contains `schemaVersion`, `dataset`, `channel`, `build`, `locale`, `resource`, and `data`. Manifest channel entries include the product, exact build, source access URL, and source table hashes.

The HTTP manifest is cached for five minutes. Dataset bytes are immutable, but origin availability is bounded: each channel keeps the latest three distinct published pin sets per patch across its latest two patches. A patch is the first three client-build components; same-build refreshes can publish another revision. Identical pin sets do not consume another revision. Current deployments and explicitly selected rollback targets remain protected while referenced. An expired origin pin returns 404, with no fallback to newer data. Save complete response envelopes in your own storage when you need longer availability. Pinning `/catalog/releases/<version>.js` freezes SDK code; its list methods resolve the current catalog on first use unless `options.dataset` supplies a pin. GET and HEAD support public cross-origin access. Unknown datasets/resources return 404, unsupported client locales return 400, and unavailable assets return 503. Errors are not cached.

## Read saved catalogs

`$WF.Catalog.createClient({ dataset, locale, reader })` or the module's `createClient` creates an isolated client. The optional reader receives the resolved URL and fetch options, and returns a normal `Response`. It handles discovery and collections; an explicit dataset pin skips discovery. It applies to that client, not per-call options. Default clients keep using `fetch`.

```js
const archived = $WF.Catalog.createClient({
  dataset: savedDataset,
  locale: 'enUS',
  reader: (url, options) => {
    // Store complete JSON envelopes under their original API paths in any folder.
    const archiveUrl = new URL('/my-saved-version' + url.pathname + '.json', location.origin);
    return fetch(archiveUrl, options);
  }
});
const races = await archived.Races.list();
```

Cache sharing, retry after failure, errors and detached returned objects retain the normal client behavior. Different clients have separate caches and readers. Your archive determines how long saved data remains available. Pin SDK code separately; images and linked site pages are separate resources and are not mirrored by the reader.

## TypeScript and agents

Use `/catalog/latest.mjs` with its adjacent declarations for typed imports. The [catalog type entry](https://warcraftforever.com/catalog/types.d.ts) exposes script-tag globals and exported interfaces; preserve its referenced declaration files when downloading. Pinned declarations are at `/catalog/releases/<version>.d.ts`, using `$WF.Catalog.version`. See the generated [type reference](https://warcraftforever.com/developers/reference/types/) for record shapes.

The [MCP endpoint](https://warcraftforever.com/developers/ai/) offers `list_catalogs` for discovery and `get_catalog` for the same complete payload. Agents can also read HTTP URLs directly, including pinned dataset URLs.

## More data to build with

Use [Game data](https://warcraftforever.com/developers/data/) for items, recipes, professions, supported spell variants and reference values. Use [headless builds](https://warcraftforever.com/developers/headless/) to validate and compare allocations. Quest, loot and NPC corpora remain unavailable until their source and coverage contracts are established.