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

# Haloapi UGC

The Halo UGC API exposes metadata for user-generated content created by Halo 5: Guardians players, specifically map variants and game variants saved to a player's file share. It returns a list of variants per player and the metadata for any single variant identified by ID. The API is read-only and authenticated with an Ocp-Apim-Subscription-Key issued by the Halo developer portal. Coverage is limited to Halo 5 player-authored content; the binary contents of variants are not returned.

## For AI agents

List a Halo 5 player's saved map and game variants and fetch metadata for a single variant by ID.

## Scope

Does not handle variant downloads, publishing, or stat tracking - use for read-only Halo 5 user-generated content metadata only.

## Capabilities

- List all Halo 5 game variants saved by a specific player
- List all Halo 5 map variants saved by a specific player
- Fetch metadata for a single Halo 5 game variant by variant ID
- Fetch metadata for a single Halo 5 map variant by variant ID

## Use cases

### Custom Games Discovery Site

Surface a curated catalogue of Halo 5 custom map and game variants for community lobby browsing. The UGC API returns each player's saved variants with names, descriptions, and variant IDs that can be cross-linked to the Halo Stats API for play counts. Coverage is limited to Halo 5 user content.

Example prompt: List all map variants for player gamertag 'AgentSmith' from `/h5/players/AgentSmith/mapvariants` and display title, description, and variant ID.

### Variant Metadata Lookup for Tournaments

Validate tournament map and game variant entries by fetching their metadata from `/h5/players/{player}/mapvariants/{variant}` and `/h5/players/{player}/gamevariants/{variant}.` Organisers can confirm a variant's owner and configuration before locking the bracket. Authentication is a single subscription key per organiser.

Example prompt: Fetch the game variant 'tournament-slayer-v3' for player 'OrgAdmin' and verify the gametype and time limit settings.

### AI Agent Variant Browser

Let an AI agent answer 'what custom maps does this player have' and 'fetch the description for variant X' through Jentic-managed tools. The agent calls the four UGC endpoints with the subscription key isolated in your Jentic One instance and never sees the raw secret. The API only returns metadata, so agents cannot publish or edit variants.

Example prompt: When asked 'show me my map variants', call `/h5/players/{player}/mapvariants` for the user's gamertag and return the list of variant names with IDs.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/h5/players/{player}/mapvariants` | List a player's Halo 5 map variants |
| GET | `/h5/players/{player}/mapvariants/{variant}` | Get a single Halo 5 map variant |
| GET | `/h5/players/{player}/gamevariants` | List a player's Halo 5 game variants |
| GET | `/h5/players/{player}/gamevariants/{variant}` | Get a single Halo 5 game variant |

## Key resources

- **Map Variants** — List or fetch a Halo 5 player's saved map variants
- **Game Variants** — List or fetch a Halo 5 player's saved game variants

## Why Jentic

- **Setup:** Wiring the Halo UGC API by hand means setting its Ocp-Apim-Subscription-Key header on every call and building each Halo 5 user-generated content lookup yourself. Through Jentic you install once, import the Halo UGC API from the API Directory, store the subscription key once, and your agent calls it.
- **Permission scoping:** The Halo UGC API is read-only, returning Halo 5 user-generated content metadata like map and game variants, so scope your agent to the operations it needs, such as listing a player's map variants. 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 'list a halo 5 player map variants', and Jentic returns the GET `/h5/players/{player}/mapvariants` operation with its input schema so the agent calls the right endpoint without crawling the developer portal.

## Related APIs

- **Halo Stats** — Pair variant metadata with match results to track which custom variants are most played.
- **Twitch API** — Twitch streams and clips alongside Halo custom-game metadata for community showcases.
- **RAWG Video Games Database** — General game metadata when the question is about Halo games as titles, not player-authored variants.

## FAQ

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

The Halo UGC API uses an API key in the Ocp-Apim-Subscription-Key header issued by the Halo developer portal. Jentic stores the key in its encrypted vault and injects it on every call so the secret never enters agent prompt logs.

### Can I list a Halo 5 player's custom maps with this API?

Yes. Call GET `/h5/players/{player}/mapvariants` with the player's gamertag to list all map variants saved to their file share, and GET `/h5/players/{player}/mapvariants/{variant}` to retrieve a single variant's metadata.

### What are the rate limits for the Halo UGC API?

Rate limits follow the Halo developer portal subscription tier (typically 10 requests per second on the standard tier) and are shared across all Halo APIs on the same key. Back off on HTTP 429 responses; the API does not return a Retry-After header.

### How do I fetch a single Halo 5 game variant through Jentic?

Search Jentic for 'get halo 5 game variant', load the schema for GET `/h5/players/{player}/gamevariants/{variant}`, and execute with the player and variant IDs. Run pip install jentic and use the async client.search, client.load, and client.execute pattern.

### Does the UGC API return the binary contents of map or game variants?

No. The API returns metadata only - variant ID, name, description, owner, and creation timestamps. The binary playable file is not exposed; players still need to download it in-game from the file share.

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

Yes. Because you run your own self-hosted Jentic One instance, your own rules decide which of the four Halo UGC operations the agent may call and which credentials it may use. You can scope the agent to only the operations it needs, such as GET `/h5/players/{player}/mapvariants` to list a player's map variants, while withholding the game-variant lookups. The API is read-only with no write operations, so the agent can never publish or edit variants regardless of how you scope it.