# Using the CardSight AI API - Health API

## Overview
Check the health and status of the CardSight AI service. Use these endpoints to verify connectivity, validate API keys, and monitor service dependencies.

## Endpoint Details
- **Base URL**: `https://api.cardsight.ai`
- **Authentication**: Varies by endpoint (see below)

## Endpoints

| Method | URL | Auth Required | Description |
|--------|-----|---------------|-------------|
| GET | /health | No | Basic health check - verify the API is online |
| GET | /health/auth | Yes | Authenticated health check - validate your API key |
| GET | /health/detailed | Yes | Detailed health check - includes dependency status |

## Using the CardSight AI SDK (Recommended)

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

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

// Basic health check (no auth needed)
const basicHealth = await client.health.check()

if (basicHealth.error) {
  console.error('API is unreachable:', basicHealth.error)
} else {
  console.log('Status:', basicHealth.data.status)
  console.log('Timestamp:', basicHealth.data.timestamp)
}

// Authenticated health check - validates your API key
const authHealth = await client.health.auth()

if (authHealth.error) {
  console.error('API key is invalid:', authHealth.error)
} else {
  console.log('API key is valid!')
  console.log('Status:', authHealth.data.status)
}

// Detailed health check - includes dependency status
const detailedHealth = await client.health.detailed()

if (!detailedHealth.error) {
  console.log('Overall Status:', detailedHealth.data.status)
  console.log('Checks:', detailedHealth.data.checks)

  // Check individual dependencies
  for (const [name, check] of Object.entries(detailedHealth.data.checks)) {
    console.log(`  ${name}: ${check.status} (${check.responseTime}ms)`)
  }
}
```

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

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

# Basic health check
basic = client.health.check()
print(f"Status: {basic.status}")

# Authenticated health check - validates API key
auth = client.health.auth()
print(f"API key valid: {auth.status == 'healthy'}")

# Detailed health check
detailed = client.health.detailed()
print(f"Overall: {detailed.status}")
for name, check in detailed.checks.items():
    print(f"  {name}: {check.status}")
```

## Direct API Calls (cURL)

```bash
# Basic health check (no API key needed)
curl -X GET "https://api.cardsight.ai/health"

# Authenticated health check (validates your API key)
curl -X GET "https://api.cardsight.ai/health/auth" \
  -H "X-Api-Key: your-api-key"

# Detailed health check (requires API key)
curl -X GET "https://api.cardsight.ai/health/detailed" \
  -H "X-Api-Key: your-api-key"
```

## Example Responses

### Basic Health Check (/health)
```json
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z"
}
```

### Authenticated Health Check (/health/auth)
```json
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z"
}
```

### Detailed Health Check (/health/detailed)
```json
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "checks": {
    "database": {
      "status": "healthy",
      "message": "Connected",
      "responseTime": 5
    },
    "redis": {
      "status": "healthy",
      "message": "Connected",
      "responseTime": 2
    }
  }
}
```

## Response Fields

### BasicHealthResponse (for /health and /health/auth)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| status | string | Yes | Overall health status (e.g., "healthy") |
| timestamp | string | Yes | ISO 8601 timestamp when check was performed |

### DetailedHealthResponse (for /health/detailed)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| status | string | Yes | Overall status: "healthy", "degraded", or "unhealthy" |
| timestamp | string | Yes | ISO 8601 timestamp when check was performed |
| checks | object | Yes | Health status of individual dependencies |

### Check Object (within checks)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| status | string | Yes | "healthy" or "unhealthy" |
| message | string | No | Description of the health status |
| responseTime | number | No | Response time in milliseconds |

### Status Values

| Status | Description |
|--------|-------------|
| healthy | All systems operational |
| degraded | Some non-critical dependencies down (detailed only) |
| unhealthy | Critical dependencies down |

## Common Use Cases
- Verify the API is online before making requests
- Validate that your API key is correctly configured
- Build monitoring dashboards for API health
- Troubleshoot connectivity issues
- Check dependency status (database, cache, etc.)

## Tips for AI Assistants
- The SDK returns `{ data, error }` - always check for errors first
- Use `/health` (no auth) to check if the API is reachable
- Use `/health/auth` to validate your API key is working
- Use `/health/detailed` to diagnose issues with specific dependencies
- A 401 error on `/health/auth` means your API key is invalid
- The `/health` endpoint never requires authentication
- Response times in detailed checks help identify slow dependencies