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

# Halo API

The Halo API (deprecated production endpoint) provided structured access to Halo 5: Guardians game data including match details, player service records for arena, warzone, and custom modes, leaderboards, company stats, and a curated set of metadata, profile, and stats endpoints. This consolidated spec exposes 22 operations across stats, metadata, and profile groups for fan sites, esports trackers, and Halo community tools. Note that 343 Industries has deprecated this title-specific API as Halo 5 services have wound down.

## For AI agents

Pull Halo 5 player service records, match details, leaderboards, company stats, and player profile assets for community and esports tooling.

## Scope

Does not cover Halo Infinite or modern Waypoint services, matchmaking control, or in-game commerce - use for legacy Halo 5 stats, metadata, and profile reads only.

## Capabilities

- Fetch the full match details for a Halo 5 match by match id
- Retrieve a player's recent matches with map, mode, and outcome
- Pull arena, warzone, and custom service records for one or more players
- Read company stats and roster for a Halo 5 company by id
- Get the CSR season-end leaderboard for a specific playlist and season
- Read Halo 5 metadata: maps, playlists, weapons, medals, vehicles, seasons, and more
- Retrieve player profile appearance, emblem, and Spartan render images

## Use cases

### Esports Match Recap Generator

Generate match recap pages from Halo 5 match details. The agent fetches `/stats/h5/matches/{matchId}` for each event, pulls per-player stats, and renders a Markdown recap with kill counts, medals earned, and map-specific outcomes. Fan sites and tournament organisers used this to publish recaps within minutes of a match finishing.

Example prompt: GET `/stats/h5/matches/{matchId}` for the match id and emit a Markdown recap listing each player's score, kills, deaths, and top three medals.

### Player Stats Dashboard

Power a personal Halo 5 stats dashboard by combining service records and recent matches. The agent calls `/stats/h5/players/{player}/matches` for activity and the arena, warzone, and custom service-record endpoints for cumulative stats. The result is a single page showing K/D, win rate, and recent match history per player.

Example prompt: GET `/stats/h5/servicerecords/arena` and `/stats/h5/players/Player1/matches` and combine the result into a dashboard payload.

### Leaderboard Tracker

Track CSR leaderboard movement across a season for a chosen playlist. The agent polls `/stats/h5/player-leaderboards/csr/{seasonId}/{playlistId}` on a schedule, diffs against the previous snapshot, and posts movement (rank up, rank down, new entries) to a Discord channel. Useful for competitive Halo communities and coaching groups.

Example prompt: GET `/stats/h5/player-leaderboards/csr/{seasonId}/{playlistId}` for the current season and emit the top 100 with delta versus the snapshot saved 24 hours ago.

### Spartan Profile Card Generator

Build a profile-card image for a player using their Halo 5 emblem and Spartan render. The agent calls `/profile/h5/profiles/{player}/emblem` and `/profile/h5/profiles/{player}/spartan` to retrieve image assets, composites them with the player's gamertag, and returns a shareable PNG. Useful for community sigs and tournament programmes.

Example prompt: GET `/profile/h5/profiles/Player1/emblem` and `/profile/h5/profiles/Player1/spartan` and return the asset URLs for image composition.

### Agent Discovery Through Jentic

Halo community agents search Jentic with intents like 'get halo player service record' and Jentic returns the matching operation with its input schema. The agent invokes the call without writing custom HTTP code. The Ocp-Apim-Subscription-Key stays in your Jentic One instance.

