Housing — Blizzard API Endpoint Mapping

Mapping of all Blizzard REST API endpoints for the Housing & Neighborhoods feature. Housing was introduced in WoW Midnight (11.1.5) with REST API access in 11.2.7 (December 2025).

Status Summary

Area	Status	Notes
Decor catalog (Game Data)	Live	1,668 decor items, 581 fixtures, 1,808 fixture hooks, 22 rooms
Decor collection (Profile)	Live	Per-character collected decor with quantities
Character house (Profile)	Not live	Documented but 404 universally (Feb 2026)
Account-wide collection	404	`/profile/user/wow/collections/decor` listed but returns 404

Auth note: Game Data endpoints work with client-credentials tokens via Authorization: Bearer header (NOT query param). Profile endpoints require user access tokens.

Game Data API — Housing Decor

Namespace: static-us (versioned as static-12.0.1_65617-us) Auth: Client credentials token Base: https://{region}.api.blizzard.com

Decor (Decorative Items)

Endpoint	Purpose	Items
`GET /data/wow/decor/index`	List all decor items	1,668
`GET /data/wow/decor/{decorId}`	Single decor item detail	—
`GET /data/wow/search/decor`	Paginated search with locale data	—

Index response:

{
  "_links": { "self": { "href": "..." } },
  "decor_items": [
    {
      "key": { "href": "...decor/533?namespace=static-..." },
      "name": "Sturdy Wooden Interior Pillar",
      "id": 533
    }
  ]
}

Detail response:

{
  "_links": { "self": { "href": "..." } },
  "id": 80,
  "name": "Ornate Stonework Fireplace",
  "items": {
    "key": { "href": "...item/235994?namespace=static-..." },
    "name": "Ornate Stonework Fireplace",
    "id": 235994
  },
  "dye_slots": [
    { "slot_index": 1, "dye_color_category": "Metal" },
    { "slot_index": 2, "dye_color_category": "General" }
  ]
}

Key fields:

id — Blizzard decor ID
name — Localized decor name
items — Link to the underlying WoW item (use items.id for media lookup)
dye_slots — Optional; array of dyeable slots with color categories

Media: Decor items don't have their own /media endpoint. Use the linked item ID:

