Auto Ontology API (1.1.0)

List every acronym, newest first.

With ?name=, the route answers { exists } instead of listing — the create form uses it to pre-check the unique constraint before submitting.

Create an acronym: the term plus the expansion the agent should read it as.

name must be unique; description is optional and defaults to empty.

Delete an acronym permanently. Answers 204 with no body.

Update an acronym's name or description.

Both fields are optional and only the ones present in the body are written, so a partial body leaves the rest of the record untouched.

Viewing the analytics report requires the analytics:read permission (admin).

List the caller's own API tokens.

Metadata only: tokens are stored hashed, so the plaintext value is never returned again after creation. Requires a browser session — an API token may not enumerate tokens.

Mint a new API token for the caller, carrying the caller's own permissions.

expires_in_days is optional — omitting it mints a non-expiring token, which is what an unattended script usually wants. The response is the only place the plaintext token ever appears; it is stored hashed and cannot be shown again. Requires a browser session — a token may not mint another token.

Revoke a token. Deletion is immediate and irreversible — the next request carrying that token fails to resolve a user and gets a 401. The plugin scopes the delete to the session user, so id can only ever name the caller's own token; an id belonging to someone else reads back as "not found".

Better Auth's GET surface: session lookup and the SSO callbacks.

Public by design — sign-in and the callback that completes it must both be reachable without a session. The plugin's own /api/auth/api-key/* routes are blocked here so /api/api-tokens stays the single way to manage tokens.

Better Auth's POST surface: sign-in, sign-out, and the SSO callbacks.

Public for the same reason GET is — none of it can require a session. The plugin's own /api/auth/api-key/* management routes are blocked here so /api/api-tokens stays the single way to mint or revoke a token.

Abort the agent run in flight for a conversation the caller owns.

This is what makes the chat UI's Stop button actually stop the run rather than merely detach the browser from it: an abandoned run keeps the conversation's slot claimed and the next question is rejected with 409. Cancelling ends the run without a final answer, so the persisted user turn keeps no assistant reply. 404 when the conversation does not exist or belongs to someone else.

Ask a question and stream the answer back as Server-Sent Events.

FastAPI emits the SQL plus the formatted answer first (result), then — when that answer has an executed result — generates and persists the chart/table bubble itself and streams it back as its own charts event before the stream closes. No second request needed from this route or the browser. Passing conversation_id persists the turn and additionally requires conversation: ['write']; the route answers 409 while that conversation already has a run in flight. Omitting it runs the question statelessly, with no history and no chart step.

Reattach to a chat run already in progress, as a Server-Sent Events stream.

A reloaded or reopened tab uses this to follow a run it did not start. It is a passive observer: it never submits a question and persists nothing, so a dropped watch connection has no effect on the run or on what gets saved. 400 without conversation_id, 404 when the conversation is not the caller's.

datasources.getColumnsForTable — list columns for one table.

Report whether compilation scans low-cardinality columns for distinct values.

Turn distinct value scanning on or off instance-wide (admin-only).

Deliberately does NOT trigger a compilation run. The flag is read at the top of each run, so it applies from the next one onward — flipping it is a change of policy, not a request to recompile. Operators who want it applied now can use Reset, which is on the same page.

Rejects a non-boolean enabled rather than coercing it, which is why this differs from the sibling configuration routes. Those flags are opt-in, so coercing a malformed value to false lands on their default and is harmless. This one is opt-out: coercion would silently turn OFF something that is on by default, so {"enabled": "true"} from a shell client would disable scanning while reading as if it enabled it.

Report whether ingest classifies catalog columns as PII.

Turn PII detection on or off instance-wide (admin-only).

Deliberately does NOT trigger an ingest. The flag is read at the start of each ingest's PII step, so it applies from the next one onward — flipping it is a change of policy, not a request to re-scan. Existing PII tags are left in place.

Rejects a non-boolean enabled rather than coercing it, so {"enabled": "true"} from a shell client cannot silently disagree with what the page would show after a save.

Report whether scheduled semantic compilation is enabled instance-wide.

Turn scheduled semantic compilation on or off instance-wide (admin-only).

