API QUICKSTART · V1

Make your first request.

Aethel provides an OpenAI-compatible chat completions route with customer API keys, a daily request quota, and persistent usage records.

V1 is a private API pilot. It is not a self-serve paid launch. Aethel does not charge customers yet; provider usage is billed to the operator’s provider accounts. The primary provider’s rate limits still apply. An optional Groq fallback retries mapped requests after an HTTP 429 response.

1. Configure the service

Create a Supabase project and run supabase/migrations/202610230001_aethel_gateway.sql in the Supabase SQL Editor.
Add the variables from .env.example to the Vercel project. Use your Supabase project URL and server-only secret key (SUPABASE_SECRET_KEY), a provider API key, and a long random AETHEL_ADMIN_KEY. Keep these secrets server-side.
Set AETHEL_ALLOWED_MODELS to the comma-separated models enabled for your provider account. The default is gpt-4o-mini.
Redeploy, then confirm /api/health reports ready.

2. Optional: configure Groq fallback

The fallback code can route a primary HTTP 429 to Groq when the request model has a configured mapping. Production currently has this fallback enabled. For another deployment, set GROQ_API_KEY, AETHEL_ENABLE_GROQ_FALLBACK=true, and AETHEL_GROQ_MODEL_MAP, then redeploy. A fallback request may incur charges on the Groq account. The default mapping is gpt-4o-mini → openai/gpt-oss-20b.

3. Create a customer key

Run this from a trusted terminal. The admin key authorizes key creation. The generated customer key is returned once; store it securely.

curl -X POST https://www.aethelai.online/api/v1/keys \
  -H "X-Aethel-Admin-Key: $AETHEL_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-app"}'

Save the returned api_key as AETHEL_API_KEY in your application’s server-side secrets. The database stores only its SHA-256 hash. Never put the admin key, provider key, or customer key in frontend code.

4. Send a chat completion

curl https://www.aethelai.online/api/v1/chat/completions \
  -H "Authorization: Bearer $AETHEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role":"user","content":"Hello from Aethel"}]
  }'

The response follows the OpenAI chat completion shape. The gateway records the request status and token counts returned by the upstream provider. The default limit is 100 attempted requests per UTC day per key; provider errors also count. Set AETHEL_DAILY_REQUEST_LIMIT to change it. Output is capped at 2,048 tokens by default; configure AETHEL_MAX_OUTPUT_TOKENS to adjust that ceiling.

Routes and current boundaries

`GET`	`/api/health`	Service and dependency readiness
`POST`	`/api/v1/keys`	Create a customer key (admin secret required)
`POST`	`/api/v1/keys/revoke`	Disable a customer key using its ID from the JSON body (admin secret required)
`POST`	`/api/v1/chat/completions`	Authenticated, non-streaming chat completion

Streaming, payment collection, refunds, and distributed GPU execution are not implemented in this first release. Provider fallback is limited to a Groq retry after a primary HTTP 429, and requires the feature flag and a model mapping. Upstream usage and costs are charged by the configured provider account.