Choose an interface
Select REST, MCP, an SDK, the Query workspace, or AI-readable docs for each job.
Every supported interface uses the same Account resolution, Source grants, SQL policy, query worker, and receipts. Choose based on the consuming runtime rather than expected privilege.
| Interface | Use it for | Important behavior |
|---|---|---|
| Query workspace | Human exploration and debugging | Interactive stop, catalogue browser, results and receipts |
| REST API | Services, CI, deterministic integrations | Complete public operation set and explicit HTTP semantics |
| TypeScript SDK | Node, browser-compatible runtimes, edge services | Dependency-free Fetch client, safe GET retry |
| Python SDK | Python services and notebooks | Typed HTTPX client with explicit close/context manager |
| MCP | Agent runtimes with tool calling | Six read-only tools, OAuth discovery, structured output |
| Agent Skill | Teaching an agent the safe workflow | Procedure and helper script; no added data capability |
| AI-readable docs | Runtime documentation retrieval | llms.txt, llms-full.txt, page Markdown, OpenAPI |
Decision rules
Use MCP when the agent host supports remote Streamable HTTP and OAuth discovery. Use an SDK when a program needs deterministic control over retries, pagination, typed models, and error handling. Use REST directly for languages without an SDK or for infrastructure where dependency count matters.
Use the Query workspace to validate relation names and SQL before embedding a query in code. Use the public documentation endpoints for setup questions only; they never contain Account data.
The hand-written CLI is deliberately deferred. Shell automation should use curl or the Agent
Skill's transparent helper so no separate credential or authorization model develops.