# V3 BFF API Documentation

doc-set: `v3-bff-api-docs.v1` source-routes:
`apps/lilith/bff/src/routes/v3-lilith-*.ts`

## Route Coverage

| Route                   | Method | OpenAPI                                                 | Examples                                                |
| ----------------------- | ------ | ------------------------------------------------------- | ------------------------------------------------------- |
| `/api/v3/lilith/launch` | `POST` | `apps/lilith/bff/openapi/v3-lilith-launch.openapi.yaml` | `apps/lilith/bff/openapi/examples/lilith-launch-*.json` |

## Contract Summary

`POST /api/v3/lilith/launch` accepts a V3 client probe and returns a launch
decision for native, Pixel Streaming, Tier-2 fallback, or static landing. The
response includes `decisionId`, `selectedSurface`, `reasonCodes`, `target`,
`clientRegion`, `decidedAt`, `expiresAt`, and a `LilithLaunchDecision` event
ready for telemetry.

The OpenAPI artifact includes:

- request schema for native, browser, network, region, entry, and Pixel
  Streaming probes;
- response schema for all launch target variants;
- examples for native, Pixel Streaming, fallback, static, and invalid request
  families;
- `400` error schema for invalid request payloads.

Run `pnpm verify:v3 documentation-runbooks` after changing any `/api/v3/*` route
in the Lilith BFF.