2026-06-27 01:17:07AeThex Docs:
Build out operational docs platform
api-reference.md ..
@@ 1,47 1,87 @@
# API Reference
-
The AeThex API allows developers to interact with platform resources programmatically.
+
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.
-
> [!IMPORTANT]
-
> Authentication is required for most API operations.
+
| 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
-
## Sections
+
```bash
+
curl https://api.aethex.tech/health
+
```
-
### Authentication
+
## Endpoint groups
-
API authentication and token management.
+
| Group | Examples | Purpose |
+
|---|---|---|
+
| Health | `/health`, `/ping`, `/active` | Reachability and runtime state |
- 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.
-
### Webhooks
+
## Public contract boundary
-
Event-based integrations.
+
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.
-
## Authentication
+
## Errors
-
Currently supported authentication methods:
+
Standard JSON failures use an `error` field. Streaming requests can report failures inside SSE data after the HTTP response has begun.
-
- OAuth 2.0
-
- OpenID Connect
-
- API Keys
+
Clients should handle:
-
See [[Authentication]].
+
- `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]]
authentication.md ..
@@ 1,36 1,72 @@
# Authentication
-
Authentication explains how users, services, and integrations prove identity before accessing AeThex systems.
+
AeThex services use different credentials for people, browser sessions, tenants, integrations, and operators. They must not be mixed.
-
<div class="docs-section-heading">
-
<h2>Authentication model</h2>
-
<p>Authentication starts with Passport and extends into API, app, and organization access.</p>
-
</div>
+
| Field | Value |
+
|---|---|
+
| Documentation status | Active |
+
| Applies to | Passport, KAEL, API clients, tenants, and integrations |
+
| Last source review | 2026-06-26 |
-
AeThex authentication should be handled through [[Passport]] wherever possible. Passport acts as the user-facing identity layer, while APIs and backend services validate sessions, tokens, or service credentials against that identity context.
+
## Browser identity
-
## Common flows
+
KAEL currently supports:
-
- User sign-in through [[Passport]].
-
- Account linking through [[Linked-Accounts]].
-
- Organization access checks through [[Organizations]] and [[Teams]].
-
- API requests authenticated through documented credentials in [[Api-Reference]].
-
- Automation and local tooling authenticated through [[CLI]] or [[SDKs]].
+
- An AeThex identity-provider redirect flow beginning at `GET /auth/login`.
+
- A secure KAEL session cookie.
+
- Email one-time-code requests through `POST /auth/email`.
+
- Email code verification through `POST /auth/verify`.
+
- Session inspection through `GET /auth/me`.
+
- Logout through `GET /auth/logout`.
-
## Implementation checklist
+
The session cookie is intended to be `HttpOnly` and `Secure`; browser JavaScript should not read it.
-
1. Choose the identity flow: user session, linked account, or service credential.
-
2. Request only the scopes needed for the integration.
-
3. Validate tokens server-side before trusting user claims.
-
4. Check [[Permissions]] after authentication; identity alone is not authorization.
-
5. Log security-relevant failures for audit and support.
After authentication, the runtime can resolve Passport profile and ARM membership information. That context contributes to server-calculated clearance.
-
> [!WARNING]
-
> Do not store long-lived secrets in client-side code, public repos, browser storage, or Discord bot commands.
+
The client must not grant itself a higher clearance level.
+
+
## Tenant authentication
+
+
Approved server-side tenant integrations can supply `x-tenant-key` to tenant-aware endpoints.
+
+
Tenant keys can select:
+
+
- Tenant prompt.
+
- Tenant knowledge.
+
- Model policy.
+
- Tenant rate limits.
+
+
Never embed a tenant key in public browser JavaScript.
+
+
## Operator authentication
+
+
Operator tokens authorize privileged KAEL operations. They are not user sessions and must remain in trusted server or operator environments.
+
+
Owner-level credentials can authorize particularly sensitive operations. They must be rotated if exposed and must never appear in documentation.
+
+
## Webhook authentication
+
+
AeThex deployment webhooks require an HMAC signature in the configured Gitea or GitHub signature header. Discord interactions use Discord’s Ed25519 signature and timestamp headers.
+
+
See [[Webhooks]].
+
+
## Client checklist
+
+
- Verify the hostname before signing in.
+
- Use HTTPS.
+
- Keep cookies out of logs.
+
- Keep tenant and operator credentials server-side.
+
- Validate redirect targets.
+
- Rate-limit email code and verification attempts.
+
- Clear sessions on logout.
+
- Handle `401` and `403` differently.
+
+
## Related documentation
+
+
- [[Passport]]
+
- [[Permissions]]
+
- [[Security]]
+
- [[KAEL Safety]]
+
- [[API Reference]]
cli.md ..
@@ 1,35 1,53 @@
# CLI
-
The AeThex CLI is the command-line interface for developers, operators, and maintainers who need repeatable local workflows.
+
The AeThex CLI documentation currently defines the intended operational contract. Treat commands not present in the installed CLI as planned rather than shipped.
-
<div class="docs-section-heading">
-
<h2>Role in the ecosystem</h2>
-
<p>The CLI should make common AeThex workflows scriptable without replacing the API or dashboard.</p>
-
</div>
-
-
Use the CLI for tasks that benefit from automation: project setup, authentication checks, local configuration, deployment helpers, API inspection, and operational diagnostics.
+
| Field | Value |
+
|---|---|
+
| Product maturity | In development |
+
| Documentation status | Active |
+
| Last verified | 2026-06-26 |
## Expected workflows
-
- Authenticate with AeThex using [[Authentication]].
-
- Select an organization, team, or project context.
-
- Inspect API resources from [[Api-Reference]].
-
- Generate local config for [[SDKs]].
-
- Run checks for permissions, tokens, or integration health.
+
A stable AeThex CLI should eventually support:
+
+
- Identity and session inspection.
+
- Project initialization.
+
- Configuration validation.
+
- Build and deployment workflows.
+
- API and service health checks.
+
- Documentation and OpenAPI retrieval.
+
+
## Verify before use
+
+
Before following a command example:
+
+
```bash
+
aethex --version
+
aethex --help
+
```
+
+
If the command is unavailable, use the documented HTTP or web workflow instead. Do not install an unverified package solely because it uses the AeThex name.
+
+
## Command design requirements
+
+
- Non-interactive mode for automation.
+
- Structured output such as JSON.
+
- Explicit confirmation for destructive actions.
+
- No credentials in process arguments when a safer input method exists.
+
- Useful exit codes.
+
- Dry-run behavior for deployment and mutation commands.
-
## Command design principles
+
## Current alternatives
-
- Commands should be explicit and safe by default.
-
- Destructive commands should ask for confirmation unless run in CI-safe mode.
-
- Output should support both human-readable and JSON modes.
-
- Errors should include next-step guidance and links back to docs.
+
- Use [[API Quickstart]] for direct API access.
+
- Use [[OpenAPI Reference]] to generate a client.
+
- Use the appropriate public service from [[Service Directory]].
> Document actual commands here as the CLI stabilizes. Avoid inventing command syntax before implementation exists.
+
- [[SDKs]]
+
- [[API Reference]]
+
- [[Security]]
+
- [[Projects]]
rate-limits.md ..
@@ 1,33 1,67 @@
# Rate Limits
-
Rate Limits protect AeThex services from overload, abuse, accidental loops, and unfair resource consumption.
+
KAEL applies daily request limits based on server-calculated clearance. Tenant integrations can have a separate configured daily limit.
-
<div class="docs-section-heading">
-
<h2>Why limits exist</h2>
-
<p>Limits keep APIs reliable for everyone using the platform.</p>
-
</div>
+
| Field | Value |
+
|---|---|
+
| Documentation status | Active |
+
| Reset boundary | 00:00 UTC |
+
| Last source review | 2026-06-26 |
-
Rate limits may apply by user, organization, project, API credential, IP address, or endpoint. Exact limits should be documented here as APIs stabilize.
+
## Current KAEL daily limits
-
## Limit dimensions
+
| Clearance | Daily request limit |
+
|---|---:|
+
| L1 | 20 |
+
| L2 | 50 |
+
| L3 | 200 |
+
| L4 | Effectively unrestricted |
+
| L5 | Effectively unrestricted |
-
- Requests per time window.
-
- Burst capacity.
-
- Endpoint-specific limits.
-
- Project or organization quotas.
-
- Webhook delivery retry limits.
+
These are runtime defaults and can change. Tenant configuration can override the per-tenant daily limit.
+
+
## Limit key
+
+
KAEL derives the limit key from the strongest available identity context, such as:
+
+
- Signed-in subject.
+
- ARM or invite state.
+
- Client network identity.
+
- Tenant and caller scope.
+
+
Clients must not assume that changing a session ID resets a server-side limit.
+
+
## Streaming behavior
+
+
`POST /kael/stream` starts an SSE response before all checks finish. A limit failure can therefore arrive as an event:
+
+
```json
+
{
+
"error": "rate_limit",
+
"clearance": 1,
+
"limit": 20,
+
"message": "L1 daily limit reached."
+
}
+
```
+
+
The stream then emits `[DONE]`.
## Client behavior
-
1. Respect status codes and retry headers.
-
2. Use exponential backoff for retries.
-
3. Cache stable responses where appropriate.
-
4. Avoid polling when [[Webhooks]] can provide updates.
-
5. Contact support if a legitimate integration needs higher limits.
- Do not fabricate a remaining count when the server did not provide one.
+
- Use exponential backoff for transient `5xx` failures, not daily limits.
+
+
## Infrastructure limits
+
+
The documentation site separately limits mutation requests at nginx to reduce automated abuse. Those controls do not change KAEL’s application-level daily limits.
+
+
## Related documentation
+
+
- [[API Quickstart]]
+
- [[KAEL API]]
+
- [[Authentication]]
+
- [[Security]]
sdks.md ..
@@ 1,36 1,48 @@
# SDKs
-
SDKs provide language-specific tools for working with AeThex APIs and platform services.
+
AeThex does not currently publish a guaranteed stable first-party SDK release contract for the KAEL API. Use the OpenAPI contract or direct HTTP integration while interfaces are evolving.
-
<div class="docs-section-heading">
-
<h2>SDK purpose</h2>
-
<p>SDKs should make common integrations easier while preserving the behavior documented in the API Reference.</p>
-
</div>
+
| Field | Value |
+
|---|---|
+
| Product maturity | In development |
+
| Documentation status | Active |
+
| Contract source | [[OpenAPI Reference]] |
+
| Last source review | 2026-06-26 |
-
SDKs should wrap authentication, request signing, pagination, error handling, retry behavior, and typed access to common resources. They should not hide important security or permission requirements.
+
## Recommended approach
+
+
For ordinary JSON endpoints:
+
+
1. Download `/static/custom/openapi.yaml`.
+
2. Generate a client for your language.
+
3. Wrap generated code behind your own application boundary.
+
4. Pin the generated client to the contract version you reviewed.
+
+
For `/kael/stream`, use an SSE-capable fetch client. Many generated SDKs treat streaming responses as a plain string and need a small custom adapter.
- Client model keys are more stable than provider model IDs.
+
- Public routes are more stable than privileged operator routes.
+
- Experimental fields can change before a formal SDK release.
+
- Review [[KAEL Changelog]] before regenerating.
+
+
## Related documentation
+
+
- [[API Quickstart]]
+
- [[API Reference]]
+
- [[OpenAPI Reference]]
+
- [[Rate Limits]]
webhooks.md ..
@@ 1,35 1,64 @@
# Webhooks
-
Webhooks let AeThex notify external systems when events happen, reducing the need for polling.
+
Webhooks allow an external service to deliver a signed event to AeThex.
-
<div class="docs-section-heading">
-
<h2>Event delivery</h2>
-
<p>Use webhooks when an integration needs to react to changes in near real time.</p>
-
</div>
+
| Field | Value |
+
|---|---|
+
| Documentation status | Active |
+
| Current uses | Signed deployment events and Discord interactions |
+
| Last source review | 2026-06-26 |
-
Webhooks may be used for project events, identity changes, organization updates, support workflows, build notifications, or integration-specific events as the platform expands.
+
## Deployment webhooks
-
## Webhook lifecycle
+
The AeThex API currently exposes signed deployment webhook handlers for selected repositories.
-
1. Register an endpoint for a project or organization.
-
2. Select event types.
-
3. Store and protect the signing secret.
-
4. Verify signatures on incoming requests.
-
5. Return success quickly and process work asynchronously.
-
6. Monitor failures and retries.
+
The receiver:
+
+
1. Reads the signature from the configured Gitea or GitHub signature header.
+
2. Computes an HMAC SHA-256 value using the shared webhook secret.
+
3. Rejects an invalid signature with `401`.
+
4. Ignores branches other than `main`.
+
5. Acknowledges the accepted event before starting the deployment script.
+
+
Deployment webhook URLs and secrets are operational credentials and are not published here.
+
+
## Discord interactions
+
+
Discord sends interactions to `/discord/interactions`.
