API Reference

SQL API

The SQL API executes SQL against the database branch associated with the API key.

Overview

Database-scoped keys pin requests to a runtime branch.

The hosted gateway rejects explicit branch override SQL for scoped keys.

Use SQL for schema, data, branches, contexts, capabilities, and selected operator-reviewed workflows.

Developer notes

Use parameterized calls in SDKs where available.
Avoid branch-control SQL from public database-scoped keys.
Treat DDL as migration-controlled.
Check result size limits for user-facing queries.

SQL request

REST

POST /v1/sql
Authorization: Bearer <database-api-key>
Content-Type: application/json

{
  "sql": "SELECT 1;"
}

Notes:
  The database API key determines the project/database/branch scope.
  SQL text can include -- line comments and /* block comments */.

Examples

sql

-- tenant_id is a normal column, but values should come from trusted session/app scope.
CREATE TABLE tickets (
  id INT PRIMARY KEY,
  tenant_id VARCHAR NOT NULL,
  subject VARCHAR NOT NULL,
  status VARCHAR NOT NULL
);

-- 'acme' is an example tenant value from your app's account/project context.
INSERT INTO tickets VALUES (1, 'acme', 'Late fee question', 'open');
SELECT id, subject FROM tickets WHERE tenant_id = 'acme';