Blame
|
1 | # API Reference |
||||||
| 2 | ||||||||
|
3 | The public AeThex API is available at `https://api.aethex.tech`. Its current primary responsibility is the KAEL runtime and related identity, history, memory, document, feed, and integration services. |
||||||
|
4 | |||||||
|
5 | | Field | Value | |
||||||
| 6 | |---|---| |
|||||||
| 7 | | Product maturity | Live / evolving | |
|||||||
| 8 | | Documentation status | Active | |
|||||||
| 9 | | Runtime version | 4.0 | |
|||||||
| 10 | | Base URL | `https://api.aethex.tech` | |
|||||||
| 11 | | OpenAPI | [[OpenAPI Reference]] | |
|||||||
| 12 | | Last source review | 2026-06-26 | |
|||||||
|
13 | |||||||
|
14 | ## Start with health |
||||||
|
15 | |||||||
|
16 | ```bash |
||||||
| 17 | curl https://api.aethex.tech/health |
|||||||
| 18 | ``` |
|||||||
|
19 | |||||||
|
20 | ## Endpoint groups |
||||||
|
21 | |||||||
|
22 | | Group | Examples | Purpose | |
||||||
| 23 | |---|---|---| |
|||||||
| 24 | | Health | `/health`, `/ping`, `/active` | Reachability and runtime state | |
|||||||
| 25 | | Chat | `/chat`, `/kael`, `/kael/stream` | Non-streaming and SSE generation | |
|||||||
| 26 | | Models | `/kael/models` | Stable client model keys | |
|||||||
| 27 | | Authentication | `/auth/me`, `/auth/login`, `/auth/email`, `/auth/verify` | Browser identity and email codes | |
|||||||
| 28 | | History | `/kael/history/*` | Conversation persistence | |
|||||||
| 29 | | Memory | `/kael/memory/*` | Keyed user or visitor memory | |
|||||||
| 30 | | Identity | `/kael/identity`, `/kael/profile/stats` | Linked identity and usage context | |
|||||||
| 31 | | Documents | `/kael/docs/*` | Generate and manage documents | |
|||||||
| 32 | | Feed | `/kael/feed`, `/kael/featured` | Public activity and featured content | |
|||||||
| 33 | | Integrations | `/discord/interactions`, signed webhooks | External event delivery | |
|||||||
|
34 | |||||||
|
35 | ## Streaming |
||||||
|
36 | |||||||
|
37 | `POST /kael/stream` returns `text/event-stream`. |
||||||
|
38 | |||||||
|
39 | ```bash |
||||||
| 40 | curl --no-buffer https://api.aethex.tech/kael/stream \ |
|||||||
| 41 | -H 'Content-Type: application/json' \ |
|||||||
| 42 | -d '{"message":"Explain Passport","sessionId":"example","source":"docs","model":"standard"}' |
|||||||
| 43 | ``` |
|||||||
|
44 | |||||||
|
45 | Clients receive: |
||||||
|
46 | |||||||
|
47 | 1. Model metadata. |
||||||
| 48 | 2. JSON token or error events. |
|||||||
| 49 | 3. `data: [DONE]`. |
|||||||
|
50 | |||||||
|
51 | See [[API Quickstart]] for parsing guidance. |
||||||
|
52 | |||||||
|
53 | ## Authentication classes |
||||||
|
54 | |||||||
|
55 | - Anonymous requests use network and session context. |
||||||
| 56 | - Signed-in browser requests use the secure KAEL session cookie. |
|||||||
| 57 | - Approved tenant integrations use `x-tenant-key`. |
|||||||
| 58 | - Operator and owner credentials are privileged server-side credentials and are not public client authentication methods. |
|||||||
|
59 | |||||||
|
60 | ## Public contract boundary |
||||||
|
61 | |||||||
|
62 | The published OpenAPI contract intentionally excludes privileged deployment, operator administration, world-model mutation, and tenant-management operations. |
||||||
|
63 | |||||||
|
64 | > [!WARNING] |
||||||
| 65 | > Never embed a tenant key, operator token, provider key, webhook secret, or session cookie in public source code. |
|||||||
|
66 | |||||||
|
67 | ## Errors |
||||||
|
68 | |||||||
|
69 | Standard JSON failures use an `error` field. Streaming requests can report failures inside SSE data after the HTTP response has begun. |
||||||
|
70 | |||||||
|
71 | Clients should handle: |
||||||
|
72 | |||||||
|
73 | - `400` invalid input. |
||||||
| 74 | - `401` failed authentication. |
|||||||
| 75 | - `403` insufficient authorization. |
|||||||
| 76 | - `404` missing resource. |
|||||||
| 77 | - `429` rate limit. |
|||||||
| 78 | - `5xx` provider or service failure. |
|||||||
|
79 | |||||||
|
80 | ## Related documentation |
||||||
| 81 | ||||||||
| 82 | - [[OpenAPI Reference]] |
|||||||
| 83 | - [[Authentication]] |
|||||||
| 84 | - [[Rate Limits]] |
|||||||
| 85 | - [[Webhooks]] |
|||||||
| 86 | - [[KAEL API]] |
|||||||
| 87 | - [[KAEL Safety]] |
|||||||