api-layer git:20261003.1568dd5A

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

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

# HTTP API layer (`external/httpserver`)

- Built with **`-tags http`**. SPA root **`/`** (`go:embed` from **`external/ui`**) links only when you add **`tags=ui`** with **`go build -tags=http,ui`** (see **`mountEmbeddedSPARoot`** splits in **`spa_embed_ui.go`** / **`spa_no_ui.go`**). 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/reference/http-api.md`**; keep it aligned when endpoints or semantics change.
- **Which workspace a request describes.** **`resolveSessionCWD`** (**`slash_commands.go`**) answers with the session in **`X-Coddy-Session-ID`** (a persisted one loaded on demand; **`400`** malformed, **`404`** unknown) or the server default cwd. The read-only listings the composer asks for while the user types - **`/coddy/slash-commands`**, **`GET /coddy/skills`**, **`/coddy/mentions`**, **`POST /coddy/mentions/check`**, **`/coddy/workspace/file`** - go through **`resolveListingCWD`** instead, which adds the **`cwd`** query: the folder a new chat picked before its session exists, an absolute existing directory or **`400`**, used when the header is absent or names a session the server does not have yet, ignored next to one it has. A new listing of that kind uses **`resolveListingCWD`** and adds **`listingCWDParam()`** in **`openapi.go`**. Routes that change a workspace (the MCP routes through **`mcpWorkspace`**, trust and untrust, **`POST /coddy/workspace/folders`**) stay on **`resolveSessionCWD`** and never take **`cwd`**: an arbitrary folder must not get a declaration written or approved without a session in it. Held by **`TestListingCWDQueryEdges`** and **`features/skills_session_workspace.feature`**.

## References

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