# Using the CardSight AI API - AI Query API

## Overview
Ask natural language questions about trading cards. The AI can search the catalog, answer questions about cards, players, releases, and provide insights from the CardSight database.

## Endpoint Details
- **Method**: POST
- **URL**: `https://api.cardsight.ai/v1/ai/query`
- **Authentication**: API Key required (X-Api-Key header)
- **Content-Type**: application/json

## Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| query | string | Yes | Natural language question (1-1000 characters) |
| context | object | No | Optional context (collectionId, userId) |
| conversationHistory | array | No | Previous messages for multi-turn conversations (max 50) |
| maxIterations | integer | No | Max tool use iterations (1-10, default: 5) |

## Using the CardSight AI SDK (Recommended)

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

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

// Ask a question
const response = await client.ai.query({
  query: 'What are the most valuable Shohei Ohtani rookie cards?'
})

// Always check for errors
if (response.error) {
  console.error('Error:', response.error)
} else {
  console.log('Answer:', response.data.answer)
  console.log('Processing Time:', response.data.processingTime, 'ms')

  if (response.data.toolsUsed) {
    console.log('Tools Used:', response.data.toolsUsed)
  }
}

// Multi-turn conversation
const followUp = await client.ai.query({
  query: 'Which of those are from Topps?',
  conversationHistory: [
    { role: 'user', content: 'What are the most valuable Shohei Ohtani rookie cards?' },
    { role: 'assistant', content: response.data.answer }
  ]
})
```

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

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

# Ask a question
response = client.ai.query(
    query='What are the most valuable Shohei Ohtani rookie cards?'
)

print(f"Answer: {response.answer}")
print(f"Processing Time: {response.processing_time}ms")
```

## Direct API Call (cURL)
```bash
curl -X POST "https://api.cardsight.ai/v1/ai/query" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the most valuable Shohei Ohtani rookie cards?"}'
```

## Example Response
```json
{
  "answer": "Based on the CardSight catalog, the most valuable Shohei Ohtani rookie cards include the 2018 Topps Chrome Update base card, 2018 Bowman Chrome prospects, and various refractor parallels. The Chrome Update base typically sells for $50-100 raw, while PSA 10 copies can reach $500-1000 depending on the parallel.",
  "toolsUsed": ["catalog_search", "price_lookup"],
  "processingTime": 2345
}
```

## Response Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| answer | string | Yes | AI-generated response to the query |
| toolsUsed | array | No | List of internal tools used to answer the query |
| processingTime | number | Yes | Time taken to process in milliseconds |

## Context Object (optional)

| Field | Type | Description |
|-------|------|-------------|
| collectionId | UUID | Scope query to a specific collection |
| userId | string | User identifier for personalized context |

## Conversation Message Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| role | string | Yes | "user" or "assistant" |
| content | string | Yes | The message content (1-10000 characters) |

## Example Questions
- "What are the most valuable rookie cards from 2023?"
- "Find all Mike Trout cards from Topps Chrome"
- "How many cards are in the 2024 Bowman Draft set?"
- "What parallels exist for the Topps Chrome base set?"
- "Which manufacturers made Pokemon cards in 2023?"

## Common Use Cases
- Natural language card search
- Getting card collecting advice
- Learning about sets and releases
- Exploring the catalog conversationally

## Tips for AI Assistants
- The SDK returns `{ data, error }` - always check for errors first
- Use `conversationHistory` for follow-up questions that reference previous answers
- The AI has access to the full CardSight catalog and can search it
- Questions about pricing, rarity, and card details are all supported
- Keep queries under 1000 characters
- The `toolsUsed` field shows which internal tools were used to generate the answer