Query Editor API

The Query Editor API provides endpoints for executing SQL queries against connected data sources, managing saved queries and tab drafts, viewing execution history, and exporting results.

All endpoints are scoped to a space and require authentication.

Base path: /spaces/{slug}/query

Endpoints

Execute Query

POST /spaces/{slug}/query/execute

Execute a SQL query against a connected data source. Only SELECT statements are allowed.

Request Body:

Field	Type	Required	Description
connector_id	UUID	✅	ID of the query-capable connector
sql	string	✅	SQL query text
row_limit	integer		Maximum rows to return (default: 500)

Response:

{
  "columns": [
    {"name": "id", "type": "integer"},
    {"name": "email", "type": "varchar"}
  ],
  "rows": [
    {"id": 1, "email": "***MASKED***"}
  ],
  "row_count": 1,
  "execution_ms": 142,
  "warnings": []
}

Error Codes:

Status	Reason
400	Connector not queryable or query execution error
403	DML/DDL statement blocked
429	Rate limit exceeded

---

List Queryable Connectors

GET /spaces/{slug}/query/connectors

Returns connectors in the space that support SQL execution.

Response: QueryableConnectorResponse[]

[
  {
    "id": "uuid",
    "name": "Production DB",
    "connector_type": "query_postgres",
    "source_system_name": "data-warehouse"
  }
]

---

Autocomplete

GET /spaces/{slug}/query/autocomplete

Returns table and column names from the catalog for SQL editor autocompletion.

Response:

{
  "tables": [
    {
      "name": "users",
      "schema": "public",
      "columns": ["id", "email", "created_at"]
    }
  ]
}

---

Saved Queries

Create

POST /spaces/{slug}/query/saved

Field	Type	Required	Description
title	string	✅	Query title
sql_text	string	✅	SQL query text
connector_id	UUID	✅	Associated connector
is_shared	boolean		Share with space members (default: false)

List

GET /spaces/{slug}/query/saved

Returns saved queries visible to the current user (personal + shared). Supports pagination via X-Pagination-* headers.

Update

PUT /spaces/{slug}/query/saved/{query_id}

Update title, SQL, or sharing setting. Owner only.

Delete

DELETE /spaces/{slug}/query/saved/{query_id}

Returns 204 No Content. Owner only.

---

Tab Drafts

Tab drafts persist the user's editor tab state across sessions.

Get Drafts

GET /spaces/{slug}/query/drafts

Response:

{
  "tabs": [
    {
      "id": "tab-1",
      "title": "Untitled",
      "sql_text": "SELECT * FROM users",
      "connector_id": "uuid"
    }
  ],
  "active_tab_id": "tab-1",
  "updated_at": "2026-02-16T12:00:00Z"
}

Save Drafts

PUT /spaces/{slug}/query/drafts

Upserts the full tab state for the current user/space.

---

Query History

User History

GET /spaces/{slug}/query/history

Returns the current user's query execution history. Supports pagination.

Response item:

{
  "id": "uuid",
  "connector_id": "uuid",
  "sql_text": "SELECT ...",
  "row_count": 42,
  "execution_ms": 203,
  "status": "success",
  "error_message": null,
  "executed_at": "2026-02-16T12:00:00Z"
}

Admin History

GET /spaces/{slug}/query/history/admin

Returns all users' query executions in the space. Requires admin permissions. Includes user_email field.

---

Export Results

POST /spaces/{slug}/query/export

Executes a query and streams results as CSV or JSON. Uses StreamingResponse for memory efficiency.

Field	Type	Required	Description
connector_id	UUID	✅	Connector to query
sql	string	✅	SQL query text
format	string	✅	"csv" or "json"

Maximum export rows: 2,000.

PII/PHI Masking

All query endpoints respect PII/PHI masking. Columns flagged as sensitive are masked unless the user's product role explicitly grants PII/PHI access. Masking applies to both result grids and exports.