# CGC Cards API - CGC's own graded-card population report and certification lookup: how many copies of a card CGC has graded at every grade (Perfect 10, Pristine 10, Gem Mint 10, Mint+ 9.5 … 1, Authentic), by game or sport, series, set and card, card search, and cert verification with grade, slab images and population. Pokémon, Magic, One Piece, Yu-Gi-Oh!, Lorcana, 450+ TCGs, sports and non-sports. No account, no browser.

> Verify a CGC-graded card by its certification number (the number on the slab label): card name or player, game, set, card number, year, language, variants, rarity, attributes, grade as printed (e.g. PRISTINE 10, GEM MINT 10, 9, AUTHENTIC) with CGC's grade name and number, autograph grade, sub-grades when the label carries them, grade date, front/back slab images, and that card's population (how many CGC graded at this grade and above, full grade breakdown). An unknown cert returns NOT_FOUND (not charged).
> ReefAPI engine `cgc` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/cgc/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/cgc/v1/cert_lookup — 2 credits
Verify a CGC-graded card by its certification number (the number on the slab label): card name or player, game, set, card number, year, language, variants, rarity, attributes, grade as printed (e.g. PRISTINE 10, GEM MINT 10, 9, AUTHENTIC) with CGC's grade name and number, autograph grade, sub-grades when the label carries them, grade date, front/back slab images, and that card's population (how many CGC graded at this grade and above, full grade breakdown). An unknown cert returns NOT_FOUND (not charged).

**Parameters:**
- `cert_number` (string, required) — CGC Cards certification number (10-13 digits) or a cgccards.com certlookup URL.
- `include_population` (boolean, optional, default true) — Also return the card's population report (one more lookup).
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** cert{cert_number, grading_company, collectible (tcg|sports|non_sports), subject, card_name, player_name, game, year, manufacturer, set, subset, card_number, language, rarity, variants[], attributes, grade, grade_name, grade_number, designation (AU|AA), subgrades{centering, corners, edges, surface}|null, autograph_grade, grade_date, images[]{side, url, thumbnail_url}, population_id, other_fields, cert_url}, population{population_at_grade, population_higher, top_pop, card{population_id, name, card_number, year, variant, description (rarity for TCGs), language, language_id, set_id, collectible, has_autograph / is_parallel (sports), population{total, numeric_graded, by_grade{perfect_10, pristine_10, gem_mint_10, 9.5, 9, 8.5 … 1, authentic, authentic_altered}, grades[]{grade, grade_number, count}, perfect_10, pristine_10, gem_mint_10, ten_total, gem_rate_percent, authentic, authentic_altered, highest_grade{grade, grade_number, count}}, updated_at, url}, category, subcategory, set}|null

**Example request body:**
```json
{
  "cert_number": "6090960083"
}
```

### POST https://api.reefapi.com/cgc/v1/search — 2 credits
Find cards in CGC's population report by name, player, set or number ("charizard base set", "tom brady 2000", "luffy op01") across trading card games, sports and non-sports. Returns the population_id that card_population takes, plus set, year, number, variant, language. CGC answers at most 50 matches per collectible type.

