# Using the CardSight AI API - Global Search

## Overview
Search across cards, sets, releases, and parallels simultaneously with fuzzy matching and relevance scoring. This is the most versatile search endpoint — ideal for building universal search bars or exploring the catalog with natural language queries.

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

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| q | string | Yes | Free-text search query. Supports multi-word queries like "aaron judge topps" or "1952 mickey mantle". Minimum 2 characters. |
| take | integer | No | Results per page (1-100, default: 20) |
| skip | integer | No | Number of results to skip for pagination (default: 0) |
| type | string | No | Filter to a specific entity type: "card", "set", "release", or "parallel". When omitted, returns mixed results. |
| segment | string | No | Filter by segment name or UUID (case-insensitive). e.g., "Baseball", "Football" |
| manufacturer | string | No | Filter by manufacturer name or UUID (case-insensitive). e.g., "Topps", "Panini" |
| year | string | No | Filter by exact release year (e.g., "2023"). Overrides min_year/max_year when specified. |
| min_year | string | No | Filter results from this year onwards (inclusive). Ignored if "year" is specified. |
| max_year | string | No | Filter results up to this year (inclusive). Ignored if "year" is specified. |

## Using the CardSight AI SDK (Recommended)

### Node.js / TypeScript
```typescript
import { CardSightAI } from 'cardsightai'

const client = new CardSightAI({ apiKey: 'your-api-key' })

// Basic search
const response = await client.catalog.search({
  q: 'michael jordan baseball',
  take: 20
})

if (response.error) {
  console.error('Error:', response.error)
} else {
  console.log(`Found ${response.data.total_count} results`)

  for (const result of response.data.results) {
    console.log(`[${result.type}] ${result.name} (relevance: ${result.relevance})`)
    if (result.year) console.log(`  Year: ${result.year}`)
    if (result.releaseName) console.log(`  Release: ${result.releaseName}`)
    if (result.setName) console.log(`  Set: ${result.setName}`)
    if (result.manufacturerName) console.log(`  Manufacturer: ${result.manufacturerName}`)
  }
}

// Filter to only cards from a specific year
const cardResponse = await client.catalog.search({
  q: 'aaron judge',
  type: 'card',
  year: '2023',
  take: 10
})

// Filter by segment and manufacturer
const filteredResponse = await client.catalog.search({
  q: 'chrome refractor',
  segment: 'Baseball',
  manufacturer: 'Topps',
  take: 15
})
```

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

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

# Basic search
response = client.catalog.search(
    q='michael jordan baseball',
    take=20
)

print(f"Found {response.total_count} results")
for result in response.results:
    print(f"[{result.type}] {result.name} (relevance: {result.relevance})")
```

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

## Example Response
```json
{
  "results": [
    {
      "type": "card",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Michael Jordan",
      "relevance": 9.5,
      "year": "1986",
      "setName": "Base Set",
      "releaseName": "Fleer",
      "manufacturerName": "Fleer"
    },
    {
      "type": "release",
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "1996-97 Topps Chrome Basketball",
      "relevance": 7.8,
      "year": "1996",
      "manufacturerName": "Topps"
    },
    {
      "type": "set",
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "Refractors",
      "relevance": 6.2,
      "year": "1996",
      "releaseName": "1996-97 Topps Chrome Basketball",
      "manufacturerName": "Topps"
    },
    {
      "type": "parallel",
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "name": "Michael Jordan",
      "relevance": 5.9,
      "year": "1996",
      "setName": "Base Set",
      "releaseName": "1996-97 Topps Chrome Basketball",
      "manufacturerName": "Topps",
      "parallelName": "Refractor"
    }
  ],
  "total_count": 156,
  "skip": 0,
  "take": 20
}
```

## Response Fields

| Field | Type | Description |
|-------|------|-------------|
| results | array | Array of search result objects, sorted by relevance (descending) |
| total_count | number | Total number of matching results across all types |
| skip | number | Number of results skipped (offset) |
| take | number | Number of results in this page |

### SearchResult Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| type | string | Yes | Entity type: "card", "set", "release", or "parallel" |
| id | UUID | Yes | Unique identifier for this entity |
| name | string | Yes | Primary name (player name for cards, set/release name for others) |
| relevance | number | Yes | Relevance score — higher is better match. Results sorted by this. |
| year | string | No | Release year associated with this result |
| setName | string | No | Set name (present for card and parallel results) |
| releaseName | string | No | Release name (present for card, set, and parallel results) |
| manufacturerName | string | No | Manufacturer name |
| parallelName | string | No | Parallel variant name (present when a parallel name contributed to relevance) |

## Common Use Cases
- Build a universal search bar that finds cards, sets, and releases at once
- Natural language search like "1952 mickey mantle" or "topps chrome 2023"
- Explore the catalog when you're not sure which entity type you need
- Filter results to only cards, sets, releases, or parallels as needed
- Combine with type-specific detail endpoints for full entity information

## 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 `q` parameter is required and must be at least 2 characters
- Results are pre-sorted by `relevance` score (descending) — no separate sort parameter
- Use the `type` filter to narrow results when the user wants a specific entity type
- Each result's `id` can be used with the corresponding detail endpoint (e.g., card ID → `/v1/catalog/cards/{id}`)
- The `parallelName` field is only present on results where a parallel name boosted relevance
- For pagination, use `skip` and `take` — e.g., page 2 with 20 results per page uses `skip=20`
- This endpoint is great for autocomplete-style interfaces, though the dedicated `/v1/autocomplete` endpoint may be faster for simple suggestions