api-layer git:20260507.fc5df68A

Immutable. This exact content never changes and is served at /api/v1/blob/af29d627a6c64c28.

---
description: Optional HTTP gateway, OpenAPI spec source of truth
globs: external/httpserver/**/*.go
alwaysApply: false
---

# HTTP API layer (`external/httpserver`)

- Built only with **`-tags http`**. Handlers are registered in **`Server.New`** in **`server.go`**.
- **`openapi.go`** builds the served OpenAPI 3 document (`openAPISpec`). It is the **programmatic** spec; it must describe the same paths, methods, parameters, schemas, and response shapes as the live handlers.
- After any change to routes or externally visible request or response behavior, update **`openAPISpec`** and extend **`server_test.go`** (or add tests) under the **`http` build tag.
- User-facing narrative lives in **`docs/http-api.md`**; keep it aligned when endpoints or semantics change.

## References

@workflow.mdc
@docs/http-api.md
@external/httpserver/server.go
@external/httpserver/openapi.go