# Using the CardSight AI API - Card Search API

## Overview
Search for trading cards across the entire CardSight AI catalog. This is the primary endpoint for card discovery, supporting complex filtering by player name, card number, year, manufacturer, release, and set.

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

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | No | Search by player/subject name (partial match, case-insensitive) |
| number | string | No | Filter by exact card number |
| year | string | No | Filter by exact release year (e.g., "2023") |
| min_year | string | No | Filter cards from this year onwards |
| max_year | string | No | Filter cards up to this year |
| manufacturer | string | No | Filter by manufacturer name or UUID |
| releaseId | UUID | No | Filter to a specific release |
| releaseName | string | No | Filter by release name (partial match) |
| setId | UUID | No | Filter to a specific set |
| setName | string | No | Filter by set name (partial match) |
| attributeId | UUID | No | Filter by attribute UUID (e.g., Rookie Card, Autograph) |
| attributeShortName | string | No | Filter by attribute code (e.g., "RC" for Rookie, "AU" for Autograph) |
| take | integer | No | Results per page (1-100, default: 20) |
| skip | integer | No | Number of results to skip for pagination |
| sort | string | No | Sort by: name, release, set, year, price-raw |
| order | string | No | Sort order: asc, desc (default: asc) |

## Using the CardSight AI SDK (Recommended)

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

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

// Search for cards by player name
const response = await client.catalog.cards.list({
  name: 'Shohei Ohtani',
  year: '2023',
  take: 20
})

// Always check for errors
if (response.error) {
  console.error('Error:', response.error)
} else {
  console.log(`Found ${response.data.total_count} cards`)

  for (const card of response.data.cards) {
    console.log(`${card.name} #${card.number}`)
    console.log(`  Set: ${card.setName}`)
    console.log(`  Release: ${card.releaseName} (${card.releaseYear})`)
    console.log(`  ID: ${card.id}`)
  }
}
```

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

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

# Search for cards
response = client.catalog.cards.list(
    name='Shohei Ohtani',
    year='2023',
    take=20
)

print(f"Found {response.total_count} cards")
for card in response.cards:
    print(f"{card.name} #{card.number} - {card.set_name}")
```

## Direct API Call (cURL)
```bash
curl -X GET "https://api.cardsight.ai/v1/catalog/cards?name=Ohtani&year=2023&take=20" \
  -H "X-Api-Key: your-api-key"
```

## Example Response
```json
{
  "cards": [
    {
      "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",
      "setName": "Base Set",
      "releaseName": "Topps Chrome",
      "releaseYear": "2023",
      "attributes": ["RC"],
      "prices": {
        "raw": "25.00",
        "psa-10": "150.00",
        "psa-9": "75.00"
      }
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "releaseId": "550e8400-e29b-41d4-a716-446655440001",
      "setId": "550e8400-e29b-41d4-a716-446655440004",
      "name": "Shohei Ohtani",
      "number": "1",
      "setName": "Refractors",
      "releaseName": "Topps Chrome",
      "releaseYear": "2023",
      "variationOf": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "total_count": 156,
  "skip": 0,
  "take": 20
}
```

## Response Fields

| Field | Type | Description |
|-------|------|-------------|
| cards | array | Array of card objects |
| total_count | number | Total number of matching cards |
| skip | number | Number of results skipped |
| take | number | Number of results returned |

### Card Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | UUID | Yes | Unique card identifier |
| releaseId | UUID | Yes | UUID of the release this card belongs to |
| setId | UUID | Yes | UUID of the set this card belongs to |
| name | string | Yes | Player/subject name |
| setName | string | Yes | Name of the card set |
| number | string | No | Card number within the set (e.g., "23", "RC-15") |
| description | string | No | Additional details (team, position, etc.) |
| releaseName | string | No | Name of the release/product |
| releaseYear | string | No | Year of the release |
| attributes | array | No | Array of attribute codes (e.g., ["RC", "AU"]) |
| prices | object | No | Pricing data with raw, psa-10, psa-9 fields |
| variationOf | UUID | No | If this is a variation, the UUID of the base card |

## Common Use Cases
- Find all cards of a specific player
- Search for cards from a specific year
- Filter by attributes like Rookie Cards (RC) or Autographs (AU)
- Build player collections across multiple products
- Research card availability and pricing

## 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
- Use `name` for player searches - it's case-insensitive and supports partial matching
- Combine filters for more specific results (e.g., name + year + manufacturer)
- Use `take` and `skip` for pagination when dealing with large result sets
- Card IDs can be used with the Card Details endpoint for more information
- Use `attributeShortName: "RC"` to find rookie cards specifically
- The `variationOf` field (UUID) indicates this card is a parallel/variation of a base card
- The `prices` object contains average market prices when available