# Using the CardSight AI API - Set Details API

## Overview
Get comprehensive information about a specific card set including card count, release context, and all available parallel variants.

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

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | UUID | Yes | The set 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.sets.get('550e8400-e29b-41d4-a716-446655440000')

// Always check for errors
if (response.error) {
  console.error('Error:', response.error)
} else {
  const set = response.data
  console.log(`${set.name} - ${set.releaseName} (${set.releaseYear})`)
  console.log(`Cards: ${set.cardCount}`)
  console.log(`Parallels: ${set.parallelCount}`)

  for (const parallel of set.parallels) {
    console.log(`  - ${parallel.name}${parallel.numberedTo ? ` /${parallel.numberedTo}` : ''}`)
  }
}
```

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

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

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

print(f"{response.name} - {response.card_count} cards")
```

## Direct API Call (cURL)
```bash
curl -X GET "https://api.cardsight.ai/v1/catalog/sets/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",
  "name": "Base Set",
  "description": "220-card chrome base set",
  "releaseName": "Topps Chrome Baseball",
  "releaseYear": "2023",
  "cardCount": 220,
  "parallelCount": 15,
  "is_identifiable": true,
  "parallels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "name": "Refractor"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "name": "Gold Refractor",
      "numberedTo": 50
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440012",
      "name": "Superfractor",
      "numberedTo": 1
    }
  ]
}
```

## Response Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | UUID | Yes | Unique set identifier |
| releaseId | UUID | Yes | UUID of the parent release |
| name | string | Yes | Name of the set |
| description | string | No | Additional details about the set |
| releaseName | string | Yes | Name of the release |
| releaseYear | string | Yes | Year of the release |
| cardCount | number | Yes | Number of base cards |
| parallelCount | number | Yes | Number of parallel types |
| is_identifiable | boolean | Yes | Whether cards in this set can be identified by the CardSight AI identification service |
| parallels | array | Yes | List of parallel variants |

### Parallel Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | UUID | Yes | Unique parallel type identifier |
| name | string | Yes | Name of the parallel variant |
| description | string | No | Additional details about the parallel |
| numberedTo | number | No | Limited print run (if numbered, e.g., 50 for /50) |
| isPartial | boolean | No | True if parallel only applies to specific cards in the set |
| prices | object | No | Market prices (see Prices Object below) |
| cards | array | No | Card UUIDs that have this parallel (only when isPartial is true) |

### Prices Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| raw | string | No | Ungraded card price (USD, e.g., "25.00") |
| psa-10 | string | No | PSA 10 graded price (USD) |
| psa-9 | string | No | PSA 9 graded price (USD) |

## Common Use Cases
- Get detailed set information for display
- View all available parallels for a set
- Build set checklists with parallel options
- Display complete set composition

## 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
- The `parallels` array shows all variant types available for cards in this set
- `numberedTo` on a parallel indicates a limited print run (e.g., /50)
- If `isPartial` is true, the parallel only applies to specific cards (check the `cards` array)
- The `prices` object contains average market prices when available (strings in USD format)
- Use the set's cards endpoint to get the actual card listings
- When `is_identifiable` is true, cards in this set can be identified via the `/v1/identify/card` endpoint