# Using the CardSight AI API - Collection Details API

## Overview
Get information about a specific card collection. Returns the collection's basic metadata. For statistics like card counts and values, use the Collection Analytics endpoint.

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

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| collectionId | UUID | Yes | The collection UUID (path parameter) |

## 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.get('550e8400-e29b-41d4-a716-446655440000')

// Always check for errors
if (response.error) {
  console.error('Error:', response.error)
} else {
  const collection = response.data
  console.log(`Collection: ${collection.name || 'Unnamed'}`)
  console.log(`ID: ${collection.id}`)
  console.log(`Owner: ${collection.collectorId}`)

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

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

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

response = client.collections.get('550e8400-e29b-41d4-a716-446655440000')

print(f"Collection: {response.name or 'Unnamed'}")
print(f"Owner: {response.collector_id}")
```

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

## Example Response
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "collectorId": "550e8400-e29b-41d4-a716-446655440099",
  "name": "2023 Baseball Rookies",
  "description": "My rookie card collection from 2023"
}
```

## Response Fields

| 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}/analytics` | Get card counts, values, ROI, top performers |
| `/v1/collection/{collectionId}/breakdown` | Analyze collection by year, player, manufacturer, etc. |
| `/v1/collection/{collectionId}/cards` | List all cards in the collection |
| `/v1/collection/{collectionId}/set-progress` | Track set completion progress |

## Common Use Cases
- Get basic collection metadata
- Verify collection ownership (collectorId)
- Display collection name and description
- Navigate to related collection endpoints

## Tips for AI Assistants
- The SDK returns `{ data, error }` - always check for errors first
- URL uses singular "collection" not "collections": `/v1/collection/{collectionId}`
- This endpoint returns only basic metadata (id, collectorId, name, description)
- For card counts, total values, and statistics, use the **analytics** endpoint
- For breaking down by year/manufacturer/player, use the **breakdown** endpoint
- The `name` and `description` fields are optional and may be null