# Using the CardSight AI API - Release Search API

## Overview
Search for card releases (products) in the CardSight AI catalog. Releases represent complete card products like "2023 Topps Chrome Baseball" or "2024 Panini Prizm Basketball".

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

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | No | Search by release name (partial match, case-insensitive) |
| year | string | No | Filter by exact release year (e.g., "2023") |
| min_year | string | No | Filter releases from this year onwards |
| max_year | string | No | Filter releases up to this year |
| manufacturer | string | No | Filter by manufacturer name or UUID (e.g., "Topps", "Panini") |
| segment | string | No | Filter by segment name or UUID (e.g., "Sports") |
| is_identifiable | string | No | Filter by AI identification support ("true" returns releases with at least one identifiable set, "false" returns releases with no identifiable sets) |
| 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: year, 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' })

// Search for releases
const response = await client.catalog.releases.list({
  name: 'Chrome',
  year: '2023',
  manufacturer: 'Topps',
  take: 20
})

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

  for (const release of response.data.releases) {
    console.log(`${release.year} ${release.name}`)
    console.log(`  ID: ${release.id}`)
    console.log(`  Manufacturer ID: ${release.manufacturerId}`)
    console.log(`  Segment ID: ${release.segmentId}`)
  }
}
```

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

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

# Search for releases
response = client.catalog.releases.list(
    name='Chrome',
    year='2023',
    manufacturer='Topps',
    take=20
)

print(f"Found {response.total_count} releases")
for release in response.releases:
    print(f"{release.year} {release.name}")
```

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

## Example Response
```json
{
  "releases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "manufacturerId": "550e8400-e29b-41d4-a716-446655440001",
      "segmentId": "550e8400-e29b-41d4-a716-446655440002",
      "year": "2023",
      "name": "Topps Chrome Baseball",
      "description": "Premium chrome baseball cards featuring top MLB players",
      "is_identifiable": true
    }
  ],
  "total_count": 1,
  "skip": 0,
  "take": 20
}
```

## Response Fields

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

### Release Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | UUID | Yes | Unique release identifier |
| manufacturerId | UUID | Yes | UUID of the manufacturer (Topps, Panini, etc.) |
| segmentId | UUID | Yes | UUID of the segment (Sports, Entertainment, etc.) |
| year | string | Yes | Year the release was issued (e.g., "2023") |
| 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. True if at least one set has is_identifiable = true |

## Common Use Cases
- Browse available card products by year
- Find all releases from a specific manufacturer
- Discover new products in a sport/segment
- Get release IDs for more detailed queries

## 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
- Release IDs can be used with the Release Details endpoint to get full info including sets
- Use `segment` to filter by sport/category (the segment name or UUID)
- The response contains `manufacturerId` and `segmentId` (UUIDs), not the names
- To get manufacturer/segment names, use those IDs with the respective endpoints
- Use Release Details endpoint (`/v1/catalog/releases/{id}`) to get sets and card counts
- Use `is_identifiable` to filter releases that support AI card identification
- A release's `is_identifiable` is true if at least one of its sets supports identification