# Using the CardSight AI API - Collection Cards API

## Overview
List and manage cards in a specific collection. Returns paginated card entries with quantity, pricing, and sale information. Note that this endpoint returns card references (UUIDs) - use the catalog cards endpoint to get full card details.

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

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| collectionId | UUID | Yes | - | Collection UUID (path) |
| take | integer | No | 20 | Results per page (1-100) |
| skip | integer | No | 0 | Number of results to skip |
| cardId | UUID | No | - | Filter by catalog card UUID |
| parallelId | UUID | No | - | Filter by parallel UUID |
| gradeId | UUID | No | - | Filter by grade UUID |
| hasSold | boolean | No | - | Filter by sold status (true = sold, false = not sold) |
| sort | string | No | - | Sort by: `buyDate`, `soldDate`, `buyPrice`, `soldPrice` |
| order | string | No | "desc" | 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.cards.list('550e8400-e29b-41d4-a716-446655440000', {
  take: 20,
  sort: 'buyDate',
  order: 'desc'
})

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

  for (const card of response.data.cards) {
    console.log(`Collection Card ID: ${card.id}`)
    console.log(`  Catalog Card ID: ${card.cardId}`)
    console.log(`  Quantity: ${card.quantity}`)

    if (card.parallelId) {
      console.log(`  Parallel ID: ${card.parallelId}`)
    }

    if (card.gradeId) {
      console.log(`  Grade ID: ${card.gradeId}`)
    }

    if (card.buyPrice) {
      console.log(`  Buy Price: $${card.buyPrice}`)
    }

    if (card.soldPrice) {
      console.log(`  Sold Price: $${card.soldPrice} on ${card.soldDate}`)
    }
  }
}

// Filter to show only sold cards
const soldCards = await client.collections.cards.list('550e8400-e29b-41d4-a716-446655440000', {
  hasSold: true,
  sort: 'soldDate'
})
```

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

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

response = client.collections.cards.list(
    '550e8400-e29b-41d4-a716-446655440000',
    take=20,
    sort='buyDate'
)

for card in response.cards:
    print(f"Card ID: {card.card_id}, Qty: {card.quantity}")
    if card.buy_price:
        print(f"  Paid: ${card.buy_price}")
```

## Direct API Call (cURL)
```bash
# List all cards in collection
curl -X GET "https://api.cardsight.ai/v1/collection/550e8400-e29b-41d4-a716-446655440000/cards?take=20" \
  -H "X-Api-Key: your-api-key"

# Filter by sold status and sort by sold date
curl -X GET "https://api.cardsight.ai/v1/collection/550e8400-e29b-41d4-a716-446655440000/cards?hasSold=true&sort=soldDate&order=desc" \
  -H "X-Api-Key: your-api-key"

# Filter by specific card
curl -X GET "https://api.cardsight.ai/v1/collection/550e8400-e29b-41d4-a716-446655440000/cards?cardId=550e8400-e29b-41d4-a716-446655440010" \
  -H "X-Api-Key: your-api-key"
```

## Example Response
```json
{
  "cards": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "collectionId": "550e8400-e29b-41d4-a716-446655440000",
      "cardId": "550e8400-e29b-41d4-a716-446655440010",
      "parallelId": null,
      "gradeId": "550e8400-e29b-41d4-a716-446655440020",
      "quantity": 1,
      "buyPrice": "25.00",
      "buyDate": "2023-10-15",
      "sellPrice": null,
      "soldPrice": null,
      "soldDate": null
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "collectionId": "550e8400-e29b-41d4-a716-446655440000",
      "cardId": "550e8400-e29b-41d4-a716-446655440011",
      "parallelId": "550e8400-e29b-41d4-a716-446655440030",
      "gradeId": null,
      "quantity": 2,
      "buyPrice": "50.00",
      "buyDate": "2023-11-20",
      "sellPrice": "75.00",
      "soldPrice": "70.00",
      "soldDate": "2024-01-10"
    }
  ],
  "total_count": 150,
  "skip": 0,
  "take": 20
}
```

## Response Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| cards | array | Yes | Array of CollectionCard objects |
| total_count | number | Yes | Total cards in collection |
| skip | number | Yes | Number of results skipped |
| take | number | Yes | Number of results returned |

### CollectionCard Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | UUID | Yes | Unique collection card identifier |
| collectionId | UUID | Yes | ID of the collection |
| cardId | UUID | Yes | ID of the catalog card (use to fetch card details) |
| quantity | number | Yes | Number of copies (minimum: 1) |
| parallelId | UUID | No | ID of the parallel variant if applicable |
| gradeId | UUID | No | ID of the grade if card is graded |
| buyPrice | string | No | Purchase price (USD, e.g., "25.00") |
| buyDate | string | No | Purchase date (YYYY-MM-DD) |
| sellPrice | string | No | Listed selling price (USD) |
| soldPrice | string | No | Actual sold price (USD) |
| soldDate | string | No | Date sold (YYYY-MM-DD) |

## Common Use Cases
- Browse all cards in a collection
- Filter to show only sold or unsold cards
- Sort by purchase date or price
- Find specific cards by catalog card ID
- Track buying and selling history
- Export collection contents

## Tips for AI Assistants
- **Note on IDs:** your `collectionId` (and other resources you create) are stable and yours to keep — saving cards to a collection or list is the recommended way to hold onto them for the long term. The card and set IDs inside a collection (`cardId`, `setId`) are catalog references you can use to pull fresh details from the catalog. See the FAQ for how IDs should be used.
- The SDK returns `{ data, error }` - always check for errors first
- URL uses singular "collection" not "collections": `/v1/collection/{collectionId}/cards`
- This endpoint returns **references** (UUIDs) to cards, not full card details
- To get card name, set, release info, call `/v1/catalog/cards/{cardId}` with the `cardId`
- To get grade details, call the grades endpoint with the `gradeId`
- To get parallel details, use the card details endpoint
- `buyPrice`, `sellPrice`, `soldPrice` are strings formatted as USD (e.g., "25.00")
- Dates are in YYYY-MM-DD format
- Use `hasSold=true` to filter to sold cards only, `hasSold=false` for unsold
- A card is considered "sold" when `soldPrice` and `soldDate` are set