API Reference

All API endpoints are prefixed with /api and served by FastAPI routers. This reference lists every endpoint with its HTTP method, auth identity, and purpose.

Auth identity key:

• OBO — uses the signed-in user's On-Behalf-Of token
• SP — uses the app's Service Principal
• OBO → SP — tries OBO first, falls back to SP on scope error
• Mixed — uses both identities for different parts of the operation

Analysis Router (/api)

Method	Path	Auth	Purpose
POST	/api/space/fetch	OBO → SP	Fetch serialized Genie Agent by ID
POST	/api/space/parse	None	Parse pasted Genie API JSON (client-side data, no auth needed)
GET	/api/debug/auth	OBO	Dev-only auth debug endpoint (404 on Databricks Apps)
GET	/api/settings	None	Read-only app settings (LLM model, warehouse, host)
GET	/api/models	None	Curated chat serving endpoints selectable per Create Agent / Auto-Optimize run

Spaces Router (/api)

Method	Path	Auth	Purpose
GET	/api/spaces	OBO → SP	List Genie Agents with IQ scores, starred sort, filters
GET	/api/spaces/{space_id}	OBO	Space metadata + latest scan + star status
POST	/api/spaces/{space_id}/scan	OBO	Run IQ scan and persist result to Lakebase
GET	/api/spaces/{space_id}/history	OBO	Scan + auto-optimize run history for a space
PUT	/api/spaces/{space_id}/star	OBO	Toggle starred status (Lakebase)

Admin Router (/api/admin)

Method	Path	Auth	Purpose
GET	/api/admin/dashboard	OBO	Org-wide stats: space count, scan count, avg score, maturity distribution
GET	/api/admin/leaderboard	OBO	Top/bottom spaces by IQ score (top_n param)
GET	/api/admin/alerts	OBO	Spaces with "Not Ready" maturity (max 20)

Auth Router (/api/auth)

Method	Path	Auth	Purpose
GET	/api/auth/me	OBO	Current user info from OBO headers, dev env, or SDK
GET	/api/auth/status	OBO	Lightweight health check with workspace client / auth type

Create Router (/api/create)

Method	Path	Auth	Purpose
GET	/api/create/preflight	OBO	Pre-check that the user can create Genie Agents
GET	/api/create/discover/catalogs	OBO	List Unity Catalog catalogs
GET	/api/create/discover/schemas	OBO	List schemas in a catalog
GET	/api/create/discover/tables	OBO	List tables in a catalog.schema
GET	/api/create/discover/columns	OBO	List columns for a table
GET	/api/create/discover/search	OBO	Keyword search for candidate tables across Unity Catalog
POST	/api/create/validate	OBO	Validate serialized space config (errors/warnings)
POST	/api/create	OBO	Create Genie Agent from wizard payload
POST	/api/create/agent/chat	OBO	SSE — Create agent conversational flow
GET	/api/create/agent/sessions/{session_id}	OBO	Load agent session for refresh/reconnect
DELETE	/api/create/agent/sessions/{session_id}	OBO	Delete agent session

Auto-Optimize Router (/api/auto-optimize)

