65 lines
3.9 KiB
Markdown
65 lines
3.9 KiB
Markdown
# 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.
|