# CodingVibez API - AI Quick Reference

> Track AI token usage, costs, and expenses across OpenAI, Anthropic, Google, and more.

## Authentication
All endpoints require Supabase JWT in Authorization header:
`Authorization: Bearer <supabase-access-token>`

## Base URL
`https://your-domain.com`

---

## Token Tracking

### Track Usage (POST /api/tokens/track)
```json
{
  "provider": "openai|anthropic|google",
  "model": "gpt-4-turbo",
  "inputTokens": 1000,
  "outputTokens": 500,
  "cachedTokens": 0,
  "cost": 0.05,
  "flush": true
}
```
Response: `{ success: true, data: { id, provider, model, inputTokens, outputTokens, cost, timestamp } }`

### Get Usage (GET /api/tokens)
Query: `?billingStartDate=2026-01-01&billingEndDate=2026-01-31`
Response: `{ success: true, data: { tokens: [...], lastUpdated, dataFreshness, billingPeriod } }`

### Get Stats (GET /api/tokens/stats)
Query: `?provider=openai`
Response: `{ success: true, data: { budget: { limit, used, remaining }, projections: { endOfMonth, trend }, usage: { totalTokens, totalCost } } }`

### Get Timeseries (GET /api/tokens/timeseries)
Query: `?startDate=2026-01-01&endDate=2026-01-29`
Response: `{ success: true, data: { series: [{ date, totalTokens, cost }], aggregations } }`

### Get Burn Rate (GET /api/tokens/burn-rate)
Query: `?hours=24&service=openai`
Response: `{ success: true, data: { burnRate: { tokensPerHour, costPerHour, tokensPerDay, costPerDay }, byService } }`

---

## Cost Management

### Get Provider Costs (GET /api/costs/{provider})
Providers: openai, anthropic, google, aws, gcp, azure, vercel, supabase, cursor, github, lovable, kiro, replit
Query: `?month=1&year=2026`
Response: `{ success: true, data: { service, currentMonth, previousMonth, breakdown: { model: cost }, tokenUsage, dataFreshness } }`

### Get All Costs (GET /api/costs/all)
Query: `?month=1&year=2026`
Response: `{ success: true, data: { total, byProvider: { provider: cost }, comparison: { previousMonth, changePercent } } }`

### Add Manual Cost (POST /api/costs/manual)
```json
{
  "service": "OpenAI",
  "amount": 50.00,
  "month": 1,
  "year": 2026,
  "category": "API Calls",
  "description": "Monthly subscription"
}
```

---

## Sync & Import

### Sync All (POST /api/sync)
```json
{ "providers": ["openai", "anthropic"], "force": false }
```
Response: `{ success: true, data: { results: { provider: { status, records } }, syncedAt } }`

### Sync Org Usage (POST /api/sync-organization-usage)
Requires admin API keys for OpenAI/Anthropic.
```json
{ "service": "openai", "force": false }
```

---

## Dashboard & Analytics

### Get Dashboard (GET /api/dashboard)
Response: `{ success: true, data: { totalCosts: { currentMonth, previousMonth }, tokenUsage, topModels, budgetStatus, alerts } }`

### Get Analytics (GET /api/analytics)
Query: `?startDate=2026-01-01&endDate=2026-01-29&groupBy=day`
Response: `{ success: true, data: { series: [{ date, cost, tokens, requests }], totals, averages } }`

### Get Projections (GET /api/projections)
Response: `{ success: true, data: { endOfMonth: { estimatedCost, confidence }, budgetImpact: { willExceedBudget } } }`

---

## Health & Status

### Health Check (GET /api/health)
Public, no auth required.
Response: `{ success: true, data: { status: "healthy", database: { healthy: true }, services } }`

### Tracking Health (GET /api/tracking-health)
Response: `{ success: true, data: { status, buffer: { size, lastFlush }, dataFreshness, errors } }`

### Integration Status (GET /api/status)
Response: `{ success: true, data: { integrations: { openai: { connected, lastSync, status } } } }`

---

## Team & Billing

### Get Organizations (GET /api/organizations)
### Get Team Members (GET /api/team/members)
### Invite Member (POST /api/team/invitations)
```json
{ "email": "user@example.com", "role": "member" }
```

### Subscription Status (GET /api/subscription-status)
### Create Checkout (POST /api/checkout)
```json
{ "priceId": "price_xxx", "successUrl": "https://...", "cancelUrl": "https://..." }
```

### Billing History (GET /api/billing-history)

---

## Expenses

### List Expenses (GET /api/expenses)
Query: `?startDate=2026-01-01&endDate=2026-01-31`

### Create Expense (POST /api/expenses)
```json
{ "amount": 150, "currency": "USD", "vendor": "OpenAI", "date": "2026-01-15", "category": "Software" }
```

### OCR Receipt (POST /api/receipts/ocr)
Content-Type: multipart/form-data, field: file

---

## Response Format

Success: `{ success: true, data: {...}, timestamp, requestId }`
Error: `{ success: false, error: "message", code: "ERROR_CODE", requestId }`

Error codes: VALIDATION_ERROR, AUTHENTICATION_ERROR, AUTHORIZATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, INTEGRATION_ERROR, DATABASE_ERROR, INTERNAL_ERROR

HTTP codes: 200 OK, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Rate Limited, 500 Server Error

---

## Quick Integration (TypeScript)

```typescript
class CodingVibez {
  constructor(private baseUrl: string, private token: string) {}

  private headers = () => ({
    'Authorization': `Bearer ${this.token}`,
    'Content-Type': 'application/json'
  });

  async track(provider: string, model: string, inputTokens: number, outputTokens: number) {
    return fetch(`${this.baseUrl}/api/tokens/track`, {
      method: 'POST',
      headers: this.headers(),
      body: JSON.stringify({ provider, model, inputTokens, outputTokens, flush: true })
    }).then(r => r.json());
  }

  async getCosts(provider: string, month: number, year: number) {
    return fetch(`${this.baseUrl}/api/costs/${provider}?month=${month}&year=${year}`, {
      headers: this.headers()
    }).then(r => r.json());
  }

  async getDashboard() {
    return fetch(`${this.baseUrl}/api/dashboard`, { headers: this.headers() }).then(r => r.json());
  }
}

// Usage
const cv = new CodingVibez('https://your-domain.com', 'supabase-token');
await cv.track('openai', 'gpt-4-turbo', 1000, 500);
```

---

## OpenAI Integration

```typescript
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: 'sk-...' });
const cv = new CodingVibez(baseUrl, token);

const response = await openai.chat.completions.create({
  model: 'gpt-4-turbo',
  messages: [{ role: 'user', content: 'Hello' }]
});

// Track usage
if (response.usage) {
  await cv.track('openai', 'gpt-4-turbo', response.usage.prompt_tokens, response.usage.completion_tokens);
}
```

---

## Anthropic Integration

```typescript
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({ apiKey: 'sk-ant-...' });
const cv = new CodingVibez(baseUrl, token);

const response = await anthropic.messages.create({
  model: 'claude-3-opus-20240229',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello' }]
});

// Track usage
await cv.track('anthropic', 'claude-3-opus-20240229', response.usage.input_tokens, response.usage.output_tokens);
```

---

## Data Freshness
- fresh: <15 minutes old
- stale: 15-60 minutes old
- very_stale: >60 minutes old
- no_data: no records found

## Rate Limits
- GET: 100/min
- POST: 30/min
- Sync: 10/min
- Upload: 5/min

Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

---

## Files
- Full docs: /public/api-docs.md
- OpenAPI spec: /public/openapi.json
- This file: /public/llms.txt