# API Reference

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.

| Field | Value |
|---|---|
| Product maturity | Live / evolving |
| Documentation status | Active |
| Runtime version | 4.0 |
| Base URL | `https://api.aethex.tech` |
| OpenAPI | [[OpenAPI Reference]] |
| Last source review | 2026-06-26 |

## Start with health

```bash
curl https://api.aethex.tech/health
```

## Endpoint groups

| Group | Examples | Purpose |
|---|---|---|
| Health | `/health`, `/ping`, `/active` | Reachability and runtime state |
| Chat | `/chat`, `/kael`, `/kael/stream` | Non-streaming and SSE generation |
| Models | `/kael/models` | Stable client model keys |
| Authentication | `/auth/me`, `/auth/login`, `/auth/email`, `/auth/verify` | Browser identity and email codes |
| History | `/kael/history/*` | Conversation persistence |
| Memory | `/kael/memory/*` | Keyed user or visitor memory |
| Identity | `/kael/identity`, `/kael/profile/stats` | Linked identity and usage context |
| Documents | `/kael/docs/*` | Generate and manage documents |
| Feed | `/kael/feed`, `/kael/featured` | Public activity and featured content |
| Integrations | `/discord/interactions`, signed webhooks | External event delivery |

## Streaming

`POST /kael/stream` returns `text/event-stream`.

```bash
curl --no-buffer https://api.aethex.tech/kael/stream \
  -H 'Content-Type: application/json' \
  -d '{"message":"Explain Passport","sessionId":"example","source":"docs","model":"standard"}'
```

Clients receive:

1. Model metadata.
2. JSON token or error events.
3. `data: [DONE]`.

See [[API Quickstart]] for parsing guidance.

## Authentication classes

- Anonymous requests use network and session context.
- Signed-in browser requests use the secure KAEL session cookie.
- Approved tenant integrations use `x-tenant-key`.
- Operator and owner credentials are privileged server-side credentials and are not public client authentication methods.

## Public contract boundary

The published OpenAPI contract intentionally excludes privileged deployment, operator administration, world-model mutation, and tenant-management operations.

> [!WARNING]
> Never embed a tenant key, operator token, provider key, webhook secret, or session cookie in public source code.

## Errors

Standard JSON failures use an `error` field. Streaming requests can report failures inside SSE data after the HTTP response has begun.

Clients should handle:

- `400` invalid input.
- `401` failed authentication.
- `403` insufficient authorization.
- `404` missing resource.
- `429` rate limit.
- `5xx` provider or service failure.

## Related documentation

- [[OpenAPI Reference]]
- [[Authentication]]
- [[Rate Limits]]
- [[Webhooks]]
- [[KAEL API]]
- [[KAEL Safety]]