canonical: https://jentic.com/apis/haloapi.com

# Halo API APIs

Halo API is the developer platform for Halo 5: Guardians and Halo Wars 2 game data, covering player statistics, match details, leaderboards, Spartan Company rosters, the in-game content catalogue, player-generated map and game variants, and player imagery. The APIs are read-only and title-specific to Halo 5 and Halo Wars 2, and they cover legacy 343 Industries services that fan sites, esports trackers, and community tools built on. A single Azure API Management subscription key authenticates every API in the portfolio.

## For AI agents

An agent can pull a player's Halo 5 match history, service records, and CSR leaderboard placement, resolve the map, weapon, and medal ids in those results into human-readable names and images, list a player's saved custom map and game variants, and fetch emblem, appearance, and Spartan render imagery for profile cards and match recaps.

## Scope

Use for: Read-only lookups of Halo 5: Guardians and Halo Wars 2 player stats, match details, leaderboards, in-game content metadata, user-generated variants, and player imagery for community sites, esports trackers, and recap tools.

Not supported:
- Halo Infinite stats
- matchmaking control
- in-game commerce
- writing game data
- variant binary downloads
- modern Waypoint services

## APIs

| API | Category | Endpoints | Description |
| --- | --- | --- | --- |
| Halo Metadata API | media | 37 | 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. |
| Stats | media | 28 | Look up Halo 5 and Halo Wars 2 player stats, match results, leaderboards, and service records using a developer subscription key. |
| Halo API | media | 22 | Pull Halo 5 player service records, match details, leaderboards, company stats, and player profile assets for community and esports tooling. |
| UGC | media | 4 | List a Halo 5 player's saved map and game variants and fetch metadata for a single variant by ID. |
| Halo Profile API | media | 3 | Fetch Halo 5 player imagery - emblem, appearance, and Spartan render - by gamertag for use in profile cards and match recaps. |

## Which API to use

| Need | API | Why |
| --- | --- | --- |
| Player stats, match results, service records, and CSR leaderboards | stats | Dedicated stats surface with 28 read-only endpoints for arena, warzone, custom, and campaign modes plus per-match event timelines. |
| Player stats plus a bundled set of metadata and profile lookups in one API | halo | Consolidated vendor-official spec that exposes 22 stats, metadata, and profile operations together for tools that want a single import. |
| Resolve match, map, weapon, and medal ids to names and images | metadata | The catalogue lookup layer with 37 endpoints covering Halo 5 and Halo Wars 2 in-game content. |
| Player emblem, appearance, and Spartan render imagery | profile | Three image endpoints scoped to player visuals for profile cards and recap graphics. |
| A player's saved custom map and game variants | ugc | Four endpoints for listing and fetching user-generated variant metadata from a player's file share. |

## Cross-API use cases

### Match recap with resolved names and player imagery

Fetch a Halo 5 match's details and per-player stats from the stats API, resolve the map, weapon, and medal ids against the metadata catalogue, then pull each participant's emblem and appearance image from the profile API to render a Waypoint-style recap.

Example prompt: Get the match result for a Halo 5 match id from stats, resolve every map and weapon id via metadata, fetch each player's emblem and appearance from profile, and emit a Markdown recap.

### CSR leaderboard with tier images and avatars

Poll the CSR leaderboard from the stats API, resolve each row's CSR designation id to its tier image and label through the metadata catalogue, and decorate each row with the player's emblem thumbnail from the profile API for broadcast graphics.

Example prompt: Read the CSR leaderboard for a season and playlist from stats, resolve each CSR designation via metadata, fetch each gamertag's emblem thumbnail from profile, and emit the decorated top 100.

### Custom games directory with play data

List a player's saved map and game variants from the UGC API, then cross-link each variant to match results and play counts from the stats API to build a browsable custom-games directory for a community lobby site.

Example prompt: List map and game variants for a gamertag from ugc, then query stats for matches referencing those variants and rank them by play count.

### Player profile card with recent matches

Build a shareable profile card by fetching a player's emblem and Spartan render from the profile API, their service record and recent matches from the stats API, and resolving map and playlist ids to labels through the metadata catalogue.

Example prompt: Fetch emblem and Spartan render from profile, pull the arena service record and recent matches from stats, resolve map and playlist ids via metadata, and composite a profile card.

## Why Jentic

- **Setup:** Wiring these Halo APIs by hand means registering a Halo developer portal subscription and setting the Ocp-Apim-Subscription-Key header on every stats, metadata, profile, UGC, and consolidated request yourself. With Jentic you install Jentic One once, add the Halo APIs you need from the Jentic directory, store the subscription key once, and your agent calls any of them.
- **Permission scoping:** Every Halo API in this portfolio is read-only, so your own rules in Jentic One scope the agent to just the operations it needs, such as reading a service record or listing a player's map variants, and there are no write operations for it to reach.
- **Credential handling:** Your single Halo Ocp-Apim-Subscription-Key is stored encrypted by your own Jentic One instance and injected at execution time across all five APIs, so it never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search the Jentic directory by intent such as 'get halo 5 player match history' or 'list halo maps', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint across the portfolio without crawling the Halo developer portal.

## Related vendors

- **Riot Games API** — Equivalent per-player stats, match data, and profile assets for League of Legends, Valorant, and TFT when the agent targets a Riot title instead of Halo.
- **Steam Web API** — Player stats and game data for Steam titles when the player's game is on Steam rather than Halo's Xbox ecosystem.
- **Twitch API** — Live stream and clip metadata to pair with Halo match results and custom-game variants for esports overlays and community showcases.
- **RAWG Video Games Database** — General game metadata, screenshots, and reviews for enrichment around Halo titles as games rather than per-player stats.

## FAQ

### Which Halo titles do these APIs cover?

The portfolio covers Halo 5: Guardians (including Halo 5 PC) and Halo Wars 2. It does not cover Halo Infinite or other Halo Waypoint era games, which are served by separate endpoints outside these specs.

### Are these Halo APIs still active?

These are legacy 343 Industries services for Halo 5 and Halo Wars 2. They still serve historical data for fan tools, but the Halo 5 production endpoint is marked deprecated and no new feature work or matchmaking telemetry is shipping. Check the Halo developer portal for current key availability before building.

### Do I need a separate key for each API?

No. All five APIs authenticate with the same Azure API Management subscription key sent in the Ocp-Apim-Subscription-Key header. One Halo developer portal key covers stats, metadata, profile, UGC, and the consolidated Halo API, and the rate limit is shared across them.

### How do the APIs fit together?

The stats API returns match and player data full of ids, the metadata API resolves those ids to names and images, the profile API supplies player imagery, and the UGC API lists player-authored variants. The consolidated Halo API bundles a subset of stats, metadata, and profile operations into one spec for tools that prefer a single import.

### Can an agent modify game data with these APIs?

No. Every API in the portfolio is read-only. Agents can look up stats, metadata, variants, and imagery but cannot write matches, publish variants, alter rosters, or control matchmaking.

### How should agents handle rate limits across the portfolio?

Limits are tied to the developer portal subscription tier and are shared across all APIs on the same key, so the standard tier is roughly ten requests per second in total. Cache near-static catalogue data from the metadata API and back off on HTTP 429 responses.

### Why are some of these specs published by Jentic rather than the vendor?

343 Industries does not publish an OpenAPI specification for every surface. Jentic generates and maintains specs for the metadata and profile APIs so agents can call them through structured tooling, validated against the live API, while the consolidated Halo API is the vendor-official spec.