# Using the CardSight AI API - Collection Search API

## Overview
List and search for card collections. Collections are organized groups of cards owned by collectors. For detailed collection statistics like card counts and values, use the Collection Analytics endpoint.

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

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| take | integer | No | 20 | Results per page (1-100) |
| skip | integer | No | 0 | Number of results to skip |
| collectorId | UUID | No | - | Filter to a specific collector's collections |
| name | string | No | - | Search collections by name (partial match) |
| sort | string | No | - | Field to sort by: `name` |
| order | string | No | "asc" | Sort order: `asc` or `desc` |

## 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.collections.list({
  take: 20,
  name: 'Rookies',
  sort: 'name',
  order: 'asc'
})

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

  for (const collection of response.data.collections) {
    console.log(`ID: ${collection.id}`)
    console.log(`  Name: ${collection.name || 'Unnamed'}`)
    console.log(`  Owner: ${collection.collectorId}`)

    if (collection.description) {
      console.log(`  Description: ${collection.description}`)
    }
  }
}

// Filter by collector
const collectorCollections = await client.collections.list({
  collectorId: '550e8400-e29b-41d4-a716-446655440099'
})
```

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

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

response = client.collections.list(take=20, name='Rookies')

print(f"Found {response.total_count} collections")
for collection in response.collections:
    print(f"{collection.name or 'Unnamed'} - Owner: {collection.collector_id}")
```

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

# Search by name
curl -X GET "https://api.cardsight.ai/v1/collection/?name=Rookies&sort=name&order=asc" \
  -H "X-Api-Key: your-api-key"

# Filter by collector
curl -X GET "https://api.cardsight.ai/v1/collection/?collectorId=550e8400-e29b-41d4-a716-446655440099" \
  -H "X-Api-Key: your-api-key"
```

## Example Response
```json
{
  "collections": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "collectorId": "550e8400-e29b-41d4-a716-446655440099",
      "name": "2023 Baseball Rookies",
      "description": "My rookie card collection from 2023"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "collectorId": "550e8400-e29b-41d4-a716-446655440099",
      "name": "Vintage Cards",
      "description": null
    }
  ],
  "total_count": 10,
  "skip": 0,
  "take": 20
}
```

## Response Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| collections | array | Yes | Array of Collection objects |
| total_count | number | Yes | Total number of collections matching filters |
| skip | number | Yes | Number of results skipped |
| take | number | Yes | Number of results returned |

### Collection Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | UUID | Yes | Unique collection identifier |
| collectorId | UUID | Yes | ID of the collector who owns this collection |
| name | string | No | Collection name |
| description | string | No | Collection description |

## Related Endpoints

For more detailed collection information, use these endpoints:

| Endpoint | Description |
|----------|-------------|
| `/v1/collection/{collectionId}` | Get single collection details |
| `/v1/collection/{collectionId}/analytics` | Get card counts, values, ROI, top performers |
| `/v1/collection/{collectionId}/cards` | List all cards in the collection |
| `/v1/collection/{collectionId}/breakdown` | Analyze collection by year, player, manufacturer |

## Common Use Cases
- Browse all available collections
- Search for collections by name
- Find all collections owned by a specific collector
- List collections for a dashboard view
- Get collection IDs for use with other endpoints

## Tips for AI Assistants
- The SDK returns `{ data, error }` - always check for errors first
- URL uses singular "collection" with trailing slash: `/v1/collection/`
- This endpoint returns only basic metadata (id, collectorId, name, description)
- For card counts and values, use the **analytics** endpoint with the collection ID
- The `name` and `description` fields are optional and may be null
- Use `collectorId` filter to find all collections by a specific user
- Only `name` is available as a sort field