canonical: https://jentic.com/apis/haloapi.com/halo-metadata

# Haloapi Halo Metadata API

Jentic publishes the only available OpenAPI specification for Halo Metadata API, keeping it validated and agent-ready. The Halo Metadata API exposes the catalogue of in-game content for Halo 5: Guardians and Halo Wars 2 - maps, playlists, weapons, vehicles, medals, seasons, CSR designations, leader powers, cards, campaign missions, and more. Agents use it to translate ids in match records into human-readable names and images. The catalogue is the lookup layer that pairs with the Halo stats and profile APIs.

## For AI agents

Look up Halo 5 and Halo Wars 2 in-game content - maps, playlists, weapons, vehicles, medals, cards, and leader powers - by id or in bulk.

## Scope

Does not return live match data, player stats, or profile imagery - use for Halo 5 and Halo Wars 2 catalogue lookups (maps, weapons, medals, cards, leader powers) only.

## Capabilities

- List all Halo 5 maps, weapons, vehicles, medals, and team colors
- Resolve a Halo 5 game variant by id to its name and metadata
- Look up Halo 5 playlists, seasons, skulls, and Spartan ranks
- List Halo 5 campaign missions, enemies, and commendations
- Read Halo Wars 2 cards, leader powers, and game objects
- Fetch Halo Wars 2 campaign levels, logs, and difficulties
- Resolve Halo 5 requisitions and requisition packs by id

## Use cases

### Match Detail Hydration

Convert raw Halo 5 match ids and weapon ids in a match payload into human-readable strings and image URLs by joining against the metadata catalogue. The agent caches `/h5/metadata/maps`, `/h5/metadata/weapons`, and `/h5/metadata/medals` once per session and looks up entries by id during render. This is the lookup layer that powers any Halo stats UI.

Example prompt: GET `/h5/metadata/maps` and `/h5/metadata/weapons`, build an in-memory id-to-name map, then resolve a list of match ids.

### Halo Wars 2 Leader Builder

Build a deck or leader-power loadout tool by listing `/hw2/leader-powers` and `/hw2/cards.` The agent presents the catalogue with metadata (cost, faction, rarity) and lets the user assemble a build to share. Useful for HW2 community sites that want richer build-share features.

Example prompt: GET `/hw2/cards` filtered by faction and emit the card list with name, cost, and rarity for each.

### CSR Display Tier Lookup

Render a player's CSR rank with the correct tier image and label by joining the leaderboard payload against `/h5/metadata/csr-designations.` The agent fetches CSR rows from the stats API, looks up each designation by id, and emits the tier image URL plus localised label. Saves community sites from hardcoding CSR tier data.

Example prompt: GET `/h5/metadata/csr-designations` and resolve a list of CSR ids returned by the leaderboard API.

### Agent Discovery Through Jentic

Halo community agents discover the metadata operations through Jentic by searching for intents like 'list halo maps'. Jentic returns the matching GET operation with its input schema and the agent retrieves the catalogue. The Ocp-Apim-Subscription-Key stays in your Jentic One instance.

Example prompt: Use Jentic search 'list halo maps' to find GET `/h5/metadata/maps` and execute it.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/h5/metadata/maps` | List all Halo 5 maps |
| GET | `/h5/metadata/weapons` | List all Halo 5 weapons |
| GET | `/h5/metadata/medals` | List all Halo 5 medals |
| GET | `/h5/metadata/playlists` | List all Halo 5 playlists |
| GET | `/h5/metadata/seasons` | List all Halo 5 seasons |
| GET | `/hw2/cards` | List all Halo Wars 2 cards |
| GET | `/hw2/leader-powers` | List Halo Wars 2 leader powers |
| GET | `/hw2/campaign-levels` | List Halo Wars 2 campaign levels |

## Key resources

- **Halo 5 maps** — List Halo 5 maps with image and metadata fields
- **Halo 5 weapons and medals** — List weapons, medals, vehicles, and commendations
- **Halo 5 playlists and seasons** — Read playlists and season metadata for ranked and social play
- **Halo 5 ranks** — List Spartan ranks and CSR designations
- **Halo 5 campaign** — List campaign missions, enemies, skulls, and team colors
- **Halo Wars 2 cards** — List HW2 cards, card keywords, and game object categories
- **Halo Wars 2 powers** — Read HW2 leader powers, difficulties, and campaign levels
- **Requisitions** — Resolve Halo 5 requisitions and requisition packs by id

## Why Jentic

- **Setup:** Wiring the Halo Metadata API by hand means setting its Ocp-Apim-Subscription-Key header on every call and building each Halo 5 and Halo Wars 2 catalogue lookup yourself. Through Jentic you install once, import the Halo Metadata API from the API Directory, store the subscription key once, and your agent calls it.
- **Permission scoping:** The Halo Metadata API is read-only, returning catalogue data like maps, weapons, medals, and leader powers, so scope your agent to the operations it needs, such as listing maps or Halo Wars 2 cards. You choose what it may call, and there are no write operations for it to reach.
- **Credential handling:** Your Halo Metadata Ocp-Apim-Subscription-Key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list halo maps' or 'get halo wars 2 cards', and Jentic returns the matching metadata operation with its input schema so the agent calls the right endpoint without building URLs by hand.

## Related APIs

- **Halo API** — Stats, profile, and consolidated Halo 5 endpoints that reference these metadata ids.
- **Halo Profile API** — Player profile assets - emblem, appearance, Spartan render.
- **Riot Games API** — In-game catalogue (champions, items, runes) for League of Legends and Valorant.

## FAQ

### Why is there no official OpenAPI spec for Halo Metadata API?

343 Industries does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Halo Metadata API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Halo Metadata API use?

The API uses an Azure API Management subscription key passed as the Ocp-Apim-Subscription-Key header or the subscription-key query parameter. Through Jentic, the key is encrypted in the vault and injected at execution time so the agent does not handle it directly.

### Does the Halo Metadata API cover Halo Wars 2 as well as Halo 5?

Yes. Endpoints under `/h5/metadata` serve Halo 5 catalogues (maps, weapons, medals, etc.) and endpoints under /hw2 serve Halo Wars 2 (cards, leader-powers, game-objects, campaign-levels). Both are queried with the same subscription key.

### How often does the Halo Metadata catalogue change?

Catalogue entries change rarely - typically only when 343 ships a content update for the supported title. Agents should cache responses aggressively (hours to a day) rather than calling on every request, to stay under the subscription rate limits.

### How do I look up a Halo weapon name by id through Jentic?

Run pip install jentic, then search 'list halo weapons' to find GET `/h5/metadata/weapons.` Execute it once, build an id-to-name map in memory, and reuse it across requests. The full setup runs in under five minutes.

### What rate limits apply to the Halo Metadata API?

Rate limits are tied to the Azure subscription tier of your developer key. Free keys receive a low quota and return 429 quickly; paid tiers receive higher quotas. Always cache catalogue responses since the data is near-static.

### Can I limit what my agent is allowed to do with the Halo Metadata API?

Yes. Because you run Jentic One yourself, your own rules decide which Halo Metadata operations your agent may call and which credential it uses. The Halo Metadata API is read-only catalogue data, so you can scope the agent to just the endpoints it needs, such as GET `/h5/metadata/maps` and `/h5/metadata/weapons` or GET `/hw2/cards` and `/hw2/leader-powers`, and leave the rest unavailable. There are no write operations for the agent to reach, so the worst it can do within your allowed set is list catalogue entries.