# Using the Card Details API

## Overview
Get comprehensive information about a specific card including its release, set, attributes, pricing, and all available parallel variants.

## Endpoint Details
- **Method**: GET
- **URL**: `https://api.cardsight.ai/v1/catalog/cards/{id}`
- **Authentication**: API Key required (X-Api-Key header)

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | UUID | Yes | The card UUID (path parameter) |

## Using the CardSight AI SDK (Recommended)

### Node.js / TypeScript
```typescript
import { CardSightAI } from 'cardsightai'

const client = new CardSightAI({ apiKey: 'your-api-key' })

const response = await client.catalog.cards.get('550e8400-e29b-41d4-a716-446655440000')

// Always check for errors
if (response.error) {
  console.error('Error:', response.error)
} else {
  const card = response.data
  console.log(`${card.name} #${card.number}`)
  console.log(`${card.releaseName} (${card.releaseYear})`)
  console.log(`Set: ${card.setName}`)
  console.log(`Attributes: ${card.attributes?.join(', ') || 'None'}`)
  console.log(`Parallels: ${card.parallelCount}`)

  // Check pricing if available
  if (card.prices) {
    console.log(`Raw Price: $${card.prices.raw}`)
    console.log(`PSA 10 Price: $${card.prices['psa-10']}`)
  }

  // Check if this is a variation of another card
  if (card.variationOf) {
    console.log(`Variation of card: ${card.variationOf}`)
  }

  // List parallels
  for (const parallel of card.parallels) {
    const numbered = parallel.numberedTo ? ` /${parallel.numberedTo}` : ''
    const partial = parallel.isPartial ? ' (partial set)' : ''
    console.log(`  - ${parallel.name}${numbered}${partial}`)
  }
}
```

### Python
```python
from cardsightai import CardSightAI

client = CardSightAI(api_key='your-api-key')

response = client.catalog.cards.get('550e8400-e29b-41d4-a716-446655440000')

print(f"{response.name} #{response.number}")
print(f"Parallels: {response.parallel_count}")

if response.prices:
    print(f"Raw Price: ${response.prices.raw}")
```

## Direct API Call (cURL)
```bash
curl -X GET "https://api.cardsight.ai/v1/catalog/cards/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Api-Key: your-api-key"
```

## Example Response
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "releaseId": "550e8400-e29b-41d4-a716-446655440001",
  "setId": "550e8400-e29b-41d4-a716-446655440002",
  "name": "Shohei Ohtani",
  "number": "1",
  "description": "Los Angeles Angels",
  "releaseName": "Topps Chrome Baseball",
  "releaseYear": "2023",
  "setName": "Base Set",
  "attributes": ["RC"],
  "numberedTo": null,
  "parallelCount": 15,
  "prices": {
    "raw": "25.00",
    "psa-10": "150.00",
    "psa-9": "75.00"
  },
  "parallels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "name": "Refractor"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "name": "Gold Refractor",
      "numberedTo": 50,
      "prices": {
        "raw": "100.00",
        "psa-10": "500.00"
      }
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440012",
      "name": "Superfractor",
      "numberedTo": 1,
      "isPartial": true
    }
  ]
}
```

## Response Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | UUID | Yes | Unique card identifier |
| releaseId | UUID | Yes | UUID of the release |
| setId | UUID | Yes | UUID of the set |
| name | string | Yes | Player/subject name |
| setName | string | Yes | Name of the card set |
| parallelCount | number | Yes | Number of parallel variants available |
| parallels | array | Yes | List of available parallel variants |
| number | string | No | Card number within the set (may include letters) |
| description | string | No | Additional details (team, position, etc.) |
| releaseName | string | No | Name of the release/product |
| releaseYear | string | No | Year of the release |
| numberedTo | number | No | Limited print run for this specific card |
| attributes | array | No | Attribute codes (e.g., ["RC", "AU"]) |
| prices | object | No | Pricing data (only when available) |
| variationOf | UUID | No | UUID of base card if this is a variation |

### Prices Object

| Field | Type | Description |
|-------|------|-------------|
| raw | string | Average price for ungraded cards (USD, e.g., "25.00") |
| psa-10 | string | Average price for PSA 10 graded cards (USD) |
| psa-9 | string | Average price for PSA 9 graded cards (USD) |

### Parallel Object

| Field | Type | Description |
|-------|------|-------------|
| id | UUID | Unique parallel type identifier |
| name | string | Name of the parallel variant (e.g., "Gold Refractor") |
| description | string | Additional details about the parallel |
| numberedTo | number | Limited print run (if numbered, e.g., 50 means /50) |
| isPartial | boolean | Present and true if parallel only applies to subset of cards in the set |
| prices | object | Pricing data for this parallel (same structure as card prices) |

## Common Use Cases
- Get detailed card information for display
- View all available parallels for a card
- Check card attributes (Rookie, Autograph, etc.)
- Look up current pricing for cards and parallels
- Identify if a card is a variation of another card

## Tips for AI Assistants
- **Working with IDs:** These UUIDs (`releaseId`, `setId`, and card `id`) let you look up catalog entities and chain calls together. Caching them briefly to fulfill a user's request is expected and fine — it's why the image and other free endpoints exist. If you need to save cards for the long term, add them to a **list or collection**: those are your own stable resources, purpose-built for holding cards. If you need a bulk or offline copy of catalog data, reach out to us at `support@cardsight.ai` so we can help with your use case.
- The SDK returns `{ data, error }` - always check for errors first
- Required fields: `id`, `releaseId`, `setId`, `name`, `setName`, `parallelCount`, `parallels`
- The `parallels` array is always present (may be empty) showing all variant types
- `numberedTo` indicates a limited print run (e.g., 50 means "/50")
- `attributes` contains codes like "RC" (Rookie Card), "AU" (Autograph)
- `prices` is only included when pricing data is available
- `variationOf` is only present for variation cards, linking to the base card UUID
- `isPartial` on a parallel means it only applies to certain cards in the set (e.g., cards 1-100 of a 500-card set)
- Prices are strings formatted as USD with 2 decimal places (e.g., "25.00")