openapi: 3.0.3 info: title: SaturnSQL API description: |- HTTP API for the SaturnSQL database query platform. SaturnSQL connects to your PostgreSQL, MySQL, MSSQL, Amazon Redshift, ClickHouse, DynamoDB and BigQuery databases and lets people — and AI agents — explore their schema and run queries through one authenticated surface, without ever handling raw database credentials. ## Authentication Two bearer credentials are accepted on the `Authorization` header: - **API key** (recommended for scripts, integrations, and AI agents) — a long-lived, scoped, revocable key in the `sat_live_...` format, created in Settings → Profile → API keys. - **JWT session token** — obtained from `POST /auth/login`; expires after 24 hours and requires the TOTP step when MFA is enrolled. This is what the web app uses. ``` Authorization: Bearer sat_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ``` ### API key scopes A key carries one or more scopes. Everything not in the list below fails closed — a key can never manage other keys, users, billing, or connections. | Scope | Grants | |-------|--------| | `read` | `GET /connections`, `GET /schema/{connectionId}`, `GET /schema/context`, `GET /queries`, `GET /queries/{id}`, `GET /queries/history` | | `execute` | `POST /queries/execute` (run SQL), `POST /queries/{id}/run` (run a saved query from values) | | `write` | `POST /queries`, `PUT /queries` (save / update saved queries) | Give an agent the narrowest scope it needs: `read` alone to explore schema and saved queries, add `execute` only when it must run SQL, add `write` only when it should persist queries. Name the key after the agent and set an expiry. ## Building queries and insights with an AI agent The intended agent loop is **discover → understand → query → (optionally) save**. Every call is scoped to the company the key belongs to, and only connections the key's owner can see are reachable. ### 1. Discover connections List the databases available to the key and pick a `connectionId`: ``` curl -s https://saturnsql.com/api/connections \ -H 'Authorization: Bearer sat_live_...' ``` Each connection reports its `id`, `name`, database `type` and whether it is read-only. ### 2. Understand the schema Pull the tables, columns and types so the agent writes SQL against the real structure — never guess table or column names: ``` # Full schema for a connection curl -s 'https://saturnsql.com/api/schema/CONNECTION_ID' \ -H 'Authorization: Bearer sat_live_...' # Relevance-ranked subset for a goal (best for large databases) curl -s 'https://saturnsql.com/api/schema/context?connection_id=CONNECTION_ID&intent=monthly%20revenue%20by%20plan' \ -H 'Authorization: Bearer sat_live_...' ``` `GET /schema/context` accepts `connection_id` (required), `intent` (a natural-language description of what you're after), `tables` (comma-separated allowlist) and `current_sql`, and returns only the slice of schema relevant to that intent. Feed it straight into your SQL-generation prompt to keep context small and accurate. ### 3. Run read-only queries Execute generated SQL and get rows back (`execute` scope required): ``` curl -s https://saturnsql.com/api/queries/execute \ -H 'Authorization: Bearer sat_live_...' \ -H 'Content-Type: application/json' \ -d '{"connectionId":"CONNECTION_ID","sql":"SELECT plan, count(*) AS n FROM companies GROUP BY plan ORDER BY n DESC","limit":100}' ``` `limit` defaults to 1000 and caps at 10000. The response returns the result rows plus column metadata. **Read-only enforcement.** Execution is guarded so an agent cannot mutate data: only `SELECT`, `WITH` (CTEs) and `EXPLAIN` are accepted, one statement at a time, and write / DDL / admin verbs (`INSERT`, `UPDATE`, `DELETE`, `DROP`, `CREATE`, `ALTER`, `TRUNCATE`, `GRANT`, `EXEC`, `SELECT … INTO`, …) are rejected. Connections flagged read-only are additionally enforced at the driver level. Design agent prompts around exploration and reporting, not mutation. ### Insight-query patterns Once the schema is known, these read-only patterns surface useful insights on almost any database — adapt table and column names from step 2: - **Shape & volume** — `SELECT count(*) FROM `; row counts per table to find the big / active ones. - **Distributions** — `SELECT , count(*) n FROM
GROUP BY ORDER BY n DESC LIMIT 20` for top categories, statuses, plans. - **Trends over time** — `SELECT date_trunc('month', ) m, count(*) FROM
GROUP BY 1 ORDER BY 1` for growth and seasonality. - **Data-quality audit** — null / blank counts per column, duplicate keys, orphaned foreign keys. - **Cohorts & funnels** — first-seen vs last-seen per entity, step-to-step conversion with `WITH` CTEs. Run `EXPLAIN` first on unfamiliar or large tables, and keep a `LIMIT` on ad-hoc `SELECT`s. ### 4. Save the good ones (optional, `write` scope) Persist a query the user will want again, optionally filed into a folder with `folderPath` (`null` = root): ``` curl -s https://saturnsql.com/api/queries \ -H 'Authorization: Bearer sat_live_...' \ -H 'Content-Type: application/json' \ -d '{"name":"Signups by month","sql":"SELECT ...","connectionId":"CONNECTION_ID","folderPath":"Growth"}' ``` Browse queries the team already trusts with `GET /queries`, and recent runs with `GET /queries/history`, to reuse rather than reinvent. (Sharing a query company-wide is a plan-gated action available in the web app, not over an API key.) ### 5. A saved query is also a report page Every saved query is readable at `https://saturnsql.com/app/report/{id}` — the result as a table, with a chart above it when the shape allows one. With no chart pinned (the only case an API key can produce), the shape decides: - 1 date/timestamp column + 1–3 numeric columns → line / area - no date column + exactly 2 numeric columns → scatter - no date column + 1 text column (2–12 values) + 1 numeric → bar - anything else, including a 4th numeric column → table only So keep the numeric columns to three and the date columns to one; emit the rest as text. Rows plot in result order, so a time series needs `ORDER BY