# Using the CardSight AI API - Segment Search API

## Overview
List and search for market segments (categories) in the CardSight AI catalog. Segments represent card categories like "Baseball", "Basketball", "Football", "Pokemon", "One Piece", etc.

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

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | No | Filter segments by name (partial match, case-insensitive) |
| is_identifiable | string | No | Filter by AI identification support ("true" or "false") |
| 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 |
| 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' })

// Get all segments
const response = await client.catalog.segments()

// Search with filters
const filteredResponse = await client.catalog.segments({
  name: 'Sport',
  is_identifiable: 'true',
  take: 20
})

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

  for (const segment of response.data.segments) {
    console.log(`${segment.name} (ID: ${segment.id})`)
  }
}
```

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

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

# Get all segments
response = client.catalog.segments()

# Search with filters
response = client.catalog.segments(name='Sport', is_identifiable='true', take=20)

print(f"Found {response.total_count} segments")
for segment in response.segments:
    print(f"- {segment.name} (ID: {segment.id})")
```

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

## Example Response
```json
{
  "segments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Baseball",
      "is_identifiable": true
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Basketball",
      "is_identifiable": true
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "Football",
      "is_identifiable": true
    }
  ],
  "total_count": 12,
  "skip": 0,
  "take": 20
}
```

## Response Fields

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

### Segment Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | UUID | Yes | Unique segment identifier |
| name | string | Yes | Display name of the segment |
| is_identifiable | boolean | Yes | Whether cards in this segment can be identified by the CardSight AI identification service |

## Common Use Cases
- Get a list of all available card categories
- Build a segment picker/dropdown for filtering releases
- Discover what types of cards are in the catalog

## Tips for AI Assistants
- The SDK returns `{ data, error }` - always check for errors first
- Segment IDs are UUIDs and are stable - they can be cached
- Use segment IDs when filtering releases to a specific category
- Use the Statistics endpoint to get card counts per segment
- Common segments include: Baseball, Basketball, Football, Hockey, Pokemon, One Piece, etc.
- Use `is_identifiable` to filter segments that support AI card identification
- When `is_identifiable` is true, cards in that segment can be identified via the `/v1/identify/card` endpoint