Enabling also kicks off a compilation run immediately and starts the ingestion service's scheduler, so the change takes effect without a restart. That trigger is best-effort: the setting is still saved if the service is down, and the scheduler picks the flag up on its next boot.

Key/value stored in the configurations table. The text-to-SQL pipeline reads this same key (see auto_ontology/infra/feature_flags.py) before each statement it issues, and cancels the statement once it runs this long. An absent row means 30 seconds, which is also what a backend running without this frontend uses. Report the instance-wide SQL query timeout, in seconds.

Set the instance-wide SQL query timeout (admin-only).

Rejects anything but an in-range integer rather than coercing it: the backend treats an unusable stored value as the default, so a coerced value would be silently ignored while the page showed it as saved.

Report whether the instance-wide "Visualize SQL Results" setting is on.

The flag lives under Settings > Agent Settings, stored in the configurations key/value table. The chat proxy route resolves the value per request, so a client cannot override it.

Turn the instance-wide "Visualize SQL Results" setting on or off (admin-only).

Chat resolves the value per request, so the change takes effect on the next question without a client reload. It gates chart generation only — the result table still renders when it is off.

connectionsApi.getAll — list connections (viewable by all).

connectionsApi.create — add a connection (admin only; carries credentials).

connectionsApi.delete — remove a connection (admin only).

connectionsApi.update — rewrite a connection's settings (admin only).

connectionsApi.setSsoFederation — toggle "authenticate as signed-in user" on an existing connection (admin only).

connectionsApi.isEnvSource — whether connections come from env config.

connectionsApi.test — validate a connection config (admin only).

List the caller's own conversations, newest first, without their messages.

Scoped to the authenticated user: a conversation is only ever visible to its owner, so there is no way to list someone else's.

Start a new, empty conversation owned by the caller.

title is optional and defaults to empty. Chat clients usually create the conversation here first, then pass its id to POST /api/chat/completions.

Delete a conversation and its messages; 404 when it is not the caller's.

Answers 204 with no body. The delete cascades to the conversation's messages.

Fetch one conversation with its full message history, oldest message first.

Scoped to the caller, so another user's conversation reads as 404 rather than 403 — ownership is not disclosed.

Rename a conversation the caller owns; 404 when it is not theirs.

Append a message to a conversation the caller owns.

The manual path, for clients that record their own turns; the chat routes persist their messages themselves via FastAPI, so a normal chat flow never calls this. Also bumps the conversation's updated_at. 404 when the conversation does not exist or belongs to someone else.

Anyone may list custom analyses; only admins (analysis:manage) may add one.

Create a new CustomAnalysis with its Sql node.

Strict insert: input shape is enforced by :class:CustomAnalysisCreate and the frontend is responsible for trimming and rejecting blank values before sending. Updating an existing analysis goes through PUT /custom-analyses/{analysis_id}.

Returns 409 when name or sql is already used by another CustomAnalysis (both are unique natural keys), and 422 when the SQL can't be parsed against the current catalog (no recognised tables) — without those references the analysis would be invisible to retrieval.

Delete a CustomAnalysis (with its Sql node and VDB embedding).

Returns 404 when no CustomAnalysis with analysis_id exists. On success the deleted {"id": ...} is echoed so the UI can confirm the targeted record was removed.

Editing/deleting a custom analysis is admin-only (analysis:manage).

Validating SQL is part of the create/edit flow, so it shares the same analysis:manage permission as POST /custom-analyses.

List every custom prompt: the instance-wide prompt overrides the agent uses.

Create a custom prompt from content, which defaults to empty when omitted.

Delete a custom prompt permanently. Answers 204 with no body.

Fetch one custom prompt by id; 404 when no prompt has that id.

Update a custom prompt's text. content is the only writable field, and a body without it leaves the prompt unchanged.

datasources.getDBs — list databases.

explorationApi.getColumnAttributeExplorationDetails — a ColumnAttribute's own owning Term, for expanding it on the graph.

explorationApi.getColumnExplorationDetails — the Column's own ColumnAttribute, for expanding it on the graph.

explorationApi.getEdges — table connections backed by a shared SQL query or a foreign key.

explorationApi.getDataExplorationGraph — full data-layer graph ({nodes, links}).