portfolio_rs/docs/http-api.md
Markus Zoppelt 9a40461008 docs: slim down README, move reference material to docs/, drop outdated images
The README had grown to ~600 lines, mostly MCP and HTTP API reference.
It now keeps the pitch, installation, quick start, a short TUI section,
the command table and an index of docs/. The reference material moved to
docs/ (tui, agents, mcp, http-api, library, quotes, configuration), and
the MCP docs test now checks docs/mcp.md.

The TUI screenshots and the CLI demo gif were outdated and are removed;
img/ is excluded from the published crate. Em-dashes are gone from the
README, the new docs and the crate description.
2026-10-28 08:51:53 +01:00

49 lines
2.5 KiB
Markdown

# HTTP API
Serve your portfolio to local scripts, agents, and GUIs:
portfolio_rs api positions.json [--policy portfolio/policy.toml] [--host 127.0.0.1] [--port 3000] [--token-file PATH]
| Endpoint | Description |
|---|---|
| `GET /health` | Liveness check |
| `GET /api/portfolio` | Full portfolio summary, with `complete`, `hasStale` and `dataStatus` |
| `GET/POST /api/positions` | List / create positions |
| `GET/PUT/DELETE /api/positions/{id}` | Read / update / delete a position by stable `pos_` id (`positionId`; a numeric index still works) |
| `GET /api/allocation` | Allocation breakdown |
| `GET /api/performance` | Performance metrics |
| `GET /api/context` | Agent briefing (JSON) |
| `GET /api/review` | Policy review (requires `--policy`) |
| `GET /api/simulate` | Rebalance simulation (requires `--policy`) |
| `GET /api/validate` | Portfolio file validation |
| `GET /api/doctor?dir=DIR` | Workspace health check |
| `POST /api/refresh` | Force a live quote refresh |
Notes:
- The API is intended for **local use only**; binding to a non-loopback host
prints a loud warning. Requests must use `Host: localhost:<port>`,
`127.0.0.1:<port>` or `[::1]:<port>` (anything else gets `421`), which
blocks DNS-rebinding attacks from web pages.
- `--token-file PATH` turns on bearer auth: a random token is written to
`PATH` (mode 0600, never printed or logged) and every `/api/*` request
needs `Authorization: Bearer $(cat PATH)` (`401` otherwise). `/health`
stays open.
- Positions carry a stable `positionId` (`pos_…`, generated if missing and
persisted on the next save; a stored `Id` always wins). Generated ids of
market positions derive from ticker and asset class only, so renaming a
position keeps its id; cash and manual positions use name and asset class.
Use it in `/api/positions/{id}`. The numeric
`id` is the array index, kept for older clients.
- Purchase `price` is the recorded price only; prices estimated from
historic closes are `null`.
- Position mutations are persisted back to the portfolio file, except for
`.gpg` files, which are never rewritten.
- Live quotes are cached for a short TTL; `POST /api/refresh` bypasses the
cache.
- Application config is not an API payload. Embedding clients that read
`AppConfigDto` still never receive the LLM API key: `llmApiKey` is always
`null`, and `hasLlmApiKey` reports whether a non-empty key is configured.
A null or missing `llmApiKey` does not clear a stored key; an empty string
passed to `AppConfig::set_llm_api_key` (or `AppConfigDto::apply_to`) does.