canonical: https://jentic.com/apis/battle.net/battlenet

# Battle StarCraft 2 API

Jentic publishes the only available OpenAPI specification for StarCraft 2 API, keeping it validated and agent-ready. Blizzard's StarCraft 2 API on Battle.net exposes player profiles, ladder rankings, match history, and league standings for the StarCraft II competitive scene. The API is split into community endpoints (profiles, ladders, matches) and game-data endpoints (leagues, seasons), all secured with OAuth 2.0 client-credentials. Regional servers cover US, EU, KR, TW, and a separate China gateway, so client code must select the correct base URL for the player's region.

## For AI agents

Look up StarCraft 2 player profiles, ladder standings, match history, and league data across Blizzard's regional servers. Useful for esports trackers and tournament agents.

## Scope

Does not handle World of Warcraft, Diablo, Hearthstone, or Overwatch data, in-game purchases, or account management - use for StarCraft 2 community and game-data endpoints only.

## Capabilities

- Look up a StarCraft 2 player profile by region, realm, and profile ID
- Fetch the grandmaster ladder for a region with GET /sc2/ladder/grandmaster/{regionId}
- Retrieve a player's ladder summary and per-ladder placement
- Pull a player's recent match history via the legacy profile endpoints
- List active and historic seasons with GET /sc2/ladder/season/{regionId}
- Fetch league data for a given season, queue, team type, and league tier

## Use cases

### Esports Ladder Tracker

