# Using the CardSight AI API - Release Cards API

## Overview
List all cards within a specific release. Retrieve a paginated list of base cards across all sets in a release, with optional filtering by set or player name.

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

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | UUID | Yes | The release UUID (path parameter) |
| setId | UUID | No | Filter to a specific set within the release |
| name | string | No | Search by player/subject name (partial match) |
| 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: number, name |
| 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' })

const response = await client.catalog.releases.cards('550e8400-e29b-41d4-a716-446655440000', {
  take: 20,
  sort: 'number'
})

// 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.number} ${card.name} - ${card.setName}`)
  }
}
```

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

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

response = client.catalog.releases.cards(
    '550e8400-e29b-41d4-a716-446655440000',
    take=20,
    sort='number'
)

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

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

## Example Response
```json
{
  "cards": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "releaseId": "550e8400-e29b-41d4-a716-446655440000",
      "setId": "550e8400-e29b-41d4-a716-446655440003",
      "name": "Shohei Ohtani",
      "number": "1",
      "setName": "Base Set",
      "releaseName": "Topps Chrome Baseball",
      "releaseYear": "2023",
      "attributes": ["RC"],
      "prices": {
        "raw": "25.00",
        "psa-10": "150.00",
        "psa-9": "75.00"
      }
    }
  ],
  "total_count": 220,
  "skip": 0,
  "take": 20
}
```

## Response Fields

| Field | Type | Description |
|-------|------|-------------|
| cards | array | Array of card objects |
| total_count | number | Total cards in this release |
| 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 |
| setId | UUID | Yes | UUID of the set |
| name | string | Yes | Player/subject name |
| setName | string | Yes | Name of the card set |
| number | string | No | Card number within the set |
| description | string | No | Additional details |
| releaseName | string | No | Name of the release |
| releaseYear | string | No | Year of the release |
| attributes | array | No | Attribute codes (e.g., ["RC", "AU"]) |
| prices | object | No | Market prices (see Prices Object below) |
| variationOf | UUID | No | UUID of the base card if this is a variation |

### 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
- Build complete card checklists for a release
- Search for specific players within a product
- Display all cards in a set
- Track collection progress against a release

## 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 `setId` to filter to a specific set within the release
- Sort by `number` to get cards in checklist order
- This endpoint returns base cards only, not parallel variants
- Use Card Details endpoint to get parallel information for a card
- The `prices` object contains market prices as strings (USD format)
- If `variationOf` is present, the card is a variation of another base card