API Reference: ai-api.sofe.dev

AI Engine API — handles explain, policy generation, model discovery, and provider routing.

Base URL

https://ai-api.sofe.dev

Authentication

Same credentials as api.sofe.dev — your SOFE API key or Firebase Bearer token.

AI Rate Limits (separate from evaluations)

TierAI calls/dayNote
Free5Each /explain or /generate-policy = 1 call
Pro100Sufficient for daily review
Enterprise1,000Bulk analysis

Endpoints (7)

POST/explain

AI-powered explanation of a finding (calls user's configured provider)

Auth: API key or Bearer

POST/generate-policy

Generate SOFE policy YAML from natural language description

Auth: API key or Bearer

POST/test

Test AI provider connection (sends hello prompt)

Auth: API key or Bearer

GET/models?provider=X

List available models for a provider (dynamic, fetched from provider API)

Auth: API key or Bearer

GET/usage

AI usage stats for current day (calls_today)

Auth: API key or Bearer

GET/providers

List all supported AI providers with auth type + free tier info

Auth: None (public)

GET/health

Status check

Auth: None (public)

Example: Explain a Finding

curl -X POST https://ai-api.sofe.dev/explain \
  -H "X-API-Key: sk_sofe_xxx" \
  -H "Content-Type: application/json" \
  -d '{"finding": {"policy_name": "require-cost-tags", "severity": "medium", "resource_id": "my-lambda", "message": "missing owner tag"}}'

# Response:
{
  "explanation": "**Why this matters:** ...",
  "provider": "openrouter",
  "model": "meta-llama/llama-3.3-70b-instruct:free",
  "latency_ms": 4200,
  "remaining": 94
}

Example: Generate Policy

curl -X POST https://ai-api.sofe.dev/generate-policy \
  -H "X-API-Key: sk_sofe_xxx" \
  -H "Content-Type: application/json" \
  -d '{"description": "alert when S3 buckets dont have encryption"}'

# Response:
{
  "policy_yaml": "apiVersion: sofe/v1\nkind: Policy\n...",
  "generated": true,
  "provider": "openrouter",
  "model": "anthropic/claude-sonnet-5",
  "latency_ms": 3920,
  "attempts": 1
}