REST API Overview

The REST API exposes endpoints for query execution, result retrieval, table and data management, and account usage metrics.

Detailed request/response schemas are available in the Reference page. For authentication, see API Tokens in the visual interface docs.

Endpoint groups

Service health

• GET /health: liveness status for the REST service.

Query execution and results

• POST /query: execute SQL (including AI operators) and materialize the result. Response format: empty, json, csv, or zip.
• POST /results/rows: fetch paginated rows from the latest materialized result.
• POST /results/download: download the full latest result as JSON, CSV, or ZIP.

Table discovery and inspection

• POST /schema/overview: list every visible schema and its tables in one introspection pass.
• POST /tables: list visible tables in one schema.
• POST /tables/{table_name}/schema: retrieve visible column metadata for one table.
• POST /tables/{table_name}/preview: retrieve paginated preview rows.

Data lifecycle

• POST /upload: upload CSV or ZIP data into the configured database.
• DELETE /tables/{table_name}?confirm=true: drop a table with explicit confirmation.

Usage and account metrics

• POST /usage: return daily usage counters and plan-bounded balances (AI credits and daily compute time) for the authenticated account. No db payload is required.

Authentication and target database

All gateway-facing endpoints require Authorization: Bearer <api_token>.

Database-backed endpoints additionally require a request payload with a db object describing the PostgreSQL connection. The exception is POST /usage, which reads account metrics from internal usage tables and accepts only the bearer token.

The optional db.system field must be omitted or set to postgres.