Method	Path	Auth	Purpose
GET	/api/auto-optimize/health	SP	GSO health check: job/warehouse configuration status
GET	/api/auto-optimize/permissions/{space_id}	Mixed	Pre-check SP manage + UC read
POST	/api/auto-optimize/trigger	Mixed	Start GSO optimization job; benchmark_policy is review_only or repair_allowed (OBO for auth, SP for job submission)
GET	/api/auto-optimize/runs/{run_id}	SP	Full run detail: stages, steps, levers, links
GET	/api/auto-optimize/runs/{run_id}/status	SP	Lightweight status poll: steps, scores
GET	/api/auto-optimize/levers	None	List optimization lever definitions
POST	/api/auto-optimize/runs/{run_id}/apply	OBO	Mark an already-published result APPLIED for integration compatibility; the post-run UI does not require this step
POST	/api/auto-optimize/runs/{run_id}/discard	Mixed	Discard run / rollback changes
GET	/api/auto-optimize/runs/{run_id}/revert-options	Mixed	Preview champion/baseline availability and live-to-snapshot benchmark diffs
POST	/api/auto-optimize/runs/{run_id}/revert	Mixed	Revert with independent config_target=champion|baseline and benchmark_target=current|champion|baseline query parameters
GET	/api/auto-optimize/spaces/{space_id}/active-run	SP	Check for QUEUED/IN_PROGRESS run
GET	/api/auto-optimize/spaces/{space_id}/runs	SP	List optimization runs for a space
DELETE	/api/auto-optimize/runs/{run_id}/history-entry	Mixed	Hide a terminal run from Workbench history after OBO CAN_EDIT/CAN_MANAGE authorization; preserves the workflow run and GSO audit data
GET	/api/auto-optimize/spaces/{space_id}/current-version	Mixed	Match live config and benchmarks independently to history-visible captured baselines/champions; report matched, mixed, component drift, or incomplete history (refresh=true bypasses the live-state cache)
GET	/api/auto-optimize/runs/{run_id}/iterations	SP	Per-iteration evaluation rows
GET	/api/auto-optimize/runs/{run_id}/loop-state	SP	Optimizer controller loop state for the run
GET	/api/auto-optimize/runs/{run_id}/publish	SP	Publish record and champion outcome
GET	/api/auto-optimize/runs/{run_id}/debug-data	SP	Diagnostics for Lakebase vs Delta data
GET	/api/auto-optimize/runs/{run_id}/eval-results	SP	Native Eval-Run rows (requires iteration param)
GET	/api/auto-optimize/runs/{run_id}/question-results	SP	Per-question results (requires iteration param)
GET	/api/auto-optimize/runs/{run_id}/patches	SP	All patches for the run
GET	/api/auto-optimize/runs/{run_id}/benchmark-changes	SP	Benchmark mutation ledger plus QC window, structured quality findings, semantic-review coverage, and proposed repairs

GenieWatch Routers (/api/watch)

Most GenieWatch metrics read Databricks system tables, which are not OBO-readable, so those routes execute as the service principal and use an in-process TTL cache. The traffic-gap route is user-authorized and does not persist traffic: it requires CAN_MANAGE, reads all conversation pages transiently, and fails instead of returning partial results. It is OBO-only — it never falls back to the service principal and returns 401 without user authorization. See OBO-only routes. These routers are registered separately in main.py.

Method	Path	Auth	Purpose
GET	/api/watch/spaces	SP	List watched Genie Agents with cost/usage summaries
GET	/api/watch/spaces/{space_id}	SP	Watch detail for one Agent
GET	/api/watch/spaces/{space_id}/traffic-gaps	OBO only	Manager-only, reviewable benchmark candidate gaps; no SP fallback, and no raw question or user identity in the response
POST	/api/watch/spaces/refresh	SP	Refresh the watched-space cache
GET	/api/watch/overview	SP	Org-wide cost overview
GET	/api/watch/cost/top	SP	Highest-cost Agents
GET	/api/watch/spaces/{space_id}/cost	SP	Per-Agent cost breakdown
GET	/api/watch/spaces/{space_id}/cost/top-queries	SP	Most expensive queries for an Agent
GET	/api/watch/spaces/{space_id}/cost/conversations	SP	Cost attributed per conversation
GET	/api/watch/spaces/{space_id}/usage	SP	Query volume and usage trend
GET	/api/watch/feedback	SP	Org-wide feedback signals
GET	/api/watch/feedback/comments	SP	Feedback comment text
GET	/api/watch/spaces/{space_id}/feedback	SP	Per-Agent feedback
GET	/api/watch/spaces/{space_id}/resources	SP	Tables actually executed by an Agent
GET	/api/watch/resources/rollup	SP	Executed-resource rollup
GET	/api/watch/resources/spaces	SP	Agents grouped by executed resource
GET	/api/watch/resources/graph	SP	Agent-to-resource lineage graph
GET	/api/watch/settings/health	SP	Watch health: system-table access and cache state
POST	/api/watch/settings/cache/refresh	SP	Force a cache refresh
POST	/api/watch/admin/refresh-rollup	SP	Rebuild usage rollups (admin-gated via require_admin)

Static File Serving (main.py)

Method	Path	Auth	Purpose
GET	/	None	Serve index.html (React SPA)
GET	/{full_path:path}	None	Serve static assets from frontend/dist/, fallback to SPA

SSE Streaming Endpoints

One endpoint uses Server-Sent Events:

Endpoint	Keepalive	Events
POST /api/create/agent/chat	15s	session, step, thinking, tool_call, tool_result, message_delta, message, created, updated, heartbeat, error, done

The frontend consumes SSE via manual fetch + ReadableStream in lib/api.ts (not EventSource). Buffers are split on \n\n.

Related Documentation

• Authentication & Permissions — which identity is used where and why
• Architecture Overview — router and service structure