SchemaChat API

Connect SchemaChat to backend jobs, internal tools, Slack bots, notebooks, and automations. The API uses workspace API keys and respects the same plan limits and read-only data protections as the app.

Bearer auth

Send your key in the Authorization header. Raw keys are only shown once.

Ask questions

Plain English in; answers, SQL or Mongo queries, rows, chart config, and follow-ups out.

Read-only data

SQL execution is limited to safe SELECT/WITH statements and capped result sizes.

1. Create an API key

Go to Settings → API access, create a key, and copy it immediately. Store it in your server-side environment variables.

SCHEMACHAT_API_KEY=sk_live_sc_...

2. Authentication

Every API request must include this header:

Authorization: Bearer $SCHEMACHAT_API_KEY

3. Rate limits

Limits scale with your plan. Every response includes your current rate-limit state in headers, so you can throttle proactively.

Plan	Limit
Free	30 requests / hour
Pro	120 requests / minute
Premium	300 requests / minute

Response headers

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1735689600   # unix seconds

When you exceed the limit you'll get 429 with aRetry-After header.

Endpoints

GET/api/v1/usage

Current plan, monthly AI-question quota, and live API rate-limit state.

curl https://www.schemachat.co/api/v1/usage \
  -H "Authorization: Bearer $SCHEMACHAT_API_KEY"

GET/api/v1/data-sources

List connected sources, tables, columns, row counts, and business context. Supports ?limit and ?offset.

curl https://www.schemachat.co/api/v1/data-sources \
  -H "Authorization: Bearer $SCHEMACHAT_API_KEY"

POST/api/v1/chat

Ask a plain-English question. This counts against the workspace AI question quota.

cURL

curl https://www.schemachat.co/api/v1/chat \
  -H "Authorization: Bearer $SCHEMACHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What were our top sales last month?",
    "dataSourceId": "optional_source_id"
  }'

Node.js (fetch)

const res = await fetch("https://www.schemachat.co/api/v1/chat", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMACHAT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ question: "What were our top sales last month?" }),
});
const data = await res.json();
console.log(data.answer, data.queryResult);

POST/api/v1/query

Run safe read-only SQL against SQL and CSV sources. MongoDB questions should use the chat endpoint.

curl https://www.schemachat.co/api/v1/query \
  -H "Authorization: Bearer $SCHEMACHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataSourceId": "source_id",
    "sql": "select customer_name, sum(total) as revenue from orders group by customer_name"
  }'

GET/api/v1/charts

Fetch saved charts and their chart configuration.

curl https://www.schemachat.co/api/v1/charts \
  -H "Authorization: Bearer $SCHEMACHAT_API_KEY"

GET/api/v1/dashboards

Fetch saved dashboards and pinned chart references.

curl https://www.schemachat.co/api/v1/dashboards \
  -H "Authorization: Bearer $SCHEMACHAT_API_KEY"

Response shape

The chat endpoint returns the answer plus any generated query, result rows, chart configuration, and follow-up prompts.

{
  "answer": "Total sales last month were $284,500.",
  "sqlQuery": "SELECT ... LIMIT 100",
  "queryResult": [{ "month": "May", "sales": 284500 }],
  "chartConfig": { "type": "bar", "title": "Sales by month", "data": [] },
  "followUps": ["Break this down by region"],
  "remainingQuestions": 199
}

Errors

Errors return a non-2xx status with a human-readable error and a stable machine-readable code.

{ "error": "Invalid or revoked API key.", "code": "invalid_api_key" }

Status	code	Meaning
401	missing_api_key / invalid_api_key	No key sent, or key invalid/revoked.
400	invalid_request / sql_rejected	Bad body, or SQL failed safety checks.
404	data_source_not_found	No connected source with that id.
429	rate_limited / ai_quota_exceeded	API rate limit or monthly AI quota reached.

Limits and safety

Chat requests also use the normal monthly AI question quota — check /api/v1/usage.
Read-only query execution blocks write/admin SQL and applies a row limit.
Raw keys are shown once at creation — store them securely server-side.
Revoke leaked keys immediately from Settings → API access.

Ready to build?

Create an API key in your workspace settings and make your first call in minutes.