# Using the CardSight AI API - Parallels API

## Overview
Search for parallel variants across sets and releases, or get detailed information about a specific parallel. Parallels are visual variants of base cards (e.g., Refractor, Prizm, Gold, numbered cards).

## Endpoint Details
- **Base URL**: `https://api.cardsight.ai`
- **Authentication**: API Key required (X-Api-Key header)

## Endpoints

| Method | URL | Description |
|--------|-----|-------------|
| GET | /v1/catalog/parallels | Search parallels across sets and releases |
| GET | /v1/catalog/parallels/{id} | Get detailed information about a specific parallel |

## Search Parallels Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | No | Search by parallel name (partial match, case-insensitive). Example: "gold" matches "Gold Refractor", "Gold Prizm" |
| releaseId | UUID | No | Filter to parallels in a specific release |
| releaseName | string | No | Filter by release name (partial match). Example: "prizm" matches "Prizm Basketball" |
| year | string | No | Filter by exact release year (e.g., "2023") |
| min_year | string | No | Filter parallels from this year onwards |
| max_year | string | No | Filter parallels up to this year |
| 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 |
| 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 parallels by name
const response = await client.catalog.parallels.list({
  name: 'Gold',
  year: '2023',
  take: 20
})

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

  for (const parallel of response.data.parallels) {
    console.log(`${parallel.name} - ${parallel.setName} (${parallel.releaseName})`)
    if (parallel.numberedTo) {
      console.log(`  Numbered to: /${parallel.numberedTo}`)
    }
    if (parallel.isPartial) {
      console.log(`  Partial parallel (applies to specific cards only)`)
    }
    if (parallel.prices) {
      console.log(`  Price (raw): $${parallel.prices.raw}`)
    }
  }
}

// Get details for a specific parallel
const details = await client.catalog.parallels.get('550e8400-e29b-41d4-a716-446655440000')

if (!details.error) {
  console.log(`Parallel: ${details.data.name}`)
  console.log(`Set: ${details.data.setName}`)
  console.log(`Release: ${details.data.releaseName} (${details.data.releaseYear})`)
  console.log(`Numbered to: ${details.data.numberedTo || 'Unlimited'}`)
  if (details.data.isPartial && details.data.cards) {
    console.log(`Cards with this parallel: ${details.data.cards.length}`)
  }
}
```

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

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

# Search for parallels
response = client.catalog.parallels.list(name='Gold', year='2023', take=20)

print(f"Found {response.total_count} parallels")
for parallel in response.parallels:
    print(f"- {parallel.name} ({parallel.set_name})")
    if parallel.numbered_to:
        print(f"  Numbered to: /{parallel.numbered_to}")

# Get parallel details
details = client.catalog.parallels.get('550e8400-e29b-41d4-a716-446655440000')
print(f"Parallel: {details.name}")
print(f"Set: {details.set_name}")
print(f"Release: {details.release_name} ({details.release_year})")
```

## Direct API Calls (cURL)

```bash
# Search for gold parallels in 2023 releases
curl -X GET "https://api.cardsight.ai/v1/catalog/parallels?name=Gold&year=2023&take=20" \
  -H "X-Api-Key: your-api-key"

# Filter parallels by release
curl -X GET "https://api.cardsight.ai/v1/catalog/parallels?releaseId=550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Api-Key: your-api-key"

# Get parallel details
curl -X GET "https://api.cardsight.ai/v1/catalog/parallels/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Api-Key: your-api-key"
```

## Example Responses

### Search Parallels Response
```json
{
  "parallels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Gold Refractor",
      "description": "Gold chrome refractor parallel",
      "numberedTo": 50,
      "setId": "550e8400-e29b-41d4-a716-446655440001",
      "setName": "Base Set",
      "releaseId": "550e8400-e29b-41d4-a716-446655440002",
      "releaseName": "2023 Topps Chrome Baseball",
      "releaseYear": "2023",
      "cardCount": 220,
      "prices": {
        "raw": "25.00",
        "psa-10": "150.00",
        "psa-9": "75.00"
      }
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "name": "Gold Prizm",
      "description": null,
      "isPartial": true,
      "numberedTo": 10,
      "setId": "550e8400-e29b-41d4-a716-446655440011",
      "setName": "Base Set",
      "releaseId": "550e8400-e29b-41d4-a716-446655440012",
      "releaseName": "2023 Panini Prizm Basketball",
      "releaseYear": "2023",
      "cardCount": 300,
      "cards": [
        "550e8400-e29b-41d4-a716-446655440020",
        "550e8400-e29b-41d4-a716-446655440021",
        "550e8400-e29b-41d4-a716-446655440022"
      ]
    }
  ],
  "total_count": 156,
  "skip": 0,
  "take": 20
}
```

