# Documentation β AuCore
> How to get an AuCore API key and use it: authentication, models, chat completions, streaming, token optimization and error handling.
Source: https://ai.aunuhost.bond/docs
Documentation
# Getting started
AuCore exposes one OpenAI-compatible API for every model in the catalog.
If your code already talks to OpenAI, you only need to change two values.
AI API β Base URL
This is the value you set as `base_url` in the OpenAI SDK (or any
compatible client). Both and resolve.
## 1. Get a key
1. Choose a plan on the [pricing page](https://ai.aunuhost.bond/plan).
2. Request access on the [support page](https://ai.aunuhost.bond/support), naming your plan.
3. AuCore issues your key and sends it to you.
4. Redeem it at [/login](https://ai.aunuhost.bond/login). Your [dashboard](https://ai.aunuhost.bond/client) then shows the key, base URL and analytics.
Keys look like `auc_live_a1b2c3d4e5f6g7h8`. They are account-scoped, rotatable and revocable at any time.
## 2. Two APIs β which one do I use?
AuCore runs **two independent API planes**, each with its own key type, base URL and quota system. Pick the one that matches what you're building:
| | π€ AI API (this page) | π§° REST API Toolkit ([catalog](https://ai.aunuhost.bond/restapi)) |
| --- |--- |--- |
| **What it does** | Chat completions, embeddings, moderations, media generation β the OpenAI-compatible inference surface | 580+ utility endpoints: Islamic tools, web scraping, anime, finance, crypto, QR codes, weather, security, and more |
| **Key prefix** | `auc_live_β¦` / `auc_premier_β¦` / `auc_platinum_β¦` / `auc_free_β¦` | `auc_rest_β¦` |
| **Base URL** | (same origin β this page's domain) | https://api.fallsad.biz.id/api |
| **Auth** | Bearer token in `Authorization` header | `?key=β¦` query param, `x-api-key` header, or Bearer |
| **Quota** | RPM + daily requests by plan (Free β Platinum) | 5 calls/day free (admin-adjustable per key) |
| **Key source** | Issued by AuCore after plan purchase, or Google sign-in (free) | Issued from the admin dashboard (API keys tab) |
| **Use it for** | Chatbots, RAG, agents, code generation, summarization, image/video generation | Utility microservices: prayer times, weather, currency, QR, short links, anime search⦠|
**Rule of thumb:** if you're calling a model (GPT, Claude, Gemini, Llamaβ¦), use the **AI API** with your `auc_live_` key. If you're calling a utility endpoint (weather, QR, prayer timesβ¦), use the **REST API Toolkit** with your `auc_rest_` key. They never mix β a `auc_rest_` key cannot call chat completions, and a `auc_live_` key cannot call toolkit features.
## 3. Authenticate
Send your key as a bearer token on every request.
```
Authorization: Bearer auc_live_a1b2c3d4e5f6g7h8
Content-Type: application/json
```
| Status | Meaning |
| --- |--- |
| `401` | Key missing or unknown |
| `403` | Key revoked or expired, or model above your plan |
| `429` | Rate or daily budget exceeded |
## 4. List models
```
curl /models \
-H "Authorization: Bearer $AUCORE_KEY"
```
```
{
"object": "list",
"data": [
{
"id": "aucore-router-auto",
"owned_by": "Anthropic",
"context_window": 1000000,
"modalities": ["text", "vision", "tools"],
"min_plan": "premier",
"available": true
}
]
}
```
`available` reflects your own plan, so you can filter the catalog client-side.
## 5. Chat completions
```
curl /chat/completions \
-H "Authorization: Bearer $AUCORE_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "aucore-router-auto",
"messages": [
{"role": "system", "content": "You are concise."},
{"role": "user", "content": "What is retrieval augmented generation?"}
],
"temperature": 0.7,
"max_tokens": 1024
}'
```
**Response**
```
{
"id": "chatcmpl_aucore_8f2aβ¦",
"object": "chat.completion",
"model": "aucore-router-auto",
"choices": [{
"index": 0,
"message": {"role": "assistant", "content": "RAG isβ¦"},
"finish_reason": "stop"
}],
"usage": {"prompt_tokens": 24, "completion_tokens": 148, "total_tokens": 172}
}
```
### Parameters
| Field | Type | Notes |
| --- |--- |--- |
| `model` | string | Required. Any ID from the catalog. |
| `messages` | array | Required. Roles: system, user, assistant. |
| `temperature` | number | 0β2. Default 1. |
| `max_tokens` | integer | Capped at 32,000. |
| `top_p` | number | Nucleus sampling. |
| `stream` | boolean | Server-sent events when true. |
| `tools` | array | Premier and Platinum only. |
## 6. Streaming
Set `"stream": true` and read server-sent events. Each chunk is a `data:` line, ending with `data: [DONE]`.
```
data: {"choices":[{"delta":{"content":"RAG"}}]}
data: {"choices":[{"delta":{"content":" combines"}}]}
data: [DONE]
```
```
// Node.js β stream with the OpenAI SDK
const stream = await client.chat.completions.create({
model: "aucore-router-auto",
messages: [{ role: "user", content: "Write a haiku" }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```
## 7. Automatic model selection
Send `aucore-router-auto` as the model and AuCore chooses the cheapest model capable of handling the prompt: short prompts go to a fast small model, code-heavy or long prompts escalate automatically.
```
{
"model": "aucore-router-auto",
"messages": [{"role": "user", "content": "Summarise this in one line: β¦"}]
}
```
## 8. Use an existing SDK
```
# Python
from openai import OpenAI
client = OpenAI(base_url=, api_key=os.environ["AUCORE_KEY"])
r = client.chat.completions.create(
model="aucore-router-auto",
messages=[{"role": "user", "content": "Hello"}],
)
print(r.choices[0].message.content)
```
LangChain, LlamaIndex, the AI SDK and anything else that accepts a custom base URL work the same way. `/v1` is accepted as an alias, so `β¦/api/v1` and `β¦/api` both resolve.
## 9. Token optimization
Every request passes through the AuCore token minimizer before it reaches a model provider. Whitespace is normalized, oversized histories are windowed to fit your plan's context budget, and bloated tool results are capped β typically saving 15β40% of input tokens on long conversations, which makes free-tier quotas last dramatically longer.
- Automatic by default; nothing to configure.
- Add `"optimize": "aggressive"` to the request body for deeper compression (strips filler phrases).
- Check the savings in every response: headers `X-AuCore-Tokens-In` / `X-AuCore-Tokens-Saved`, or the `aucore.tokens_minimized` field.
## 10. Rate limits
| Plan | Per minute | Per day | Context | Weight |
| --- |--- |--- |--- |--- |
| Basic | 20 | 1,500 | 64K | 1Γ |
| Premier | 60 | 6,000 | 200K | 3Γ |
| Platinum | 180 | 25,000 | 1M | 9Γ |
Every response includes limit headers:
```
X-AuCore-Plan: platinum
X-RateLimit-Limit: 180
X-RateLimit-Remaining: 174
X-RateLimit-Reset: 1786000060
X-RateLimit-Daily-Remaining: 24985
```
## 11. Errors
```
{
"error": {
"type": "rate_limit_exceeded",
"message": "Daily request budget reached for plan basic.",
"code": 429,
"retry_after": 41,
"reset_at": "2026-08-17T00:00:00.000Z"
}
}
```
Retry `429` and `502` with exponential backoff plus jitter. Never retry `400` or `403` without changing the request.
## 12. Account management & support
Beyond chat, the gateway exposes account endpoints for everything the dashboard does β all with the same Bearer key.
### Profile & usage
```
PATCH /account/profile # update your name / email
GET /account/history?days=30 # daily request series (max 90 days)
GET /account/requests?limit=50 # recent request log (metadata only)
```
### Secondary keys
Mint up to five named keys for separate projects. They authenticate as your account with the same plan limits and can be revoked independently β no need to share the master key.
```
POST /account/keys # { "name": "chatbot-prod" } β key shown once
GET /account/keys # list every secondary key
DELETE /account/keys/:id # revoke one key instantly
```
### Webhooks
Register up to three HTTPS endpoints and AuCore POSTs events to them: `usage.daily`, `quota.warn` (β₯80% of the daily budget) and `key.rotate`.
```
POST /account/webhooks # { "url": "https://your.app/hook", "events": ["usage.daily"] }
GET /account/webhooks # list registered webhooks
DELETE /account/webhooks/:id
```
### Support & subscribe
```
POST /support # { name, email, topic, message, consent: true }
POST /subscribe # { email } β product updates by email
```
Support requests **require** `consent: true` (the checkbox on the [support form](https://ai.aunuhost.bond/support)) and a valid email β replies are sent there by our email plane. Subscribers receive feature updates and promos; unsubscribe by contacting support.
## 13. Good practice
- Keep keys on your server; have your own backend call AuCore.
- Rotate immediately if a key may have leaked β old keys stop working at once.
- Set `max_tokens` deliberately; it is the simplest cost control you have.
- Use `aucore-router-auto` when quality requirements vary per request.
- Log the `id` from responses so support can trace a specific call.
## 14. Official SDK
The AuCore SDK is a zero-dependency JavaScript client that works everywhere β Node.js 18+, browsers, Deno, Bun, and edge runtimes. No npm install needed β download it directly:
**Download the SDK**
Single file, ~8 KB, zero dependencies
[Download .mjs](https://ai.aunuhost.bond/assets/sdk/aucore-sdk.mjs)
### Quick start
```
// Node.js / Deno / Bun / edge β import the downloaded file
import AuCore from "./aucore-sdk.mjs";
const ai = new AuCore({ apiKey: "auc_live_β¦" });
// Chat completion
const res = await ai.chat.create({
model: "aucore-router-auto",
messages: [{ role: "user", content: "Hello!" }]
});
console.log(res.choices[0].message.content);
// Streaming
const stream = await ai.chat.create({ messages: [β¦], stream: true });
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
// REST toolkit (separate key)
const rest = new AuCore({ restKey: "auc_rest_β¦" });
const weather = await rest.rest.call("info/weather", { city: "Jakarta" });
```
### Browser usage (no build step)
In a browser, add a `type="module"` script tag that imports the SDK from this site's CDN at
`/assets/sdk/aucore-sdk.mjs`, then instantiate `new AuCore({ apiKey: "auc_live_β¦" })`
and call `ai.chat.create()` β the same API as the Node.js example above.
**How it works:** the SDK is a single ES module that wraps the same REST API you'd call with `fetch`. It adds automatic retry on 429/5xx, request timeouts, typed errors, and a clean API surface (`ai.chat.create()`, `ai.rest.call()`). Since it's zero-dependency, you can copy the file into any project β no package manager needed. If you prefer npm, run `npm publish` from the `sdk/` folder after setting up an npm account.
## 15. REST API Toolkit β quick reference
The toolkit is a separate plane with its own base URL and key. Full interactive catalog at [/restapi](https://ai.aunuhost.bond/restapi).
```
# call any toolkit feature with your auc_rest_ key
curl "https://api.fallsad.biz.id/api/islamic/prayer-times?lat=-6.2&lon=106.8&key=auc_rest_β¦"
curl "https://api.fallsad.biz.id/api/info/weather?city=Jakarta&key=auc_rest_β¦"
curl "https://api.fallsad.biz.id/api/tools/qr-code?text=hello&key=auc_rest_β¦"
```
Every response carries rate-limit headers (`X-RateLimit-Limit`, `-Remaining`, `-Reset`) so you can track your quota client-side. Check `GET /me` for a full usage report.
---
Need something not covered here? See the [full API reference](https://ai.aunuhost.bond/reference),
the [FAQ](https://ai.aunuhost.bond/faq), or [contact support](https://ai.aunuhost.bond/support).