<!-- Generated by full-example docs http --save; do not edit. -->

# HTTP API (full-example)

full-example exposes user commands over HTTP REST routes derived from the CLI tree.

## Running

```bash
full-example http
```

Listens on **http://127.0.0.1:3000** by default (`httpServer.host` / `httpServer.port`).

Bind is localhost-only by default — use a reverse proxy for remote access.

## Endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/health/liveness` | Liveness — server is online and accepting requests |
| `GET` | `/health/readiness` | Readiness — online plus config and `program.readiness` checks passed |
| `GET` | `/openapi.json` | OpenAPI 3.1 REST paths |
| `GET` | `/swagger` | Interactive Swagger UI API reference |
| * | `/*` | Invoke user commands (method per route) |
| `OPTIONS` | `*` | CORS preflight |

Discover paths from `openapi.json` (`/*`). Query binds options; POST/PUT/PATCH body binds options and `inputSchema` fields.

## Examples

```bash
curl -s http://127.0.0.1:3000/health/liveness
curl -s http://127.0.0.1:3000/health/readiness
curl -s http://127.0.0.1:3000/openapi.json
curl -s http://127.0.0.1:3000/workspaces
curl -s -X POST http://127.0.0.1:3000/workspaces \
  -H "content-type: application/json" \
  -d '{"name":"qa2"}'
```

## Responses

Success: status from handler → `http.successStatus` → method default (GET 200, POST 201, DELETE 204).

Handlers must use `ctx.respond()` or return a value for API/MCP tool calls.

Errors use `{ "error": "..." }` with `400`, `404`, `503`, or `500`.

## Logging

Server logs go to **stderr** (one JSON object per line by default).

- Configure with `program.log` on the program root
- **`enrich`** — add custom JSON fields on top of the default line
- **`serialize`** — replace the formatter and emit your own line shape

See the argsbarg [logging guide](https://github.com/bdombro/bun-argsbarg/blob/main/docs/logging.md) for examples and the full `LogEnrichContext` shape.

## REST routes

- `POST /echo` (CLI: `full-example echo`) — Echo a message (MCP-friendly leaf).
- `POST /status` (CLI: `full-example status`) — Show app version.

## Request bodies

POST/PUT/PATCH bodies are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).

For HTTP clients, use **`GET /openapi.json`** (or **`GET /swagger`**) for per-route request shapes.

Varargs positionals accept a JSON array of strings (not a comma-separated string).
Options with `format: comma-list` accept a comma-separated string or JSON array.
Options with a schema `default` are applied when omitted.

Shell invocation reference: `full-example docs cli`. Full CLI tree JSON: `full-example docs cli-schema`.

## OpenAPI

The HTTP API is described in OpenAPI 3.1.

- **Browse** — [http://127.0.0.1:3000/swagger](http://127.0.0.1:3000/swagger) (Swagger UI; loads `/openapi.json`)
- **Fetch** — `curl -s http://127.0.0.1:3000/openapi.json`
- **Save offline** — `full-example docs openapi --save` → `./docs/openapi.json` (or `just docgen` in app repos)

Use the spec to discover REST paths and request/response shapes before calling `/*`.