Quickstart
A five-minute path from zero to a streaming chat completion through the Aetherin API. Every call below maps to an operation in `../openapi/openapi.yaml` (../openapi/openapi.yaml).
1. Base URL and auth modes
All routes are under /v1:
export AETHERIN_API="https://api.example.com/v1" # your deploymentThere are two credentials, for two different audiences:
| Mode | Credential | Used by | Sent as |
|---|---|---|---|
| Operator | session cookie | the dashboard / admin UI | Cookie: session=… (set by POST /auth/login) |
| Client | API key (sk-aetherin-…) | apps, agents, SDKs | Authorization: Bearer sk-aetherin-… |
Client keys are scoped to a workspace and carry a monthly budget and an RPM limit. Provider credentials never leave the server.
2. Log in (operator)
curl -sS -c cookies.txt -X POST "$AETHERIN_API/auth/login" \
-H 'content-type: application/json' \
-d '{"email":"admin@example.com","password":"…"}'The response contains your user and organizations and sets the session cookie. -c cookies.txt stores it; later operator calls use -b cookies.txt.
Check the session at any time:
curl -sS -b cookies.txt "$AETHERIN_API/auth/me"Logout clears the cookie:
curl -sS -b cookies.txt -c cookies.txt -X POST "$AETHERIN_API/auth/logout"3. Find a workspace and create a client key
ORG=org_01HXYZ
curl -sS -b cookies.txt "$AETHERIN_API/orgs/$ORG/workspaces"Create a key with a monthly budget and a rate limit. The plaintext key is returned once:
WORKSPACE=wsp_01HXYZ
curl -sS -b cookies.txt -X POST "$AETHERIN_API/keys" \
-H 'content-type: application/json' \
-d "{
\"workspace_id\": \"$WORKSPACE\",
\"name\": \"Backend\",
\"budget_usd_monthly\": 100,
\"rpm_limit\": 600
}"{
"id": "key_01HXYZ",
"prefix": "sk-aetherin-abc",
"key": "sk-aetherin-abc.DEFGHIJKLMNOPQRSTUVWXYZ",
"...": "…"
}Store key in your secret manager (never in git or a client bundle). If it leaks, POST /keys/{id}/rotate issues a replacement and revokes the old one.
4. List models
export AETHERIN_KEY="sk-aetherin-abc.DEFGHIJKLMNOPQRSTUVWXYZ"
curl -sS "$AETHERIN_API/models" -H "Authorization: Bearer $AETHERIN_KEY"The list is OpenAI-compatible ({"data":[{"id":"…"}],"has_more":false}). A model can have ordered fallback routes; see GET /models/{id}/routes.
5. Chat completion
Non-streaming:
curl -sS "$AETHERIN_API/chat/completions" \
-H "Authorization: Bearer $AETHERIN_KEY" \
-H 'content-type: application/json' \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role":"user","content":"Hello!"}]
}'Streaming (SSE) — note -N so curl does not buffer:
curl -sN "$AETHERIN_API/chat/completions" \
-H "Authorization: Bearer $AETHERIN_KEY" \
-H 'content-type: application/json' \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role":"user","content":"Hello!"}],
"stream": true
}'Each event is a chat.completion.chunk (data: {…}), terminated by data: [DONE]. Unknown request fields are rejected rather than silently dropped — remove vendor-specific fields you do not need.
6. Embeddings
curl -sS "$AETHERIN_API/embeddings" \
-H "Authorization: Bearer $AETHERIN_KEY" \
-H 'content-type: application/json' \
-d '{"model":"text-embedding-3-small","input":["hello","world"]}'7. Budgets, limits and errors
Every client request is metered. Two limits matter at runtime:
- Budget — when the key/workspace budget is exhausted the API returns
402 with code budget_exceeded. Budgets roll over monthly.
- Rate limit — exceeding the key's
rpm_limitreturns429with code
rate_limit_exceeded.
Errors always use the same envelope:
{
"error": {
"code": "budget_exceeded",
"message": "monthly budget exhausted",
"type": "payment_required",
"param": null,
"request_id": "req_01HXYZ"
}
}Branch on error.code, never on message. Quote request_id in support requests. The full table is in `ERROR_CODES.md`.
8. Usage
Per-key usage for the current month:
curl -sS "$AETHERIN_API/usage?workspace_id=$WORKSPACE" -b cookies.txtExport the raw events as CSV:
curl -sS -b cookies.txt \
"$AETHERIN_API/usage/export.csv?workspace_id=$WORKSPACE" \
-o usage.csv9. Pagination
List endpoints take limit (1–200, default 50) and an opaque cursor:
curl -sS "$AETHERIN_API/keys?limit=50" -b cookies.txt
# → { "data": [...], "next_cursor": "key_01HXYZ", "has_more": true }
curl -sS "$AETHERIN_API/keys?limit=50&cursor=key_01HXYZ" -b cookies.txtStop when has_more is false.
10. TypeScript
const res = await fetch(`${process.env.AETHERIN_API}/chat/completions`, {
method: "POST",
headers: {
authorization: `Bearer ${process.env.AETHERIN_KEY}`,
"content-type": "application/json",
},
body: JSON.stringify({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "Hello!" }],
stream: true,
}),
});
if (!res.ok) {
const { error } = await res.json();
throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
}
const reader = res.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";
for (;;) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
for (const line of buffer.split("\n")) {
if (!line.startsWith("data: ")) continue;
const data = line.slice(6).trim();
if (data === "[DONE]") return;
const chunk = JSON.parse(data);
process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
}
buffer = buffer.slice(buffer.lastIndexOf("\n") + 1);
}Generate a typed client instead of hand-writing types:
npm run generate:ts # → generated/api.tsNext steps
- Error codes
- API stability
- Full spec (../openapi/openapi.yaml)
- Streaming behind Vercel: the public middleware forwards
Set-Cookie, custom
headers, and SSE without buffering (see aetherin-middleware).