# Using the CardSight AI API - Release Details API

## Overview
Get detailed information about a specific card release including all sets within the release and card counts.

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

## Parameters

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

// Always check for errors
if (response.error) {
  console.error('Error:', response.error)
} else {
  const release = response.data
  console.log(`${release.year} ${release.name}`)
  console.log(`Sets: ${release.sets.length}`)

  for (const set of release.sets) {
    console.log(`  - ${set.name}: ${set.cardCount} cards, ${set.parallelCount} parallels`)
  }
}
```

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

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

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

print(f"{response.year} {response.name}")
for set in response.sets:
    print(f"  - {set.name}: {set.card_count} cards")
```

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

## Example Response
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "segmentId": "550e8400-e29b-41d4-a716-446655440001",
  "manufacturerId": "550e8400-e29b-41d4-a716-446655440002",
  "year": "2023",
  "name": "Topps Chrome Baseball",
  "description": "Premium chrome baseball cards featuring top MLB players",
  "is_identifiable": true,
  "sets": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "name": "Base Set",
      "description": "220-card base set",
      "cardCount": 220,
      "parallelCount": 15,
      "is_identifiable": true
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "name": "Rookie Autographs",
      "description": "Autographed rookie cards",
      "cardCount": 50,
      "parallelCount": 8,
      "is_identifiable": true
    }
  ]
}
```

## Response Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | UUID | Yes | Unique release identifier |
| segmentId | UUID | Yes | UUID of the segment |
| manufacturerId | UUID | Yes | UUID of the manufacturer |
| year | string | Yes | Year the release was issued |
| name | string | Yes | Full name of the release |
| description | string | No | Additional details about the release |
| is_identifiable | boolean | Yes | Whether any set in this release can be identified by the CardSight AI identification service |
| sets | array | Yes | Array of sets within this release |

### Set Object

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

## Common Use Cases
- Get complete information about a release
- View all sets within a product
- Display card counts and parallel information
- Build detailed product pages

## 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 `sets` array contains all sets with their card counts
- Use set IDs from this response to query cards within specific sets
- Use Release Cards endpoint to get actual card listings
- The `is_identifiable` field on the release is true if at least one of its sets supports AI identification
- Each set also has its own `is_identifiable` field indicating per-set identification support