API Reference

Lens exposes a same-origin HTTP API through the Node BFF; the browser only calls /api/... paths, which Vite proxies to the Node backend in development. The Node backend forwards domain calls to the Python FastAPI backend (llm_d_lens), which owns validation, persistence and task execution.

flowchart LR
    UI["Lens UI"] --> BFF["Node BFF :3000"]
    BFF -->|Domain APIs, including /api/v1/deployments| PY["Python API (llm_d_lens)"]
    BFF -->|/api/remote-deploy| SSH["Remote host over SSH"]
    PY --> DB["Database"]
    PY --> K8s["Kubernetes"]

Deploy is part of the Lens Python backend, not a separate llm-d-bench API. For deployment routes, the BFF selects LLM_D_DEPLOY_API_URL, then SIMULATION_API_URL, then OPTIMALBENCH_URL, falling back to http://127.0.0.1:8081. Use scripts/lens-local.sh start for local development; see Installation and Environment variables for current startup and storage settings rather than host-specific /root/... paths. Requests require an authenticated Lens session and the relevant permission; unsafe methods also require the matching prism_csrf cookie and x-prism-csrf header. Unauthenticated smoke requests may return 401, not a resource list.

Surfaces

Surface	Description
Node BFF	Same-origin /api/... routes used by the browser; proxies to the Python API and hosts MCP tooling.
Python API	FastAPI routes for deploy, simulation, evaluation, storage, monitoring and auth.
MCP tools	Assistant-callable operations generated from backend routes into the MCP catalog.
Kubernetes backend	Server-side Kubernetes access over the official Python client, with CLI rollback.

Modules

Every Lens module has a dedicated page covering its backend HTTP endpoints and, where one exists, how to call its Python service layer directly (for internal scripts, tests or automation) instead of over HTTP:

Welcome

Scoped current issues and diagnostic links.

Model market

Catalog hand-off (frontend-only catalog).

Deployments

Runs, executions, cases, access.

Evaluation

Guided benchmark tasks.

Simulation

Trace-based simulation runs.

Model services

Gateway, providers, selection policies.

Clusters

Registration, bootstrap, overview.

Storage

Volumes and storage backends.

Model cache

Cached model artifacts.

External providers

Third-party AI providers.

Observability

Accelerator, cluster stack, GPU driver, profiling.

Lens Assistant

Node MCP tool catalog.

Administration

Auth, RBAC and system settings.

Every Python backend endpoint is also documented in the generated FastAPI OpenAPI schema. Regenerate it after backend route changes:

source .venv/bin/activate
npm run docs:api

Conventions

Every new or modified externally callable API (FastAPI routes, HTTP handlers, RPC/MCP tools and their request/response contracts) must keep its description consistent with the implemented behavior, validation, authorization, defaults, status codes and schemas. See the repository API description requirements in .github/instructions/api-documentation.instructions.md.