Developer API Documentation

Programmatically integrate DataWhisper into your applications

Overview

The DataWhisper Developer API allows you to programmatically access all features of DataWhisper, including database management, natural language querying, and SQL execution. This is ideal for building custom integrations, automating workflows, or embedding DataWhisper capabilities into your own SaaS products.

Database Management

Connect, configure, and manage databases

Natural Language

Query databases using plain English

Multi-Tenant

Built-in tenant isolation for SaaS

Authentication

Creating an API Key

Navigate to your Workspace Settings
Scroll to the API Keys section
Click Create Key
Give it a name and select the required scopes
Copy the generated key immediately (it won't be shown again)

Using Your API Key

Include your API key in requests using one of these methods:

Option 1: Authorization Header (Recommended)

curl -X GET "https://datawhisper.sh/api/v1/developer/workspace" \
  -H "Authorization: Bearer dw_live_your_api_key_here"

Option 2: X-API-Key Header

curl -X GET "https://datawhisper.sh/api/v1/developer/workspace" \
  -H "X-API-Key: dw_live_your_api_key_here"

Security Best Practices

Never expose API keys in client-side code
Use environment variables to store keys
Create separate keys for different environments (dev, staging, prod)
Rotate keys regularly and revoke unused keys
Use the minimum required scopes for each key

Scopes & Permissions

API keys have scopes that control what operations they can perform. Select only the scopes you need for better security.

Scope	Description	Allows
`workspace:read`	View workspace information	GET /workspace, GET /usage
`database:read`	List and view databases	GET /databases, GET /databases/:id
`database:write`	Create, update, delete databases	POST, PATCH, DELETE /databases
`query:read`	View query history	GET /queries
`query:write`	Execute queries	POST /query, /generate-sql, /execute-sql
`schema:read`	View database schema	GET /databases/:id/schema

API Endpoints

Base URL: https://datawhisper.sh/api/v1/developer

Workspace

GET/workspace

Get workspace information

Required scope: workspace:read

GET/usage

Get current usage statistics (queries, databases, members)

Required scope: workspace:read

Databases

GET/databases

List all databases in the workspace

Required scope: database:read

POST/databases

Create a new database connection

Required scope: database:write

GET/databases/:id

Get database details

Required scope: database:read

PATCH/databases/:id

Update database configuration

Required scope: database:write

DELETE/databases/:id

Delete a database connection

Required scope: database:write

POST/databases/:id/test

Test database connection

Required scope: database:read

GET/databases/:id/schema

Get database schema (tables and columns)

Required scope: schema:read

Queries

POST/databases/:id/query

Execute a natural language query

Required scope: query:write

POST/databases/:id/generate-sql

Generate SQL from natural language (without executing)

Required scope: query:write

POST/databases/:id/execute-sql

Execute raw SQL query

Required scope: query:write

Multi-Tenant

POST/tenant-token

Generate a signed tenant token for data isolation

Required scope: query:write

Executing Queries

Natural Language Query

Ask questions in plain English and get SQL + results:

curl -X POST "https://datawhisper.sh/api/v1/developer/databases/{database_id}/query" \
  -H "Authorization: Bearer dw_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Show me the top 10 customers by total revenue"
  }'

Response:

{
  "sql": "SELECT customer_name, SUM(amount) as total_revenue FROM orders GROUP BY customer_name ORDER BY total_revenue DESC LIMIT 10",
  "data": [
    {"customer_name": "Acme Corp", "total_revenue": 150000},
    {"customer_name": "Widget Inc", "total_revenue": 125000}
  ],
  "columns": ["customer_name", "total_revenue"],
  "row_count": 10,
  "execution_time_ms": 45.2,
  "visualization": {
    "type": "bar_chart",
    "config": {"x_axis": "customer_name", "y_axis": "total_revenue"}
  }
}

Generate SQL Only

Get the SQL without executing it (useful for review/approval workflows):

curl -X POST "https://datawhisper.sh/api/v1/developer/databases/{database_id}/generate-sql" \
  -H "Authorization: Bearer dw_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Count users who signed up this month"
  }'

Response:

{
  "sql": "SELECT COUNT(*) FROM users WHERE created_at >= DATE_TRUNC('month', CURRENT_DATE)",
  "explanation": "This query counts all users whose created_at date falls within the current month."
}

Execute Raw SQL

Run a specific SQL query directly:

curl -X POST "https://datawhisper.sh/api/v1/developer/databases/{database_id}/execute-sql" \
  -H "Authorization: Bearer dw_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT * FROM products WHERE price > 100 LIMIT 5"
  }'

Multi-Tenant Support

If you're building a SaaS product, you can use DataWhisper's multi-tenant feature to ensure each of your users only sees their own data.

1. Enable Tenant Isolation

When creating an API key, enable tenant isolation and specify the column used for tenant identification:

{
  "name": "SaaS Production Key",
  "scopes": ["database:read", "query:write", "schema:read"],
  "tenant_isolation_enabled": true,
  "tenant_column": "organization_id"
}

2. Generate Tenant Tokens

Generate signed JWT tokens for each of your tenants in your backend:

curl -X POST "https://datawhisper.sh/api/v1/developer/tenant-token" \
  -H "Authorization: Bearer dw_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "org_123",
    "expires_in_seconds": 3600
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2025-02-03T12:00:00Z"
}

3. Use Tenant Token in Queries

Pass the tenant token when executing queries to automatically filter data:

curl -X POST "https://datawhisper.sh/api/v1/developer/databases/{database_id}/query" \
  -H "Authorization: Bearer dw_live_xxx" \
  -H "X-Tenant-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Show all orders"
  }'

The generated SQL will automatically include WHERE organization_id = 'org_123'

Architecture Flow

Your user logs into your SaaS application
Your backend generates a tenant token with their org_id
Your frontend/backend makes DataWhisper API calls with the tenant token
DataWhisper automatically filters all queries by the tenant

Rate Limits

API keys have configurable rate limits. Default is 60 requests per minute.

Plan	Default Rate Limit	Max Configurable
Pro	60/min	120/min
Team	120/min	300/min
Enterprise	Custom	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1707000000

Error Handling

All errors return a consistent JSON format:

{
  "detail": "Human-readable error message",
  "error_code": "MACHINE_READABLE_CODE"
}

Status	Meaning	Common Causes
`400`	Bad Request	Invalid JSON, missing required fields
`401`	Unauthorized	Invalid/expired API key, missing auth header
`403`	Forbidden	Missing required scope, revoked key
`404`	Not Found	Resource doesn't exist
`429`	Rate Limited	Too many requests, wait and retry
`500`	Server Error	Internal error, contact support

SDKs Coming Soon

Official SDKs for popular languages are in development:

JavaScript/TypeScriptPythonGoRuby

Need Help?

Having trouble with the API? Check our FAQ or contact support.

Contact Support