# API reference

backend-api on `127.0.0.1:3028`. All routes JSON. No auth on loopback (gateway adds auth for public exposure).

## Existing modules (assistant management)

| Method | Path | Purpose |
|--------|------|---------|
| GET    | `/api/health`                        | Liveness probe |
| POST   | `/api/assistant/chat`                | LLM chat streaming (NDJSON) |
| GET    | `/api/conversations`                 | List chat sessions |
| GET    | `/api/conversations/:id`             | Get conversation |
| POST   | `/api/conversations`                 | Create conversation |
| PUT    | `/api/conversations/:id`             | Update conversation |
| DELETE | `/api/conversations/:id`             | Delete conversation |
| GET    | `/api/personality/:id`               | Personality CRUD |
| ...    | `/api/nag`, `/api/identity`, `/api/engine`, `/api/timers`, `/api/templates`, `/api/models`, `/api/skills`, `/api/plugins`, `/api/agents`, `/api/settings` | See module READMEs |

## NEW outreach control modules (this migration)

### `/api/outreach/*` — engine state + drafts

| Method | Path | Body | Returns |
|--------|------|------|---------|
| GET    | `/api/outreach/mode`                 | — | `{ mode, updatedAt, updatedBy, reason? }` |
| POST   | `/api/outreach/mode`                 | `{ mode, reason }` | updated config (shells out to `engine/run quinn-outreach mode set X --by=web --reason=Y`) |
| GET    | `/api/outreach/events?since=ISO&limit=N` | — | last N event_log rows since timestamp |
| GET    | `/api/outreach/drafts`               | — | event_log rows of type `reply_proposed`, `cover_story_proposed`, `auto_respond_pre_fire` (last 24h) |

### `/api/block-list/*` — § 49 wrong-identity registry

| Method | Path | Body | Returns |
|--------|------|------|---------|
| GET    | `/api/block-list`                    | — | `[{ handle, reason, addedAt }, ...]` |
| POST   | `/api/block-list`                    | `{ handle, reason }` | updated list (shells out to `engine/run quinn-outreach block H R`) |
| DELETE | `/api/block-list/:handle`            | — | updated list (shells out to `engine/run quinn-outreach unblock H`) |

### `/api/bookings/*` — booking state

| Method | Path | Body | Returns |
|--------|------|------|---------|
| GET    | `/api/bookings`                      | — | last 200 bookings |
| GET    | `/api/bookings/:id`                  | — | single booking row |
| POST   | `/api/bookings/:id/cancel`           | — | updated booking row (state → cancelled) |

## File-state ownership

`engine-config.json` and `block-list.json` are owned by the engine. backend-api READS them via filesystem (for display) and WRITES by shelling out to `engine/run` (canonical writer). This avoids two services racing on the same file. The CLI invocation goes through `QUINN_OUTREACH_ENGINE_RUN` env var (defaults to the absolute path of `engine/run`).

## Required environment

| Var | Default | Required for |
|-----|---------|--------------|
| `QUINN_AI_API_PORT`           | `3028` | core |
| `QUINN_AI_DATABASE_URL`       | — | core (ai.* schema, postgres on quinn cluster `:25435`) |
| `QUINN_OUTREACH_DB_URL`       | — | `/api/outreach/*` + `/api/bookings/*` (postgres on quinn_icloud cluster) |
| `MODEL_BOSS_URL`              | — | core (LLM inference) |
| `QUINN_MY_URL`                | `:3024` | assistant context |
| `AI_CORE_URL`                 | `:3790` | identity / nag |
| `QUINN_API_URL`               | `:3022` | financial tools |
| `QUINN_OUTREACH_ENGINE_RUN`   | absolute path to `engine/run` | `/api/outreach/*` + `/api/block-list/*` writes |
| `QUINN_ENGINE_CONFIG`         | `~/.local/share/quinn-outreach/engine-config.json` | `/api/outreach/mode` reads |
| `QUINN_BLOCK_LIST`            | `~/.local/share/quinn-outreach/block-list.json` | `/api/block-list` reads |

If `QUINN_OUTREACH_DB_URL` is unset, the outreach control surface is silently disabled (warned in logs). The block-list endpoints still work since they don't require the outreach DB.