# GetCardValue.com Agent & Developer API Documentation
Version: 1.0.0
Base URL: https://getcardvalue.com

GetCardValue.com is a high-density, machine-readable repository indexing Pokemon TCG card values and Pokemon sealed product valuations. This endpoint provides zero-boilerplate specifications for coding agents (Cursor, GitHub Copilot) and LLM wrappers to query our datasets directly.

---

## 1. Card Valuation Endpoint
Query card values by search term, set names, or slug.

*   **URL**: `/api/cards`
*   **Method**: `GET`
*   **Parameters**:
    *   `q` (string, optional): Search query (matches card name, set name, types, rarity). E.g. `?q=Charizard`
    *   `limit` (number, optional): Maximum results returned (default: 50, cap: 200). E.g. `?limit=10`
    *   `band` (string, optional): Value tier (`grail`, `chase`, `mid`, `budget`). E.g. `?band=grail`
*   **Response Format**: `JSON`
*   **Example Call**: `https://getcardvalue.com/api/cards?q=Lugia&limit=2`

```json
{
  "total": 45,
  "count": 2,
  "results": [
    {
      "id": "neo3-9",
      "name": "Lugia",
      "exactName": "Lugia (Neo Revelation #9)",
      "slug": "lugia-neo-revelation-9",
      "setName": "Neo Revelation",
      "valueUsd": 315.50,
      "priceStatus": "priced",
      "valueBand": "grail",
      "rarity": "Holofoil",
      "types": ["Colorless"],
      "imageSmall": "https://images.pokemontcg.io/neo3/9.png"
    }
  ]
}
```

---

## 2. Card Detail by Slug
Retrieve complete card characteristics, subtypes, variants, legalities, and cost snapshots.

*   **URL**: `/api/cards/[slug]`
*   **Method**: `GET`
*   **Example Call**: `https://getcardvalue.com/api/cards/charizard-base-set-4`

```json
{
  "id": "base1-4",
  "name": "Charizard",
  "exactName": "Charizard (Base Set #4)",
  "slug": "charizard-base-set-4",
  "valueUsd": 380.00,
  "priceStatus": "priced",
  "rarity": "Rare Holofoil",
  "types": ["Fire"],
  "legalities": {
    "unlimited": "Legal"
  },
  "market": {
    "source": "TCGplayer",
    "lowPrice": 220.00,
    "highPrice": 550.00,
    "tcgplayerUrl": "https://www.tcgplayer.com/product/10699"
  }
}
```

---

## 3. Sealed Product Valuation Endpoint
Query sealed boxes, cases, bundles, and pack values.

*   **URL**: `/api/sealed`
*   **Method**: `GET`
*   **Parameters**:
    *   `q` (string, optional): Search query (matches product name or group/set). E.g. `?q=Evolving+Skies`
    *   `limit` (number, optional): Maximum results returned (default: 50). E.g. `?limit=5`
    *   `kind` (string, optional): Product kind (`booster-box`, `booster-pack`, `etb`, etc.)
*   **Response Format**: `JSON`
*   **Example Call**: `https://getcardvalue.com/api/sealed?q=Booster+Box&limit=1`

```json
{
  "total": 167,
  "count": 1,
  "results": [
    {
      "id": "evolving-skies-booster-box",
      "productId": 248123,
      "slug": "evolving-skies-booster-box",
      "cleanName": "Evolving Skies Booster Box",
      "kind": "booster-box",
      "groupName": "Sword & Shield - Evolving Skies",
      "valueUsd": 710.00,
      "priceStatus": "priced",
      "totalPacks": 36,
      "pricePerPack": 19.72
    }
  ]
}
```

---

## 4. Content Summary Endpoint
Retrieve metadata statistics and set counts for quick mapping.

*   **URL**: `/api/content`
*   **Method**: `GET`
*   **Response Format**: `JSON`
*   **Example Call**: `https://getcardvalue.com/api/content`

```json
{
  "domain": "GetCardValue.com",
  "totalCards": 20359,
  "totalSealed": 3949,
  "medianCardUsd": 12.50
}
```

---

## 5. Pricing and Policies
All machine routes are provided under **Sovereign $0 Free Access** with no rate limits for verified AI agent headers.