**Parameters:**
- `query` (string, required) — Card name, player, set or card number - CGC's own card search.
- `collectible` (enum, optional, default "all") — Limit to one CGC population report (default: all three). [one of: all, tcg, sports, non_sports]
- `category` (string, optional) — Only matches from this game / sport (name, e.g. pokemon, magic, one piece, baseball - or a category_id). An exact name wins; otherwise every category containing the text. Applied to CGC's top matches.
- `year` (string, optional) — Only cards of this year (e.g. 1999, 2024-25).
- `language` (string, optional) — Only cards in this language (TCG).
- `limit` (integer, optional, default 50) — Rows to return (CGC answers up to 50 per collectible type).
- `include_population` (boolean, optional, default false) — Attach the full grade breakdown to the first 10 rows.
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** query, results[]{population_id, name, card_number, year, set_name, subset, variant, rarity, language, manufacturer, is_parallel, collectible, category, category_id, subcategory_id, set_id, label, url, population{…} (with include_population)}, count, capped (true when CGC's 50-per-type cap was reached)

**Example request body:**
```json
{
  "query": "charizard",
  "collectible": "tcg"
}
```

### POST https://api.reefapi.com/cgc/v1/card_population — 1 credit
One card's CGC population: how many copies CGC graded at every grade - Perfect 10, Pristine 10, Gem Mint 10, Mint+ 9.5, 9 down to 1, Authentic, Authentic Altered - with total, number of 10s, gem rate and highest grade reached, plus the card's game/sport, series and set.

**Parameters:**
- `population_id` (string, required) — population_id from search, set_population or cert_lookup (or a population-report URL with ?populationID=).
- `collectible` (enum, optional) — Report the id belongs to; when omitted all three are tried. [one of: tcg, sports, non_sports]
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** card{population_id, name, card_number, year, variant, description (rarity for TCGs), language, language_id, set_id, collectible, has_autograph / is_parallel (sports), population{total, numeric_graded, by_grade{perfect_10, pristine_10, gem_mint_10, 9.5, 9, 8.5 … 1, authentic, authentic_altered}, grades[]{grade, grade_number, count}, perfect_10, pristine_10, gem_mint_10, ten_total, gem_rate_percent, authentic, authentic_altered, highest_grade{grade, grade_number, count}}, updated_at, url}, category{category_id, name}, subcategory{subcategory_id, name}, set{set_id, name, set_name, population_count, language, year, manufacturer, url}, collectible

**Example request body:**
```json
{
  "population_id": "470876"
}
```

### POST https://api.reefapi.com/cgc/v1/set_population — 2 credits
Every card CGC has graded from one set, 50 a page, each with its count at every grade (Perfect 10 … 1, Authentic), total, 10s and gem rate - CGC's set population table. Filter by card name or number inside the set.

**Parameters:**
- `set_id` (string, required) — set_id from sets, search or cert_lookup (or the set's population-report URL).
- `collectible` (enum, optional, default "tcg") — Which CGC population report the id belongs to. Ids are only unique within one type (TCG category 1 is Magic, sports category 1 is Baseball). [one of: tcg, sports, non_sports]
- `query` (string, optional) — Only cards of the set matching this name or number.
- `page` (integer, optional, default 1) — Page number; CGC serves 50 rows a page.
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** set{set_id, name, set_name, population_count, language, year, manufacturer, url}, category{…}, subcategory{…}, cards[]{population_id, name, card_number, year, variant, description (rarity for TCGs), language, language_id, set_id, collectible, has_autograph / is_parallel (sports), population{total, numeric_graded, by_grade{perfect_10, pristine_10, gem_mint_10, 9.5, 9, 8.5 … 1, authentic, authentic_altered}, grades[]{grade, grade_number, count}, perfect_10, pristine_10, gem_mint_10, ten_total, gem_rate_percent, authentic, authentic_altered, highest_grade{grade, grade_number, count}}, updated_at, url}, count, total_count, page, page_count, has_more

**Example request body:**
```json
{
  "set_id": "16990"
}
```

### POST https://api.reefapi.com/cgc/v1/sets — 2 credits
The sets CGC files under one series (e.g. Pokémon › Scarlet & Violet, Baseball › 1980s), 50 a page, with how many cards CGC graded from each; TCG sets come per language. Sort by most graded or name, filter by name or language.

**Parameters:**
- `subcategory_id` (string, required) — subcategory_id from subcategories (a series, era or decade).
- `collectible` (enum, optional, default "tcg") — Which CGC population report the id belongs to. Ids are only unique within one type (TCG category 1 is Magic, sports category 1 is Baseball). [one of: tcg, sports, non_sports]
- `query` (string, optional) — Only sets whose name contains this text.
- `language` (string, optional) — Only sets in this language (name or language_id; TCG and non-sports).
- `sort` (enum, optional, default "default") — Row order. [one of: default, most_graded, least_graded, name, name_desc]
- `page` (integer, optional, default 1) — Page number; CGC serves 50 rows a page.
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** category{…}, subcategory{…}, languages[]{language_id, name} (TCG / non-sports), sets[]{set_id, name, set_name, subcategory_id, population_count, language, language_id | year, manufacturer (sports), updated_at, url}, count, total_count, page, page_count, has_more

**Example request body:**
```json
{
  "subcategory_id": "1014"
}
```

### POST https://api.reefapi.com/cgc/v1/subcategories — 1 credit
The series / eras CGC files under one game or sport (Pokémon: Original Series, Neo, … Scarlet & Violet, Mega Evolution, Promotional; Baseball: 2020-Present, 2010s … Pre-1900), with how many cards CGC graded in each.

**Parameters:**
- `category` (string, required) — Game or sport by name (pokemon, magic, one piece, yu-gi-oh, baseball, soccer …) or category_id from categories.
- `collectible` (enum, optional) — Needed only with a numeric category_id (default tcg); names are looked up in all three reports. [one of: tcg, sports, non_sports]
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** category{category_id, name, collectible, slug, population_count, description, image_url, url}, subcategories[]{subcategory_id, name, category_id, population_count, image_url, url}, count

**Example request body:**
```json
{
  "category": "pokemon"
}
```

### POST https://api.reefapi.com/cgc/v1/categories — 1 credit
Every game, sport and non-sports line in CGC's population report with how many cards CGC graded in each (Pokémon ~13 million, One Piece, Magic, Yu-Gi-Oh!, Lorcana and 450+ more TCGs; baseball, basketball, football … ; Pokémon Topps, Marvel, Star Wars, phone cards …), most graded first, plus when CGC last refreshed the report.

**Parameters:**
- `collectible` (enum, optional, default "all") — Limit to one CGC population report (default: all three). [one of: all, tcg, sports, non_sports]
- `query` (string, optional) — Only categories whose name contains this text.
- `sort` (enum, optional, default "most_graded") — Row order. [one of: most_graded, name]
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** categories[]{category_id, name, collectible, slug, population_count, description, image_url, updated_at, url}, count, totals{tcg, sports, non_sports}, population_updated_at

**Example request body:**
```json
{
  "query": "dragon ball"
}
```

### POST https://api.reefapi.com/cgc/v1/grading_scale — 1 credit
CGC Cards' published grading scale: every grade from Pristine 10 to Poor 1 with CGC's definition, the Authentic / Authentic Altered / Authentic ART designations, the autograph grade scale (10 to 5, AU), the legacy-grade key (old Gem Mint 9.5 and Perfect 10 labels) and the telephone-card scale.

**Parameters:**
- `max_rotations` (integer, optional, default 3) — How many fresh exits to try before giving up.

**Returns:** sections[]{scale (standard|telephone_cards), title, intro, items[]{grade, name, code, grade_number, description} | {legacy_grade, current_grade}}, population_columns[]{grade, grade_number, key}, source_url

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=cgc
- Human docs page: https://reefapi.com/docs/cgc
- Overview page: https://reefapi.com/cgc-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt