# Using the CardSight AI API - Collectors API

## Overview
Manage collector profiles in the CardSight AI platform. Collectors are entities that own collections of cards. Each API key can have multiple collectors, and each collector can have multiple collections.

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

## Endpoints

| Method | URL | Description |
|--------|-----|-------------|
| GET | /v1/collectors/ | List all collectors |
| POST | /v1/collectors/ | Create a new collector |
| GET | /v1/collectors/{collectorId} | Get a specific collector |
| PUT | /v1/collectors/{collectorId} | Update a collector |
| DELETE | /v1/collectors/{collectorId} | Delete a collector |

## List Collectors Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| take | integer | No | 20 | Results per page (1-100) |
| skip | integer | No | 0 | Number of results to skip |

## Using the CardSight AI SDK (Recommended)

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

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

// List all collectors
const response = await client.collectors.list({ take: 20 })

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

  for (const collector of response.data.collectors) {
    console.log(`ID: ${collector.id}`)
    if (collector.name) {
      console.log(`  Name: ${collector.name}`)
    }
  }
}

// Create a new collector
const newCollector = await client.collectors.create({
  name: 'Mike'
})

if (!newCollector.error) {
  console.log(`Created collector: ${newCollector.data.id}`)
}

// Get a specific collector
const collector = await client.collectors.get('550e8400-e29b-41d4-a716-446655440000')

if (!collector.error) {
  console.log(`Collector: ${collector.data.name || 'Unnamed'}`)
}

// Update a collector
const updated = await client.collectors.update('550e8400-e29b-41d4-a716-446655440000', {
  name: 'Mike Smith'
})

// Delete a collector (also deletes all their collections)
await client.collectors.delete('550e8400-e29b-41d4-a716-446655440000')
```

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

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

# List all collectors
response = client.collectors.list(take=20)

print(f"Found {response.total_count} collectors")
for collector in response.collectors:
    print(f"ID: {collector.id}, Name: {collector.name or 'Unnamed'}")

# Create a new collector
new_collector = client.collectors.create(name='Mike')
print(f"Created: {new_collector.id}")

# Get a specific collector
collector = client.collectors.get('550e8400-e29b-41d4-a716-446655440000')

# Update a collector
client.collectors.update('550e8400-e29b-41d4-a716-446655440000', name='Mike Smith')

# Delete a collector
client.collectors.delete('550e8400-e29b-41d4-a716-446655440000')
```

## Direct API Calls (cURL)

```bash
# List all collectors
curl -X GET "https://api.cardsight.ai/v1/collectors/?take=20" \
  -H "X-Api-Key: your-api-key"

# Create a new collector
curl -X POST "https://api.cardsight.ai/v1/collectors/" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mike"}'

# Get a specific collector
curl -X GET "https://api.cardsight.ai/v1/collectors/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Api-Key: your-api-key"

# Update a collector
curl -X PUT "https://api.cardsight.ai/v1/collectors/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mike Smith"}'

# Delete a collector
curl -X DELETE "https://api.cardsight.ai/v1/collectors/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Api-Key: your-api-key"
```

## Example Response (List Collectors)
```json
{
  "collectors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Mike"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": null
    }
  ],
  "total_count": 2,
  "skip": 0,
  "take": 20
}
```

## Example Response (Single Collector)
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Mike"
}
```

## Response Fields

### Paginated Collectors Response

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| collectors | array | Yes | Array of Collector objects |
| total_count | number | Yes | Total number of collectors |
| skip | number | Yes | Number of results skipped |
| take | number | Yes | Number of results returned |

### Collector Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | UUID | Yes | Unique collector identifier |
| name | string | No | Name of the collector (e.g., "Mike", "Eric") |

### Create/Update Collector Request

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | No | Name of the collector |

## Common Use Cases
- Create collectors to organize cards by person or purpose
- List all collectors under your API key
- Update collector names
- Delete collectors (and all their collections)

## Tips for AI Assistants
- The SDK returns `{ data, error }` - always check for errors first
- URL uses trailing slash: `/v1/collectors/`
- Collector objects are very simple: just `id` and optional `name`
- The `name` field is optional and may be null
- Deleting a collector will also delete all their associated collections
- There is no search/filter parameter - the list endpoint returns all collectors
- To find a collector's collections, use the Collection Search endpoint with `collectorId` filter