Authentication

All API requests (except health check) require authentication.

Getting Your API Key

1. Sign in at agent-heavy.vercel.app/dashboard
2. Go to Keys and click Create New Key
3. Store the key securely — it's shown only once

API keys start with ck_ and are managed via Unkey. Each key has its own rate limit enforced server-side.

Authentication Methods

Bearer Token (Recommended)

curl https://agent-heavy.vercel.app/api/v1/chat/completions \
  -H "Authorization: Bearer ck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt", "messages": [{"role": "user", "content": "Hello"}]}'

X-API-Key Header

curl https://agent-heavy.vercel.app/api/chat \
  -H "X-API-Key: ck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "mode": "chat", "model": "claude"}'

Endpoint Authentication

Key Management API

Manage your API keys programmatically. These endpoints require dashboard authentication (Supabase session cookie).

Create Key

POST /api/v1/keys

{
  "name": "Production Key",
  "rateLimit": 100
}

Response (201):

{
  "success": true,
  "data": {
    "keyId": "key_abc123",
    "key": "ck_full_key_shown_only_once",
    "name": "Production Key"
  }
}

List Keys

GET /api/v1/keys

Returns all your keys (masked — metadata only, never the full key).

Update Key

PATCH /api/v1/keys/:id

{
  "name": "Renamed Key",
  "rateLimit": 200,
  "enabled": true
}

Revoke Key

DELETE /api/v1/keys/:id

Permanently revokes a key. Returns 204.

Provider Keys (BYOK)

Store your own provider API keys so gateway requests use your key instead of the platform key. Keys are encrypted at rest with AES-256-GCM.

Store Provider Key

POST /api/v1/provider-keys

{
  "provider": "openai",
  "slug": "my-openai-key",
  "displayName": "My OpenAI Key",
  "apiKey": "sk-..."
}

Supported providers: openai, anthropic, google, x-ai, openrouter, minimax.

List Provider Keys

GET /api/v1/provider-keys

Returns stored keys (masked — only last 4 characters shown).

Remove Provider Key

DELETE /api/v1/provider-keys/:id

Returns 204.

Usage Analytics

GET /api/v1/usage?from=2026-03-01&to=2026-03-21

Returns request volume, token usage, and estimated costs broken down by model.

{
  "success": true,
  "data": {
    "totalRequests": 142,
    "totalTokens": 85000,
    "totalCost": 0.47,
    "byModel": {
      "claude-sonnet-4-5-20250929": { "requests": 45, "tokens": 28000, "cost": 0.18 },
      "gpt-5.2": { "requests": 52, "tokens": 31000, "cost": 0.15 }
    }
  }
}