Tournament organisers and content creators need a live view of grandmaster and master league standings across regions. The StarCraft 2 API exposes GET /sc2/ladder/grandmaster/{regionId} and GET /sc2/ladder/season/{regionId} to pull current leaderboards. The tracker can poll on an interval (respecting Blizzard's rate limits) and surface ranking changes between snapshots.

Example prompt: Call GET /sc2/ladder/grandmaster/2 (EU) and compare results to a stored snapshot to surface rank changes for a Twitch overlay

### Player Profile and Match History

Coaches and analysts looking at a specific player can pull their profile, ladder summary, and recent match list to study performance. The legacy match endpoint GET /sc2/legacy/profile/{regionId}/{realmId}/{profileId}/matches returns the player's most recent matches with race, opponent, and result, enabling automated post-game analysis.

Example prompt: Call GET /sc2/profile/1/1/12345 for a player, then GET /sc2/legacy/profile/1/1/12345/matches to retrieve their last 25 matches

### Season and League Data Snapshot

Researchers studying StarCraft 2's competitive landscape can call GET /sc2/ladder/season/{regionId} to find the current season ID, then GET /data/sc2/league/{seasonId}/{queueId}/{teamType}/{leagueId} to pull every player in a given league tier. The data feeds dashboards comparing ladder distribution by region and queue.

Example prompt: Call GET /sc2/ladder/season/1 to get the current season ID, then GET /data/sc2/league/{seasonId}/201/0/6 to pull the grandmaster 1v1 league

### Agent-Driven Tournament Lookup via Jentic

A Discord bot or stream overlay agent can use the StarCraft 2 API through Jentic to answer commands like 'show me NotPickle's last 5 matches' without the bot author handling OAuth refresh. Jentic isolates the Blizzard client credentials and exposes the 15 SC2 operations as discoverable tools.

Example prompt: Search Jentic for 'starcraft 2 player profile', load the GET /sc2/profile/{regionId}/{realmId}/{profileId} schema, and execute with the requested player's identifiers

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /sc2/profile/{regionId}/{realmId}/{profileId} | Fetch a StarCraft 2 player profile |
| GET | /sc2/profile/{regionId}/{realmId}/{profileId}/ladder/summary | Get a player's ladder summary |
| GET | /sc2/ladder/grandmaster/{regionId} | Get the grandmaster ladder for a region |
| GET | /sc2/ladder/season/{regionId} | Get the current season for a region |
| GET | /sc2/legacy/profile/{regionId}/{realmId}/{profileId}/matches | Get a player's recent match history |
| GET | /data/sc2/league/{seasonId}/{queueId}/{teamType}/{leagueId} | Fetch league composition data |

## Key resources

- **Profiles** — Look up player profiles, metadata, and static profile resources
- **Ladders** — Fetch grandmaster ladders, ladder summaries, and individual ladder data
- **Seasons** — List active and historic ladder seasons by region
- **Matches** — Retrieve a player's recent match history via legacy endpoints
- **League Data** — Fetch league composition for a given season, queue, team type, and league tier

## Why Jentic

- **Setup:** Wiring the StarCraft 2 API by hand means running the OAuth2 client-credentials grant, choosing the right regional host (us, eu, kr, tw, or the China gateway), and threading region, realm, and profile ids through each call yourself. Through Jentic you install once, import the StarCraft 2 API from the API Directory, store the client credentials once, and your agent calls it.
- **Permission scoping:** The StarCraft 2 API puts the region, realm, and profile ids in the URL path (/sc2/profile/{regionId}/{realmId}/{profileId}), so a rule can pin your agent to one profile: it reads that profile and its ladder summary and nothing else. You choose the operations it may call, and since these are read-only game-data endpoints there are no write operations to add.
- **Credential handling:** Your Battle.net OAuth2 client id and secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get a StarCraft 2 player profile' or 'fetch the grandmaster ladder', and Jentic returns the matching SC2 operation with its input schema, including the regionId and realmId parameters, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **BBC Radio & Music Services** — Different content domain; included as a placeholder media-API peer in the absence of another esports API
- **Basesnap API** — Database snapshot service - useful for backing up the database that ingests SC2 ladder snapshots
- **Baseten API** — ML model deployment - pair with SC2 data to serve match-prediction or skill-rating models

## FAQ

### Why is there no official OpenAPI spec for StarCraft 2 API?

Blizzard does not publish an OpenAPI specification for the StarCraft 2 API. Jentic generates and maintains this spec so that AI agents and developers can call StarCraft 2 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 StarCraft 2 API use?

Battle.net uses OAuth 2.0 client credentials. Register an application on the Blizzard developer portal, exchange the client_id/secret for an access token, and pass it as Authorization: Bearer <token>. Through Jentic the credentials live in the vault and the agent only receives a scoped token.

### Which regions does the StarCraft 2 API cover?

The API supports four regional servers (US, EU, KR, TW) under https://{region}.api.blizzard.com plus a China gateway at https://gateway.battlenet.com.cn. Most endpoints take a regionId path parameter (1=US, 2=EU, 3=KR, 5=CN) so make sure the host and regionId match.

### How do I look up a StarCraft 2 player profile through Jentic?

Search Jentic for 'starcraft 2 player profile', which surfaces GET /sc2/profile/{regionId}/{realmId}/{profileId}. Load the schema, supply regionId, realmId, and profileId, and execute. The response includes career stats, season highlights, and rewards.

### What are the rate limits for the StarCraft 2 API?

Blizzard applies per-account rate limits (commonly 100 requests/second and 36,000 per hour) across all Battle.net APIs. The OpenAPI spec does not enumerate them - check the Blizzard developer portal for current limits and back off on 429 responses.

### Can I get a player's match history with the StarCraft 2 API?

Yes, via the legacy match endpoint: GET /sc2/legacy/profile/{regionId}/{realmId}/{profileId}/matches. It returns the player's most recent matches with race, map, opponent, and result. The endpoint is labelled legacy by Blizzard but remains the canonical source for SC2 match history.

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

Yes. Because you run Jentic One yourself, your own rules decide which StarCraft 2 operations the agent may call and which Battle.net credentials it may use. Since the region, realm, and profile ids sit in the URL path (/sc2/profile/{regionId}/{realmId}/{profileId}), you can pin the agent to a single profile so it only reads that profile and its ladder summary and nothing else. These are read-only game-data endpoints, so the agent can look up profiles, ladders, seasons, and match history but cannot modify anything.