Operating

API reference

OptiHouse is API-first — everything the UI does is a call to the same backend. Use the API to add connections, trigger scans and read findings programmatically.

Base URL & authentication

All endpoints are served by the FastAPI backend. Authenticated endpoints expect a valid session — sign in through the app or the auth endpoints to obtain one. Two endpoints are deliberately public: the SQL optimizer and the connectivity catalogue.

Interactive schema

The backend ships OpenAPI docs at /docs and /redoc on the API host. That schema is always authoritative for exact request and response shapes.

Connections

Method & path	What it does
`GET /connections`	List configured connections (secrets are never returned).
`POST /connections`	Create a connection — host, port, user, password, optional SSH bastion.
`POST /connections/{id}/test`	Open a short-lived connection and run `SELECT version()`.
`DELETE /connections/{id}`	Remove a connection and its stored credentials.

Scans

Method & path	What it does
`POST /connections/{id}/scan`	Trigger a scan now (returns 202 — runs asynchronously).
`GET /connections/{id}/scans`	List recent scans for a connection.
`GET /connections/{id}/scans/{scan_id}`	Fetch the status and summary of one scan.

Recommendations

Method & path	What it does
`GET /recommendations`	List findings — filterable by status, type and severity.
`GET /recommendations/{id}`	Fetch one finding with its full runbook.
`PATCH /recommendations/{id}/status`	Change status — e.g. mark applied or dismissed.
`GET /recommendations/auto-apply-stats`	Counts per attribution (manual / auto-rule / auto-evidence / webhook).

Optimizer (public)

POST /api/v1/queries/optimize analyses a single query and returns ranked issues with rewrites. It needs no credentials — it only sees the SQL text plus the workload knobs you pass.

bash

curl -X POST https://<api-host>/api/v1/queries/optimize \
  -H 'Content-Type: application/json' \
  -d '{
        "sql": "SELECT * FROM events WHERE toDate(ts) = today()",
        "avg_read_gb": 8.0,
        "runs_per_day": 400,
        "avg_duration_ms": 5200
      }'

Rate limits

The public optimizer endpoint is rate-limited per IP (roughly 30 requests per minute) and caps sql length at 50,000 characters. Stay within those bounds for automated use.

Connectivity catalogue (public)

GET /api/v1/connectivity/modes returns the five connectivity modes — direct, SSH bastion, WireGuard, Cloudflare Tunnel, pull agent — each with its status, trade-offs and setup notes, plus the minimum recommended ClickHouse version.