Example prompt: Use Jentic search 'halo player service record' to find `/stats/h5/servicerecords/arena` and execute it for a list of three player gamertags.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/stats/h5/matches/{matchId}` | Fetch full match details by match id |
| GET | `/stats/h5/players/{player}/matches` | List a player's recent matches |
| GET | `/stats/h5/servicerecords/arena` | Read arena service records for one or more players |
| GET | `/stats/h5/servicerecords/warzone` | Read warzone service records |
| GET | `/stats/h5/player-leaderboards/csr/{seasonId}/{playlistId}` | Read the CSR leaderboard for a playlist and season |
| GET | `/metadata/h5/metadata/maps` | List all Halo 5 maps |
| GET | `/profile/h5/profiles/{player}/emblem` | Get the player's emblem image URL |

## Key resources

- **Matches** — Fetch Halo 5 match details by match id and recent-matches feeds per player
- **Service records** — Read arena, warzone, and custom-game service records for one or more players
- **Companies** — Read Halo 5 company information and roster by company id
- **Leaderboards** — Read CSR season-end leaderboards for specified playlists and seasons
- **Metadata** — Look up game-base variants, maps, playlists, seasons, weapons, medals, vehicles, and ranks
- **Profile** — Retrieve player emblem, appearance, and Spartan render asset URLs

## Why Jentic

- **Setup:** Wiring the Halo API by hand means registering an Azure API Management subscription, setting its Ocp-Apim-Subscription-Key header on every call, and building each Halo 5 stats, metadata, and profile request yourself. Through Jentic you install once, import the Halo API from the API Directory, store the subscription key once, and your agent calls it.
- **Permission scoping:** The Halo API is read-only, covering legacy Halo 5 stats, metadata, and profile lookups, so scope your agent to the operations it needs, such as reading a service record or match details. You choose what it may call, and there are no write operations for it to reach.
- **Credential handling:** Your Halo 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 'get a halo player service record' or 'get halo match details', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the developer portal.

## Related APIs

- **Halo Metadata API** — Pure metadata catalogue for maps, weapons, medals, vehicles, and ranks across Halo 5 and Halo Wars 2.
- **Halo Profile API** — Player profile assets - emblem, appearance, and Spartan render.
- **Riot Games API** — Equivalent player stats and match data for League of Legends, Valorant, and TFT.

## FAQ

### What authentication does the Halo API use?

The Halo API uses an Azure API Management subscription key passed as the Ocp-Apim-Subscription-Key header (or as a subscription-key query parameter). Through Jentic, this key is stored encrypted in the vault and injected at execution time so the agent never holds the raw subscription key.

### Is the Halo API still active?

The 343 Industries Halo API for Halo 5 is deprecated and the production server is marked as such in the spec. It still serves historical data for fan tools but no new feature work or matchmaking telemetry is shipping. For Infinite-era games, refer to the modern Halo Waypoint endpoints which are not part of this spec.

### Can I get a player's recent Halo 5 matches?

Yes. GET `/stats/h5/players/{player}/matches` returns the recent match list for the gamertag, paginated by start and count parameters. Each entry returns a match id which you can pass to `/stats/h5/matches/{matchId}` to expand into the full per-player breakdown.

### How do I read the CSR leaderboard for a playlist?

GET `/stats/h5/player-leaderboards/csr/{seasonId}/{playlistId}` returns the season-end CSR leaderboard rows for a specific playlist. Pair with the `/metadata/h5/metadata/playlists` endpoint to discover valid playlist ids and human-readable labels.

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

Limits are tied to the API Management subscription tier on the Azure-fronted developer portal. Free keys are heavily rate-limited; commercial tiers receive higher quotas. The API returns 429 Too Many Requests on overage, and the Retry-After header indicates back-off seconds.

### How do I use the Halo API with AI agents through Jentic?

Run pip install jentic, then search 'halo player service record' to find `/stats/h5/servicerecords/arena.` Load and execute it with a list of player gamertags. Run Jentic One, the self-hosted execution layer, to get an agent key.

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

Yes. Because you run Jentic One yourself, your own rules decide which Halo API operations and credentials the agent may use, so you can allow only what a task needs, such as reading an arena service record or fetching match details. The Halo API is read-only across Halo 5 stats, metadata, and profile lookups, so there are no write operations for the agent to reach. You could, for example, grant just `/stats/h5/players/{player}/matches` and `/stats/h5/matches/{matchId}` while withholding the CSR leaderboard and profile-asset endpoints.