GET /data/wow/media/item/{items.id}
→ assets[0].value = icon URL (e.g. https://render.worldofwarcraft.com/.../inv_12ph_opulent_fireplace01.jpg)

Search response: Paginated, includes all locale translations and item ref:

{
  "page": 1,
  "pageSize": 3,
  "pageCount": 556,
  "results": [
    {
      "key": { "href": "...decor/2230..." },
      "data": {
        "id": 2230,
        "name": {
          "en_US": "Blackrock Lamppost",
          "de_DE": "Laternenmast des Schwarzfelsklans",
          "...": "..."
        },
        "item": {
          "name": { "en_US": "Blackrock Lamppost", "...": "..." },
          "id": 246413
        }
      }
    }
  ]
}

Fixture (Structural Components)

Endpoint	Purpose	Items
`GET /data/wow/fixture/index`	List all fixtures	581
`GET /data/wow/fixture/{fixtureId}`	Single fixture detail	—
`GET /data/wow/search/fixture`	Paginated search with locale data	—

Index response:

{
  "fixtures": [
    { "key": { "href": "..." }, "name": "Woodland Dormer - Forest", "id": 5501 }
  ]
}

Detail response:

{ "id": 5501, "name": "Woodland Dormer - Forest" }

Fixtures are structural house components (dormers, walls, exterior pieces). Simpler than decor — no item link or dye slots.

Fixture Hook (Attachment Points)

Endpoint	Purpose	Items
`GET /data/wow/fixture-hook/index`	List all fixture hooks	1,808
`GET /data/wow/fixture-hook/{fixtureHookId}`	Single hook detail	—
`GET /data/wow/search/fixture-hook`	Paginated search	—

Index response:

{
  "fixture_hooks": [{ "key": { "href": "..." }, "name": "Window", "id": 21149 }]
}

Detail response:

{
  "id": 21149,
  "type_name": "Window",
  "parent_fixture": {
    "key": { "href": "...fixture/577..." },
    "name": "Stone",
    "id": 577
  }
}

Fixture hooks define where things attach to fixtures. Each hook has a type_name (e.g. "Window") and references a parent_fixture.

Room

Endpoint	Purpose	Items
`GET /data/wow/room/index`	List all room types	22
`GET /data/wow/room/{roomId}`	Single room detail	—
`GET /data/wow/search/room`	Paginated search with locale data	—

All rooms:

ID	Name
1	Square Room (Small)
2	Hallway
3	Closet
6	T-Shaped Room
7	Square Room (Tiny)
8	L-Shaped Room
9	Octagon Room (Medium)
10	Stairwell (Left)
11	Square Room (Medium)
12	Square Room (Large)
13	Cross-Shaped Room
14	Octagon Room (Small)
15	Octagon Room (Large)
18	Base Plot Medium
46	Entry
48	Stairwell Room (Empty)
50	Stairwell (Right)
223	Daylight Circle Room
233	Evening Circle Room

Profile API — Character Housing

Namespace: profile-us Auth: User access token (OAuth — requires wow.profile scope) Base: https://{region}.api.blizzard.com

Character Decor Collection

Endpoint	Purpose	Status
`GET /profile/wow/character/{realmSlug}/{characterName}/collections/decor`	Collected decor with quantities	Live
`GET /profile/user/wow/collections/decor`	Account-wide collection	404 (listed but not working)

Response:

{
  "_links": { "self": { "href": "..." } },
  "decor_collected": [
    {
      "decor": {
        "key": { "href": "...decor/5527?namespace=static-..." },
        "name": "Illidari Glaiverest",
        "id": 5527
      },
      "quantity": 1
    },
    {
      "decor": {
        "key": { "href": "...decor/772..." },
        "name": "Creeping Corner Ivy",
        "id": 772
      },
      "quantity": 21
    }
  ]
}

Key fields:

decor_collected[] — Array of collected decor items
decor_collected[].decor — Reference to Game Data decor (id, name, key)
decor_collected[].quantity — How many the player owns (stackable items can be >1)

Character House

Endpoint	Purpose	Status
`GET /profile/wow/character/{realmSlug}/{characterName}/house/house-{houseNumber}`	Character's house layout/data	Live (response shape TBD)

House numbers come from the character profile response. The standard GET /profile/wow/character/{realm}/{name} endpoint now includes a houses array:

{
  "houses": [
    {
      "href": "https://us.api.blizzard.com/profile/wow/character/illidan/dragopriest/house/house-1?namespace=profile-us"
    }
  ]
}

houses — Array of href links (characters can have multiple houses)
House number is extracted from the URL path (house-1, house-2, etc.)
Characters without a house omit the houses field entirely
Requires user access token (client credentials returns 404)

Tested via running app (Feb 2026):

collections/decor confirmed working with stored user token — returned 787 collected items
house/house-1 returns empty 404 everywhere — our stored token, client creds, and dev portal "Try It" console. Endpoint is documented but not live yet.
houses field confirmed present on character profiles for characters with a house (Dragopriest), absent for characters without one

The house/house-{N} endpoint is documented in the dev portal but returns 404 universally (as of Feb 2026). Response shape unknown. Likely includes room layout, placed decor/fixtures, and customization state once it goes live.

Data Relationships

Decor Item ──items──→ WoW Item ──media──→ Icon URL
     │
     └── dye_slots[] (optional color customization)

Fixture ←── parent_fixture ── Fixture Hook
  (structural)                  (attachment point)

Room (22 types — house layout building blocks)

Character Profile ──houses[]──→ href links to house-1, house-2, ...
Character ──collections/decor──→ decor_collected[] (with quantity)
Character ──house/house-N──→ house layout data (user token required)

Housing Domain Model (from Datamining)

Datamined PlayerHousingConstants Lua enums provide additional context not in the REST API:

Decor Classification

Enum	Values
HousingDecorFlags	Exterior (1), Interior (2)
HousingDecorType	Floor (1), Wall (2), Ceiling (3), Tabletop (4)
HousingDecorTheme	Folk (1), Rugged (2), Generic (3), Opulent (4)
HousingDecorModelType	M2 (1, small objects), Wmo (2, large world objects)
Dye Color Categories	Metal, General (from REST API)

Room / Fixture Classification

Enum	Values
HousingRoomComponentType	Wall (1), Floor (2), Ceiling (3), Stairs (4), Pillar (5)
HousingExteriorComponentSize	Any, Small, Medium, Large
HousingExteriorComponentTheme	Human (only one so far)
HousingRoomComponentDoorType	None (0), NarrowDoor (1), LargeDoor (2)

Permissions (Bitmask)

Permission	Value
AddDecor	1
ChangeDecorParam	2
EnterDecorEditMode	4
MoveDecor	8
RemoveDecor	16
SaveHouse	32
SelectDecor	64
EditLayout	128

Implementation Notes

Auth Requirements

Endpoint Type	Token	How We Get It
Game Data (`/data/wow/...`)	Client credentials	`BattleNetAdapter.ensureAccessToken()` — already implemented
Profile (`/profile/wow/...`)	User access token	`BattleNetTokenService.refresh()` — already implemented

Important: Game Data endpoints return 404 when token is passed as ?access_token= query param. Must use Authorization: Bearer header. Our BattleNetAdapter already uses headers, so this is fine.

Sync Strategy

Implemented in apps/api/src/game-data/housing-sync.service.ts. Uses incremental chunked upserts — no all-or-nothing transaction.

For each entity type (decor, fixtures, fixture hooks, rooms):

Fetch en_US index → e.g. GET /data/wow/decor/index?locale=en_US
Upsert base rows → Batched prisma.$transaction([upsert, upsert, ...]) in chunks of 100
Fetch other locale indexes → One index call per locale (6 total)
Upsert locale rows → deleteMany({ where: { locale } }) + createMany per locale
(Decor only) Detail enrichment → GET /data/wow/decor/{id} for itemId + dyeSlots, 10 concurrent
(Decor only) Icon resolution → Fetch item media URLs, upload to S3, update DB rows

Each step persists immediately — partial progress is saved if the sync fails partway through. Progress is emitted via WebSocket after each chunk.

The search endpoints are not used for decor/fixtures/rooms (search caps at 1,000 results). Search is only used for fixture hooks to get parentFixtureId (the index doesn't include it).

Volume Estimates

Resource	Count	Sync Approach
Decor items	1,668	Index per locale (7 calls) + detail per item (~1,668)
Fixtures	581	Index per locale (7 calls)
Fixture hooks	1,808	Index per locale + search for parentFixtureId (~10 pages)
Rooms	19	Index per locale (7 calls)
Character collections	per-user	On-demand with user token

Action Items

Monitor house endpoint — house/house-{N} documented but 404 universally; re-test after patches
Monitor account-wide endpoint — /profile/user/wow/collections/decor also listed but 404; may go live later
~~Design Prisma models~~ — Done (Sprint 4)
~~Implement decor catalog sync~~ — Done (Sprint 4, incremental chunked upserts)
Add to character enrichment — Fetch collected decor during character sync

Status Summary​

Game Data API — Housing Decor​

Decor (Decorative Items)​

Fixture (Structural Components)​

Fixture Hook (Attachment Points)​

Room​

Profile API — Character Housing​

Character Decor Collection​

Character House​

Data Relationships​

Housing Domain Model (from Datamining)​

Decor Classification​

Room / Fixture Classification​

Permissions (Bitmask)​

Implementation Notes​

Auth Requirements​

Sync Strategy​

Volume Estimates​

Action Items​

References​

Status Summary

Game Data API — Housing Decor

Decor (Decorative Items)

Fixture (Structural Components)

Fixture Hook (Attachment Points)

Room

Profile API — Character Housing

Character Decor Collection

Character House

Data Relationships

Housing Domain Model (from Datamining)

Decor Classification

Room / Fixture Classification

Permissions (Bitmask)

Implementation Notes

Auth Requirements

Sync Strategy

Volume Estimates

Action Items

References