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

# Haloapi Halo Profile API

Jentic publishes the only available OpenAPI specification for Halo Profile API, keeping it validated and agent-ready. The Halo Profile API serves a small set of player imagery endpoints for Halo 5: Guardians: a player's emblem, the appearance image, and a rendered Spartan model. Agents use it to display a player's identity in match recaps, leaderboards, profile cards, and community signatures. Image dimensions can be requested via query parameters.

## For AI agents

Fetch Halo 5 player imagery - emblem, appearance, and Spartan render - by gamertag for use in profile cards and match recaps.

## Scope

Does not return stats, matches, or in-game catalogue data - use for Halo 5 player imagery (emblem, appearance, Spartan render) only.

## Capabilities

- Get the emblem image URL for a Halo 5 player by gamertag
- Retrieve a player's appearance image
- Fetch the rendered Spartan model image for a player
- Request a specific image size via the size query parameter

## Use cases

### Profile Card Generator

Build profile-card images for community signatures and tournament programmes by combining the player's emblem and Spartan render. The agent fetches `/h5/profiles/{player}/emblem` and `/h5/profiles/{player}/spartan`, composites them with gamertag and stats text, and emits a shareable PNG. Halo community sites used this for sigs and stream overlays.

Example prompt: GET `/h5/profiles/Player1/emblem` and `/h5/profiles/Player1/spartan` and return both image URLs for downstream compositing.

### Leaderboard Avatar Hydration

Decorate a CSR leaderboard with each player's emblem thumbnail. The agent walks the leaderboard rows from the Halo stats API, calls `/h5/profiles/{player}/emblem` with size=64 for each, and emits an avatar URL beside each row. Useful for esports broadcast graphics.

Example prompt: For each gamertag in a leaderboard payload, GET `/h5/profiles/{player}/emblem` and emit the thumbnail URL alongside the row.

### Match Recap Embed

Embed each match participant's appearance image in the recap renderer to produce a Halo Waypoint-style match summary. The agent calls `/h5/profiles/{player}/appearance` for each participant and inlines the URL into the recap markup. The result mirrors the official post-game UI.

Example prompt: GET `/h5/profiles/Player1/appearance` and embed the returned image URL in the match recap.

### Agent Discovery Through Jentic

Halo community agents discover the profile imagery operations through Jentic by searching for intents like 'halo player emblem image'. Jentic returns the matching GET operation with its input schema. The Ocp-Apim-Subscription-Key stays in your Jentic One instance.

Example prompt: Use Jentic search 'halo player emblem' to find GET `/h5/profiles/{player}/emblem` and execute it for gamertag 'Player1'.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/h5/profiles/{player}/emblem` | Get the player's emblem image URL |
| GET | `/h5/profiles/{player}/appearance` | Get the player's appearance image URL |
| GET | `/h5/profiles/{player}/spartan` | Get the rendered Spartan model image URL |

## Key resources

- **Emblem** — Player emblem image URL endpoint with size parameter
- **Appearance** — Player appearance image URL endpoint
- **Spartan** — Rendered Spartan model image URL endpoint

## Why Jentic

- **Setup:** Wiring the Halo Profile API by hand means setting its Ocp-Apim-Subscription-Key header on every call and building each Halo 5 player imagery request yourself. Through Jentic you install once, import the Halo Profile API from the API Directory, store the subscription key once, and your agent calls it.
- **Permission scoping:** The Halo Profile API is read-only, returning Halo 5 player imagery like emblems, appearance, and Spartan renders, so scope your agent to the operations it needs, such as fetching a player emblem. You choose what it may call, and there are no write operations for it to reach.
- **Credential handling:** Your Halo Profile 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 emblem' or 'get a halo spartan render', and Jentic returns the matching profile operation with its input schema so the agent calls the right endpoint without building URLs by hand.

## Related APIs

- **Halo API** — Stats and match data that pair with profile imagery for full recaps.
- **Halo Metadata API** — In-game catalogue lookups for maps, weapons, medals, and cards.
- **Riot Games API** — Player profile and icon endpoints for Riot Games titles.

## FAQ

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

343 Industries does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Halo Profile 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 Profile 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.

### Can I request a specific image size for the Halo emblem?

Yes. The `/h5/profiles/{player}/emblem` and `/h5/profiles/{player}/spartan` endpoints accept a size query parameter (in pixels) to scale the returned image. Useful for thumbnail strips on leaderboards and full-resolution sigs.

### How do I fetch the Spartan render for a player?

GET `/h5/profiles/{player}/spartan` with the player's gamertag in the path. The response is the image URL (or a redirect to the asset). Pair with the emblem and appearance endpoints when building a complete profile card.

### How do I batch-fetch emblems for a leaderboard through Jentic?

Run pip install jentic, then search 'halo player emblem' to find GET `/h5/profiles/{player}/emblem.` Iterate over the leaderboard gamertags, executing the operation for each, and respect 429 responses by backing off.

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

Rate limits are tied to the Azure subscription tier on the developer portal. Free keys are heavily limited; commercial tiers receive higher quotas. The endpoints return 429 with a Retry-After header when exceeded.

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

Yes. Because Jentic One is self-hosted, you set the rules that decide which operations and credentials your agent may use, so you can scope it to only the imagery calls it needs, such as fetching a player emblem while withholding appearance and Spartan render. The Halo Profile API is read-only, exposing just the emblem, appearance, and Spartan render endpoints, so there are no write operations for the agent to reach. Your subscription key stays inside your own Jentic One instance and is injected at execution time rather than handled by the agent.