Andy Dixon
67a825a995
Twenty-six pages covering concepts, architecture, every subsystem, an interface tour with screenshots, the full API route table generated from openapi.json, the CLI, security and threat model, operations, ADRs, development history and a glossary. Built into the dixon.cx page skeleton, unlinked and noindex.
2.5 KiB
Every function of the interface is available over a JSON HTTP API under /api/v1. The machine-readable description is served by the daemon at /api/v1/openapi.json and a copy is published alongside this documentation as openapi.json. A test in the codebase fails if a route is added without being documented.
Authentication
Two credentials are accepted. Bearer API tokens (Authorization: Bearer noema_…) are created per user from the account page, stored hashed, optionally expiring, and revocable. Browser sessions are cookies set by the login form; a session may call the API too, but unsafe methods then require the X-CSRF-Token header carrying the session's token. Anonymous requests get 401.
Roles
Users have one of three roles. Observer can read everything. Operator can additionally act: post messages and observations, create goals and predictions, approve requests, run background jobs, take snapshots, start replays and experiments. Administrator can additionally configure: minds' lifecycle, policies, providers, integrations, users, forks and imports. Every operation in the reference below lists its minimum role; a call below it gets 403.
Conventions
- Mind-scoped paths accept a slug or an id in
{mind}. - Lists return
{"items": [...]}and often anextcursor; cursors are sequence numbers or ids, never offsets. - Errors use one envelope:
{"error": {"code": "...", "message": "...", "request_id": "..."}}with400for validation,401/403for authentication and roles,404for missing or out-of-scope resources (a resource belonging to another mind is a 404, not a 403),409for conflicts and replays,429for rate limits. - Bodies are JSON; unknown fields are rejected on inputs that create or import things.
- Long-running operations (replay, experiment run) return
202immediately and are polled. - Timestamps are RFC 3339; ids are UUIDv7 and sort by time.
Streaming
GET /api/v1/events/stream and GET /api/v1/minds/{mind}/events/stream are server-sent event streams. They accept the same filters as the event list, honour Last-Event-ID to replay missed events from the sequence, send heartbeats, and use per-client bounded buffers so a slow client cannot back-pressure the daemon.
Webhooks
POST /api/v1/webhooks/{id} is the one unauthenticated route. It requires the X-Noema-Timestamp and X-Noema-Signature headers described under integrations and refuses everything else.
Route reference
The table below is generated from the OpenAPI document.
{{openapi}}