# JSON API and published data

> The live read: the tool catalogue over HTTP, and the snapshot bucket these documents are rendered from.

| Field | Value |
| --- | --- |
| Data published | 2026-09-28 |
| This document | https://suckerpunch.gg/ai/api.md |

Two machine-readable surfaces sit behind this site, and they answer different questions from
the Markdown documents: **they are live**. A document under `/ai/` is rebuilt on deploy; these
are read at request time.

## 1. The tool API

Base: `https://us-central1-sucker-punch-71328.cloudfunctions.net/api`. Read endpoints are open, keyless and CORS-open.

```
GET https://us-central1-sucker-punch-71328.cloudfunctions.net/api/tools
```

returns the catalogue: every read endpoint, its description, its HTTP path and its input
schema as JSON Schema. Fetch it rather than hardcoding a path, for the same reason the format
list is read at run time rather than pinned: a regulation rollover moves the defaults.

Endpoints worth knowing before reading the catalogue:

| Endpoint | Answers |
| --- | --- |
| `GET /formats` | every format label with its tournament count |
| `GET /pokemon/list` | the roster |
| `GET /pokemon/search?name=` | resolve a spelling to an id before calling anything else |
| `GET /pokemon/rankings` | the usage and win-rate leaderboard, paginated |
| `GET /pokemon/builds` | moves, items, abilities, natures for one species |
| `GET /pokemon/partners` | teammates, with the share of that species' rosters |
| `GET /pokemon/matchups` | head to head, with the games behind each cell |
| `GET /matchup` | one cell: two sides, the record between them |
| `GET /ladder/rankings` | the ladder board, listed against brought against led |
| `GET /health` | liveness, and how many tools are mounted |

Every response carries the sample behind each figure. A rate without its denominator is not
published anywhere on this site, and that is deliberate.

## 2. The published snapshots

Base: `https://storage.googleapis.com/sucker-punch-public-data/data`. Static JSON on a public bucket, republished daily.

```
GET https://storage.googleapis.com/sucker-punch-public-data/data/version.json    # the publish stamp, ~400 bytes
GET https://storage.googleapis.com/sucker-punch-public-data/data/manifest.json   # scope keys, window keys, and the path of every board
```

`manifest.json` is the index: `files.scopes[scope][window]` maps a board name to its file, and
the templated entries (`{id}`, `{dim}`, `{species}`) are filled in by the caller. This is what
the site's own pages read, so an agent reading it sees exactly what a visitor sees.

Some boards are large. The 2v2 and 4v4 head-to-head payloads are tens of megabytes; prefer the
tool API for a single cell and the bucket for a full board.

## Terms

Open and keyless, no rate limit stated. Attribution to Sucker Punch is expected where figures
are republished. The ingest sources have their own terms, and the ladder corpus is parsed from
public Showdown replays.

## Freshness and provenance

- Rendered at deploy time from the published snapshots. Snapshot stamp: 2026-09-28.
- The boards behind them republish daily, so a figure here can trail the live data by a deploy.
- The read that is never behind is the JSON API: https://suckerpunch.gg/ai/api.md.
- Tournament data and ladder data are separate populations and are never blended.
- Estimator, denominators and floors: https://suckerpunch.gg/ai/method.md.
- Attribution: Sucker Punch, https://suckerpunch.gg.