### Parallel Details Response
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Gold Refractor",
  "description": "Gold chrome refractor parallel",
  "numberedTo": 50,
  "isPartial": false,
  "setId": "550e8400-e29b-41d4-a716-446655440001",
  "setName": "Base Set",
  "releaseId": "550e8400-e29b-41d4-a716-446655440002",
  "releaseName": "2023 Topps Chrome Baseball",
  "releaseYear": "2023",
  "cards": []
}
```

## Response Fields

### Search Parallels Response (PaginatedParallelsResponse)

| Field | Type | Description |
|-------|------|-------------|
| parallels | array | Array of parallel objects with set information |
| total_count | number | Total number of matching parallels |
| skip | number | Number of results skipped |
| take | number | Number of results returned |

### Parallel Object (in search results - ParallelWithSet)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | UUID | Yes | Unique parallel identifier |
| name | string | Yes | Name of the parallel variant (e.g., "Gold Refractor") |
| description | string | No | Additional details about the parallel |
| isPartial | boolean | No | Present and true if parallel applies to specific cards only |
| numberedTo | number | No | Limited print run number (e.g., 50 means /50) |
| prices | object | No | Pricing data (see Prices Object below) |
| cards | array | No | Card UUIDs when isPartial is true |
| setId | UUID | Yes | UUID of the set this parallel belongs to |
| setName | string | Yes | Name of the set |
| releaseId | UUID | Yes | UUID of the release |
| releaseName | string | Yes | Name of the release |
| releaseYear | string | Yes | Year of the release |
| cardCount | number | Yes | Number of base cards in the set |

### 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 Details Response (DetailedParallelResponse)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | UUID | Yes | Unique parallel identifier |
| name | string | Yes | Name of the parallel variant |
| description | string | No | Additional details about the parallel |
| numberedTo | number | No | Limited print run (null for unlimited) |
| isPartial | boolean | Yes | True if parallel applies to specific cards only |
| setId | UUID | Yes | UUID of the set this parallel belongs to |
| setName | string | Yes | Name of the set |
| releaseId | UUID | Yes | UUID of the release |
| releaseName | string | Yes | Name of the release |
| releaseYear | string | Yes | Year of the release |
| cards | array | No | Card UUIDs when isPartial is true |

### Key Concepts

| Term | Description |
|------|-------------|
| Parallel | A visual variant of a base card (different color, foil, numbering) |
| numberedTo | How many copies exist (e.g., 50 means /50 parallel) |
| Partial Parallel | Parallel that only applies to certain cards in the set, not all |
| Full Set Parallel | Parallel that applies to every card in the set (isPartial is false or omitted) |

## Common Use Cases
- Find all numbered parallels in a specific release
- Search for specific parallel types (Refractor, Prizm, etc.)
- Check which cards have a partial parallel
- Get print run information for rare parallels
- Build parallel collection checklists
- Research parallel availability across sets

## Tips for AI Assistants
- The SDK returns `{ data, error }` - always check for errors first
- Parallels with `numberedTo` are numbered/limited (e.g., /50, /25, /10, /1)
- Parallels with `isPartial: true` only apply to specific cards - check `cards` array
- Use the Set Details endpoint to see all parallels within a set
- Parallel names vary by manufacturer: "Refractor" (Topps), "Prizm" (Panini)
- Higher numbered parallels (closer to 1) are typically more valuable
- Some parallels have no `numberedTo` (unlimited production like base Refractors)
- Prices are strings in USD format (e.g., "25.00") - parse as needed