Veni builder API
Served under /api on :3010. Two audiences use it — the CLI installer (how you get the veni binary) and the Builder UI (the dev-only scaffold wizard). The whole surface is self-describing: GET /api/openapi.json returns the live OpenAPI spec (add ?download=true to save it).
Veni builder is stateless — it has no database. It operates on the filesystem, the vendored app-template, and the component registry, so there's no data model to document (unlike the Shell).
Key endpoints
| Endpoint | Purpose | Auth |
|---|---|---|
GET /api/cli/install.sh | The one-line CLI installer script — signs the caller in via the device flow if they bring no token | none, dev-env |
GET /api/cli/download | The veni CLI tarball | Veni / Shell token |
GET /api/openapi.json | The live OpenAPI spec (?download=true to save) | public |
POST /api/auth/exchange | Exchange a Shell token for a builder service token | Shell token |
By controller
| Base path | What it does |
|---|---|
/api/auth | Token exchange + login |
/api/cli | Serve the CLI installer script + tarball (token-gated) |
/api/builder | Dev-only scaffold — GET /info (dev mode, ports, existing apps), POST /scaffold (run veni create), POST /scaffold/download (as a .zip), POST /tokens (regenerate a brand's tokens.css) |
/api/registry | The component/block catalog for AI agents — GET / (index), GET /:type/:slug (install manifest; ?format=md, ?inline=true), GET /:type/:slug/file?path=… (raw source) |
/api/openapi.json | The generated OpenAPI spec |
The write/exec endpoints are dev-gated
Everything under /api/builder/* refuses unless APP_ENV_NODE_ENV=development and APP_ENV_BUILDER_ENABLED=true — the Builder never scaffolds in production. The installer script is ungated; the tarball it downloads still requires a valid Veni token (why).
Each base path is a controller in api/src/controllers/; how the CLI toolchain is bundled behind /api/cli and how /api/builder runs the scaffolder are in the Architecture.
See also
- Veni builder → Start — install, run, and use the Builder.
- The veni CLI — the command reference for the binary this API serves.