Skip to content

API Reference

Sardeenz has no hand-written API reference. The OpenAPI 3.1 specifications in packages/contracts/specs/ are the reference: they are the single source of truth for every inter-component API (see ADR-005) and the generated TypeScript types and hand-maintained Rust types are derived from them.

Spec Audience Served by
control-plane.yaml Operators and the dashboard BFF Control plane, /api/v1/* (bearer token: SARDEENZ_API_TOKEN)
proxy-control-plane.yaml Proxy ↔ control plane (routing map, wake) Control plane /api/v1/wake + Redis routing map
engine-runner.yaml Runner shim authors Every runner's management port (/health, /sleep, …)
worker-agent.yaml Control plane ↔ worker Worker agent (POST/DELETE /runners, logs)

The inference API is not a Sardeenz contract: the proxy forwards OpenAI-compatible requests under /openai/v1/... and KServe V2 Open Inference Protocol requests under /oip/v2/... verbatim to the engine (ADR-021, structured-output notes).

The dashboard BFF exposes its own /api/* surface (auth, events, metrics, catalog, inference relay) for the frontend only; it is documented in docs/architecture/components/dashboard.md.

Browsing the specs

# Render one spec as interactive docs (Redocly is a dev dependency of the repo)
npx redocly preview-docs packages/contracts/specs/control-plane.yaml

# Or produce a static HTML page
npx redocly build-docs packages/contracts/specs/control-plane.yaml -o /tmp/control-plane.html

# Validate all specs
npm run validate -w @sardeenz/contracts

Editing workflow and conventions: docs/development/contracts.md.