# Using the CardSight AI API - Card Detection API

## Overview
Detect whether trading cards are present in an image using CardSight AI's computer vision. This is a fast, lightweight endpoint that returns a boolean `detected` flag and a `count` of cards found — without identifying or cataloging them. Use this as a pre-filter before calling the heavier identification endpoint, or to validate that user-uploaded images contain cards. This endpoint is free and does not count toward your monthly API usage.

## Endpoint Details
- **URL**: POST `https://api.cardsight.ai/v1/detect/card`
- **Authentication**: API Key required (X-Api-Key header)
- **Content-Type**: `multipart/form-data` or direct binary (`image/jpeg`, `image/png`, `image/webp`)

## Constraints
- **Maximum file size**: 20MB
- **Supported formats**: JPEG, PNG, WebP, HEIF, HEIC

## Using the CardSight AI SDK (Recommended)

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

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

// From a file path
const imageBuffer = fs.readFileSync('path/to/image.jpg')
const file = new File([imageBuffer], 'image.jpg', { type: 'image/jpeg' })

// Detect cards in the image
const response = await client.detect.card(file)

// Always check for errors
if (response.error) {
  console.error('Error:', response.error)
} else {
  console.log('Cards detected:', response.data.detected)    // true or false
  console.log('Card count:', response.data.count)            // 0, 1, 2, ...
  console.log('Request ID:', response.data.requestId)
  console.log('Processing Time:', response.data.processingTime, 'ms')

  if (response.data.detected) {
    console.log(`Found ${response.data.count} card(s) — ready for identification!`)

    // Optionally follow up with the identify endpoint
    const identifyResponse = await client.identify.card(file)
    // ... process identification results
  }
}
```

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

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

# From a file path
with open('path/to/image.jpg', 'rb') as f:
    response = client.detect.card(f)

print(f"Cards detected: {response.detected}")     # True or False
print(f"Card count: {response.count}")             # 0, 1, 2, ...
print(f"Request ID: {response.request_id}")
print(f"Processing Time: {response.processing_time}ms")

if response.detected:
    print(f"Found {response.count} card(s)!")
```

## Direct API Call (cURL)

```bash
curl -X POST "https://api.cardsight.ai/v1/detect/card" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@path/to/image.jpg"
```

## Example Response (Cards Detected)
```json
{
  "detected": true,
  "count": 2,
  "requestId": "98cc3c7d-09a1-4433-aa9a-1939a419d411",
  "processingTime": 342
}
```

## Example Response (No Cards Detected)
```json
{
  "detected": false,
  "count": 0,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "processingTime": 198
}
```

## Response Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| detected | boolean | Yes | Whether one or more trading cards were detected in the image |
| count | number | Yes | Number of trading cards detected in the image (0 if none) |
| requestId | string | Yes | Unique identifier for tracking this detection request |
| processingTime | number | Yes | Total processing time in milliseconds |

## Detect vs Identify

| Aspect | Detect (`/v1/detect/card`) | Identify (`/v1/identify/card`) |
|--------|---------------------------|-------------------------------|
| Purpose | Check if cards are present | Full AI card identification |
| Returns card details | No | Yes (name, set, release, etc.) |
| Returns confidence | No | Yes (High/Medium/Low) |
| Speed | Faster (typically <500ms) | Slower (typically 1-3 seconds) |
| Cost | Free — no usage charge | Counts toward monthly usage |
| Use case | Pre-filtering, validation | Full card identification |

## Common Use Cases
- Pre-filter images before running the more expensive identification endpoint
- Validate user uploads contain cards before processing
- Build quick card-scanning workflows with instant feedback
- Count cards in batch image processing pipelines
- Gate access to identification features based on card presence

## Tips for AI Assistants
- The SDK returns `{ data, error }` — always check for errors first
- The response is very simple: just `detected` (boolean) and `count` (number)
- This endpoint is **free** — it does not count toward the user's monthly API usage
- Use this as a pre-check before calling `client.identify.card()` to save API calls
- There are no sport-specific variants — detection works across all card types
- `count` will be 0 when `detected` is false
- `processingTime` is in milliseconds — detection is typically very fast (<500ms)
- Use `requestId` for debugging and support requests
- Compress large images before uploading for faster processing
- The detect endpoint does NOT return any card identification data — use the identify endpoint for that