# Using the CardSight AI API - Lists API

## Overview
Create and manage card lists (want lists, wishlists, collection goals, etc.). Lists belong to collectors and contain references to catalog cards.

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

## Endpoints

| Method | URL | Description |
|--------|-----|-------------|
| GET | /v1/lists/ | Get all lists with pagination |
| POST | /v1/lists/ | Create a new list |
| GET | /v1/lists/{listId} | Get a specific list |
| PUT | /v1/lists/{listId} | Update a list |
| DELETE | /v1/lists/{listId} | Delete a list |
| GET | /v1/lists/{listId}/cards | Get all cards in a list |
| POST | /v1/lists/{listId}/cards | Add card(s) to a list (supports batch) |
| DELETE | /v1/lists/{listId}/cards/{cardId} | Remove a card from a list |

## List Lists 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 by collector |
| name | string | No | - | Search by list 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' })

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

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

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

// Create a new list
const newList = await client.lists.create({
  collectorId: '550e8400-e29b-41d4-a716-446655440099',
  name: 'My Wishlist',
  description: 'Cards I want to collect'
})

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

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

// Update a list
await client.lists.update('550e8400-e29b-41d4-a716-446655440000', {
  name: 'Updated Wishlist',
  description: 'My updated description'
})

// Add a single card to the list
const addResult = await client.lists.addCard('550e8400-e29b-41d4-a716-446655440000', {
  cardId: '550e8400-e29b-41d4-a716-446655440010'
})

// Add multiple cards at once (batch - up to 100)
const batchResult = await client.lists.addCards('550e8400-e29b-41d4-a716-446655440000', [
  { cardId: '550e8400-e29b-41d4-a716-446655440010' },
  { cardId: '550e8400-e29b-41d4-a716-446655440011' },
  { cardId: '550e8400-e29b-41d4-a716-446655440012' }
])

// Get all cards in a list
const cardsResponse = await client.lists.cards('550e8400-e29b-41d4-a716-446655440000', {
  take: 50
})

if (!cardsResponse.error) {
  for (const listCard of cardsResponse.data.cards) {
    console.log(`List Card ID: ${listCard.id}, Card ID: ${listCard.cardId}`)
  }
}

// Remove a card from the list
await client.lists.removeCard('550e8400-e29b-41d4-a716-446655440000', 'LIST_CARD_ID')

// Delete the list
await client.lists.delete('550e8400-e29b-41d4-a716-446655440000')
```

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

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

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

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

# Create a new list
new_list = client.lists.create(
    collector_id='550e8400-e29b-41d4-a716-446655440099',
    name='My Wishlist',
    description='Cards I want to collect'
)

# Add cards to the list
client.lists.add_card(new_list.id, card_id='550e8400-e29b-41d4-a716-446655440010')

# Get cards in the list
cards = client.lists.cards(new_list.id)
for card in cards.cards:
    print(f"Card ID: {card.card_id}")

# Delete the list
client.lists.delete(new_list.id)
```

## Direct API Calls (cURL)

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

# Create a list
curl -X POST "https://api.cardsight.ai/v1/lists/" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"collectorId": "550e8400-e29b-41d4-a716-446655440099", "name": "My Wishlist", "description": "Cards I want"}'

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

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

# Get cards in a list
curl -X GET "https://api.cardsight.ai/v1/lists/550e8400-e29b-41d4-a716-446655440000/cards?take=50" \
  -H "X-Api-Key: your-api-key"

# Add a single card to a list
curl -X POST "https://api.cardsight.ai/v1/lists/550e8400-e29b-41d4-a716-446655440000/cards" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"cardId": "550e8400-e29b-41d4-a716-446655440010"}'

# Add multiple cards (batch)
curl -X POST "https://api.cardsight.ai/v1/lists/550e8400-e29b-41d4-a716-446655440000/cards" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '[{"cardId": "550e8400-e29b-41d4-a716-446655440010"}, {"cardId": "550e8400-e29b-41d4-a716-446655440011"}]'

# Remove a card from a list (uses list-card ID, not card ID)
curl -X DELETE "https://api.cardsight.ai/v1/lists/550e8400-e29b-41d4-a716-446655440000/cards/LIST_CARD_ID" \
  -H "X-Api-Key: your-api-key"

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

## Example Response (List Lists)
```json
{
  "lists": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "collectorId": "550e8400-e29b-41d4-a716-446655440099",
      "name": "My Wishlist",
      "description": "Cards I want to collect"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "collectorId": "550e8400-e29b-41d4-a716-446655440099",
      "name": "Set Completion Goals",
      "description": null
    }
  ],
  "total_count": 2,
  "skip": 0,
  "take": 20
}
```

## Example Response (Get List Cards)
```json
{
  "cards": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "listId": "550e8400-e29b-41d4-a716-446655440000",
      "cardId": "550e8400-e29b-41d4-a716-446655440010"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440021",
      "listId": "550e8400-e29b-41d4-a716-446655440000",
      "cardId": "550e8400-e29b-41d4-a716-446655440011"
    }
  ],
  "total_count": 2,
  "skip": 0,
  "take": 20
}
```

## Example Response (Add Cards - Batch)
```json
{
  "cards": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "listId": "550e8400-e29b-41d4-a716-446655440000",
      "cardId": "550e8400-e29b-41d4-a716-446655440010"
    }
  ],
  "errors": []
}
```

## Response Fields

### Paginated Lists Response

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

### List Object

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

### ListCard Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | Yes | Unique list-card link identifier |
| listId | UUID | Yes | ID of the list |
| cardId | UUID | Yes | ID of the catalog card |

### Create/Update List Request

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| collectorId | UUID | Yes (create) | ID of the collector who owns this list |
| name | string | No | List name |
| description | string | No | List description |

### Add Card Request

Supports two formats:

**Single card:**
```json
{ "cardId": "uuid" }
```

**Batch (up to 100 cards):**
```json
[
  { "cardId": "uuid1" },
  { "cardId": "uuid2" }
]
```

## Common Use Cases
- Create want lists for cards you're seeking
- Track cards needed for set completion
- Organize cards by theme or priority
- Share lists with other collectors
- Batch add multiple cards at once

## Tips for AI Assistants
- The SDK returns `{ data, error }` - always check for errors first
- URL uses trailing slash for base: `/v1/lists/`
- Lists belong to collectors via `collectorId`
- The `name` and `description` fields are optional and may be null
- When removing a card, use the ListCard `id` (not the `cardId`)
- Batch add supports up to 100 cards at once
- ListCard objects contain references (UUIDs) to catalog cards, not full card details
- To get card details, use the catalog cards endpoint with the `cardId`