---
title: "Get Card Details by GemRate ID"
method: POST
path: "/v1/cards/details-by-gemrate-id"
tags: ["Card Details"]
---

# Get Card Details by GemRate ID

`POST /v1/cards/details-by-gemrate-id`

## Request

- Base URL: `https://api.cardhedger.com`
- URL: `https://api.cardhedger.com/v1/cards/details-by-gemrate-id`
- Auth: API key in header `X-API-Key`

Get card details for a GemRate card identifier.

The GemRate-ID analog of `/v1/cards/details-by-certs`, for callers who
hold a GemRate ID (grader-specific or universal) rather than a grader
certificate number.

## How it works

1. Looks the ID up directly in CardHedge.
2. Checks the persistent cert-resolution cache (any previously resolved
   certificate sharing this GemRate ID).
3. Fallback: queries the GemRate population API for the card description
   and any sibling/universal GemRate IDs, retries the CardHedge lookup
   with those, and finally matches the description via the AI
   `card-match` endpoint.

## Card resolution (`card_source` / `match_confidence`)

- `card_source: "gemrate_id"` — resolved by a direct GemRate ID →
  CardHedge lookup. `match_confidence` is null.
- `card_source: "card_match"` — resolved from the GemRate description
  via the AI fallback; `match_confidence` (0-1) is the matcher's score.
  Cards resolved this way have null `category_group` and `set_type`.

## Status codes

- `200` with `card: null` — GemRate knows the ID but no CardHedge card
  matched (`gemrate_info.description` is still populated).
- `404` — the ID is unknown to both CardHedge and GemRate.
- `502` — an upstream API failed while resolving.

**Example curl:**
```bash
curl -X POST -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{"gemrate_id": "25783324b9710f1366ca4d54f3dd4689c02b6885"}' \
     "https://api.cardhedger.com/v1/cards/details-by-gemrate-id"
```

## Request body

- DetailsByGemrateIdRequest: Request parameters for the details-by-gemrate-id endpoint.
  - `gemrate_id` string, required: GemRate card identifier (grader-specific or universal)

## Response `200`

Successful Response

- DetailsByGemrateIdResponse: Response model for the details-by-gemrate-id endpoint.
  - `gemrate_info` GemRateIdInfo, required: Identification context for a GemRate-ID lookup. The analog of `GemRateCertInfo` for the gemrate-id endpoints. `universal_gemrate_id` and `description` come from the GemRate hybrid-population-data fallback, so they are populated only when that fallback actually ran (a direct CardHedge hit never calls GemRate). Population statistics are deliberately excluded, consistent with the cert endpoints.
    - `gemrate_id` string, required: GemRate ID exactly as provided by the caller
    - `universal_gemrate_id` string, nullable: Universal GemRate ID from the GemRate population lookup. Null when the card was resolved without calling GemRate (direct CardHedge hit or cache hit).
    - `description` string, nullable: Card description from the GemRate population lookup. Null when the card was resolved without calling GemRate.
  - `card` CardDetails: Detailed card information and metadata.
    - `card_id` string, required: Unique card identifier
    - `description` string, nullable: Full card description
    - `player` string, nullable: Player or character name
    - `set` string, nullable: Card set name
    - `number` string, nullable: Card number in set
    - `variant` string, nullable: Card variant (e.g., Base, Refractor, Prizm)
    - `image` string, nullable: Card image URL
    - `category` string, nullable: Card category (e.g., Baseball, Basketball, Pokemon)
    - `category_group` string, nullable: Category group, derived from the catalog category for indexed cards
    - `set_type` string, nullable: Set type, derived from the catalog set name for indexed cards
  - `card_source` string, nullable: How the card was resolved: 'gemrate_id' for a direct GemRate ID -> CardHedge lookup, or 'card_match' when that lookup found nothing and the card was matched from the GemRate description via the AI card-match fallback. Null when no card was resolved. Cards resolved via 'card_match' have null 'category_group' and 'set_type' -- the matcher does not return those two fields.
  - `match_confidence` number, nullable: AI match confidence (0-1) when 'card_source' is 'card_match'; null otherwise. Treat results derived from a low-confidence match with care.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/cardhedger/apis/card-hedge-api.md) - [All operations](https://skmtc.dev/cardhedger/apis/card-hedge-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardhedger/apis/card-hedge-api/revisions/6de42f192a4d?raw)