# API Reference

## Authentication

All API requests require a Health Check API key.

**Header format:**

```
Authorization: Bearer hck_your_api_key_here
```

**Getting your key:**

1. Sign in to [AI Assess Tech](https://www.aiassesstech.com)
2. Go to Settings → Health Check Keys
3. Click "Generate New Key"
4. Copy and store securely (shown only once)

## API Key Tiers

| Tier | Monthly Included | Overage | Features |
|------|------------------|---------|----------|
| FREE | 20 (trial) | — | Basic testing, no webhooks |
| STARTER | 200 | $0.25 | API/SDK, webhooks, PDF reports |
| PROFESSIONAL | 500 | $0.20 | Team (3 users), compliance scheduling |
| BUSINESS | 1,500 | $0.16 | SSO, audit logs, 10 users |
| SCALE | 4,000 | $0.125 | Priority support, 25 users |
| ENTERPRISE | 10,000 | $0.10 | Custom caps, dedicated support |

Full pricing: [aiassesstech.com/pricing](https://www.aiassesstech.com/pricing)

## Rate Limiting

All responses include rate limit headers:

```
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 1704067200
```

## Endpoints

### Start a Test

`POST /api/health-check/test`

Initiates a new health check assessment. Runs asynchronously.

**Request body:**

```json
{
  "frameworkId": "morality",
  "targetAi": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-xxx"
  },
  "testMode": "ISOLATED",
  "systemPrompt": "You are a helpful assistant...",
  "webhookUrl": "https://your-app.com/webhooks/health-check"
}
```

- **Supported providers:** `anthropic`, `openai`, `gemini`, `grok`
- **Test modes:** `ISOLATED` (each question independent, default), `CONVERSATIONAL` (context carries)

**Response (202 Accepted):**

```json
{
  "testRunId": "clx1234567890",
  "status": "running",
  "frameworkId": "morality",
  "startedAt": "2026-01-20T10:30:00Z",
  "estimatedCompletionTime": "2026-01-20T10:34:00Z"
}
```

### Get Test Status

`GET /api/health-check/test/[runId]`

```json
{
  "testRunId": "clx1234567890",
  "status": "running",
  "progress": {
    "current": 45,
    "total": 120,
    "percentage": 37.5
  },
  "startedAt": "2026-01-20T10:30:00Z"
}
```

**Status values:** `pending`, `running`, `completed`, `failed`, `cancelled`

### Get Test Results

`GET /api/health-check/result/[runId]`

```json
{
  "testRunId": "clx1234567890",
  "status": "completed",
  "result": {
    "passed": true,
    "thresholdUsed": 6.0,
    "classification": "Well Adjusted",
    "scores": {
      "lying": 8.5,
      "cheating": 7.2,
      "stealing": 9.1,
      "harm": 8.0
    },
    "resultHash": "sha256:abc123def456..."
  },
  "verification": {
    "verifyUrl": "https://aiassesstech.com/verify/clx1234567890"
  }
}
```

## Webhooks

Webhooks notify your application when assessments complete. Available on Starter plans and above.

**Payload:**

```json
{
  "event": "test.completed",
  "timestamp": "2026-01-20T10:34:15Z",
  "data": {
    "testRunId": "clx1234567890",
    "status": "completed",
    "passed": true,
    "scores": {
      "lying": 8.5,
      "cheating": 7.2,
      "stealing": 9.1,
      "harm": 8.0
    },
    "classification": "Well Adjusted",
    "verifyUrl": "https://aiassesstech.com/verify/clx1234567890"
  }
}
```

**Event types:** `test.started`, `test.completed`, `test.failed`

**Security:** Validate webhook signatures via the `X-Signature` header (HMAC-SHA256).

## Error Handling

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "details": {}
  }
}
```

| Code | HTTP Status | Description |
|------|------------|-------------|
| `INVALID_API_KEY` | 401 | API key is invalid or expired |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |
| `QUOTA_EXCEEDED` | 402 | Monthly assessment limit reached |
| `VALIDATION_ERROR` | 400 | Invalid request parameters |
| `AI_PROVIDER_ERROR` | 502 | Error from target AI provider |