Ai database analytics

AI Database Analytics

Talk to any database — Postgres, MySQL, MariaDB, MongoDB, SQL Server, SQLite — through one REST API. Ask questions in plain English and get back SQL plus results, or run SQL directly against a guardrailed, audited connection. Set up workflows that watch the database and fire email/webhook alerts. No direct database credentials in the agent's context, ever.

Why this instead of a raw DB connection

Handing an agent a connection string means it can DROP TABLE, sees column names with no business meaning, and leaves no audit trail. AI for Database sits in between: scoped API keys, read-only by default, every query logged, and a semantic layer (column annotations + metric definitions) so "revenue" means the same thing in every answer.

Setup

You need one environment variable:

AFD_API_KEY=afd_...

Get a key: sign up free at https://app.aifordatabase.com/signup, add a database connection in the UI (Connections → Add), then create an API key (Settings → API Keys) with the scopes you need: query, chat, connections, dashboards, workflows, usage — or * for all.

Base URL: https://app.aifordatabase.com/api/v1 Auth header on every request: Authorization: Bearer $AFD_API_KEY

Every response uses the same envelope:

{ "data": { ... }, "error": null, "meta": { "requestId": "...", "timestamp": "..." } }

On failure data is null and error is { "code": "...", "message": "..." }. Full spec: GET /api/v1/openapi.json (no auth needed).

Step 1 — Find the connection

curl -s https://app.aifordatabase.com/api/v1/connections \
  -H "Authorization: Bearer $AFD_API_KEY"

Returns data: [{ id, name, type, host, database, isActive, ... }] (paginated: ?page=1&pageSize=20). Save the id of the connection you want — every query needs it.

Get the schema before writing any SQL (tables, columns, relationships — no discovery queries needed):

curl -s https://app.aifordatabase.com/api/v1/connections/$CONN_ID/schema \
  -H "Authorization: Bearer $AFD_API_KEY"

Step 2 — Ask questions (two ways)

Plain English (/chat) — preferred for analysis

The API's own agent translates the question to SQL, runs it, and returns both. Best when you don't know the schema well or the question is analytical.

curl -s -X POST https://app.aifordatabase.com/api/v1/chat \
  -H "Authorization: Bearer $AFD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Top 10 customers by revenue in the last 30 days",
    "connectionId": "'$CONN_ID'"
  }'

Response data:

{
  "conversationId": "conv_...",
  "content": "Here are the top 10 customers...",
  "sqlQuery": "SELECT ...",
  "intent": "query",
  "queryResult": { "columns": [...], "rows": [...], "rowCount": 10, "executionTime": 42 },
  "steps": [ { "action": "run_query", "sql": "...", "queryResult": {...} } ],
  "usage": { "model": "...", "promptTokens": 0, "completionTokens": 0 }
}

Follow-ups: pass the returned conversationId back in the next /chat call to keep context ("now break that down by month"). Rows are capped at 500 per response (queryResult.isCapped tells you if truncated). Add "stream": true for server-sent events if you want incremental output.

Direct SQL (/connections/{id}/query) — when you know exactly what to run

Deterministic, no AI in the loop, no credits consumed:

curl -s -X POST https://app.aifordatabase.com/api/v1/connections/$CONN_ID/query \
  -H "Authorization: Bearer $AFD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT status, COUNT(*) FROM orders GROUP BY status"}'

Returns data: { columns, rows, rowCount, executionTime }. A bad query returns HTTP 422 with code QUERY_FAILED and the database's error message — read it, fix the SQL, retry.

Step 3 — Database alerts (workflows)

A workflow = SQL steps + actions, run manually or on a schedule. Use it for "tell me when signups drop", "email the daily numbers", "ping my webhook when a payment fails". Actions: EMAIL and WEBHOOK (point the webhook at a Slack incoming-webhook URL for Slack alerts).

curl -s -X POST https://app.aifordatabase.com/api/v1/workflows \
  -H "Authorization: Bearer $AFD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Low daily signups alert",
    "connectionId": "'$CONN_ID'",
    "triggerType": "SCHEDULE",
    "triggerConfig": "{\"cron\": \"0 9 * * *\"}",
    "steps": [
      {
        "name": "check signups",
        "query": "SELECT COUNT(*) AS signups FROM users WHERE created_at > NOW() - INTERVAL '\''1 day'\'' HAVING COUNT(*) < 50",
        "stopIfEmpty": true
      }
    ],
    "actions": [
      { "type": "EMAIL", "config": "{\"to\": \"[email protected]\", \"subject\": \"Signups below 50\"}" },
      { "type": "WEBHOOK", "config": "{\"url\": \"https://hooks.slack.com/services/T000/B000/XXXX\"}" }
    ]
  }'

Key mechanic: "stopIfEmpty": true means the actions only fire when the step returns rows — that's how a query becomes an alert condition. triggerType is MANUAL or SCHEDULE. Step results are auto-appended to the email/webhook payload.

Run one immediately and check history:

curl -s -X POST https://app.aifordatabase.com/api/v1/workflows/$WF_ID/run \
  -H "Authorization: Bearer $AFD_API_KEY"
curl -s https://app.aifordatabase.com/api/v1/workflows/$WF_ID/runs \
  -H "Authorization: Bearer $AFD_API_KEY"

Step 4 — Dashboards (optional)

Fastest path: just ask /chat to build one — "create a dashboard showing revenue by month and top products" with a connectionId. It generates the widgets and returns a link.

Manual control:

# Create an empty dashboard
curl -s -X POST https://app.aifordatabase.com/api/v1/dashboards \
  -H "Authorization: Bearer $AFD_API_KEY" -H "Content-Type: application/json" \
  -d '{"title": "Revenue overview", "description": "Monthly KPIs"}'

# List existing ones
curl -s https://app.aifordatabase.com/api/v1/dashboards \
  -H "Authorization: Bearer $AFD_API_KEY"

Widgets live under /dashboards/{id}/widgets; fetch fresh data for a widget via GET /dashboards/{id}/widgets/{widgetId}/data. Dashboards re-run their queries on schedule server-side — nothing for the agent to maintain.

Errors, limits, and etiquette

HTTP	Code	What to do
401	UNAUTHORIZED	Key missing/wrong. Check AFD_API_KEY starts with afd_
402	CREDITS_EXHAUSTED / UPGRADE_REQUIRED	/chat AI credits used up. Fall back to direct /query (no credits) or tell the user
403	FORBIDDEN / PLAN_LIMIT	Key lacks a scope, or free-plan workflow limit (3) reached
422	QUERY_FAILED	SQL error — message contains the DB's own error, fix and retry
429	RATE_LIMITED	60 req/min free, 300 req/min Pro — back off

Check remaining credits any time: GET /api/v1/usage/budget.

Practical tips:

• Fetch the schema once per session, not per query.
• Prefer /chat for exploratory questions, /query for anything you'll run repeatedly.
• Rows cap at 500 — aggregate in SQL rather than pulling raw tables.
• Other useful endpoints when needed: /saved-queries (parameterized templates, run by id), /metrics (canonical metric definitions, GET /metrics/{id}/value), /queries/submit + /queries/pending (human-approval flow for sensitive queries), /webhooks (org-level event subscriptions).

Product home: https://aifordatabase.com · API docs: https://app.aifordatabase.com/api/v1/docs · Agent manifest: https://aifordatabase.com/api/agents