Altair

API reference

Altair’s server exposes a REST API used by the web and Android clients. This page will, in the fullness of time, be the canonical reference for that API.

This page is a stub. There isn’t a generated API reference yet — the server doesn’t currently expose an OpenAPI specification. The most accurate reference is the server source itself, in apps/server.

Until a full reference lands

A few pragmatic places to look for what a specific endpoint expects and returns:

  • Shared contracts — the canonical registries for entity types, relation types, and sync stream names. Every client and the server agree with these or the build fails.
  • Web client types — TypeScript types that mirror the server’s request and response shapes.
  • Domain specs — PRDs for each domain (Guidance, Knowledge, Tracking) that document invariants and entity shapes at a design level.

Transport basics

  • Base URL: whatever you deployed the server at. Locally, http://localhost:8000.
  • Authentication: Authorization: Bearer <jwt> on every authenticated endpoint. Tokens are issued by the login endpoint using Argon2id password hashing; see ADR-012.
  • Content type: application/json for both requests and responses.
  • Sync: the clients reach Postgres through PowerSync rather than polling the REST API for every change. Sync-aware endpoints are documented alongside the sync engine design.

What the full reference will include

  • Every endpoint, grouped by domain, with request/response shapes and status codes.
  • Authentication flows — login, refresh, registration, and admin-only endpoints.
  • Error envelope — the shape of error responses, including the AppError variants described in ADR-011.
  • Example requests for each endpoint.

If you need a specific endpoint documented before the full reference lands, the quickest path is opening an issue — or reading the handler directly in apps/server/server/src/.